diff --git a/param_extraction/chunks/chunk_001.txt b/param_extraction/chunks/chunk_001.txt new file mode 100644 index 0000000000..08de12926d --- /dev/null +++ b/param_extraction/chunks/chunk_001.txt @@ -0,0 +1,496 @@ +# Chunk: chunk_001 +# Source: a-st-ext.adoc +# Lines: 1-484 (of 484) +# Content starts: line 1 +# Line count: 484 +# Sections: 5 +# == "A" Extension for Atomic Instructions, Version 2.1 +# === Specifying Ordering of Atomic Instructions +# === "Zalrsc" Extension for Load-Reserved/Store-Conditional Instructions +# === Eventual Success of Store-Conditional Instructions +# === "Zaamo" Extension for Atomic Memory Operations +# +== "A" Extension for Atomic Instructions, Version 2.1 + +The atomic-instruction extension, named "A", contains +instructions that atomically read-modify-write memory to support +synchronization between multiple RISC-V harts running in the same memory +space. The two forms of atomic instruction provided are +load-reserved/store-conditional instructions and atomic fetch-and-op +memory instructions. Both types of atomic instruction support various +memory consistency orderings including unordered, acquire, release, and +sequentially consistent semantics. These instructions allow RISC-V to +support the RCsc memory consistency model. cite:[Gharachorloo90memoryconsistency] + +[NOTE] +==== +After much debate, the language community and architecture community +appear to have finally settled on release consistency as the standard +memory consistency model and so the RISC-V atomic support is built +around this model. +==== + +The A extension comprises instructions provided by the Zaamo and Zalrsc +extensions. + +=== Specifying Ordering of Atomic Instructions + +The base RISC-V ISA has a relaxed memory model, with the FENCE +instruction used to impose additional ordering constraints. The address +space is divided by the execution environment into memory and I/O +domains, and the FENCE instruction provides options to order accesses to +one or both of these two address domains. + +To provide more efficient support for release consistency cite:[Gharachorloo90memoryconsistency], each atomic +instruction has two bits, _aq_ and _rl_, used to specify additional +memory ordering constraints as viewed by other RISC-V harts. The bits +order accesses to one of the two address domains, memory or I/O, +depending on which address domain the atomic instruction is accessing. +No ordering constraint is implied to accesses to the other domain, and a +FENCE instruction should be used to order across both domains. + +If both bits are clear, no additional ordering constraints are imposed +on the atomic memory operation. If only the _aq_ bit is set, the atomic +memory operation is treated as an _acquire_ access, i.e., no following +memory operations on this RISC-V hart can be observed to take place +before the acquire memory operation. If only the _rl_ bit is set, the +atomic memory operation is treated as a _release_ access, i.e., the +release memory operation cannot be observed to take place before any +earlier memory operations on this RISC-V hart. If both the _aq_ and _rl_ +bits are set, the atomic memory operation is _sequentially consistent_ +and cannot be observed to happen before any earlier memory operations or +after any later memory operations in the same RISC-V hart and to the +same address domain. + +[[sec:lrsc]] +=== "Zalrsc" Extension for Load-Reserved/Store-Conditional Instructions + +include::images/wavedrom/load-reserve-st-conditional.edn[] + +Complex atomic memory operations on a single memory word or doubleword +are performed with the load-reserved (LR) and store-conditional (SC) +instructions. LR.W loads a word from the address in _rs1_, places the +sign-extended value in _rd_, and registers a _reservation set_—a set of +bytes that subsumes the bytes in the addressed word. SC.W conditionally +writes a word in _rs2_ to the address in _rs1_: the SC.W succeeds only +if the reservation is still valid and the reservation set contains the +bytes being written. If the SC.W succeeds, the instruction writes the +word in _rs2_ to memory, and it writes zero to _rd_. If the SC.W fails, +the instruction does not write to memory, and it writes a nonzero value +to _rd_. +No SC.W instruction shall retire unless it passes memory permission checks, +but it is UNSPECIFIED whether any side effects of implicit address translation +and protection memory accesses (such as setting a page-table entry D bit) +occur on a failed SC.W. +For the purposes of memory protection, a failed SC.W may be +treated like a store. +Regardless of success or failure, executing an +SC.W instruction invalidates any reservation held by this hart. LR.D and +SC.D act analogously on doublewords and are only available on RV64. For +RV64, LR.W and SC.W sign-extend the value placed in _rd_. + +[NOTE] +==== +Both compare-and-swap (CAS) and LR/SC can be used to build lock-free +data structures. After extensive discussion, we opted for LR/SC for +several reasons: 1) CAS suffers from the ABA problem, which LR/SC avoids +because it monitors all writes to the address rather than only checking +for changes in the data value; 2) CAS would also require a new integer +instruction format to support three source operands (address, compare +value, swap value) as well as a different memory system message format, +which would complicate microarchitectures; 3) Furthermore, to avoid the +ABA problem, other systems provide a double-wide CAS (DW-CAS) to allow a +counter to be tested and incremented along with a data word. This +requires reading five registers and writing two in one instruction, and +also a new larger memory system message type, further complicating +implementations; 4) LR/SC provides a more efficient implementation of +many primitives as it only requires one load as opposed to two with CAS +(one load before the CAS instruction to obtain a value for speculative +computation, then a second load as part of the CAS instruction to check +if value is unchanged before updating). + +The main disadvantage of LR/SC over CAS is livelock, which we avoid, +under certain circumstances, with an architected guarantee of eventual +forward progress as described below. Another concern is whether the +influence of the current x86 architecture, with its DW-CAS, will +complicate porting of synchronization libraries and other software that +assumes DW-CAS is the basic machine primitive. A possible mitigating +factor is the recent addition of transactional memory instructions to +x86, which might cause a move away from DW-CAS. + +More generally, a multi-word atomic primitive is desirable, but there is +still considerable debate about what form this should take, and +guaranteeing forward progress adds complexity to a system. +==== + +The failure code with value 1 encodes an unspecified failure. Other +failure codes are reserved at this time. Portable software should only +assume the failure code will be non-zero. + +[NOTE] +==== +We reserve a failure code of 1 to mean ''unspecified'' so that simple +implementations may return this value using the existing multiplexer required +for the SLT/SLTU instructions. More specific failure codes might be +defined in future versions or extensions to the ISA. +==== + +For LR and SC, the Zalrsc extension requires that the address held in _rs1_ +be naturally aligned to the size of the operand (i.e., eight-byte +aligned for _doublewords_ and four-byte aligned for _words_). If the +address is not naturally aligned, an address-misaligned exception or an +access-fault exception will be generated. The access-fault exception can +be generated for a memory access that would otherwise be able to +complete except for the misalignment, if the misaligned access should +not be emulated. +[NOTE] +==== +Emulating misaligned LR/SC sequences is impractical in most systems. + +Misaligned LR/SC sequences also raise the possibility of accessing +multiple reservation sets at once, which present definitions do not +provide for. +==== + +An implementation can register an arbitrarily large reservation set on +each LR, provided the reservation set includes all bytes of the +addressed data word or doubleword. An SC can only pair with the most +recent LR in program order. An SC may succeed only if no store from +another hart to the reservation set can be observed to have occurred +between the LR and the SC, and if there is no other SC between the LR +and itself in program order. An SC may succeed only if no write from a +device other than a hart to the bytes accessed by the LR instruction can +be observed to have occurred between the LR and SC. Note this LR might +have had a different effective address and data size, but reserved the +SC's address as part of the reservation set. + +[NOTE] +==== +Following this model, in systems with memory translation, an SC is +allowed to succeed if the earlier LR reserved the same location using an +alias with a different virtual address, but is also allowed to fail if +the virtual address is different. + +To accommodate legacy devices and buses, writes from devices other than +RISC-V harts are only required to invalidate reservations when they +overlap the bytes accessed by the LR. These writes are not required to +invalidate the reservation when they access other bytes in the +reservation set. +==== + +The SC must fail if the address is not within the reservation set of the +most recent LR in program order. The SC must fail if a store to the +reservation set from another hart can be observed to occur between the +LR and SC. The SC must fail if a write from some other device to the +bytes accessed by the LR can be observed to occur between the LR and SC. +(If such a device writes the reservation set but does not write the +bytes accessed by the LR, the SC may or may not fail.) An SC must fail +if there is another SC (to any address) between the LR and the SC in +program order. The precise statement of the atomicity requirements for +successful LR/SC sequences is defined by the Atomicity Axiom in +<>. + +[NOTE] +==== +The platform should provide a means to determine the size and shape of +the reservation set. + +A platform specification may constrain the size and shape of the +reservation set. + +A store-conditional instruction to a scratch word of memory should be +used to forcibly invalidate any existing load reservation: + +* during a preemptive context switch, and +* if necessary when changing virtual to physical address mappings, such +as when migrating pages that might contain an active reservation. + +The invalidation of a hart's reservation when it executes an LR or SC +imply that a hart can only hold one reservation at a time, and that an +SC can only pair with the most recent LR, and LR with the next following +SC, in program order. This is a restriction to the Atomicity Axiom in +<> that ensures software runs correctly on +expected common implementations that operate in this manner. +==== + +An SC instruction can never be observed by another RISC-V hart before +the LR instruction that established the reservation. + +[NOTE] +==== +The LR/SC sequence +can be given acquire semantics by setting the _aq_ bit on the LR +instruction. The LR/SC sequence can be given release semantics by +by setting the _rl_ bit on the SC instruction. Assuming +suitable mappings for other atomic operations, setting the +_aq_ bit on the LR instruction, and setting the +_rl_ bit on the SC instruction makes the LR/SC +sequence sequentially consistent in the C\++ `memory_order_seq_cst` +sense. Such a sequence does not act as a fence for ordering ordinary +load and store instructions before and after the sequence. Specific +instruction mappings for other C++ atomic operations, +or stronger notions of "sequential consistency", may require both +bits to be set on either or both of the LR or SC instruction. + +If neither bit is set on either LR or SC, the LR/SC sequence can be +observed to occur before or after surrounding memory operations from the +same RISC-V hart. This can be appropriate when the LR/SC sequence is +used to implement a parallel reduction operation. +==== + +Software should not set the _rl_ bit on an LR instruction unless the +_aq_ bit is also set, nor should software set the _aq_ bit on an SC +instruction unless the _rl_ bit is also set. LR._rl_ and SC._aq_ +instructions are not guaranteed to provide any stronger ordering than +those with both bits clear, but may result in lower performance. + +[NOTE] +==== +[[cas]] +[source,asm] +.Sample code for compare-and-swap function using LR/SC. + # a0 holds address of memory location + # a1 holds expected value + # a2 holds desired value + # a0 holds return value, 0 if successful, !0 otherwise + cas: + lr.w t0, (a0) # Load original value. + bne t0, a1, fail # Doesn't match, so fail. + sc.w t0, a2, (a0) # Try to update. + bnez t0, cas # Retry if store-conditional failed. + li a0, 0 # Set return to success. + jr ra # Return. + fail: + li a0, 1 # Set return to failure. + jr ra # Return. + +LR/SC can be used to construct lock-free data structures. An example +using LR/SC to implement a compare-and-swap function is shown in +<>. If inlined, compare-and-swap functionality need only take four instructions. +==== + +[[sec:lrscseq]] +=== Eventual Success of Store-Conditional Instructions + +The Zalrsc extension defines _constrained LR/SC loops_, which have +the following properties: + +* The loop comprises only an LR/SC sequence and code to retry the +sequence in the case of failure, and must comprise at most 16 +instructions placed sequentially in memory. +* An LR/SC sequence begins with an LR instruction and ends with an SC +instruction. The dynamic code executed between the LR and SC +instructions can only contain instructions from the base ''I'' +instruction set, excluding loads, stores, backward jumps, taken backward +branches, JALR, FENCE, and SYSTEM instructions. +Compressed forms of the aforementioned ''I'' instructions in the +C (hence Zca) and Zcb extensions are also permitted. +* The code to retry a failing LR/SC sequence can contain backwards jumps +and/or branches to repeat the LR/SC sequence, but otherwise has the same +constraint as the code between the LR and SC. +* The LR and SC addresses must lie within a memory region with the +_LR/SC eventuality_ property. The execution environment is responsible +for communicating which regions have this property. +* The SC must be to the same effective address and of the same data size +as the latest LR executed by the same hart. + +LR/SC sequences that do not lie within constrained LR/SC loops are +_unconstrained_. Unconstrained LR/SC sequences might succeed on some +attempts on some implementations, but might never succeed on other +implementations. + +[NOTE] +==== +We restricted the length of LR/SC loops to fit within 64 contiguous +instruction bytes in the base ISA to avoid undue restrictions on +instruction cache and TLB size and associativity. Similarly, we +disallowed other loads and stores within the loops to avoid restrictions +on data-cache associativity in simple implementations that track the +reservation within a private cache. The restrictions on branches and +jumps limit the time that can be spent in the sequence. Floating-point +operations and integer multiply/divide were disallowed to simplify the +operating system's emulation of these instructions on implementations +lacking appropriate hardware support. + +Software is not forbidden from using unconstrained LR/SC sequences, but +portable software must detect the case that the sequence repeatedly +fails, then fall back to an alternate code sequence that does not rely +on an unconstrained LR/SC sequence. Implementations are permitted to +unconditionally fail any unconstrained LR/SC sequence. +==== + +If a hart _H_ enters a constrained LR/SC loop, the execution environment +must guarantee that one of the following events eventually occurs: + +* _H_ or some other hart executes a successful SC to the reservation set +of the LR instruction in _H_'s constrained LR/SC loops. +* Some other hart executes an unconditional store or AMO instruction to +the reservation set of the LR instruction in _H_'s constrained LR/SC +loop, or some other device in the system writes to that reservation set. +* _H_ executes a branch or jump that exits the constrained LR/SC loop. +* _H_ traps. + +[NOTE] +==== +Note that these definitions permit an implementation to fail an SC +instruction occasionally for any reason, provided the aforementioned +guarantee is not violated. + +As a consequence of the eventuality guarantee, if some harts in an +execution environment are executing constrained LR/SC loops, and no +other harts or devices in the execution environment execute an +unconditional store or AMO to that reservation set, then at least one +hart will eventually exit its constrained LR/SC loop. By contrast, if +other harts or devices continue to write to that reservation set, it is +not guaranteed that any hart will exit its LR/SC loop. + +Loads and load-reserved instructions do not by themselves impede the +progress of other harts' LR/SC sequences. We note this constraint +implies, among other things, that loads and load-reserved instructions +executed by other harts (possibly within the same core) cannot impede +LR/SC progress indefinitely. For example, cache evictions caused by +another hart sharing the cache cannot impede LR/SC progress +indefinitely. Typically, this implies reservations are tracked +independently of evictions from any shared cache. Similarly, cache +misses caused by speculative execution within a hart cannot impede LR/SC +progress indefinitely. + +These definitions admit the possibility that SC instructions may +spuriously fail for implementation reasons, provided progress is +eventually made. + +One advantage of CAS is that it guarantees that some hart eventually +makes progress, whereas an LR/SC atomic sequence could livelock +indefinitely on some systems. To avoid this concern, we added an +architectural guarantee of livelock freedom for certain LR/SC sequences. + +Earlier versions of this specification imposed a stronger +starvation-freedom guarantee. However, the weaker livelock-freedom +guarantee is sufficient to implement the C11 and C++11 languages, and is +substantially easier to provide in some microarchitectural styles. +==== + +[[sec:amo]] +=== "Zaamo" Extension for Atomic Memory Operations + +include::images/wavedrom/atomic-mem.edn[] + +The atomic memory operation (AMO) instructions perform read-modify-write +operations for multiprocessor synchronization and are encoded with an +R-type instruction format. These AMO instructions atomically load a data +value from the address in _rs1_, place the value into register _rd_, +apply a binary operator to the loaded value and the original value in +_rs2_, then store the result back to the original address in _rs1_. AMOs +can either operate on _doublewords_ (RV64 only) or _words_ in memory. For +RV64, 32-bit AMOs always sign-extend the value placed in _rd_, and +ignore the upper 32 bits of the original value of _rs2_. + +For AMOs, the Zaamo extension requires that the address held in _rs1_ be +naturally aligned to the size of the operand (i.e., eight-byte aligned +for _doublewords_ and four-byte aligned for _words_). If the address +is not naturally aligned, an address-misaligned exception or an +access-fault exception will be generated. The access-fault exception can +be generated for a memory access that would otherwise be able to +complete except for the misalignment, if the misaligned access should +not be emulated. + +The misaligned atomicity granule PMA, defined in Volume II of this manual, +optionally relaxes this alignment requirement. +If present, the misaligned atomicity granule PMA specifies the size +of a misaligned atomicity granule, a power-of-two number of bytes. +The misaligned atomicity granule PMA applies only to AMOs, loads and stores +defined in the base ISAs, and loads and stores of no more than XLEN bits +defined in the F, D, and Q extensions, and compressed encodings thereof. +For an instruction in that set, if all accessed bytes lie within the same +misaligned atomicity granule, the instruction will not raise an exception for +reasons of address alignment, and the instruction will give rise to only one +memory operation for the purposes of RVWMO--i.e., it will execute atomically. + +The operations supported are swap, integer add, bitwise AND, bitwise OR, +bitwise XOR, and signed and unsigned integer maximum and minimum. +Without ordering constraints, these AMOs can be used to implement +parallel reduction operations, where typically the return value would be +discarded by writing to `x0`. + +[NOTE] +==== +We provided fetch-and-op style atomic primitives as they scale to highly +parallel systems better than LR/SC or CAS. A simple microarchitecture +can implement AMOs using the LR/SC primitives, provided the +implementation can guarantee the AMO eventually completes. More complex +implementations might also implement AMOs at memory controllers, and can +optimize away fetching the original value when the destination is `x0`. + +The set of AMOs was chosen to support the C11/C++11 atomic memory +operations efficiently, and also to support parallel reductions in +memory. Another use of AMOs is to provide atomic updates to +memory-mapped device registers (e.g., setting, clearing, or toggling +bits) in the I/O space. + +The Zaamo extension enables microcontroller class implementations to utilize +atomic primitives from the AMO subset of the A extension. Typically such +implementations do not have caches and thus may not be able to naturally support +the LR/SC instructions provided by the Zalrsc extension. +==== + +To help implement multiprocessor synchronization, the AMOs optionally +provide release consistency semantics. If the _aq_ bit is set, then no +later memory operations in this RISC-V hart can be observed to take +place before the AMO. Conversely, if the _rl_ bit is set, then other +RISC-V harts will not observe the AMO before memory accesses preceding +the AMO in this RISC-V hart. Setting both the _aq_ and the _rl_ bit on +an AMO makes the sequence sequentially consistent, meaning that it +cannot be reordered with earlier or later memory operations from the +same hart. + +[NOTE] +==== +The AMOs were designed to implement the C11 and C++11 memory models +efficiently. Although the FENCE R, RW instruction suffices to implement +the _acquire_ operation and FENCE RW, W suffices to implement _release_, +both imply additional unnecessary ordering as compared to AMOs with the +corresponding _aq_ or _rl_ bit set. +==== + +[NOTE] +==== +An example code sequence for a critical section guarded by a +test-and-test-and-set spinlock is shown in +Example <>. Note the first AMO is marked _aq_ to +order the lock acquisition before the critical section, and the second +AMO is marked _rl_ to order the critical section before the lock +relinquishment. + +[[critical]] +[source,asm] +.Sample code for mutual exclusion. `a0` contains the address of the lock. + li t0, 1 # Initialize swap value. + again: + lw t1, (a0) # Check if lock is held. + bnez t1, again # Retry if held. + amoswap.w.aq t1, t0, (a0) # Attempt to acquire lock. + bnez t1, again # Retry if held. + # ... + # Critical section. + # ... + amoswap.w.rl x0, x0, (a0) # Release lock by storing 0. + +We recommend the use of the AMO Swap idiom shown in <> for both lock +acquire and release to simplify the implementation of speculative lock +elision. cite:[Rajwar:2001:SLE] +==== + +[NOTE] +==== +The instructions in the "A" extension can be used to provide sequentially +consistent loads and stores, but this constrains hardware +reordering of memory accesses more than necessary. +A C++ sequentially consistent load can be implemented as +an LR with _aq_ set. However, the LR/SC eventual +success guarantee may slow down concurrent loads from the same effective +address. A sequentially consistent store can be implemented as an AMOSWAP +that writes the old value to `x0` and has _rl_ set. However the superfluous +load may impose ordering constraints that are unnecessary for this use case. +Specific compilation conventions may require both the _aq_ and _rl_ +bits to be set in either or both the LR and AMOSWAP instructions. +==== diff --git a/param_extraction/chunks/chunk_001.txt.license b/param_extraction/chunks/chunk_001.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_001.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_002.txt b/param_extraction/chunks/chunk_002.txt new file mode 100644 index 0000000000..4517c51d2e --- /dev/null +++ b/param_extraction/chunks/chunk_002.txt @@ -0,0 +1,3402 @@ +# Chunk: chunk_002 +# Source: b-st-ext.adoc +# Lines: 1-3375 (of 3375) +# Content starts: line 1 +# Line count: 3375 +# Sections: 20 +# == Bit Manipulation Extensions +# === "B" Extension for Bit Manipulation, Version 1.0.0 +# === Zba: Extension for Address generation, Version 1.0.0 +# === Zbb: Extension for Basic bit-manipulation, Version 1.0.0 +# ==== Logical with negate +# ==== Count leading/trailing zero bits +# ==== Count population +# ==== Integer minimum/maximum +# ==== Sign extension and zero extension +# ==== Bitwise rotation +# ==== OR Combine +# ==== Byte-reverse +# === Zbc: Extension for Carry-less multiplication, Version 1.0.0 +# === Zbs: Extension for Single-bit instructions, Version 1.0.0 +# === Zbkb: Extension for Bit-manipulation for Cryptography, Version 1.0.0 +# === Zbkc: Extension for Carry-less multiplication for Cryptography, Version 1.0.0 +# === Zbkx: Extension for Crossbar permutations, Version 1.0.0 +# === Instructions (in alphabetical order) +# ==== add.uw +# ==== andn +# +[[bits]] +== Bit Manipulation Extensions + +The bit-manipulation (bitmanip) extension collection is comprised of several component extensions to the base RISC-V architecture that are intended to provide some combination of code-size reduction, performance improvement, and energy reduction. +While the instructions are intended for general use, some instructions are more useful in certain domains than in others. +Hence, several smaller bitmanip extensions are provided. Each of these smaller extensions is grouped by common function and use case, and each has its own Zb*-extension name. + +Each bitmanip extension includes a group of several bitmanip instructions that have similar purposes and can often share the same logic. Some instructions are available in only one extension, while others are available in several. +The instructions have mnemonics and encodings that are independent of the extensions in which they appear. +Thus, when implementing extensions with overlapping instructions, there is no redundancy in logic or encoding. + +The bitmanip extensions are defined for RV32 and RV64. + +The bitmanip extension follows the convention in RV64 that _w_-suffixed instructions (without a dot before the _w_) ignore the upper 32 bits of their inputs, operate on the least-significant 32 bits as signed values, and produce a 32-bit signed result that is sign-extended to XLEN. + +Bitmanip instructions with the suffix _.uw_ have one operand that is an unsigned 32-bit value that is extracted from the least-significant 32 bits of the specified register. Other than that, these perform full-XLEN operations. + +Bitmanip instructions with the suffixes _.b_, _.h_, and _.w_ only look at the least-significant 8 bits, 16 bits, and 32 bits of the input (respectively) and produce an XLEN-wide result that is sign-extended or zero-extended, based on the specific instruction. + +The bit-manipulation instructions comprise the following extensions: + +* Zba: <<#zba>> +* Zbb: <<#zbb>> +* Zbs: <<#zbs>> +* Zbc: <<#zbc>> +* Zbkb: <<#zbkb>> +* Zbkc: <<#zbkc>> +* Zbkx: <<#zbkx>> + +Below is a list of all of the instructions that are included in these extensions, +along with their specific mapping: + +[%header,cols="^3,^3,10,16,^2,^2,^2,^2"] +|==== +|RV32 |RV64 |Mnemonic |Instruction |Zbb |Zbkb |Zbc |Zbkc +|{check}|{check}|andn _rd_, _rs1_, _rs2_ |<<#insns-andn>> |{check}|{check}| | +|{check}|{check}|brev8 _rd_, _rs_ |<<#insns-brev8>> | |{check}| | +|{check}|{check}|clmul _rd_, _rs1_, _rs2_ |<<#insns-clmul>> | | |{check}|{check} +|{check}|{check}|clmulh _rd_, _rs1_, _rs2_ |<<#insns-clmulh>> | | |{check}|{check} +|{check}|{check}|clmulr _rd_, _rs1_, _rs2_ |<<#insns-clmulr>> | | |{check}| +|{check}|{check}|clz _rd_, _rs_ |<<#insns-clz>> |{check}| | | +| |{check}|clzw _rd_, _rs_ |<<#insns-clzw>> |{check}| | | +|{check}|{check}|cpop _rd_, _rs_ |<<#insns-cpop>> |{check}| | | +| |{check}|cpopw _rd_, _rs_ |<<#insns-cpopw>> |{check}| | | +|{check}|{check}|ctz _rd_, _rs_ |<<#insns-ctz>> |{check}| | | +| |{check}|ctzw _rd_, _rs_ |<<#insns-ctzw>> |{check}| | | +|{check}|{check}|max _rd_, _rs1_, _rs2_ |<<#insns-max>> |{check}| | | +|{check}|{check}|maxu _rd_, _rs1_, _rs2_ |<<#insns-maxu>> |{check}| | | +|{check}|{check}|min _rd_, _rs1_, _rs2_ |<<#insns-min>> |{check}| | | +|{check}|{check}|minu _rd_, _rs1_, _rs2_ |<<#insns-minu>> |{check}| | | +|{check}|{check}|orc.b _rd_, _rs_ |<<#insns-orc_b>> |{check}| | | +|{check}|{check}|orn _rd_, _rs1_, _rs2_ |<<#insns-orn>> |{check}|{check}| | +|{check}|{check}|pack _rd_, _rs1_, _rs2_ |<<#insns-pack>> | |{check}| | +|{check}|{check}|packh _rd_, _rs1_, _rs2_ |<<#insns-packh>> | |{check}| | +| |{check}|packw _rd_, _rs1_, _rs2_ |<<#insns-packw>> | |{check}| | +|{check}|{check}|rev8 _rd_, _rs_ |<<#insns-rev8>> |{check}|{check}| | +|{check}|{check}|rol _rd_, _rs1_, _rs2_ |<<#insns-rol>> |{check}|{check}| | +| |{check}|rolw _rd_, _rs1_, _rs2_ |<<#insns-rolw>> |{check}|{check}| | +|{check}|{check}|ror _rd_, _rs1_, _rs2_ |<<#insns-ror>> |{check}|{check}| | +|{check}|{check}|rori _rd_, _rs1_, _shamt_ |<<#insns-rori>> |{check}|{check}| | +| |{check}|roriw _rd_, _rs1_, _shamt_|<<#insns-roriw>> |{check}|{check}| | +| |{check}|rorw _rd_, _rs1_, _rs2_ |<<#insns-rorw>> |{check}|{check}| | +|{check}|{check}|sext.b _rd_, _rs_ |<<#insns-sext_b>> |{check}| | | +|{check}|{check}|sext.h _rd_, _rs_ |<<#insns-sext_h>> |{check}| | | +|{check}| |unzip _rd_, _rs_ |<<#insns-unzip>> | |{check}| | +|{check}|{check}|xnor _rd_, _rs1_, _rs2_ |<<#insns-xnor>> |{check}|{check}| | +|{check}|{check}|zext.h _rd_, _rs_ |<<#insns-zext_h>> |{check}| | | +|{check}| |zip _rd_, _rs_ |<<#insns-zip>> | |{check}| | +|==== + +[%header,cols="^3,^3,10,16,^2,^2"] +|==== +|RV32 |RV64 |Mnemonic |Instruction |Zba |Zbs +| |{check}|add.uw _rd_, _rs1_, _rs2_ |<<#insns-add_uw>> |{check}| +|{check}|{check}|bclr _rd_, _rs1_, _rs2_ |<<#insns-bclr>> | |{check} +|{check}|{check}|bclri _rd_, _rs1_, _imm_ |<<#insns-bclri>> | |{check} +|{check}|{check}|bext _rd_, _rs1_, _rs2_ |<<#insns-bext>> | |{check} +|{check}|{check}|bexti _rd_, _rs1_, _imm_ |<<#insns-bexti>> | |{check} +|{check}|{check}|binv _rd_, _rs1_, _rs2_ |<<#insns-binv>> | |{check} +|{check}|{check}|binvi _rd_, _rs1_, _imm_ |<<#insns-binvi>> | |{check} +|{check}|{check}|bset _rd_, _rs1_, _rs2_ |<<#insns-bset>> | |{check} +|{check}|{check}|bseti _rd_, _rs1_, _imm_ |<<#insns-bseti>> | |{check} +|{check}|{check}|sh1add _rd_, _rs1_, _rs2_ |<<#insns-sh1add>> |{check}| +| |{check}|sh1add.uw _rd_, _rs1_, _rs2_|<<#insns-sh1add_uw>>|{check}| +|{check}|{check}|sh2add _rd_, _rs1_, _rs2_ |<<#insns-sh2add>> |{check}| +| |{check}|sh2add.uw _rd_, _rs1_, _rs2_|<<#insns-sh2add_uw>>|{check}| +|{check}|{check}|sh3add _rd_, _rs1_, _rs2_ |<<#insns-sh3add>> |{check}| +| |{check}|sh3add.uw _rd_, _rs1_, _rs2_|<<#insns-sh3add_uw>>|{check}| +| |{check}|slli.uw _rd_, _rs1_, _imm_ |<<#insns-slli_uw>> |{check}| +|==== + +=== "B" Extension for Bit Manipulation, Version 1.0.0 +The B standard extension comprises instructions provided by the Zba, Zbb, and +Zbs extensions. + +[#zba,reftext=Address generation instructions] +=== Zba: Extension for Address generation, Version 1.0.0 + +The Zba instructions can be used to accelerate the generation of addresses that index into arrays of basic types (halfword, word, doubleword) using both unsigned word-sized and XLEN-sized indices: a shifted index is added to a base address. + +The shift and add instructions do a left shift of 1, 2, or 3 because these are commonly found in real-world code and because they can be implemented with a minimal amount of additional hardware beyond that of the simple adder. This avoids lengthening the critical path in implementations. + +While the shift and add instructions are limited to a maximum left shift of 3, the slli instruction (from the base ISA) can be used to perform similar shifts for indexing into arrays of wider elements. The slli.uw -- added in this extension -- can be used when the index is to be interpreted as an unsigned word. + +The following instructions comprise the Zba extension: + +[%header,cols="^1,^1,4,8"] +|=== +|RV32 +|RV64 +|Mnemonic +|Instruction + +| +|{check} +|add.uw _rd_, _rs1_, _rs2_ +|<<#insns-add_uw>> + +|{check} +|{check} +|sh1add _rd_, _rs1_, _rs2_ +|<<#insns-sh1add>> + +| +|{check} +|sh1add.uw _rd_, _rs1_, _rs2_ +|<<#insns-sh1add_uw>> + +|{check} +|{check} +|sh2add _rd_, _rs1_, _rs2_ +|<<#insns-sh2add>> + +| +|{check} +|sh2add.uw _rd_, _rs1_, _rs2_ +|<<#insns-sh2add_uw>> + +|{check} +|{check} +|sh3add _rd_, _rs1_, _rs2_ +|<<#insns-sh3add>> + +| +|{check} +|sh3add.uw _rd_, _rs1_, _rs2_ +|<<#insns-sh3add_uw>> + +| +|{check} +|slli.uw _rd_, _rs1_, _imm_ +|<<#insns-slli_uw>> + +|=== + +[#zbb,reftext="Basic bit-manipulation"] +=== Zbb: Extension for Basic bit-manipulation, Version 1.0.0 + +==== Logical with negate + +[%header,cols="^1,^1,4,8"] +|=== +|RV32 +|RV64 +|Mnemonic +|Instruction + +|{check} +|{check} +|andn _rd_, _rs1_, _rs2_ +|<<#insns-andn>> + +|{check} +|{check} +|orn _rd_, _rs1_, _rs2_ +|<<#insns-orn>> + +|{check} +|{check} +|xnor _rd_, _rs1_, _rs2_ +|<<#insns-xnor>> +|=== + +.Implementation Hint +[NOTE, caption="Imp" ] +=============================================================== +The Logical with Negate instructions can be implemented by inverting the _rs2_ inputs to the base-required AND, OR, and XOR logic instructions. +In some implementations, the inverter on rs2 used for subtraction can be reused for this purpose. +=============================================================== + +==== Count leading/trailing zero bits + +[%header,cols="^1,^1,4,8"] +|=== +|RV32 +|RV64 +|Mnemonic +|Instruction + +|{check} +|{check} +|clz _rd_, _rs_ +|<<#insns-clz>> + +| +|{check} +|clzw _rd_, _rs_ +|<<#insns-clzw>> + +|{check} +|{check} +|ctz _rd_, _rs_ +|<<#insns-ctz>> + +| +|{check} +|ctzw _rd_, _rs_ +|<<#insns-ctzw>> +|=== + +==== Count population + +These instructions count the number of set bits (1-bits). This is also +commonly referred to as population count. + +[%header,cols="^1,^1,4,8"] +|=== +|RV32 +|RV64 +|Mnemonic +|Instruction + +|{check} +|{check} +|cpop _rd_, _rs_ +|<<#insns-cpop>> + +| +|{check} +|cpopw _rd_, _rs_ +|<<#insns-cpopw>> +|=== + +==== Integer minimum/maximum + +The integer minimum/maximum instructions are arithmetic R-type +instructions that return the smaller/larger of two operands. + +[%header,cols="^1,^1,4,8"] +|=== +|RV32 +|RV64 +|Mnemonic +|Instruction + +|{check} +|{check} +|max _rd_, _rs1_, _rs2_ +|<<#insns-max>> + +|{check} +|{check} +|maxu _rd_, _rs1_, _rs2_ +|<<#insns-maxu>> + +|{check} +|{check} +|min _rd_, _rs1_, _rs2_ +|<<#insns-min>> + +|{check} +|{check} +|minu _rd_, _rs1_, _rs2_ +|<<#insns-minu>> +|=== + +==== Sign extension and zero extension + +These instructions perform the sign extension or zero extension of the least-significant 8 bits or 16 bits of the source register. + +These instructions replace the generalized idioms `slli rd,rs,(XLEN-) + srai` (for sign extension of 8-bit and 16-bit quantities) and `slli + srli` (for zero extension of 16-bit quantities). + +[%header,cols="^1,^1,4,8"] +|=== +|RV32 +|RV64 +|Mnemonic +|Instruction + +|{check} +|{check} +|sext.b _rd_, _rs_ +|<<#insns-sext_b>> + +|{check} +|{check} +|sext.h _rd_, _rs_ +|<<#insns-sext_h>> + +|{check} +|{check} +|zext.h _rd_, _rs_ +|<<#insns-zext_h>> +|=== + +==== Bitwise rotation + +Bitwise rotation instructions are similar to the shift-logical operations from the base spec. However, where the shift-logical +instructions shift in zeros, the rotate instructions shift in the bits that were shifted out of the other side of the value. +Such operations are also referred to as ‘circular shifts’. + + + +[%header,cols="^1,^1,4,8"] +|=== +|RV32 +|RV64 +|Mnemonic +|Instruction + +|{check} +|{check} +|rol _rd_, _rs1_, _rs2_ +|<<#insns-rol>> + +| +|{check} +|rolw _rd_, _rs1_, _rs2_ +|<<#insns-rolw>> + +|{check} +|{check} +|ror _rd_, _rs1_, _rs2_ +|<<#insns-ror>> + +|{check} +|{check} +|rori _rd_, _rs1_, _shamt_ +|<<#insns-rori>> + +| +|{check} +|roriw _rd_, _rs1_, _shamt_ +|<<#insns-roriw>> + +| +|{check} +|rorw _rd_, _rs1_, _rs2_ +|<<#insns-rorw>> +|=== + +.Architecture Explanation +[NOTE, caption="AE" ] +=============================================================== +The rotate instructions were included to replace a common +four-instruction sequence to achieve the same effect (neg; sll/srl; srl/sll; or) +=============================================================== + +==== OR Combine + +*orc.b* sets the bits of each byte in the result _rd_ to all zeros if no bit within the respective byte of _rs_ is set, or to all ones if any bit within the respective byte of _rs_ is set. + +One use-case is string-processing functions, such as *strlen* and *strcpy*, which can use *orc.b* to test for the terminating zero byte by counting the set bits in leading non-zero bytes in a word. + +[%header,cols="^1,^1,4,8"] +|=== +|RV32 +|RV64 +|Mnemonic +|Instruction + +|{check} +|{check} +|orc.b _rd_, _rs_ +|<<#insns-orc_b>> +|=== + +==== Byte-reverse + +*rev8* reverses the byte-ordering of _rs_. + +[%header,cols="^1,^1,4,8"] +|==== +|RV32 +|RV64 +|Mnemonic +|Instruction + +|{check} +|{check} +|rev8 _rd_, _rs_ +|<<#insns-rev8>> + +|==== + +[#zbc,reftext="Carry-less multiplication"] +=== Zbc: Extension for Carry-less multiplication, Version 1.0.0 + +Carry-less multiplication is the multiplication in the polynomial ring over GF(2). + +*clmul* produces the lower half of the carry-less product and *clmulh* produces the upper half of the 2{times}XLEN carry-less product. + +*clmulr* produces bits 2{times}XLEN−2:XLEN-1 of the 2{times}XLEN carry-less product. + +[%header,cols="^1,^1,4,8"] +|=== +|RV32 +|RV64 +|Mnemonic +|Instruction + +|{check} +|{check} +|clmul _rd_, _rs1_, _rs2_ +|<<#insns-clmul>> + +|{check} +|{check} +|clmulh _rd_, _rs1_, _rs2_ +|<<#insns-clmulh>> + +|{check} +|{check} +|clmulr _rd_, _rs1_, _rs2_ +|<<#insns-clmulr>> + +|=== + +[#zbs,reftext="Single-bit instructions"] +=== Zbs: Extension for Single-bit instructions, Version 1.0.0 + +The single-bit instructions provide a mechanism to set, clear, invert, or extract +a single bit in a register. The bit is specified by its index. + +[%header,cols="^1,^1,4,8"] +|=== +|RV32 +|RV64 +|Mnemonic +|Instruction + +|{check} +|{check} +|bclr _rd_, _rs1_, _rs2_ +|<<#insns-bclr>> + +|{check} +|{check} +|bclri _rd_, _rs1_, _imm_ +|<<#insns-bclri>> + +|{check} +|{check} +|bext _rd_, _rs1_, _rs2_ +|<<#insns-bext>> + +|{check} +|{check} +|bexti _rd_, _rs1_, _imm_ +|<<#insns-bexti>> + +|{check} +|{check} +|binv _rd_, _rs1_, _rs2_ +|<<#insns-binv>> + +|{check} +|{check} +|binvi _rd_, _rs1_, _imm_ +|<<#insns-binvi>> + +|{check} +|{check} +|bset _rd_, _rs1_, _rs2_ +|<<#insns-bset>> + +|{check} +|{check} +|bseti _rd_, _rs1_, _imm_ +|<<#insns-bseti>> + +|=== + +[[zbkb,Bit-manipulation for Cryptography]] +=== Zbkb: Extension for Bit-manipulation for Cryptography, Version 1.0.0 + +This extension contains instructions essential for implementing +common operations in cryptographic workloads. + +[%header,cols="^1,^1,4,8"] +|=== +|RV32 +|RV64 +|Mnemonic +|Instruction + + +| {check} +| {check} +| rol +| <> + +| +| {check} +| rolw +| <> + +| {check} +| {check} +| ror +| <> + +| {check} +| {check} +| rori +| <> + +| +| {check} +| roriw +| <> + +| +| {check} +| rorw +| <> + +| {check} +| {check} +| andn +| <> + +| {check} +| {check} +| orn +| <> + +| {check} +| {check} +| xnor +| <> + +| {check} +| {check} +| pack +| <> + +| {check} +| {check} +| packh +| <> + +| +| {check} +| packw +| <> + +| {check} +| {check} +| brev8 +| <> + +| {check} +| {check} +| rev8 +| <> + +| {check} +| +| zip +| <> + +| {check} +| +| unzip +| <> + +|=== + +[[zbkc,Carry-less multiplication for Cryptography]] +=== Zbkc: Extension for Carry-less multiplication for Cryptography, Version 1.0.0 + +Carry-less multiplication is the multiplication in the polynomial ring over +GF(2). This is a critical operation in some cryptographic workloads, +particularly the AES-GCM authenticated encryption scheme. +This extension provides only the instructions needed to +efficiently implement the GHASH operation, which is part of this workload. + +[%header,cols="^1,^1,4,8"] +|=== +|RV32 +|RV64 +|Mnemonic +|Instruction + +|{check} +|{check} +|clmul _rd_, _rs1_, _rs2_ +|<<#insns-clmul>> + +|{check} +|{check} +|clmulh _rd_, _rs1_, _rs2_ +|<<#insns-clmulh>> + +|=== + +[[zbkx,Crossbar permutations]] +=== Zbkx: Extension for Crossbar permutations, Version 1.0.0 + +These instructions implement a "lookup table" for 4 and 8 bit elements +inside the general purpose registers. +_rs1_ is used as a vector of N-bit words, and _rs2_ as a vector of N-bit +indices into _rs1_. +Elements in _rs1_ are replaced by the indexed element in _rs2_, or zero +if the index into _rs2_ is out of bounds. + +These instructions are useful for expressing N-bit to N-bit boolean +operations, and implementing cryptographic code with secret +dependent memory accesses (particularly SBoxes) such that the execution +latency does not depend on the (secret) data being operated on. + +[%header,cols="^1,^1,4,8"] +|=== +|RV32 +|RV64 +|Mnemonic +|Instruction + +|{check} +|{check} +|xperm4 _rd_, _rs1_, _rs2_ +|<<#insns-xperm4>> + +|{check} +|{check} +|xperm8 _rd_, _rs1_, _rs2_ +|<<#insns-xperm8>> + +|=== + +<<< + +[#insns-b,reftext="Instructions (in alphabetical order)"] +=== Instructions (in alphabetical order) + +The semantics of each instruction is expressed in a SAIL-like syntax. + +[#insns-add_uw,reftext=Add unsigned word] +==== add.uw + +Synopsis:: +Add unsigned word + +Mnemonic:: +add.uw _rd_, _rs1_, _rs2_ + + +Pseudoinstructions:: +zext.w _rd_, _rs1_ {rightarrow} add.uw _rd_, _rs1_, zero + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x3b, attr: ['OP-32'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x0, attr: ['ADD.UW'] }, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'rs2' }, + { bits: 7, name: 0x04, attr: ['ADD.UW'] }, +]} +.... + +Description:: +This instruction performs an XLEN-wide addition between _rs2_ and the zero-extended least-significant word of _rs1_. + +Operation:: +[source,sail] +-- +let base = X(rs2); +let index = EXTZ(X(rs1)[31..0]); + +X(rd) = base + index; +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zba (<>) +|0.93 +|Ratified +|=== + +<<< +[#insns-andn,reftext="AND with inverted operand"] +==== andn + +Synopsis:: +AND with inverted operand + +Mnemonic:: +andn _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x33, attr: ['OP'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x7, attr: ['ANDN']}, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'rs2' }, + { bits: 7, name: 0x20, attr: ['ANDN'] }, +]} +.... + +Description:: +This instruction performs the bitwise logical AND operation between _rs1_ and the bitwise inversion of _rs2_. + +Operation:: +[source,sail] +-- +X(rd) = X(rs1) & ~X(rs2); +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbb (<<#zbb>>) +|v1.0 +|Ratified + +|Zbkb (<<#zbkb>>) +|v1.0 +|Ratified +|=== + +<<< +[#insns-bclr,reftext="Single-Bit Clear (Register)"] +==== bclr + +Synopsis:: +Single-Bit Clear (Register) + +Mnemonic:: +bclr _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x33, attr: ['OP'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x1, attr: ['BCLR'] }, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'rs2' }, + { bits: 7, name: 0x24, attr: ['BCLR/BEXT'] }, +]} +.... + +Description:: +This instruction returns _rs1_ with a single bit cleared at the index specified in _rs2_. +The index is read from the lower log2(XLEN) bits of _rs2_. + +Operation:: +[source,sail] +-- +let index = X(rs2) & (XLEN - 1); +X(rd) = X(rs1) & ~(1 << index) +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbs (<<#zbs>>) +|v1.0 +|Ratified +|=== + +<<< +[#insns-bclri,reftext="Single-Bit Clear (Immediate)"] +==== bclri + +Synopsis:: +Single-Bit Clear (Immediate) + +Mnemonic:: +bclri _rd_, _rs1_, _shamt_ + +Encoding (RV32):: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x13, attr: ['OP-IMM'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x1, attr: ['BCLRI'] }, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'shamt' }, + { bits: 7, name: 0x24, attr: ['BCLRI'] }, +]} +.... + +Encoding (RV64):: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x13, attr: ['OP-IMM'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x1, attr: ['BCLRI'] }, + { bits: 5, name: 'rs1' }, + { bits: 6, name: 'shamt' }, + { bits: 6, name: 0x12, attr: ['BCLRI'] }, +]} +.... + +Description:: +This instruction returns _rs1_ with a single bit cleared at the index specified in _shamt_. +The index is read from the lower log2(XLEN) bits of _shamt_. +For RV32, the encodings corresponding to shamt[5]=1 are reserved. + +Operation:: +[source,sail] +-- +let index = shamt & (XLEN - 1); +X(rd) = X(rs1) & ~(1 << index) +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbs (<<#zbs>>) +|v1.0 +|Ratified +|=== + +<<< +[#insns-bext,reftext="Single-Bit Extract (Register)"] +==== bext + +Synopsis:: +Single-Bit Extract (Register) +// Should we describe this as a Set-if-bit-is-set? + +Mnemonic:: +bext _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x33, attr: ['OP'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x5, attr: ['BEXT'] }, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'rs2' }, + { bits: 7, name: 0x24, attr: ['BCLR/BEXT'] }, +]} +.... + +Description:: +This instruction returns a single bit extracted from _rs1_ at the index specified in _rs2_. +The index is read from the lower log2(XLEN) bits of _rs2_. + +Operation:: +[source,sail] +-- +let index = X(rs2) & (XLEN - 1); +X(rd) = (X(rs1) >> index) & 1; +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbs (<<#zbs>>) +|v1.0 +|Ratified +|=== + +<<< +[#insns-bexti,reftext="Single-Bit Extract (Immediate)"] +==== bexti + +Synopsis:: +Single-Bit Extract (Immediate) + +Mnemonic:: +bexti _rd_, _rs1_, _shamt_ + +Encoding (RV32):: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x13, attr: ['OP-IMM'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x5, attr: ['BEXTI'] }, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'shamt' }, + { bits: 7, name: 0x24, attr: ['BEXTI/BCLRI'] }, +]} +.... + +Encoding (RV64):: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x13, attr: ['OP-IMM'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x5, attr: ['BEXTI'] }, + { bits: 5, name: 'rs1' }, + { bits: 6, name: 'shamt' }, + { bits: 6, name: 0x12, attr: ['BEXTI/BCLRI'] }, +]} +.... + +Description:: +This instruction returns a single bit extracted from _rs1_ at the index specified in _shamt_. +The index is read from the lower log2(XLEN) bits of _shamt_. +For RV32, the encodings corresponding to shamt[5]=1 are reserved. + +Operation:: +[source,sail] +-- +let index = shamt & (XLEN - 1); +X(rd) = (X(rs1) >> index) & 1; +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbs (<<#zbs>>) +|v1.0 +|Ratified +|=== + +<<< +[#insns-binv,reftext="Single-Bit Invert (Register)"] +==== binv + +Synopsis:: +Single-Bit Invert (Register) + +Mnemonic:: +binv _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x33, attr: ['OP'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x1, attr: ['BINV'] }, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'rs2' }, + { bits: 7, name: 0x34, attr: ['BINV'] }, +]} +.... + +Description:: +This instruction returns _rs1_ with a single bit inverted at the index specified in _rs2_. +The index is read from the lower log2(XLEN) bits of _rs2_. + +Operation:: +[source,sail] +-- +let index = X(rs2) & (XLEN - 1); +X(rd) = X(rs1) ^ (1 << index) +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbs (<<#zbs>>) +|v1.0 +|Ratified +|=== + +<<< +[#insns-binvi,reftext="Single-Bit Invert (Immediate)"] +==== binvi + +Synopsis:: +Single-Bit Invert (Immediate) + +Mnemonic:: +binvi _rd_, _rs1_, _shamt_ + +Encoding (RV32):: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x13, attr: ['OP-IMM'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x1, attr: ['BINV'] }, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'shamt' }, + { bits: 7, name: 0x34, attr: ['BINVI'] }, +]} +.... + +Encoding (RV64):: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x13, attr: ['OP-IMM'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x1, attr: ['BINV'] }, + { bits: 5, name: 'rs1' }, + { bits: 6, name: 'shamt' }, + { bits: 6, name: 0x1a, attr: ['BINVI'] }, +]} +.... + +Description:: +This instruction returns _rs1_ with a single bit inverted at the index specified in _shamt_. +The index is read from the lower log2(XLEN) bits of _shamt_. +For RV32, the encodings corresponding to shamt[5]=1 are reserved. + +Operation:: +[source,sail] +-- +let index = shamt & (XLEN - 1); +X(rd) = X(rs1) ^ (1 << index) +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbs (<<#zbs>>) +|v1.0 +|Ratified +|=== + +<<< +[#insns-bset,reftext="Single-Bit Set (Register)"] +==== bset + +Synopsis:: +Single-Bit Set (Register) + +Mnemonic:: +bset _rd_, _rs1_,_rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x33, attr: ['OP'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x1, attr: ['BSET'] }, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'rs2' }, + { bits: 7, name: 0x14, attr: ['BSET'] }, +]} +.... + +Description:: +This instruction returns _rs1_ with a single bit set at the index specified in _rs2_. +The index is read from the lower log2(XLEN) bits of _rs2_. + +Operation:: +[source,sail] +-- +let index = X(rs2) & (XLEN - 1); +X(rd) = X(rs1) | (1 << index) +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbs (<<#zbs>>) +|v1.0 +|Ratified +|=== + +<<< +[#insns-bseti,reftext="Single-Bit Set (Immediate)"] +==== bseti + +Synopsis:: +Single-Bit Set (Immediate) + +Mnemonic:: +bseti _rd_, _rs1_,_shamt_ + +Encoding (RV32):: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x13, attr: ['OP-IMM'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x1, attr: ['BSETI'] }, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'shamt' }, + { bits: 7, name: 0x14, attr: ['BSETI'] }, +]} +.... + +Encoding (RV64):: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x13, attr: ['OP-IMM'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x1, attr: ['BSETI'] }, + { bits: 5, name: 'rs1' }, + { bits: 6, name: 'shamt' }, + { bits: 6, name: 0x0a, attr: ['BSETI'] }, +]} +.... + +Description:: +This instruction returns _rs1_ with a single bit set at the index specified in _shamt_. +The index is read from the lower log2(XLEN) bits of _shamt_. +For RV32, the encodings corresponding to shamt[5]=1 are reserved. + +Operation:: +[source,sail] +-- +let index = shamt & (XLEN - 1); +X(rd) = X(rs1) | (1 << index) +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbs (<<#zbs>>) +|v1.0 +|Ratified +|=== + +<<< +[#insns-clmul,reftext="Carry-less multiply (low-part)"] +==== clmul + +Synopsis:: +Carry-less multiply (low-part) + +Mnemonic:: +clmul _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x33, attr: ['OP'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x1, attr: ['CLMUL'] }, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'rs2' }, + { bits: 7, name: 0x5, attr: ['MINMAX/CLMUL'] }, +]} +.... + +Description:: +clmul produces the lower half of the 2·XLEN carry-less product. + +Operation:: +[source,sail] +-- +let rs1_val = X(rs1); +let rs2_val = X(rs2); +let output : xlenbits = 0; + +foreach (i from 0 to (xlen - 1) by 1) { + output = if ((rs2_val >> i) & 1) + then output ^ (rs1_val << i); + else output; +} + +X[rd] = output +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbc (<<#zbc>>) +|v1.0 +|Ratified + +|Zbkc (<<#zbkc>>) +|v1.0 +|Ratified +|=== + +<<< +[#insns-clmulh,reftext="Carry-less multiply (high-part)"] +==== clmulh + +Synopsis:: +Carry-less multiply (high-part) + +Mnemonic:: +clmulh _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x33, attr: ['OP'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x3, attr: ['CLMULH'] }, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'rs2' }, + { bits: 7, name: 0x5, attr: ['MINMAX/CLMUL'] }, +]} +.... + +Description:: +clmulh produces the upper half of the 2·XLEN carry-less product. + +Operation:: +[source,sail] +-- +let rs1_val = X(rs1); +let rs2_val = X(rs2); +let output : xlenbits = 0; + +foreach (i from 1 to xlen by 1) { + output = if ((rs2_val >> i) & 1) + then output ^ (rs1_val >> (xlen - i)); + else output; +} + +X[rd] = output +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbc (<<#zbc>>) +|v1.0 +|Ratified + +|Zbkc (<<#zbkc>>) +|v1.0 +|Ratified +|=== + + +<<< +[#insns-clmulr,reftext="Carry-less multiply (reversed)"] +==== clmulr + +Synopsis:: +Carry-less multiply (reversed) + +Mnemonic:: +clmulr _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x33, attr: ['OP'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x2, attr: ['CLMULR'] }, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'rs2' }, + { bits: 7, name: 0x5, attr: ['MINMAX/CLMUL'] }, +]} +.... + +Description:: +*clmulr* produces bits 2·XLEN−2:XLEN-1 of the 2·XLEN carry-less +product. + +Operation:: +[source,sail] +-- +let rs1_val = X(rs1); +let rs2_val = X(rs2); +let output : xlenbits = 0; + +foreach (i from 0 to (xlen - 1) by 1) { + output = if ((rs2_val >> i) & 1) + then output ^ (rs1_val >> (xlen - i - 1)); + else output; +} + +X[rd] = output +-- + +.Note +[NOTE, caption="A" ] +=============================================================== +The *clmulr* instruction is used to accelerate CRC calculations. +The *r* in the instruction's mnemonic stands for _reversed_, as the +instruction is equivalent to bit-reversing the inputs, performing +a *clmul*, then bit-reversing the output. +=============================================================== + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbc (<<#zbc>>) +|v1.0 +|Ratified +|=== + +<<< +[#insns-clz,reftext="Count leading zero bits"] +==== clz + +Synopsis:: +Count leading zero bits + +Mnemonic:: +clz _rd_, _rs_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x13, attr: ['OP-IMM'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x1, attr: ['CLZ'] }, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 0x0, attr: ['CLZ'] }, + { bits: 7, name: 0x30, attr: ['CLZ'] }, +]} +.... + +Description:: +This instruction counts the number of 0's before the first 1, starting at the most-significant bit (i.e., XLEN-1) and progressing to bit 0. Accordingly, if the input is 0, the output is XLEN, and if the most-significant bit of the input is a 1, the output is 0. + +Operation:: +[source,sail] +-- +val HighestSetBit : forall ('N : Int), 'N >= 0. bits('N) -> int + +function HighestSetBit x = { + foreach (i from (xlen - 1) to 0 by 1 in dec) + if [x[i]] == 0b1 then return(i) else (); + return -1; +} + +let rs = X(rs); +X[rd] = (xlen - 1) - HighestSetBit(rs); +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbb (<<#zbb>>) +|v1.0 +|Ratified +|=== + +<<< +[#insns-clzw,reftext="Count leading zero bits in word"] +==== clzw + +Synopsis:: +Count leading zero bits in word + +Mnemonic:: +clzw _rd_, _rs_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x1b, attr: ['OP-IMM-32'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x1, attr: ['CLZW'] }, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 0x0, attr: ['CLZW'] }, + { bits: 7, name: 0x30, attr: ['CLZW'] }, +]} +.... + +Description:: +This instruction counts the number of 0's before the first 1 starting at bit 31 and progressing to bit 0. +Accordingly, if the least-significant word is 0, the output is 32, and if the most-significant bit of the word (i.e., bit 31) is a 1, the output is 0. + +Operation:: +[source,sail] +-- +val HighestSetBit32 : forall ('N : Int), 'N >= 0. bits('N) -> int + +function HighestSetBit32 x = { + foreach (i from 31 to 0 by 1 in dec) + if [x[i]] == 0b1 then return(i) else (); + return -1; +} + +let rs = X(rs); +X[rd] = 31 - HighestSetBit(rs); +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbb (<<#zbb>>) +|v1.0 +|Ratified +|=== + +<<< +[#insns-cpop,reftext="Count set bits"] +==== cpop + +Synopsis:: +Count set bits + +Mnemonic:: +cpop _rd_, _rs_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x13, attr: ['OP-IMM'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x1, attr: ['CPOP'] }, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 0x2, attr: ['CPOP'] }, + { bits: 7, name: 0x30, attr: ['CPOP'] }, +]} +.... +Description:: +This instructions counts the number of 1's (i.e., set bits) in the source register. + +Operation:: +[source,sail] +-- +let bitcount = 0; +let rs = X(rs); + +foreach (i from 0 to (xlen - 1) in inc) + if rs[i] == 0b1 then bitcount = bitcount + 1 else (); + +X[rd] = bitcount +-- + +.Software Hint +[NOTE, caption="SH" ] +=============================================================== +This operations is known as population count, popcount, sideways sum, bit summation, or Hamming weight. + +The GCC builtin function `+__builtin_popcount (unsigned int x)+` is implemented by cpop on RV32 and by *cpopw* on RV64. +The GCC builtin function `+__builtin_popcountl (unsigned long x)+` for LP64 is implemented by *cpop* on RV64. +=============================================================== + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbb (<<#zbb>>) +|v1.0 +|Ratified +|=== + +<<< +[#insns-cpopw,reftext="Count set bits in word"] +==== cpopw + +Synopsis:: +Count set bits in word + +Mnemonic:: +cpopw _rd_, _rs_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x1b, attr: ['OP-IMM-32'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x1, attr: ['CPOPW'] }, + { bits: 5, name: 'rs' }, + { bits: 5, name: 0x2, attr: ['CPOPW'] }, + { bits: 7, name: 0x30, attr: ['CPOPW'] }, +]} +.... +Description:: +This instructions counts the number of 1's (i.e., set bits) in the least-significant word of the source register. + +Operation:: +[source,sail] +-- +let bitcount = 0; +let val = X(rs); + +foreach (i from 0 to 31 in inc) + if val[i] == 0b1 then bitcount = bitcount + 1 else (); + +X[rd] = bitcount +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbb (<<#zbb>>) +|v1.0 +|Ratified +|=== + +<<< +[#insns-ctz,reftext="Count trailing zero bits"] +==== ctz + +Synopsis:: +Count trailing zeros + +Mnemonic:: +ctz _rd_, _rs_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x13, attr: ['OP-IMM'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x1, attr: ['CTZ/CTZW'] }, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 0x1, attr: ['CTZ/CTZW'] }, + { bits: 7, name: 0x30, attr: ['CTZ/CTZW'] }, +]} +.... + +Description:: +This instruction counts the number of 0's before the first 1, starting at the least-significant bit (i.e., 0) and progressing to the most-significant bit (i.e., XLEN-1). +Accordingly, if the input is 0, the output is XLEN, and if the least-significant bit of the input is a 1, the output is 0. + +Operation:: +[source,sail] +-- +val LowestSetBit : forall ('N : Int), 'N >= 0. bits('N) -> int + +function LowestSetBit x = { + foreach (i from 0 to (xlen - 1) by 1 in dec) + if [x[i]] == 0b1 then return(i) else (); + return xlen; +} + +let rs = X(rs); +X[rd] = LowestSetBit(rs); +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbb (<<#zbb>>) +|v1.0 +|Ratified +|=== + +<<< +[#insns-ctzw,reftext="Count trailing zero bits in word"] +==== ctzw + +Synopsis:: +Count trailing zero bits in word + +Mnemonic:: +ctzw _rd_, _rs_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x1b, attr: ['OP-IMM-32'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x1, attr: ['CTZ/CTZW'] }, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 0x1, attr: ['CTZ/CTZW'] }, + { bits: 7, name: 0x30, attr: ['CTZ/CTZW'] }, +]} +.... + +Description:: +This instruction counts the number of 0's before the first 1, starting at the least-significant bit (i.e., 0) and progressing to the most-significant bit of the least-significant word (i.e., 31). Accordingly, if the least-significant word is 0, the output is 32, and if the least-significant bit of the input is a 1, the output is 0. + +Operation:: +[source,sail] +-- +val LowestSetBit32 : forall ('N : Int), 'N >= 0. bits('N) -> int + +function LowestSetBit32 x = { + foreach (i from 0 to 31 by 1 in dec) + if [x[i]] == 0b1 then return(i) else (); + return 32; +} + +let rs = X(rs); +X[rd] = LowestSetBit32(rs); +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbb (<<#zbb>>) +|v1.0 +|Ratified +|=== + +<<< +[#insns-max,reftext="Maximum"] +==== max + +Synopsis:: +Maximum + +Mnemonic:: +max _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x33, attr: ['OP'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x6, attr: ['MAX']}, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'rs2' }, + { bits: 7, name: 0x05, attr: ['MINMAX/CLMUL'] }, +]} +.... + +Description:: +This instruction returns the larger of two signed integers. + +Operation:: +[source,sail] +-- +let rs1_val = X(rs1); +let rs2_val = X(rs2); + +let result = if rs1_val <_s rs2_val + then rs2_val + else rs1_val; + +X(rd) = result; +-- + +.Software Hint +[NOTE, caption="SW"] +=============================================================== +Calculating the absolute value of a signed integer can be performed +using the following sequence: *neg rD,rS* followed by *max +rD,rS,rD*. When using this common sequence, it is suggested that they +are scheduled with no intervening instructions so that +implementations that are so optimized can fuse them together. +=============================================================== + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbb (<<#zbb>>) +|v1.0 +|Ratified +|=== + +<<< +[#insns-maxu,reftext="Unsigned maximum"] +==== maxu + +Synopsis:: +Unsigned maximum + +Mnemonic:: +maxu _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x33, attr: ['OP'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x7, attr: ['MAXU']}, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'rs2' }, + { bits: 7, name: 0x05, attr: ['MINMAX/CLMUL'] }, +]} +.... + +Description:: +This instruction returns the larger of two unsigned integers. + +Operation:: +[source,sail] +-- +let rs1_val = X(rs1); +let rs2_val = X(rs2); + +let result = if rs1_val <_u rs2_val + then rs2_val + else rs1_val; + +X(rd) = result; +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbb (<<#zbb>>) +|v1.0 +|Ratified +|=== + +<<< +[#insns-min,reftext="Minimum"] +==== min + +Synopsis:: +Minimum + +Mnemonic:: +min _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x33, attr: ['OP'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x4, attr: ['MIN']}, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'rs2' }, + { bits: 7, name: 0x05, attr: ['MINMAX/CLMUL'] }, +]} +.... + +Description:: +This instruction returns the smaller of two signed integers. + +Operation:: +[source,sail] +-- +let rs1_val = X(rs1); +let rs2_val = X(rs2); + +let result = if rs1_val <_s rs2_val + then rs1_val + else rs2_val; + +X(rd) = result; +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbb (<<#zbb>>) +|v1.0 +|Ratified +|=== + +<<< +[#insns-minu,reftext="Unsigned minimum"] +==== minu + +Synopsis:: +Unsigned minimum + +Mnemonic:: +minu _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x33, attr: ['OP'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x5, attr: ['MINU']}, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'rs2' }, + { bits: 7, name: 0x05, attr: ['MINMAX/CLMUL'] }, +]} +.... + +Description:: +This instruction returns the smaller of two unsigned integers. + +Operation:: +[source,sail] +-- +let rs1_val = X(rs1); +let rs2_val = X(rs2); + +let result = if rs1_val <_u rs2_val + then rs1_val + else rs2_val; + +X(rd) = result; +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbb (<<#zbb>>) +|v1.0 +|Ratified +|=== + +<<< +[#insns-orc_b,reftext="Bitwise OR-Combine, byte granule"] +==== orc.b + +Synopsis:: +Bitwise OR-Combine, byte granule + +Mnemonic:: +orc.b _rd_, _rs_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x13, attr: ['OP-IMM'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x5 }, + { bits: 5, name: 'rs' }, + { bits: 12, name: 0x287 } +]} +.... + +Description:: +Combines the bits within each byte using bitwise logical OR. +This sets the bits of each byte in the result _rd_ to all zeros if no bit within the respective byte of _rs_ is set, or to all ones if any bit within the respective byte of _rs_ is set. + +Operation:: +[source,sail] +-- +let input = X(rs); +let output : xlenbits = 0; + +foreach (i from 0 to (xlen - 8) by 8) { + output[(i + 7)..i] = if input[(i + 7)..i] == 0 + then 0b00000000 + else 0b11111111; +} + +X[rd] = output; +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbb (<<#zbb>>) +|v1.0 +|Ratified +|=== + +<<< +[#insns-orn,reftext="OR with inverted operand"] +==== orn + +Synopsis:: +OR with inverted operand + +Mnemonic:: +orn _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x33, attr: ['OP'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x6, attr: ['ORN']}, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'rs2' }, + { bits: 7, name: 0x20, attr: ['ORN'] }, +]} +.... + +Description:: +This instruction performs the bitwise logical OR operation between _rs1_ and the bitwise inversion of _rs2_. + +Operation:: +[source,sail] +-- +X(rd) = X(rs1) | ~X(rs2); +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbb (<<#zbb>>) +|v1.0 +|Ratified + +|Zbkb (<<#zbkb>>) +|v1.0 +|Ratified +|=== + +<<< +[#insns-pack,reftext="Pack low halves of registers"] +==== pack + +Synopsis:: +Pack the low halves of _rs1_ and _rs2_ into _rd_. + +Mnemonic:: +pack _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + {bits: 7, name: 0x33, attr: ['OP'] }, + {bits: 5, name: 'rd'}, + {bits: 3, name: 0x4, attr:['PACK']}, + {bits: 5, name: 'rs1'}, + {bits: 5, name: 'rs2'}, + {bits: 7, name: 0x4, attr:['PACK']}, +]} +.... + +Description:: +The pack instruction packs the XLEN/2-bit lower halves of _rs1_ and _rs2_ into +_rd_, with _rs1_ in the lower half and _rs2_ in the upper half. + +Operation:: +[source,sail] +-- +let lo_half : bits(xlen/2) = X(rs1)[xlen/2-1..0]; +let hi_half : bits(xlen/2) = X(rs2)[xlen/2-1..0]; +X(rd) = EXTZ(hi_half @ lo_half); +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbkb (<<#zbkb>>) +|v1.0 +|Ratified +|=== + +NOTE: For RV32, the `pack` instruction with _rs2_=`x0` is the `zext.h` +instruction. +Hence, for RV32, any extension that contains the `pack` instruction also +contains the `zext.h` instruction (but not necessarily the `c.zext.h` +instruction, which is only guaranteed to exist if both the Zcb and Zbb +extensions are implemented). + +<<< +[#insns-packh,reftext="Pack low bytes of registers"] +==== packh + +Synopsis:: +Pack the low bytes of _rs1_ and _rs2_ into _rd_. + +Mnemonic:: +packh _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + {bits: 7, name: 0x33, attr: ['OP'] }, + {bits: 5, name: 'rd'}, + {bits: 3, name: 0x7, attr: ['PACKH']}, + {bits: 5, name: 'rs1'}, + {bits: 5, name: 'rs2'}, + {bits: 7, name: 0x4, attr: ['PACKH']}, +]} +.... + +Description:: +The packh instruction packs the least-significant bytes of +_rs1_ and _rs2_ into the 16 least-significant bits of _rd_, +zero extending the rest of _rd_. + +Operation:: +[source,sail] +-- +let lo_half : bits(8) = X(rs1)[7..0]; +let hi_half : bits(8) = X(rs2)[7..0]; +X(rd) = EXTZ(hi_half @ lo_half); +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbkb (<<#zbkb>>) +|v1.0 +|Ratified +|=== + +<<< +[#insns-packw,reftext="Pack low 16-bits of registers (RV64)"] +==== packw + +Synopsis:: +Pack the low 16-bits of _rs1_ and _rs2_ into _rd_ on RV64. + +Mnemonic:: +packw _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 0x3b, attr: ['OP-32']}, +{bits: 5, name: 'rd'}, +{bits: 3, name: 0x4}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 'rs2'}, +{bits: 7, name: 0x4}, +]} +.... + +Description:: +This instruction packs the low 16 bits of +_rs1_ and _rs2_ into the 32 least-significant bits of _rd_, +sign extending the 32-bit result to the rest of _rd_. +This instruction only exists on RV64 based systems. + +Operation:: +[source,sail] +-- +let lo_half : bits(16) = X(rs1)[15..0]; +let hi_half : bits(16) = X(rs2)[15..0]; +X(rd) = EXTS(hi_half @ lo_half); +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbkb (<<#zbkb>>) +|v1.0 +|Ratified +|=== + +NOTE: For RV64, the `packw` instruction with _rs2_=`x0` is the `zext.h` +instruction. +Hence, for RV64, any extension that contains the `packw` instruction also +contains the `zext.h` instruction (but not necessarily the `c.zext.h` +instruction, which is only guaranteed to exist if both the Zcb and Zbb +extensions are implemented). + +<<< +[#insns-rev8,reftext="Byte-reverse register"] +==== rev8 + +Synopsis:: +Byte-reverse register + +Mnemonic:: +rev8 _rd_, _rs_ + +Encoding (RV32):: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x13, attr: ['OP-IMM'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x5 }, + { bits: 5, name: 'rs' }, + { bits: 12, name: 0x698 } +]} +.... + +Encoding (RV64):: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x13, attr: ['OP-IMM'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x5 }, + { bits: 5, name: 'rs' }, + { bits: 12, name: 0x6b8 } +]} +.... + +Description:: +This instruction reverses the order of the bytes in _rs_. + +Operation:: +[source,sail] +-- +let input = X(rs); +let output : xlenbits = 0; +let j = xlen - 1; + +foreach (i from 0 to (xlen - 8) by 8) { + output[i..(i + 7)] = input[(j - 7)..j]; + j = j - 8; +} + +X[rd] = output +-- + +.Note +[NOTE, caption="A" ] +=============================================================== +The *rev8* mnemonic corresponds to different instruction encodings in RV32 and RV64. +=============================================================== + +.Software Hint +[NOTE, caption="SH" ] +=============================================================== +The byte-reverse operation is only available for the full register +width. To emulate word-sized and halfword-sized byte-reversal, +perform a `rev8 rd,rs` followed by a `srai rd,rd,K`, where K is +XLEN-32 and XLEN-16, respectively. +=============================================================== + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbb (<<#zbb>>) +|v1.0 +|Ratified + +|Zbkb (<<#zbkb>>) +|v1.0 +|Ratified +|=== + +<<< +[#insns-brev8,reftext="Reverse bits in bytes"] +==== brev8 + +Synopsis:: +Reverse the bits in each byte of a source register. + +Mnemonic:: +brev8 _rd_, _rs_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x13, attr: ['OP-IMM'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x5 }, + { bits: 5, name: 'rs' }, + { bits: 12, name: 0x687 } +]} +.... + +Description:: +This instruction reverses the order of the bits in every byte of a register. + +Operation:: +[source,sail] +-- +result : xlenbits = EXTZ(0b0); +foreach (i from 0 to sizeof(xlen) by 8) { + result[i+7..i] = reverse_bits_in_byte(X(rs1)[i+7..i]); +}; +X(rd) = result; +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbkb (<<#zbkb>>) +|v1.0 +|Ratified +|=== + +<<< +[#insns-rol,reftext="Rotate left (Register)"] +==== rol + +Synopsis:: +Rotate Left (Register) + +Mnemonic:: +rol _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x33, attr: ['OP'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x1, attr: ['ROL']}, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'rs2' }, + { bits: 7, name: 0x30, attr: ['ROL'] }, +]} +.... + +Description:: +This instruction performs a rotate left of _rs1_ by the amount in least-significant log2(XLEN) bits of _rs2_. + +Operation:: +[source,sail] +-- +let shamt = if xlen == 32 + then X(rs2)[4..0] + else X(rs2)[5..0]; +let result = (X(rs1) << shamt) | (X(rs1) >> (xlen - shamt)); + +X(rd) = result; +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbb (<<#zbb>>) +|0.93 +|Ratified + +|Zbkb (<<#zbkb>>) +|v1.0 +|Ratified +|=== + +<<< +[#insns-rolw,reftext="Rotate Left Word (Register)"] +==== rolw + +Synopsis:: +Rotate Left Word (Register) + +Mnemonic:: +rolw _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x3b, attr: ['OP-32'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x1, attr: ['ROLW']}, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'rs2' }, + { bits: 7, name: 0x30, attr: ['ROLW'] }, +]} +.... + +Description:: +This instruction performs a rotate left on the least-significant word of _rs1_ by the amount in least-significant 5 bits of _rs2_. +The resulting word value is sign-extended by copying bit 31 to all of the more-significant bits. + +Operation:: +[source,sail] +-- +let rs1 = EXTZ(X(rs1)[31..0]) +let shamt = X(rs2)[4..0]; +let result = (rs1 << shamt) | (rs1 >> (32 - shamt)); +X(rd) = EXTS(result[31..0]); +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbb (<<#zbb>>) +|0.93 +|Ratified + +|Zbkb (<<#zbkb>>) +|v1.0 +|Ratified +|=== + +<<< +[#insns-ror,reftext="Rotate right (Register)"] +==== ror + +Synopsis:: +Rotate Right + +Mnemonic:: +ror _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x33, attr: ['OP'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x5, attr: ['ROR']}, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'rs2' }, + { bits: 7, name: 0x30, attr: ['ROR'] }, +]} +.... + +Description:: +This instruction performs a rotate right of _rs1_ by the amount in least-significant log2(XLEN) bits of _rs2_. + +Operation:: +[source,sail] +-- +let shamt = if xlen == 32 + then X(rs2)[4..0] + else X(rs2)[5..0]; +let result = (X(rs1) >> shamt) | (X(rs1) << (xlen - shamt)); + +X(rd) = result; +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbb (<<#zbb>>) +|0.93 +|Ratified + +|Zbkb (<<#zbkb>>) +|v1.0 +|Ratified +|=== + +<<< +[#insns-rori,reftext="Rotate right (Immediate)"] +==== rori + +Synopsis:: +Rotate Right (Immediate) + +Mnemonic:: +rori _rd_, _rs1_, _shamt_ + +Encoding (RV32):: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x13, attr: ['OP-IMM'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x5, attr: ['RORI']}, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'shamt' }, + { bits: 7, name: 0x30, attr: ['RORI'] }, +]} +.... + +Encoding (RV64):: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x13, attr: ['OP-IMM'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x5, attr: ['RORI']}, + { bits: 5, name: 'rs1' }, + { bits: 6, name: 'shamt' }, + { bits: 6, name: 0x18, attr: ['RORI'] }, +]} +.... + +Description:: +This instruction performs a rotate right of _rs1_ by the amount in the least-significant log2(XLEN) bits of _shamt_. +For RV32, the encodings corresponding to shamt[5]=1 are reserved. + +Operation:: +[source,sail] +-- +let shamt = if xlen == 32 + then shamt[4..0] + else shamt[5..0]; +let result = (X(rs1) >> shamt) | (X(rs1) << (xlen - shamt)); + +X(rd) = result; +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbb (<<#zbb>>) +|0.93 +|Ratified + +|Zbkb (<<#zbkb>>) +|v1.0 +|Ratified +|=== + +<<< +[#insns-roriw,reftext="Rotate right Word (Immediate)"] +==== roriw + +Synopsis:: +Rotate Right Word by Immediate + +Mnemonic:: +roriw _rd_, _rs1_, _shamt_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x1b, attr: ['OP-IMM-32'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x5, attr: ['RORIW']}, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'shamt' }, + { bits: 7, name: 0x30, attr: ['RORIW'] }, +]} +.... + +Description:: +This instruction performs a rotate right on the least-significant word +of _rs1_ by the amount in the least-significant log2(XLEN) bits of +_shamt_. +The resulting word value is sign-extended by copying bit 31 to all of +the more-significant bits. + + +Operation:: +[source,sail] +-- +let rs1_data = EXTZ(X(rs1)[31..0]; +let result = (rs1_data >> shamt) | (rs1_data << (32 - shamt)); +X(rd) = EXTS(result[31..0]); +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbb (<<#zbb>>) +|0.93 +|Ratified + +|Zbkb (<<#zbkb>>) +|v1.0 +|Ratified +|=== + +<<< +[#insns-rorw,reftext="Rotate right Word (Register)"] +==== rorw + +Synopsis:: +Rotate Right Word (Register) + +Mnemonic:: +rorw _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x3b, attr: ['OP-32'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x5, attr: ['RORW']}, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'rs2' }, + { bits: 7, name: 0x30, attr: ['RORW'] }, +]} +.... + +Description:: +This instruction performs a rotate right on the least-significant word of _rs1_ by the amount in least-significant 5 bits of _rs2_. +The resultant word is sign-extended by copying bit 31 to all of the more-significant bits. + +Operation:: +[source,sail] +-- +let rs1 = EXTZ(X(rs1)[31..0]) +let shamt = X(rs2)[4..0]; +let result = (rs1 >> shamt) | (rs1 << (32 - shamt)); +X(rd) = EXTS(result); +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbb (<<#zbb>>) +|0.93 +|Ratified + +|Zbkb (<<#zbkb>>) +|v1.0 +|Ratified +|=== + +<<< +[#insns-sext_b,reftext="Sign-extend byte"] +==== sext.b + +Synopsis:: +Sign-extend byte + +Mnemonic:: +sext.b _rd_, _rs_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x13, attr: ['OP-IMM'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x1, attr: ['SEXT.B/SEXT.H'] }, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 0x04, attr: ['SEXT.B'] }, + { bits: 7, name: 0x30 }, +]} +.... + +Description:: +This instruction sign-extends the least-significant byte in the source to XLEN by copying the most-significant bit in the byte (i.e., bit 7) to all of the more-significant bits. + +Operation:: +[source,sail] +-- +X(rd) = EXTS(X(rs)[7..0]); +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbb (<<#zbb>>) +|0.93 +|Ratified +|=== + +<<< +[#insns-sext_h,reftext="Sign-extend halfword"] +==== sext.h + +Synopsis:: +Sign-extend halfword + +Mnemonic:: +sext.h _rd_, _rs_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x13, attr: ['OP-IMM'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x1, attr: ['SEXT.B/SEXT.H'] }, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 0x05, attr: ['SEXT.H'] }, + { bits: 7, name: 0x30 }, +]} +.... + +Description:: +This instruction sign-extends the least-significant halfword in _rs_ to XLEN by copying the most-significant bit in the halfword (i.e., bit 15) to all of the more-significant bits. + +Operation:: +[source,sail] +-- +X(rd) = EXTS(X(rs)[15..0]); +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbb (<<#zbb>>) +|0.93 +|Ratified +|=== + + +<<< +[#insns-sh1add,reftext=Shift left by 1 and add] +==== sh1add + +Synopsis:: +Shift left by 1 and add + +Mnemonic:: +sh1add _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x33, attr: ['OP'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x2, attr: ['SH1ADD'] }, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'rs2' }, + { bits: 7, name: 0x10, attr: ['SH1ADD'] }, +]} +.... + +Description:: +This instruction shifts _rs1_ to the left by 1 bit and adds it to _rs2_. + +Operation:: +[source,sail] +-- +X(rd) = X(rs2) + (X(rs1) << 1); +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zba (<<#zba>>) +|0.93 +|Ratified +|=== + +// We have decided that this and all other instructions will not have reserved encodings for "useless encodings" +// We could follow suit of the base ISA and create HINTs if there is some recognized value for doing so + +<<< +[#insns-sh1add_uw,reftext=Shift unsigned word left by 1 and add] +==== sh1add.uw + +Synopsis:: +Shift unsigned word left by 1 and add + +Mnemonic:: +sh1add.uw _rd_, _rs1_, _rs2_ +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x3b, attr: ['OP-32'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x2, attr: ['SH1ADD.UW'] }, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'rs2' }, + { bits: 7, name: 0x10, attr: ['SH1ADD.UW'] }, +]} +.... + +Description:: +This instruction performs an XLEN-wide addition of two addends. +The first addend is _rs2_. The second addend is the unsigned value formed by extracting the least-significant word of _rs1_ and shifting it left by 1 place. + +Operation:: +[source,sail] +-- +let base = X(rs2); +let index = EXTZ(X(rs1)[31..0]); + +X(rd) = base + (index << 1); +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zba (<<#zba>>) +|0.93 +|Ratified +|=== + +<<< +[#insns-sh2add,reftext=Shift left by 2 and add] +==== sh2add + +Synopsis:: +Shift left by 2 and add + +Mnemonic:: +sh2add _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x33, attr: ['OP'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x4, attr: ['SH2ADD'] }, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'rs2' }, + { bits: 7, name: 0x10, attr: ['SH2ADD'] }, +]} +.... + +Description:: +This instruction shifts _rs1_ to the left by 2 places and adds it to _rs2_. + +Operation:: +[source,sail] +-- +X(rd) = X(rs2) + (X(rs1) << 2); +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zba (<<#zba>>) +|0.93 +|Ratified +|=== + +<<< +[#insns-sh2add_uw,reftext=Shift unsigned word left by 2 and add] +==== sh2add.uw + +Synopsis:: +Shift unsigned word left by 2 and add + +Mnemonic:: +sh2add.uw _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x3b, attr: ['OP-32'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x4, attr: ['SH2ADD.UW'] }, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'rs2' }, + { bits: 7, name: 0x10, attr: ['SH2ADD.UW'] }, +]} +.... + +Description:: +This instruction performs an XLEN-wide addition of two addends. +The first addend is _rs2_. +The second addend is the unsigned value formed by extracting the least-significant word of _rs1_ and shifting it left by 2 places. + +Operation:: +[source,sail] +-- +let base = X(rs2); +let index = EXTZ(X(rs1)[31..0]); + +X(rd) = base + (index << 2); +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zba (<<#zba>>) +|0.93 +|Ratified +|=== + +<<< +[#insns-sh3add,reftext=Shift left by 3 and add] +==== sh3add + +Synopsis:: +Shift left by 3 and add + +Mnemonic:: +sh3add _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x33, attr: ['OP'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x6, attr: ['SH3ADD'] }, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'rs2' }, + { bits: 7, name: 0x10, attr: ['SH3ADD'] }, +]} +.... + +Description:: +This instruction shifts _rs1_ to the left by 3 places and adds it to _rs2_. + +Operation:: +[source,sail] +-- +X(rd) = X(rs2) + (X(rs1) << 3); +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zba (<<#zba>>) +|0.93 +|Ratified +|=== + +<<< +[#insns-sh3add_uw,reftext=Shift unsigned word left by 3 and add] +==== sh3add.uw + +Synopsis:: +Shift unsigned word left by 3 and add + +Mnemonic:: +sh3add.uw _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x3b, attr: ['OP-32'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x6, attr: ['SH3ADD.UW'] }, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'rs2' }, + { bits: 7, name: 0x10, attr: ['SH3ADD.UW'] }, +]} +.... + +Description:: +This instruction performs an XLEN-wide addition of two addends. The first addend is _rs2_. The second addend is the unsigned value formed by extracting the least-significant word of _rs1_ and shifting it left by 3 places. + +Operation:: +[source,sail] +-- +let base = X(rs2); +let index = EXTZ(X(rs1)[31..0]); + +X(rd) = base + (index << 3); +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zba (<<#zba>>) +|0.93 +|Ratified +|=== + +<<< +[#insns-slli_uw,reftext="Shift-left unsigned word (Immediate)"] +==== slli.uw + +Synopsis:: +Shift-left unsigned word (Immediate) + +Mnemonic:: +slli.uw _rd_, _rs1_, _shamt_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x1b, attr: ['OP-IMM-32'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x1, attr: ['SLLI.UW'] }, + { bits: 5, name: 'rs1' }, + { bits: 6, name: 'shamt' }, + { bits: 6, name: 0x02, attr: ['SLLI.UW'] }, +]} +.... + +Description:: +This instruction takes the least-significant word of _rs1_, zero-extends it, and shifts it left by the immediate. + +Operation:: +[source,sail] +-- +X(rd) = (EXTZ(X(rs)[31..0]) << shamt); +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zba (<<#zba>>) +|0.93 +|Ratified +|=== + +.Architecture Explanation +[NOTE, caption="A" ] +=============================================================== +This instruction is the same as *slli* with *zext.w* performed on _rs1_ before shifting. +=============================================================== + +<<< +[#insns-unzip,reftext="Bit deinterleave"] +==== unzip + +Synopsis:: +Place odd and even bits of the source register into upper and lower halves of +the destination register, respectively. + +Mnemonic:: +unzip _rd_, _rs_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 0x13, attr: ['OP-IMM']}, +{bits: 5, name: 'rd'}, +{bits: 3, name: 0x5}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 0xf}, +{bits: 7, name: 0x4}, +]} +.... + +Description:: +This instruction scatters all of the odd and even bits of a source word into +the high and low halves of a destination word. +It is the inverse of the <> instruction. +This instruction is available only on RV32. + +Operation:: +[source,sail] +-- +foreach (i from 0 to xlen/2-1) { + X(rd)[i] = X(rs1)[2*i] + X(rd)[i+xlen/2] = X(rs1)[2*i+1] +} +-- + +.Software Hint +[NOTE, caption="SH" ] +=============================================================== +This instruction is useful for implementing the SHA3 cryptographic +hash function on a 32-bit architecture, as it implements the +bit-interleaving operation used to speed up the 64-bit rotations +directly. +=============================================================== + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbkb (<<#zbkb>>) (RV32) +|v1.0 +|Ratified +|=== + +<<< +[#insns-xnor,reftext="Exclusive NOR"] +==== xnor + +Synopsis:: +Exclusive NOR + +Mnemonic:: +xnor _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x33, attr: ['OP'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x4, attr: ['XNOR']}, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'rs2' }, + { bits: 7, name: 0x20, attr: ['XNOR'] }, +]} +.... + +Description:: +This instruction performs the bit-wise exclusive-NOR operation on _rs1_ and _rs2_. + +Operation:: +[source,sail] +-- +X(rd) = ~(X(rs1) ^ X(rs2)); +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbb (<<#zbb>>) +|0.93 +|Ratified + +|Zbkb (<<#zbkb>>) +|v1.0 +|Ratified +|=== + +<<< +[#insns-xperm8,reftext="Crossbar permutation (bytes)"] +==== xperm8 + +Synopsis:: +Byte-wise lookup of indices into a vector in registers. + +Mnemonic:: +xperm8 _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 0x33, attr: ['OP'] }, +{bits: 5, name: 'rd'}, +{bits: 3, name: 0x4}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 'rs2'}, +{bits: 7, name: 0x14}, +]} +.... + +Description:: +The xperm8 instruction operates on bytes. +The _rs1_ register contains a vector of XLEN/8 8-bit elements. +The _rs2_ register contains a vector of XLEN/8 8-bit indexes. +The result is each element in _rs2_ replaced by the indexed element in _rs1_, +or zero if the index into _rs2_ is out of bounds. + +Operation:: +[source,sail] +-- +val xperm8_lookup : (bits(8), xlenbits) -> bits(8) +function xperm8_lookup (idx, lut) = { + (lut >> (idx @ 0b000))[7..0] +} + +function clause execute ( XPERM8 (rs2,rs1,rd)) = { + result : xlenbits = EXTZ(0b0); + foreach(i from 0 to xlen by 8) { + result[i+7..i] = xperm8_lookup(X(rs2)[i+7..i], X(rs1)); + }; + X(rd) = result; + RETIRE_SUCCESS +} +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbkx (<<#zbkx>>) +|v1.0 +|Ratified +|=== + +<<< +[#insns-xperm4,reftext="Crossbar permutation (nibbles)"] +==== xperm4 + +Synopsis:: +Nibble-wise lookup of indices into a vector. + +Mnemonic:: +xperm4 _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 0x33, attr: ['OP'] }, +{bits: 5, name: 'rd'}, +{bits: 3, name: 0x2}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 'rs2'}, +{bits: 7, name: 0x14}, +]} +.... + +Description:: +The xperm4 instruction operates on nibbles. +The _rs1_ register contains a vector of XLEN/4 4-bit elements. +The _rs2_ register contains a vector of XLEN/4 4-bit indexes. +The result is each element in _rs2_ replaced by the indexed element in _rs1_, +or zero if the index into _rs2_ is out of bounds. + +Operation:: +[source,sail] +-- +val xperm4_lookup : (bits(4), xlenbits) -> bits(4) +function xperm4_lookup (idx, lut) = { + (lut >> (idx @ 0b00))[3..0] +} + +function clause execute ( XPERM4 (rs2,rs1,rd)) = { + result : xlenbits = EXTZ(0b0); + foreach(i from 0 to xlen by 4) { + result[i+3..i] = xperm4_lookup(X(rs2)[i+3..i], X(rs1)); + }; + X(rd) = result; + RETIRE_SUCCESS +} +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbkx (<<#zbkx>>) +|v1.0 +|Ratified +|=== + +<<< +[#insns-zext_h,reftext="Zero-extend halfword"] +==== zext.h + +Synopsis:: +Zero-extend halfword + +Mnemonic:: +zext.h _rd_, _rs_ + +Encoding (RV32):: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x33, attr: ['OP'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x4, attr: ['ZEXT.H']}, + { bits: 5, name: 'rs' }, + { bits: 5, name: 0x00 }, + { bits: 7, name: 0x04 }, +]} +.... + +Encoding (RV64):: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x3b, attr: ['OP-32'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x4, attr: ['ZEXT.H']}, + { bits: 5, name: 'rs' }, + { bits: 5, name: 0x00 }, + { bits: 7, name: 0x04 }, +]} +.... + +Description:: +This instruction zero-extends the least-significant halfword of the source to XLEN by inserting 0's into all of the bits more significant than 15. + +Operation:: +[source,sail] +-- +X(rd) = EXTZ(X(rs)[15..0]); +-- + +.Note +[NOTE, caption="A" ] +=============================================================== +The *zext.h* mnemonic corresponds to different instruction encodings in RV32 and RV64. +=============================================================== + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbb (<<#zbb>>) +|0.93 +|Ratified +|=== + +<<< +[#insns-zip,reftext="Bit interleave"] +==== zip + +Synopsis:: +Interleave upper and lower halves of the source register into odd and even +bits of the destination register, respectively. + +Mnemonic:: +zip _rd_, _rs_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 0x13, attr: ['OP-IMM']}, +{bits: 5, name: 'rd'}, +{bits: 3, name: 0x1}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 0xf}, +{bits: 7, name: 0x4}, +]} +.... + +Description:: +This instruction gathers bits from the high and low halves of the source +word into odd/even bit positions in the destination word. +It is the inverse of the <> instruction. +This instruction is available only on RV32. + +Operation:: +[source,sail] +-- +foreach (i from 0 to xlen/2-1) { + X(rd)[2*i] = X(rs1)[i] + X(rd)[2*i+1] = X(rs1)[i+xlen/2] +} +-- + +.Software Hint +[NOTE, caption="SH" ] +=============================================================== +This instruction is useful for implementing the SHA3 cryptographic +hash function on a 32-bit architecture, as it implements the +bit-interleaving operation used to speed up the 64-bit rotations +directly. +=============================================================== + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbkb (<<#zbkb>>) (RV32) +|v1.0 +|Ratified +|=== diff --git a/param_extraction/chunks/chunk_002.txt.license b/param_extraction/chunks/chunk_002.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_002.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_003.txt b/param_extraction/chunks/chunk_003.txt new file mode 100644 index 0000000000..14137fbcd2 --- /dev/null +++ b/param_extraction/chunks/chunk_003.txt @@ -0,0 +1,807 @@ +# Chunk: chunk_003 +# Source: bfloat16.adoc +# Lines: 1-790 (of 790) +# Content starts: line 1 +# Line count: 790 +# Sections: 10 +# == "BF16" Extensions for BFloat16-precision Floating-Point, Version 1.0 +# === Introduction +# === Intended Audience +# === Number Format +# ==== BF16 Operand Format +# ==== BF16 Behavior +# ===== Subnormal Numbers: +# ===== Infinities: +# ===== NaNs +# ===== Scalar NaN Boxing +# +[[bf16]] +== "BF16" Extensions for BFloat16-precision Floating-Point, Version 1.0 + +[[BF16_introduction]] +=== Introduction + +When FP16 (officially called binary16) was first introduced by the IEEE-754 standard, +it was just an interchange format. It was intended as a space/bandwidth efficient +encoding that would be used to transfer information. This is in line with the Zfhmin +extension. + +However, there were some applications (notably graphics) that found that the smaller +precision and dynamic range was sufficient for their space. So, FP16 started to see +some widespread adoption as an arithmetic format. This is in line with +the Zfh extension. + +While it was not the intention of '754 to have FP16 be an arithmetic format, it is +supported by the standard. Even though the '754 committee recognized that FP16 was +gaining popularity, the committee decided to hold off on making it a basic format +in the 2019 release. This means that a '754 compliant implementation of binary +floating point, which needs to support at least one basic format, cannot support +only FP16 - it needs to support at least one of binary32, binary64, and binary128. + +Experts working in machine learning noticed that FP16 was a much more compact way of +storing operands and often provided sufficient precision for them. However, they also +found that intermediate values were much better when accumulated into a higher precision. +The final computations were then typically converted back into the more compact FP16 +encoding. This approach has become very common in machine learning +(ML) inference where the weights and +activations are stored in FP16 encodings. There was the added benefit that smaller +multiplication blocks could be created for the FP16's smaller number of significant bits. At this +point, widening multiply-accumulate instructions became much more common. Also, more +complicated dot product instructions started to show up including those that packed two +FP16 numbers in a 32-bit register, multiplied these by another pair of FP16 numbers in +another register, added these two products to an FP32 accumulate value in a 3rd register +and returned an FP32 result. + +Experts working in machine learning at Google who continued to work with FP32 values +noted that the least significant 16 bits of their mantissas were not always needed +for good results, even in training. They proposed a truncated version of FP32, which was +the 16 most significant bits of the FP32 encoding. This format was named BFloat16 +(or BF16). The B in BF16, stands for Brain since it was initially introduced +by the Google Brain team. Not only did they find that the number of +significant bits in BF16 tended to be sufficient for their work (despite being fewer than +in FP16), but it was very easy for them to reuse their existing data; FP32 numbers could +be readily rounded to BF16 with a minimal amount of work. Furthermore, the even smaller +number of the BF16 significant bits enabled even smaller +multiplication blocks to be built. Similar +to FP16, BF16 multiply-accumulate widening and dot-product instructions started to +proliferate. + +// include::riscv-bfloat16-audience.adoc[] +[[BF16_audience]] +=== Intended Audience +Floating-point arithmetic is a specialized subject, requiring people with many different +backgrounds to cooperate in its correct and efficient implementation. +Where possible, we have written this specification to be understandable by +all, though we recognize that the motivations and references to +algorithms or other specifications and standards may be unfamiliar to those +who are not domain experts. + +This specification anticipates being read and acted on by various people +with different backgrounds. +We have tried to capture these backgrounds +here, with a brief explanation of what we expect them to know, and how +it relates to the specification. +We hope this aids people's understanding of which aspects of the specification +are particularly relevant to them, and which they may (safely!) ignore or +pass to a colleague. + +Software developers:: +These are the people we expect to write code using the instructions +in this specification. +They should understand the motivations for the +instructions we include, and be familiar with most of the algorithms +and outside standards to which we refer. + +Computer architects:: +We expect architects to have some basic floating-point background. +Furthermore, we expect architects to be able to examine our instructions +for implementation issues, understand how the instructions will be used +in context, and advise on how they best to fit the functionality. + +Digital design engineers & micro-architects:: +These are the people who will implement the specification inside a +core. Floating-point expertise is assumed as not all of the corner +cases are pointed out in the specification. + +Verification engineers:: +Responsible for ensuring the correct implementation of the extension +in hardware. These people are expected to have some floating-point +expertise so that they can identify and generate the interesting corner +cases --- include exceptions --- that are common in floating-point +architectures and implementations. + + +These are by no means the only people concerned with the specification, +but they are the ones we considered most while writing it. + +[[BF16_format]] +=== Number Format + +==== BF16 Operand Format + +BF16 bits:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'frac'}, +{bits: 8, name: 'expo'}, +{bits: 1, name: 'S'}, +]} +.... + +IEEE Compliance: While BF16 (also known as BFloat16) is not an IEEE-754 _standard_ format, it is a valid +floating-point format as defined by IEEE-754. +There are three parameters that specify a format: radix (b), number of digits in the significand (p), +and maximum exponent (emax). +For BF16 these values are: + +[%autowidth] +.BF16 parameters +[cols = "2,1"] +|=== +| Parameter | Value +|radix (b)|2 +|significand (p)|8 +|emax|127 +|=== + + +[%autowidth] +.Obligatory Floating Point Format Table +[cols = "1,1,1,1,1,1,1,1"] +|=== +|Format|Sign Bits|Expo Bits|fraction bits|padded 0s|encoding bits|expo max/bias|expo min + +|FP16 |1| 5|10| 0|16| 15| -14 +|BF16|1| 8| 7| 0|16| 127|-126 +|TF32 |1| 8|10|13|32| 127|-126 +|FP32 |1| 8|23| 0|32| 127|-126 +|FP64 |1|11|52| 0|64|1023|-1022 +|FP128 |1|15|112|0|128|16,383|-16,382 +|=== + +==== BF16 Behavior + +For these BF16 extensions, instruction behavior on BF16 operands is the same as for other floating-point +instructions in the RISC-V ISA. For easy reference, some of this behavior is repeated here. + +===== Subnormal Numbers: +Floating-point values that are too small to be represented as normal numbers, but can still be expressed +by the format's smallest exponent value with a "0" integer bit and at least one "1" bit +in the trailing fractional bits are called subnormal numbers. Basically, the idea is there is +a trade off of precision to support _gradual underflow_. + +[[norm:bf16_subnorm]] +All of the BF16 instructions in the extensions defined in this specification (i.e., Zfbfmin, Zvfbfmin, +and Zvfbfwma) fully support subnormal numbers. That is, instructions are able to accept subnormal values as +inputs and they can produce subnormal results. + + +[NOTE] +==== +Future floating-point extensions, including those that operate on BF16 values, may chose not to support subnormal numbers. +The comments about supporting subnormal BF16 values are limited to those instructions defined in this specification. +==== + +===== Infinities: +Infinities are used to represent values that are too large to be represented by the target format. +These are usually produced as a result of overflows (depending on the rounding mode), but can also +be provided as inputs. Infinities have a sign associated with them: there are positive infinities and negative infinities. + +Infinities are important for keeping meaningless results from being operated upon. + +===== NaNs + +NaN stands for Not a Number. + +There are two types of NaNs: signalling (sNaN) and quiet (qNaN). No computational +instruction will ever produce an sNaN; These are only provided as input data. Operating on an sNaN will cause +an invalid operation exception. Operating on a Quiet NaN usually does not cause an exception. + +QNaNs are provided as the result of an operation when it cannot be represented +as a number or infinity. For example, performing the square root of -1 will result in a qNaN because +there is no real number that can represent the result. NaNs can also be used as inputs. + +NaNs include a sign bit, but the bit has no meaning. + +NaNs are important for keeping meaningless results from being operated upon. + +Except where otherwise explicitly stated, when the result of a floating-point operation is a qNaN, it +is the RISC-V canonical NaN. For BF16, the RISC-V canonical NaN corresponds to the pattern of _0x7fc0_ which +is the most significant 16 bits of the RISC-V single-precision canonical NaN. + +===== Scalar NaN Boxing + +RISC-V applies NaN boxing to scalar results and checks for NaN boxing when a floating-point operation +--- even a vector-scalar operation --- consumes a value from a scalar floating-point register. +If the value is properly NaN-boxed, its least significant bits are used as the operand, otherwise +it is treated as if it were the canonical QNaN. + +NaN boxing is nothing more than putting the smaller encoding in the least significant bits of a register +and setting all of the more significant bits to “1”. This matches the encoding of a qNaN (although +not the canonical NaN) in the larger precision. + +Nan-boxing never affects the value of the operand itself, it just changes the bits of the register that +are more significant than the operand's most significant bit. + + +===== Rounding Modes: + +As is the case with other floating-point instructions, +the BF16 instructions support all 5 RISC-V Floating-point rounding modes. +These modes can be specified in the `rm` field of scalar instructions +as well as in the `frm` CSR + +[%autowidth] +.RISC-V Floating Point Rounding Modes +[cols = "1,1,1"] +|=== +|Rounding Mode | Mnemonic | Meaning +| 000 | RNE | Round to Nearest, ties to Even +| 001 | RTZ | Round towards Zero +| 010 | RDN | Round Down (towards −{inf}) +| 011 | RUP | Round Up (towards +{inf}) +|100 | RMM | Round to Nearest, ties to Max Magnitude +|=== + +As with other scalar floating-point instructions, the rounding mode field +`rm` can also take on the +`DYN` encoding, which indicates that the instruction uses the rounding +mode specified in the `frm` CSR. + +[%autowidth] +.Additional encoding for the `rm` field of scalar instructions +[cols = "1,1,1"] +|=== +|Rounding Mode | Mnemonic | Meaning +|111 | DYN | select dynamic rounding mode +|=== + +In practice, the default IEEE rounding mode (round to nearest, ties to even) is generally used for arithmetic. + +===== Handling exceptions +RISC-V supports IEEE-defined default exception handling. BF16 is no exception. + +Default exception handling, as defined by IEEE, is a simple and effective approach to producing results +in exceptional cases. For the coder to be able to see what has happened, and take further action if needed, +BF16 instructions set floating-point exception flags the same way as all other floating-point instructions +in RISC-V. + +====== Underflow + +The IEEE-defined underflow exception requires that a result be inexact and tiny, where tininess can be +detected before or after rounding. In RISC-V, tininess is detected after rounding. + +It is important to note that the detection of tininess after rounding requires its own rounding +that is different from the final result rounding. This tininess detection requires rounding as if the +exponent were unbounded. +This means that the input to the rounder is always a normal number. +This is different from the final result rounding where the input to the rounder is a subnormal number when +the value is too small to be represented as a normal number in the target format. +The two different roundings can result in underflow being signalled for results that are rounded +back to the normal range. + +As is defined in '754, under default exception handling, underflow is only signalled when the result is tiny +and inexact. In such a case, both the underflow and inexact flags are raised. + +<<< + +[[BF16_extensions]] +=== Extensions + +The group of extensions introduced by the BF16 Instruction Set +Extensions is listed here. + +Detection of individual BF16 extensions uses the +unified software-based RISC-V discovery method. + +[NOTE] +==== +At the time of writing, these discovery mechanisms are still a work in +progress. +==== + +The BF16 extensions defined in this specification (i.e., `Zfbfmin`, +`Zvfbfmin`, and `Zvfbfwma`) depend on the single-precision floating-point extension +`F`. Furthermore, the vector BF16 extensions (i.e.,`Zvfbfmin`, and +`Zvfbfwma`) depend on the `"V"` Vector Extension for Application +Processors or the `Zve32f` Vector Extension for Embedded Processors. + +As stated later in this specification, +there exists a dependency between the newly defined extensions: +`Zvfbfwma` depends on `Zfbfmin` +and `Zvfbfmin`. + +This initial set of BF16 extensions provides very basic functionality +including scalar and vector conversion between BF16 and +single-precision values, and vector widening multiply-accumulate +instructions. + + +// include::riscv-bfloat16-zfbfmin.adoc[] +[[zfbfmin, Zfbfmin]] +==== `Zfbfmin` - Scalar BF16 Converts + +This extension provides the minimal set of instructions needed to enable scalar support +of the BF16 format. It enables BF16 as an interchange format as it provides conversion +between BF16 values and FP32 values. + +This extension depends upon the single-precision floating-point extension +`F`. + +This extension includes six instructions: the `FCVT.BF16.S` and `FCVT.S.BF16` +instructions, defined below, and the `FLH`, `FSH`, `FMV.X.H`, and `FMV.H.X` +instructions, defined in <>. + +[NOTE] +==== +While conversion instructions tend to include all supported formats, in these extensions we +only support conversion between BF16 and FP32 as we are targeting a special use case. +These extensions are intended to support the case where BF16 values are used as reduced +precision versions of FP32 values, where use of BF16 provides a two-fold advantage for +storage, bandwidth, and computation. In this use case, the BF16 values are typically +multiplied by each other and accumulated into FP32 sums. +These sums are typically converted to BF16 +and then used as subsequent inputs. The operations on the BF16 values can be performed +on the CPU or a loosely coupled coprocessor. + +Subsequent extensions might provide support for native BF16 arithmetic. Such extensions +could add additional conversion +instructions to allow all supported formats to be converted to and from BF16. +==== + +[NOTE] +==== +BF16 addition, subtraction, multiplication, division, and square-root operations can be +faithfully emulated by converting the BF16 operands to single-precision, performing the +operation using single-precision arithmetic, and then converting back to BF16. Performing +BF16 fused multiply-addition using this method can produce results that differ by 1-ulp +on some inputs for the RNE and RMM rounding modes. + + +Conversions between BF16 and formats larger than FP32 can be +emulated. +Exact widening conversions from BF16 can be synthesized by first +converting to FP32 and then converting from FP32 to the target +precision. +Conversions narrowing to BF16 can be synthesized by first +converting to FP32 through a series of halving steps and then +converting from FP32 to BF16. +As with the fused multiply-addition instruction described above, +this method of converting values to BF16 can be off by 1-ulp +on some inputs for the RNE and RMM rounding modes. +==== + +[%autowidth] +[%header,cols="2,4"] +|=== +|Mnemonic +|Instruction +|FCVT.BF16.S | <> +|FCVT.S.BF16 | <> +|FLH | +|FSH | +|FMV.H.X | +|FMV.X.H | +|=== + +// include::riscv-bfloat16-zvfbfmin.adoc[] +[[zvfbfmin,Zvfbfmin]] +==== `Zvfbfmin` - Vector BF16 Converts + +This extension provides the minimal set of instructions needed to enable vector support of the BF16 +format. It enables BF16 as an interchange format as it provides conversion between BF16 values +and FP32 values. + +This extension depends upon `Zve32f` vector extension. + +[NOTE] +==== +While conversion instructions tend to include all supported formats, in these extensions we +only support conversion between BF16 and FP32 as we are targeting a special use case. +These extensions are intended to support the case where BF16 values are used as reduced +precision versions of FP32 values, where use of BF16 provides a two-fold advantage for +storage, bandwidth, and computation. In this use case, the BF16 values are typically +multiplied by each other and accumulated into FP32 sums. +These sums are typically converted to BF16 +and then used as subsequent inputs. The operations on the BF16 values can be performed +on the CPU or a loosely coupled coprocessor. + +Subsequent extensions might provide support for native BF16 arithmetic. Such extensions +could add additional conversion +instructions to allow all supported formats to be converted to and from BF16. +==== + +[NOTE] +==== +BF16 addition, subtraction, multiplication, division, and square-root operations can be +faithfully emulated by converting the BF16 operands to single-precision, performing the +operation using single-precision arithmetic, and then converting back to BF16. Performing +BF16 fused multiply-addition using this method can produce results that differ by 1-ulp +on some inputs for the RNE and RMM rounding modes. + +Conversions between BF16 and formats larger than FP32 can be +faithfully emulated. +Exact widening conversions from BF16 can be synthesized by first +converting to FP32 and then converting from FP32 to the target +precision. Conversions narrowing to BF16 can be synthesized by first +converting to FP32 through a series of halving steps using +vector round-towards-odd narrowing conversion instructions +(_vfncvt.rod.f.f.w_). The final convert from FP32 to BF16 would use +the desired rounding mode. + +==== + +[%autowidth] +[%header,cols="^2,4"] +|=== +|Mnemonic +|Instruction +| vfncvtbf16.f.f.w | <> +| vfwcvtbf16.f.f.v | <> +|=== + +// include::riscv-bfloat16-zvfbfwma.adoc[] +[[zvfbfwma,Zvfbfwma]] +==== `Zvfbfwma` - Vector BF16 widening mul-add + +This extension provides +a vector widening BF16 mul-add instruction that accumulates into FP32. + +This extension depends upon the `Zvfbfmin` extension and the `Zfbfmin` extension. + +[%autowidth] +[%header,cols="2,4"] +|=== +|Mnemonic +|Instruction + +|VFWMACCBF16 | <> +|=== + + +[[BF16_insns, reftext="BF16 Instructions"]] +=== Instructions + +// include::insns/fcvt_BF16_S.adoc[] +// <<< +[[insns-fcvt.bf16.s, Convert FP32 to BF16]] + +==== fcvt.bf16.s + +Synopsis:: +Convert FP32 value to a BF16 value + +Mnemonic:: +fcvt.bf16.s rd, rs1 + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: '1010011', attr: ['OP-FP']}, +{bits: 5, name: 'rd'}, +{bits: 3, name: 'rm'}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: '01000', attr: ['bf16.s']}, +{bits: 2, name: '10', attr: ['h']}, +{bits: 5, name: '01000', attr: 'fcvt'}, +]} +.... + + +[NOTE] +==== +.Encoding +While the mnemonic of this instruction is consistent with that of the other RISC-V floating-point convert instructions, +a new encoding is used in bits 24:20. + +`BF16.S` and `H` are used to signify that the source is FP32 and the destination is BF16. +==== + + +Description:: +[[norm:fcvt-bf16-s_op]] +Narrowing convert FP32 value to a BF16 value. Round according to the RM field. + +This instruction is similar to other narrowing +floating-point-to-floating-point conversion instructions. + + +Exceptions: Overflow, Underflow, Inexact, Invalid + +Included in: <> + +<<< +// include::insns/fcvt_S_BF16.adoc[] +// <<< +[[insns-fcvt.s.bf16, Convert BF16 to FP32]] +==== fcvt.s.bf16 + +Synopsis:: +Convert BF16 value to an FP32 value + +Mnemonic:: +fcvt.s.bf16 rd, rs1 + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: '1010011', attr: ['OP-FP']}, +{bits: 5, name: 'rd'}, +{bits: 3, name: 'rm'}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: '00110', attr: ['bf16']}, +{bits: 2, name: '00', attr: ['s']}, +{bits: 5, name: '01000', attr: 'fcvt'}, +]} +.... + +[NOTE] +==== +.Encoding +While the mnemonic of this instruction is consistent with that of the other RISC-V floating-point +convert instructions, a new encoding is +used in bits 24:20 to indicate that the source is BF16. +==== + + +Description:: +[[norm:fcvt-s-bf16_op]] +Converts a BF16 value to an FP32 value. The conversion is exact. + +This instruction is similar to other widening +floating-point-to-floating-point conversion instructions. + +[NOTE] +==== +If the input is normal or infinity, the BF16 encoded value is shifted +to the left by 16 places and the +least significant 16 bits are written with 0s. + +The result is NaN-boxed by writing the most significant `FLEN`-32 bits with 1s. +==== + + + +Exceptions: Invalid + +Included in: <> + +<<< + +// include::insns/vfncvtbf16_f_f_w.adoc[] +// <<< +[[insns-vfncvtbf16.f.f.w, Vector convert FP32 to BF16]] +==== vfncvtbf16.f.f.w + +Synopsis:: +Vector convert FP32 to BF16 + +Mnemonic:: +vfncvtbf16.f.f.w vd, vs2, vm + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: '1010111', attr:['OP-V']}, +{bits: 5, name: 'vd'}, +{bits: 3, name: '001', attr:['OPFVV']}, +{bits: 5, name: '11101', attr:['vfncvtbf16']}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: 'vm'}, +{bits: 6, name: '010010', attr:['VFUNARY0']}, +]} +.... + +Reserved Encodings:: +[[norm:vfncvtbf16-f-f-w_sew_rsv]] +* `SEW` is any value other than 16 + +Arguments:: + +[%autowidth] +[%header,cols="4,2,2,2"] +|=== +|Register +|Direction +|EEW +|Definition + +| Vs2 | input | 32 | FP32 Source +| Vd | output | 16 | BF16 Result +|=== + + + +Description:: +[[norm:vfncvtbf16-f-f-w_op]] +Narrowing convert from FP32 to BF16. Round according to the _frm_ register. + +This instruction is similar to `vfncvt.f.f.w` which converts a +floating-point value in a 2*SEW-width format into an SEW-width format. +However, here the SEW-width format is limited to BF16. + +Exceptions: Overflow, Underflow, Inexact, Invalid + +Included in: <> + +<<< + +// include::insns/vfwcvtbf16_f_f_v.adoc[] +// <<< +[[insns-vfwcvtbf16.f.f.v, Vector convert BF16 to FP32]] +==== vfwcvtbf16.f.f.v + +Synopsis:: +Vector convert BF16 to FP32 + +Mnemonic:: +vfwcvtbf16.f.f.v vd, vs2, vm + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: '1010111', attr:['OP-V']}, +{bits: 5, name: 'vd'}, +{bits: 3, name: '001', attr:['OPFVV']}, +{bits: 5, name: '01101', attr:['vfwcvtbf16']}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: 'vm'}, +{bits: 6, name: '010010', attr:['VFUNARY0']}, +]} +.... + +Reserved Encodings:: +[[norm:vfwcvtbf16-f-f-v_sew_rsv]] +* `SEW` is any value other than 16 + +Arguments:: +[%autowidth] +[%header,cols="4,2,2,2"] +|=== +|Register +|Direction +|EEW +|Definition + +| Vs2 | input | 16 | BF16 Source +| Vd | output | 32 | FP32 Result +|=== + +Description:: +[[norm:vfwcvtbf16-f-f-v_op]] +Widening convert from BF16 to FP32. The conversion is exact. + +This instruction is similar to `vfwcvt.f.f.v` which converts a +floating-point value in an SEW-width format into a 2*SEW-width format. +However, here the SEW-width format is limited to BF16. + +[NOTE] +==== +If the input is normal or infinity, the BF16 encoded value is shifted +to the left by 16 places and the +least significant 16 bits are written with 0s. +==== + +Exceptions: Invalid + +Included in: <> + +<<< + +// include::insns/vfwmaccbf16.adoc[] +// <<< +[#insns-vfwmaccbf16, reftext="Vector BF16 widening multiply-accumulate"] +==== vfwmaccbf16 + +Synopsis:: +Vector BF16 widening multiply-accumulate + +Mnemonic:: +vfwmaccbf16.vv vd, vs1, vs2, vm + +vfwmaccbf16.vf vd, rs1, vs2, vm + + +Encoding (Vector-Vector):: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: '1010111', attr:['OP-V']}, +{bits: 5, name: 'vd'}, +{bits: 3, name: '001', attr:['OPFVV']}, +{bits: 5, name: 'vs1'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: 'vm'}, +{bits: 6, name: '111011', attr:['vfwmaccbf16']}, +]} +.... + +Encoding (Vector-Scalar):: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: '1010111', attr:['OP-V']}, +{bits: 5, name: 'vd'}, +{bits: 3, name: '101', attr:['OPFVF']}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: 'vm'}, +{bits: 6, name: '111011', attr:['vfwmaccbf16']}, +]} +.... + +Reserved Encodings:: +[[norm:vfwmaccbf16_sew_rsv]] +* `SEW` is any value other than 16 + +Arguments:: +[%autowidth] +[%header,cols="4,2,2,2"] +|=== +|Register +|Direction +|EEW +|Definition + +| Vd | input | 32 | FP32 Accumulate +| Vs1/rs1 | input | 16 | BF16 Source +| Vs2 | input | 16 | BF16 Source +| Vd | output | 32 | FP32 Result +|=== + +Description:: + +[[norm:vfwmaccbf16_op]] +This instruction performs a widening fused multiply-accumulate +operation, where each pair of BF16 values are multiplied and their +unrounded product is added to the corresponding FP32 accumulate value. +The sum is rounded according to the _frm_ register. + +[[norm:vfwmaccbf16_vv]] +In the vector-vector version, the BF16 elements are read from `vs1` +and `vs2` and FP32 accumulate value is read from `vd`. The FP32 result +is written to the destination register `vd`. + +[[norm:vfwmaccbf16_vf]] +The vector-scalar version is similar, but instead of reading elements +from `vs1`, a scalar BF16 value is read from the FPU register `rs1`. + + +Exceptions: Overflow, Underflow, Inexact, Invalid + +Operation:: + +This `vfwmaccbf16.vv` instruction is equivalent to widening each of the BF16 inputs to +FP32 and then performing an FMACC as shown in the following +instruction sequence: + +[source,asm] +-- +vfwcvtbf16.f.f.v T1, vs1, vm +vfwcvtbf16.f.f.v T2, vs2, vm +vfmacc.vv vd, T1, T2, vm +-- + +Likewise, `vfwmaccbf16.vf` is equivalent to the following instruction sequence: + +[source,asm] +-- +fcvt.s.bf16 T1, rs1 +vfwcvtbf16.f.f.v T2, vs2, vm +vfmacc.vf vd, T1, T2, vm +-- + +Included in: <> + + +// include::../bibliography.adoc[ieee] +[bibliography] +=== Bibliography + +// bibliography::[] + +https://ieeexplore.ieee.org/document/8766229[754-2019 - IEEE Standard for Floating-Point Arithmetic] + +https://ieeexplore.ieee.org/document/4610935[754-2008 - IEEE Standard for Floating-Point Arithmetic] diff --git a/param_extraction/chunks/chunk_003.txt.license b/param_extraction/chunks/chunk_003.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_003.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_004.txt b/param_extraction/chunks/chunk_004.txt new file mode 100644 index 0000000000..9dce76d5f2 --- /dev/null +++ b/param_extraction/chunks/chunk_004.txt @@ -0,0 +1,12 @@ +# Chunk: chunk_004 +# Source: bibliography.adoc +# Lines: 1-4 (of 4) +# Content starts: line 1 +# Line count: 4 +# Sections: 1 +# == Bibliography +# +[bibliography] +== Bibliography + +bibliography::[] diff --git a/param_extraction/chunks/chunk_004.txt.license b/param_extraction/chunks/chunk_004.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_004.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_005.txt b/param_extraction/chunks/chunk_005.txt new file mode 100644 index 0000000000..4cbc87bca6 --- /dev/null +++ b/param_extraction/chunks/chunk_005.txt @@ -0,0 +1,155 @@ +# Chunk: chunk_005 +# Source: bitmanip-examples.adoc +# Lines: 1-145 (of 145) +# Content starts: line 1 +# Line count: 145 +# Sections: 3 +# == Bit Manipulation Extensions Assembly Code Examples +# === strlen +# === strcmp +# +[appendix] +== Bit Manipulation Extensions Assembly Code Examples + +The following examples provide software optimization guidance. + +=== strlen + +The *orc.b* instruction allows for the efficient detection of *NUL* bytes in an XLEN-sized chunk of data: + + * the result of *orc.b* on a chunk that does not contain any *NUL* bytes will be all-ones, and + * after a bitwise-negation of the result of *orc.b*, the number of data bytes before the first *NUL* byte (if any) can be detected by *ctz*/*clz* (depending on the endianness of data). + +A full example of a *strlen* function, which uses these techniques and also demonstrates the use of it for unaligned/partial data, is the following: + +[source,asm] +-- +#include + + .text + .globl strlen + .type strlen, @function +strlen: + andi a3, a0, (SZREG-1) // offset + andi a1, a0, -SZREG // align pointer +.Lprologue: + li a4, SZREG + sub a4, a4, a3 // XLEN - offset + slli a3, a3, 3 // offset * 8 + REG_L a2, 0(a1) // chunk + /* + * Shift the partial/unaligned chunk we loaded to remove the bytes + * from before the start of the string, adding NUL bytes at the end. + */ +#if __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__ + srl a2, a2 ,a3 // chunk >> (offset * 8) +#else + sll a2, a2, a3 +#endif + orc.b a2, a2 + not a2, a2 + /* + * Non-NUL bytes in the string have been expanded to 0x00, while + * NUL bytes have become 0xff. Search for the first set bit + * (corresponding to a NUL byte in the original chunk). + */ +#if __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__ + ctz a2, a2 +#else + clz a2, a2 +#endif + /* + * The first chunk is special: compare against the number of valid + * bytes in this chunk. + */ + srli a0, a2, 3 + bgtu a4, a0, .Ldone + addi a3, a1, SZREG + li a4, -1 + .align 2 + /* + * Our critical loop is 4 instructions and processes data in 4 byte + * or 8 byte chunks. + */ +.Lloop: + REG_L a2, SZREG(a1) + addi a1, a1, SZREG + orc.b a2, a2 + beq a2, a4, .Lloop + +.Lepilogue: + not a2, a2 +#if __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__ + ctz a2, a2 +#else + clz a2, a2 +#endif + sub a1, a1, a3 + add a0, a0, a1 + srli a2, a2, 3 + add a0, a0, a2 +.Ldone: + ret +-- + +=== strcmp + +[source,asm] +-- +#include + + .text + .globl strcmp + .type strcmp, @function +strcmp: + or a4, a0, a1 + li t2, -1 + and a4, a4, SZREG-1 + bnez a4, .Lsimpleloop + + # Main loop for aligned strings +.Lloop: + REG_L a2, 0(a0) + REG_L a3, 0(a1) + orc.b t0, a2 + bne t0, t2, .Lfoundnull + addi a0, a0, SZREG + addi a1, a1, SZREG + beq a2, a3, .Lloop + + # Words don't match, and no null byte in first word. + # Get bytes in big-endian order and compare. +#if __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__ + rev8 a2, a2 + rev8 a3, a3 +#endif + # Synthesize (a2 >= a3) ? 1 : -1 in a branchless sequence. + sltu a0, a2, a3 + neg a0, a0 + ori a0, a0, 1 + ret + +.Lfoundnull: + # Found a null byte. + # If words don't match, fall back to simple loop. + bne a2, a3, .Lsimpleloop + + # Otherwise, strings are equal. + li a0, 0 + ret + + # Simple loop for misaligned strings +.Lsimpleloop: + lbu a2, 0(a0) + lbu a3, 0(a1) + addi a0, a0, 1 + addi a1, a1, 1 + bne a2, a3, 1f + bnez a2, .Lsimpleloop + +1: + sub a0, a2, a3 + ret + +.size strcmp, .-strcmp +-- diff --git a/param_extraction/chunks/chunk_005.txt.license b/param_extraction/chunks/chunk_005.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_005.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_006.txt b/param_extraction/chunks/chunk_006.txt new file mode 100644 index 0000000000..b1e367c8f2 --- /dev/null +++ b/param_extraction/chunks/chunk_006.txt @@ -0,0 +1,948 @@ +# Chunk: chunk_006 +# Source: c-st-ext.adoc +# Lines: 1-931 (of 931) +# Content starts: line 1 +# Line count: 931 +# Sections: 10 +# == "C" Extension for Compressed Instructions, Version 2.0 +# === Overview +# === Compressed Instruction Formats +# === Load and Store Instructions +# ==== Stack-Pointer-Based Loads and Stores +# ==== Register-Based Loads and Stores +# === Control Transfer Instructions +# === Integer Computational Instructions +# ==== Integer Constant-Generation Instructions +# ==== Integer Register-Immediate Operations +# +[[compressed]] +== "C" Extension for Compressed Instructions, Version 2.0 + +This chapter describes the RISC-V standard compressed instruction-set +extension, named "C", which reduces static and dynamic code size by +adding short 16-bit instruction encodings for common operations. The C +extension can be added to any of the base ISAs (RV32I, RV32E, RV64I, RV64E), and +we use the generic term "RVC" to cover any of these. Typically, +50%-60% of the RISC-V instructions in a program can be replaced with RVC +instructions, resulting in a 25%-30% code-size reduction. + +=== Overview + +RVC uses a simple compression scheme that offers shorter 16-bit versions +of common 32-bit RISC-V instructions when: + +* the immediate or address offset is small, or +* one of the registers is the zero register (`x0`), the ABI link register +(`x1`), or the ABI stack pointer (`x2`), or +* the destination register and the first source register are identical, or +* the registers used are the 8 most popular ones. + +The C extension is compatible with all other standard instruction +extensions. [#norm:Zca_align16]#The C extension allows 16-bit instructions to be freely +intermixed with 32-bit instructions, with the latter now able to start +on any 16-bit boundary, i.e., IALIGN=16.# [#norm:Zca_no_misaligned]#With the addition of the C +extension, no instructions can raise instruction-address-misaligned +exceptions.# + +[NOTE] +==== +Removing the 32-bit alignment constraint on the original 32-bit +instructions allows significantly greater code density. +==== + +The compressed instruction encodings are mostly common across RV32C and +RV64C, but as shown in <>, a few opcodes are used for +different purposes depending on base ISA. For example, the wider +address-space RV64C variant requires additional opcodes to +compress loads and stores of 64-bit integer values, while RV32C uses the +same opcodes to compress loads and stores of single-precision +floating-point values. +If the C extension is implemented, the +appropriate compressed floating-point load and store instructions must +be provided whenever the relevant standard floating-point extension (F +and/or D) is also implemented. In addition, RV32C includes a compressed +jump and link instruction to compress short-range subroutine calls, +where the same opcode is used to compress ADDIW for RV64C. + +[NOTE] +==== +Double-precision loads and stores are a significant fraction of static +and dynamic instructions, hence the motivation to include them in the +RV32C and RV64C encoding. + +Although single-precision loads and stores are not a significant source +of static or dynamic compression for benchmarks compiled for the +currently supported ABIs, for microcontrollers that only provide +hardware single-precision floating-point units and have an ABI that only +supports single-precision floating-point numbers, the single-precision +loads and stores will be used at least as frequently as double-precision +loads and stores in the measured benchmarks. Hence, the motivation to +provide compressed support for these in RV32C. + +Short-range subroutine calls are more likely in small binaries for +microcontrollers, hence the motivation to include these in RV32C. + +Although reusing opcodes for different purposes for different base ISAs +adds some complexity to documentation, the impact on implementation +complexity is small even for designs that support multiple base ISAs. +The compressed floating-point load and store variants use the same +instruction format with the same register specifiers as the wider +integer loads and stores. +==== + +RVC was designed under the constraint that each RVC instruction expands +into a single 32-bit instruction in either the base ISA (RV32I/E or RV64I/E) +or the F and D standard extensions where present. Adopting +this constraint has two main benefits: + +* Hardware designs can simply expand RVC instructions during decode, +simplifying verification and minimizing modifications to existing +microarchitectures. + +* Compilers can be unaware of the RVC extension and leave code compression +to the assembler and linker, although a compression-aware compiler will +generally be able to produce better results. + +[NOTE] +==== +We felt the multiple complexity reductions of a simple one-one mapping +between C and base IFD instructions far outweighed the potential gains +of a slightly denser encoding that added additional instructions only +supported in the C extension, or that allowed encoding of multiple IFD +instructions in one C instruction. +==== + +It is important to note that the C extension is not designed to be a +stand-alone ISA, and is meant to be used alongside a base ISA. + +[NOTE] +==== +Variable-length instruction sets have long been used to improve code +density. For example, the IBM Stretch cite:[stretch], developed in the late 1950s, had +an ISA with 32-bit and 64-bit instructions, where some of the 32-bit +instructions were compressed versions of the full 64-bit instructions. +Stretch also employed the concept of limiting the set of registers that +were addressable in some of the shorter instruction formats, with short +branch instructions that could only refer to one of the index registers. +The later IBM 360 architecture cite:[ibm360] supported a simple variable-length +instruction encoding with 16-bit, 32-bit, or 48-bit instruction formats. + +In 1963, CDC introduced the Cray-designed CDC 6600 cite:[cdc6600], a precursor to RISC +architectures, that introduced a register-rich load-store architecture +with instructions of two lengths, 15-bits and 30-bits. The later Cray-1 +design used a very similar instruction format, with 16-bit and 32-bit +instruction lengths. + +The initial RISC ISAs from the 1980s all picked performance over code +size, which was reasonable for a workstation environment, but not for +embedded systems. Hence, both ARM and MIPS subsequently made versions of +the ISAs that offered smaller code size by offering an alternative +16-bit wide instruction set instead of the standard 32-bit wide +instructions. The compressed RISC ISAs reduced code size relative to +their starting points by about 25-30%, yielding code that was +significantly smaller than 80x86. This result surprised some, as their +intuition was that the variable-length CISC ISA should be smaller than +RISC ISAs that offered only 16-bit and 32-bit formats. + +Since the original RISC ISAs did not leave sufficient opcode space free +to include these unplanned compressed instructions, they were instead +developed as complete new ISAs. This meant compilers needed different +code generators for the separate compressed ISAs. The first compressed +RISC ISA extensions (e.g., ARM Thumb and MIPS16) used only a fixed +16-bit instruction size, which gave good reductions in static code size +but caused an increase in dynamic instruction count, which led to lower +performance compared to the original fixed-width 32-bit instruction +size. This led to the development of a second generation of compressed +RISC ISA designs with mixed 16-bit and 32-bit instruction lengths (e.g., +ARM Thumb2, microMIPS, PowerPC VLE), so that performance was similar to +pure 32-bit instructions but with significant code size savings. +Unfortunately, these different generations of compressed ISAs are +incompatible with each other and with the original uncompressed ISA, +leading to significant complexity in documentation, implementations, and +software tools support. + +Of the commonly used 64-bit ISAs, only PowerPC and microMIPS currently +supports a compressed instruction format. It is surprising that the most +popular 64-bit ISA for mobile platforms (ARM v8) does not include a +compressed instruction format given that static code size and dynamic +instruction fetch bandwidth are important metrics. Although static code +size is not a major concern in larger systems, instruction fetch +bandwidth can be a major bottleneck in servers running commercial +workloads, which often have a large instruction working set. + +Benefiting from 25 years of hindsight, RISC-V was designed to support +compressed instructions from the outset, leaving enough opcode space for +RVC to be added as a simple extension on top of the base ISA (along with +many other extensions). The philosophy of RVC is to reduce code size for +embedded applications _and_ to improve performance and energy-efficiency +for all applications due to fewer misses in the instruction cache. +Waterman shows that RVC fetches 25%-30% fewer instruction bits, which +reduces instruction cache misses by 20%-25%, or roughly the same +performance impact as doubling the instruction cache size. cite:[waterman-ms] +==== + +=== Compressed Instruction Formats +((((compressed, formats)))) + +<> shows the nine compressed instruction +formats. CR, CI, and CSS can use any of the 32 RVI registers, but [#norm:Zca_regs8]#CIW, +CL, CS, CA, and CB are limited to just 8 of them. +<> lists these popular registers, which +correspond to registers `x8` to `x15`.# Note that there is a separate +version of load and store instructions that use the stack pointer as the +base address register, since saving to and restoring from the stack are +so prevalent, and that they use the CI and CSS formats to allow access +to all 32 data registers. CIW supplies an 8-bit immediate for the +ADDI4SPN instruction. + +[NOTE] +==== +The RISC-V ABI was changed to make the frequently used registers map to +registers 'x8-x15'. This simplifies the decompression decoder by +having a contiguous naturally aligned set of register numbers, and is +also compatible with the RV32E and RV64E base ISAs, which only have 16 integer +registers. +==== +[#norm:Zc_fp_regs]#Compressed register-based floating-point loads and stores also use the +CL and CS formats respectively, with the eight registers mapping to `f8` to `f15`.# +((((calling convention, standard)))) +[NOTE] +==== +_The standard RISC-V calling convention maps the most frequently used +floating-point registers to registers `f8` to `f15`, which allows the +same register decompression decoding as for integer register numbers._ +==== +((((register source specifiers, c-ext)))) +The formats were designed to keep bits for the two register source +specifiers in the same place in all instructions, while the destination +register field can move. When the full 5-bit destination register +specifier is present, it is in the same place as in the 32-bit RISC-V +encoding. Where immediates are sign-extended, the sign extension is +always from bit 12. Immediate fields have been scrambled, as in the base +specification, to reduce the number of immediate multiplexers required. +[NOTE] +==== +The immediate fields are scrambled in the instruction formats instead of +in sequential order so that as many bits as possible are in the same +position in every instruction, thereby simplifying implementations. +==== + +For many RVC instructions, zero-valued immediates are disallowed and +`x0` is not a valid 5-bit register specifier. These restrictions free up +encoding space for other instructions requiring fewer operand bits. + +//[[cr-register]] +//include::images/wavedrom/cr-register.edn[] +//.Compressed 16-bit RVC instructions +//(((compressed, 16-bit))) + +[[rvc-form]] +.Compressed 16-bit RVC instruction formats +//[%header] +[float="center",align="center",cols="1a, 2a",frame="none",grid="none"] +|=== +| +[%autowidth,float="right",align="right",cols="^,^",frame="none",grid="none",options="noheader"] +!=== +!Format ! Meaning +!CR ! Register +!CI ! Immediate +!CSS ! Stack-relative Store +!CIW ! Wide Immediate +!CL ! Load +!CS ! Store +!CA ! Arithmetic +!CB ! Branch/Arithmetic +!CJ ! Jump +!=== +| +[float="left",align="left",cols="1,1,1,1,1,1,1",options="noheader"] +!=== +^!15 14 13 ^!12 ^!11 10 ^!9 8 7 ^!6 5 ^!4 3 2 ^!1 0 +2+^!funct4 2+^!rd/rs1 2+^!rs2 ^! op +^!funct3 ^!imm 2+^!rd/rs1 2+^!imm ^! op +^!funct3 3+^!imm 2+^!rs2 ^! op +^!funct3 4+^!imm ^!rd{prime} ^! op +^!funct3 2+^!imm ^!rs1{prime} ^!imm ^!rd{prime} ^! op +^!funct3 2+^!imm ^!rs1{prime} ^! imm ^!rs2{prime} ^! op +3+^!funct6 ^!rd{prime}/rs1{prime} ^!funct2 ^!rs2{prime} ^! op +^!funct3 2+^!offset ^!rd{prime}/rs1{prime} 2+^!offset ^! op +^!funct3 5+^!jump target ^! op +!=== +|=== + +[[registers]] +.Registers specified by the three-bit _rs1_{prime}, _rs2_{prime}, and _rd_{prime} fields of the CIW, CL, CS, CA, and CB formats. +//[cols="20%,10%,10%,10%,10%,10%,10%,10%,10%"] +[float="center",align="center",cols="1a, 1a",frame="none",grid="none"] +|=== +| +[%autowidth,cols="<",frame="none",grid="none",options="noheader"] +!=== +!RVC Register Number +!Integer Register Number +!Integer Register ABI Name +!Floating-Point Register Number +!Floating-Point Register ABI Name +!=== +| + +[%autowidth,cols="^,^,^,^,^,^,^,^",options="noheader"] +!=== +!`000` !`001` !`010` !`011` !`100` !`101` !`110` !`111` +!`x8` !`x9` !`x10` !`x11` !`x12` !`x13` !`x14`!`x15` +!`s0` !`s1` !`a0` !`a1` !`a2` !`a3` !`a4`!`a5` +!`f8` !`f9` !`f10` !`f11` !`f12` !`f13`!`f14` !`f15` +!`fs0` !`fs1` !`fa0` !`fa1` !`fa2`!`fa3` !`fa4` !`fa5` +!=== +|=== + + +=== Load and Store Instructions + +To increase the reach of 16-bit instructions, data-transfer instructions +use zero-extended immediates that are scaled by the size of the data in +bytes: ×4 for words, ×8 for double +words, and ×16 for quad words. + +RVC provides two variants of loads and stores. One uses the ABI stack +pointer, `x2`, as the base address and can target any data register. The +other can reference one of 8 base address registers and one of 8 data +registers. + +==== Stack-Pointer-Based Loads and Stores + +include::images/wavedrom/c-sp-load-store.edn[] +[[c-sp-load-store]] +//.Stack-Pointer-Based Loads and Stores--these instructions use the CI format. + +These instructions use the CI format. + +[#norm:c-lwsp_op]#C.LWSP loads a 32-bit value from memory into register _rd_. It computes +an effective address by adding the _zero_-extended offset, scaled by 4, +to the stack pointer, `x2`. It expands to `lw rd, offset(x2)`.# +[#norm:c-lwsp_rsv]#C.LWSP is +valid only when _rd_≠`x0`; the code points with _rd_=`x0` are reserved.# + +[#norm:c-ldsp_op]#C.LDSP is an RV64C-only instruction that loads a 64-bit value +from memory into register _rd_. It computes its effective address by +adding the zero-extended offset, scaled by 8, to the stack pointer, +`x2`. It expands to `ld rd, offset(x2)`.# +[#norm:c-ldsp_rsv]#C.LDSP is valid only when +_rd_≠`x0`; the code points with +_rd_=`x0` are reserved.# + +[#norm:c-flwsp_op]#C.FLWSP is an RV32FC-only instruction that loads a single-precision +floating-point value from memory into floating-point register _rd_. It +computes its effective address by adding the _zero_-extended offset, +scaled by 4, to the stack pointer, `x2`. It expands to +`flw rd, offset(x2)`.# + +[#norm:c-fldsp_op]#C.FLDSP is an RV32DC/RV64DC-only instruction that loads a +double-precision floating-point value from memory into floating-point +register _rd_. It computes its effective address by adding the +_zero_-extended offset, scaled by 8, to the stack pointer, `x2`. It +expands to `fld rd, offset(x2)`.# + +include::images/wavedrom/c-sp-load-store-css.edn[] +[[c-sp-load-store-css]] +//.Stack-Pointer-Based Loads and Stores--these instructions use the CSS format. + +These instructions use the CSS format. + +[#norm:c-swsp_op]#C.SWSP stores a 32-bit value in register _rs2_ to memory. It computes an +effective address by adding the _zero_-extended offset, scaled by 4, to +the stack pointer, `x2`. It expands to `sw rs2, offset(x2)`.# + +[#norm:c-sdsp_op]#C.SDSP is an RV64C-only instruction that stores a 64-bit value in +register _rs2_ to memory. It computes an effective address by adding the +_zero_-extended offset, scaled by 8, to the stack pointer, `x2`. It +expands to `sd rs2, offset(x2)`.# + +[#norm:c-fswsp_op]#C.FSWSP is an RV32FC-only instruction that stores a single-precision +floating-point value in floating-point register _rs2_ to memory. It +computes an effective address by adding the _zero_-extended offset, +scaled by 4, to the stack pointer, `x2`. It expands to +`fsw rs2, offset(x2)`.# + +[#norm:c-fsdwsp_op]#C.FSDSP is an RV32DC/RV64DC-only instruction that stores a +double-precision floating-point value in floating-point register _rs2_ +to memory. It computes an effective address by adding the +_zero_-extended offset, scaled by 8, to the stack pointer, `x2`. It +expands to `fsd rs2, offset(x2)`.# + +[NOTE] +==== +Register save/restore code at function entry/exit represents a +significant portion of static code size. The stack-pointer-based +compressed loads and stores in RVC are effective at reducing the +save/restore static code size by a factor of 2 while improving +performance by reducing dynamic instruction bandwidth. + +A common mechanism used in other ISAs to further reduce save/restore +code size is load-multiple and store-multiple instructions. We +considered adopting these for RISC-V but noted the following drawbacks +to these instructions: + +* These instructions complicate processor implementations. +* For virtual memory systems, some data accesses could be resident in +physical memory and some could not, which requires a new restart +mechanism for partially executed instructions. +* Unlike the rest of the RVC instructions, there is no IFD equivalent to +Load Multiple and Store Multiple. +* Unlike the rest of the RVC instructions, the compiler would have to be aware +of these load-multiple and store-multiple instructions to both allocate +registers in the expected order and also to schedule the loads and +stores contiguously and in the proper order, to maximize the chances of them +being detected and replaced by an assembler or linker with the equivalent +load-multiple or store-multiple compressed instruction. +* Simple microarchitectural implementations will constrain how other +instructions can be scheduled around the load and store multiple +instructions, leading to a potential performance loss. +* The desire for sequential register allocation might conflict with the +featured registers selected for the CIW, CL, CS, CA, and CB formats. + +Furthermore, much of the gains can be realized in software by replacing +prologue and epilogue code with subroutine calls to common prologue and +epilogue code, a technique described in Section 5.6 of cite:[waterman-phd]. + +While reasonable architects might come to different conclusions, we +decided to omit load and store multiple and instead use the +software-only approach of calling save/restore millicode routines to +attain the greatest code size reduction. +==== + +==== Register-Based Loads and Stores + +[[reg-based-ldnstr]] +include::images/wavedrom/reg-based-ldnstr.edn[] +//.Compressed, register-based load and stores--these instructions use the CL format. +(((compressed, register-based load and store))) +These instructions use the CL format. + +[#norm:c-lw_op]#C.LW loads a 32-bit value from memory into register +`_rd′_`. It computes an effective address by adding the +_zero_-extended offset, scaled by 4, to the base address in register +`_rs1′_`. It expands to `lw rd′, offset(rs1′)`.# + +[#norm:c-ld_op]#C.LD is an RV64C-only instruction that loads a 64-bit value from +memory into register `_rd′_`. It computes an effective +address by adding the _zero_-extended offset, scaled by 8, to the base +address in register `_rs1′_`. It expands to +`ld rd′, offset(rs1′)`.# + +[#norm:c-flw_op]#C.FLW is an RV32FC-only instruction that loads a single-precision +floating-point value from memory into floating-point register +`_rd′_`. It computes an effective address by adding the +_zero_-extended offset, scaled by 4, to the base address in register +`_rs1′_`. It expands to +`flw rd′, offset(rs1′)`.# + +[#norm:c-fld_op]#C.FLD is an RV32DC/RV64DC-only instruction that loads a double-precision +floating-point value from memory into floating-point register +`_rd′_`. It computes an effective address by adding the +_zero_-extended offset, scaled by 8, to the base address in register +`_rs1′_`. It expands to +`fld rd′, offset(rs1′)`.# + +[[c-cs-format-ls]] +include::images/wavedrom/c-cs-format-ls.edn[] +//.Compressed, CS format load and store--these instructions use the CS format. +(((compressed, cs-format load and store))) + +These instructions use the CS format. + +[#norm:c-sw_op]#C.SW stores a 32-bit value in register `_rs2′_` to memory. +It computes an effective address by adding the _zero_-extended offset, +scaled by 4, to the base address in register `_rs1′_`. It +expands to `sw rs2′, offset(rs1′)`.# + +[#norm:c-sd_op]#C.SD is an RV64C-only instruction that stores a 64-bit value in +register `_rs2′_` to memory. It computes an effective +address by adding the _zero_-extended offset, scaled by 8, to the base +address in register `_rs1′_`. It expands to +`sd rs2′, offset(rs1′)`.# + +[#norm:c-fsw_op]#C.FSW is an RV32FC-only instruction that stores a single-precision +floating-point value in floating-point register `_rs2′_` to +memory. It computes an effective address by adding the _zero_-extended +offset, scaled by 4, to the base address in register +`_rs1′_`. It expands to +`fsw rs2′, offset(rs1′)`.# + +[#norm:c-fsd_op]#C.FSD is an RV32DC/RV64DC-only instruction that stores a +double-precision floating-point value in floating-point register +`_rs2′_` to memory. It computes an effective address by +adding the _zero_-extended offset, scaled by 8, to the base address in +register `_rs1′_`. It expands to +`fsd rs2′, offset(rs1′)`.# + +=== Control Transfer Instructions + +RVC provides unconditional jump instructions and conditional branch +instructions. [#norm:Zca_offsets_mul2]#As with base RVI instructions, the offsets of all RVC +control transfer instructions are in multiples of 2 bytes.# + +[[c-cj-format-ls]] +include::images/wavedrom/c-cj-format-ls.edn[] +//.Compressed, CJ format load and store--these instructions use the CJ format. +(((compressed, cj-format load and store))) + +These instructions use the CJ format. + +[#norm:c-j_op]#C.J performs an unconditional control transfer. The offset is +sign-extended and added to the `pc` to form the jump target address. C.J +can therefore target a {pm}2 KiB range. C.J expands to +`jal x0, offset`.# + +[#norm:c-jal_op]#C.JAL is an RV32C-only instruction that performs the same operation as +C.J, but additionally writes the address of the instruction following +the jump (`pc+2`) to the link register, `x1`. C.JAL expands to +`jal x1, offset`.# + +[[c-cr-format-ls]] +include::images/wavedrom/c-cr-format-ls.edn[] +//.Compressed, CR format load and store--these instructions use the CR format. +(((compressed, cr-format load and store))) + +These instructions use the CR format. + +[#norm:c-jr_op]#C.JR (jump register) performs an unconditional control transfer to the +address in register _rs1_. C.JR expands to `jalr x0, 0(rs1)`.# +[#norm:c-jr_rsv]#C.JR is +valid only when _rs1_≠`x0`; the code +point with _rs1_=`x0` is reserved.# + +[#norm:c-jalr_op]#C.JALR (jump and link register) performs the same operation as C.JR, but +additionally writes the address of the instruction following the jump +(`pc`+2) to the link register, `x1`. C.JALR expands to +`jalr x1, 0(rs1)`.# +[#norm:c-jalr_ebreak]#C.JALR is valid only when +_rs1_≠`x0`; the code point with +_rs1_=`x0` corresponds to the C.EBREAK +instruction.# + +[NOTE] +==== +Strictly speaking, C.JALR does not expand exactly to a base RVI +instruction as the value added to the PC to form the link address is 2 +rather than 4 as in the base ISA, but supporting both offsets of 2 and 4 +bytes is only a very minor change to the base microarchitecture. +==== + +[[c-cb-format-ls]] +include::images/wavedrom/c-cb-format-ls.edn[] +//.Compressed, CB format load and store--these instructions use the CB format. +(((compressed, cb-format load and store))) + +These instructions use the CB format. + +[#norm:c-beqz_op]#C.BEQZ performs conditional control transfers. The offset is +sign-extended and added to the `pc` to form the branch target address. +It can therefore target a {pm}256 B range. C.BEQZ takes the +branch if the value in register _rs1′_ is zero. It +expands to `beq rs1′, x0, offset`.# + +[#norm:c-bnez_op]#C.BNEZ is defined analogously, but it takes the branch if +_rs1′_ contains a nonzero value. It expands to +`bne rs1′, x0, offset`.# + +=== Integer Computational Instructions + +RVC provides several instructions for integer arithmetic and constant +generation. + +==== Integer Constant-Generation Instructions + +The two constant-generation instructions both use the CI instruction +format and can target any integer register. + +[[c-integer-const-gen]] +include::images/wavedrom/c-integer-const-gen.edn[] +//.Integer constant generation format. +(((compressed, integer constant generation))) + + +[#norm:c-li_op]#C.LI loads the sign-extended 6-bit immediate, _imm_, into register _rd_. +C.LI expands into `addi rd, x0, imm`.# +[#norm:c-li_hint]#The C.LI code points with _rd_=`x0` are HINTs.# + +[#norm:c-lui_op]#C.LUI loads the non-zero 6-bit immediate field into bits 17–12 of the +destination register, clears the bottom 12 bits, and sign-extends bit 17 +into all higher bits of the destination. C.LUI expands into +`lui rd, imm`.# +[#norm:c-lui_rsv]#C.LUI is valid only when +_rd_≠`x2`, +and when the immediate is not equal to zero. The code points with +_imm_=0 are reserved. +The code points with _rd_=`x2` and _imm_≠0 correspond to the +C.ADDI16SP instruction.# +[#norm:c-lui_hint]#The code points with _rd_=`x0` and _imm_≠0 are HINTs.# + +==== Integer Register-Immediate Operations + +These integer register-immediate operations are encoded in the CI format +and perform operations on an integer register and a 6-bit immediate. + +[[c-integer-register-immediate]] +include::images/wavedrom/c-int-reg-immed.edn[] +//.Integer register-immediate format. +(((compressed, integer register-immediate))) + +[#norm:c-addi_op]#C.ADDI adds the non-zero sign-extended 6-bit immediate to the value in +register _rd_ then writes the result to _rd_. C.ADDI expands into +`addi rd, rd, imm`.# +[#norm:c-addi_hint]#The code points with _rd_≠0 and _imm_=0 are HINTs.# +[#norm:c-addi_nop]#The code points with _rd_=`x0` encode the C.NOP instruction, of +which the code points with _imm_≠0 are HINTs.# + + +[#norm:c-addiw_op]#C.ADDIW is an RV64C-only instruction that performs the same +computation but produces a 32-bit result, then sign-extends result to 64 +bits. C.ADDIW expands into `addiw rd, rd, imm`. The immediate can be +zero for C.ADDIW, where this corresponds to `sext.w rd`.# +[#norm:c-addiw_rsv]#C.ADDIW is +valid only when _rd_≠`x0`; the code points with +_rd_=`x0` are reserved.# + +[#norm:c-addi16sp_op]#C.ADDI16SP (add immediate to stack pointer) +shares the opcode with C.LUI, but has a destination field of +`x2`. C.ADDI16SP adds the non-zero sign-extended 6-bit immediate to the +value in the stack pointer (`sp=x2`), where the immediate is scaled to +represent multiples of 16 in the range [-512, 496]. C.ADDI16SP is used to +adjust the stack pointer in procedure prologues and epilogues. It +expands into `addi x2, x2, nzimm[9:4]`.# +[#norm:c-addi16sp_rsv]#C.ADDI16SP is valid only when +_nzimm_≠0; the code point with _nzimm_=0 is reserved.# + +[NOTE] +==== +In the standard RISC-V calling convention, the stack pointer `sp` is +always 16-byte aligned. +==== + +[[c-ciw]] +include::images/wavedrom/c-ciw.edn[] +//.CIW format. +(((compressed, CIW))) +[#norm:c-addi4spn_op]#C.ADDI4SPN (add immediate to stack pointer, non-destructive) +is a CIW-format instruction that adds a _zero_-extended +non-zero immediate, scaled by 4, to the stack pointer, `x2`, and writes +the result to `rd′`. This instruction is used to generate +pointers to stack-allocated variables, and expands to +`addi rd′, x2, nzuimm[9:2]`.# +[#norm:c-addi4spn_rsv]#C.ADDI4SPN is valid only when +_nzuimm_≠0; the code points with _nzuimm_=0 are +reserved.# + +[[c-ci]] +include::images/wavedrom/c-ci.edn[] +//.CI format. +(((compressed, CI))) + +[#norm:c-slli_op]#C.SLLI is a CI-format instruction that performs a logical left shift of +the value in register _rd_ then writes the result to _rd_. The shift +amount is encoded in the _shamt_ field. +C.SLLI expands into `slli rd, rd, shamt[5:0]`.# + +[#norm:c-slli_hint]#The C.SLLI code points with _shamt_=0 or with _rd_=`x0` are HINTs.# + +[#norm:c-slli_shamt5]#For RV32C, _shamt[5]_ must be zero; the code points with _shamt[5]_=1 +are designated for custom extensions.# + +[[c-srli-srai]] + +include::images/wavedrom/c-srli-srai.edn[] +//.C-SRLI-SRAI format. +(((compressed, C.SRLI, C.SRAI))) + +[#norm:c-srli_op]#C.SRLI is a CB-format instruction that performs a logical right shift of +the value in register _rd′_ then writes the result to +_rd′_. The shift amount is encoded in the _shamt_ field. +C.SRLI expands into `srli rd′, rd′, shamt`.# + +[#norm:c-srli_hint]#The C.SRLI code points with _shamt_=0 are HINTs.# + +[#norm:c-srli_shamt5]#For RV32C, _shamt[5]_ must be zero; the code points with _shamt[5]_=1 +are designated for custom extensions.# + +[#norm:c-srai_op]#C.SRAI is defined analogously to C.SRLI, but instead performs an +arithmetic right shift. C.SRAI expands to +`srai rd′, rd′, shamt`.# + +[NOTE] +==== +Left shifts are usually more frequent than right shifts, as left shifts +are frequently used to scale address values. Right shifts have therefore +been granted less encoding space and are placed in an encoding quadrant +where all other immediates are sign-extended. +==== +[[c-andi]] +include::images/wavedrom/c-andi.edn[] +//.C.ANDI format +(((compressed, C.ANDI))) + +[#norm:c-andi_op]#C.ANDI is a CB-format instruction that computes the bitwise AND of the +value in register _rd′_ and the sign-extended 6-bit +immediate, then writes the result to _rd′_. C.ANDI +expands to `andi rd′, rd′, imm`.# + +==== Integer Register-Register Operations + +[[c-cr]] +include::images/wavedrom/c-int-reg-to-reg-cr-format.edn[] +//C.CR format +((((compressed. C.CR)))) +These instructions use the CR format. + +[#norm:c-mv_op]#C.MV copies the value in register _rs2_ into register _rd_. C.MV expands +into `add rd, x0, rs2`.# +[#norm:c-mv_jr]#C.MV is valid only when +_rs2_≠`x0`; the code points with _rs2_=`x0` correspond to the C.JR instruction.# +[#norm:c-mv_hint]#The code points with _rs2_≠`x0` and _rd_=`x0` are HINTs.# + +[NOTE] +==== +_C.MV expands to a different instruction than the canonical MV +pseudoinstruction, which instead uses ADDI. Implementations that handle +MV specially, e.g. using register-renaming hardware, may find it more +convenient to expand C.MV to MV instead of ADD, at slight additional +hardware cost._ +==== + +[#norm:c-add_op]#C.ADD adds the values in registers _rd_ and _rs2_ and writes the result +to register _rd_. C.ADD expands into `add rd, rd, rs2`.# +[#norm:c-add_val]#C.ADD is only +valid when _rs2_≠`x0`; the code points with _rs2_=`x0` correspond to the C.JALR +and C.EBREAK instructions.# +[#norm:c-add_hint]#The code points with _rs2_≠`x0` and _rd_=`x0` are HINTs.# + +[[c-ca]] +include::images/wavedrom/c-int-reg-to-reg-ca-format.edn[] +//C.CA format +((((compressed. C.CA)))) + +These instructions use the CA format. + +[#norm:c-and_op]#`C.AND` computes the bitwise `AND` of the values in registers +_rd′_ and _rs2′_, then writes the result +to register _rd′_. `C.AND` expands into +`and rd′, rd′, rs2′`.# + +[#norm:c-or_op]#`C.OR` computes the bitwise `OR` of the values in registers +_rd′_ and _rs2′_, then writes the result +to register _rd′_. `C.OR` expands into +`or rd′, rd′, rs2′`.# + +[#norm:c-xor_op]#`C.XOR` computes the bitwise `XOR` of the values in registers +_rd′_ and _rs2′_, then writes the result +to register _rd′_. `C.XOR` expands into +`xor rd′, rd′, rs2′`.# + +[#norm:c-sub_op]#`C.SUB` subtracts the value in register _rs2′_ from the +value in register _rd′_, then writes the result to +register _rd′_. `C.SUB` expands into +`sub rd′, rd′, rs2′`.# + +[#norm:c-addw_op]#`C.ADDW` is an RV64C-only instruction that adds the values in +registers _rd′_ and _rs2′_, then +sign-extends the lower 32 bits of the sum before writing the result to +register _rd′_. `C.ADDW` expands into +`addw rd′, rd′, rs2′`.# + +[#norm:c-subw_op]#`C.SUBW` is an RV64C-only instruction that subtracts the value in +register _rs2′_ from the value in register +_rd′_, then sign-extends the lower 32 bits of the +difference before writing the result to register _rd′_. +`C.SUBW` expands into `subw rd′, rd′, rs2′`.# + +[NOTE] +==== +This group of six instructions do not provide large savings +individually, but do not occupy much encoding space and are +straightforward to implement, and as a group provide a worthwhile +improvement in static and dynamic compression. +==== + +==== Defined Illegal Instruction + +[[c-def-illegal-inst]] +include::images/wavedrom/c-def-illegal-inst.edn[] +((((compressed. C.DIINST)))) + +[#norm:Zca_illegal]#A 16-bit instruction with all bits zero is permanently reserved as an +illegal instruction.# + +[NOTE] +==== +We reserve all-zero instructions to be illegal instructions to help trap +attempts to execute zero-ed or non-existent portions of the memory +space. The all-zero value should not be redefined in any non-standard +extension. Similarly, we reserve instructions with all bits set to 1 +(corresponding to very long instructions in the RISC-V variable-length +encoding scheme) as illegal to capture another common value seen in +non-existent memory regions. +==== + +==== NOP Instruction + +[[c-nop-instr]] +include::images/wavedrom/c-nop-instr.edn[] +((((compressed. C.NOPINSTR)))) + +[#norm:c-nop_op]#`C.NOP` is a CI-format instruction that does not change any user-visible +state, except for advancing the `pc` and incrementing any applicable +performance counters. `C.NOP` expands to `nop`.# +[#norm:c-nop_hint]#The `C.NOP` code points +with _imm_≠0 encode HINTs.# + +==== Breakpoint Instruction + +[[c-breakpoint-instr]] +include::images/wavedrom/c-breakpoint-instr.edn[] +((((compressed. C.BREAKPOINTINSTR)))) + +[#norm:c-ebreak_op]#Debuggers can use the `C.EBREAK` instruction, which expands to `ebreak`, +to cause control to be transferred back to the debugging environment. +`C.EBREAK` shares the opcode with the `C.ADD` instruction, but with _rd_ and +_rs2_ both zero, thus can also use the `CR` format.# + +=== Usage of C Instructions in LR/SC Sequences + +On implementations that support the C extension, compressed forms of the +I instructions permitted inside constrained LR/SC sequences, as +described in <>, are also permitted +inside constrained LR/SC sequences. + +[NOTE] +==== +The implication is that any implementation that claims to support both +the A and C extensions must ensure that LR/SC sequences containing valid +C instructions will eventually complete. +==== + +[[rvc-hints]] +=== HINT Instructions + +[#norm:Zca_hints]#A portion of the RVC encoding space is reserved for microarchitectural +HINTs. Like the HINTs in the RV32I base ISA (see +<>), these instructions do not +modify any architectural state, except for advancing the `pc` and any +applicable performance counters. HINTs are executed as no-ops on +implementations that ignore them.# + +RVC HINTs are encoded as computational instructions that do not modify +the architectural state, either because _rd_=`x0` (e.g. +`C.ADD _x0_, _t0_`), or because _rd_ is overwritten with a copy of itself +(e.g. `C.ADDI _t0_, 0`). + +[NOTE] +==== +This HINT encoding has been chosen so that simple implementations can +ignore HINTs altogether, and instead execute a HINT as a regular +computational instruction that happens not to mutate the architectural +state. +==== + +RVC HINTs do not necessarily expand to their RVI HINT counterparts. For +example, `C.ADD` _x0_, _a0_ might not encode the same HINT as +`ADD` _x0_, _x0_, _a0_. + +[NOTE] +==== +The primary reason to not require an RVC HINT to expand to an RVI HINT +is that HINTs are unlikely to be compressible in the same manner as the +underlying computational instruction. Also, decoupling the RVC and RVI +HINT mappings allows the scarce RVC HINT space to be allocated to the +most popular HINTs, and in particular, to HINTs that are amenable to +macro-op fusion. +==== + +<> lists all RVC HINT code points. For RV32C, 78% +of the HINT space is reserved for standard HINTs. The remainder of the HINT space is designated for custom HINTs; +no standard HINTs will ever be defined in this subspace. + +[[rvc-t-hints]] +.RVC HINT instructions. +[cols="<,<,>,<",options="header",] +|=== +|Instruction |Constraints |Code Points |Purpose + +|C.NOP |_imm_≠0 |63 .6+.^|_Designated for future standard use_ + +|C.ADDI | _rd_≠`x0`, _imm_=0 |31 + +|C.LI | _rd_=`x0` |64 + +|C.LUI | _rd_=`x0`, _imm_≠0 |63 + +|C.MV | _rd_=`x0`, _rs2_≠`x0` |31 + +|C.ADD | _rd_=`x0`, _rs2_≠`x0`, _rs2_≠`x2-x5` | 27 + +|C.ADD | _rd_=`x0`, _rs2_=`x2-x5` |4|(rs2=x2) C.NTL.P1 (rs2=x3) C.NTL.PALL (rs2=x4) C.NTL.S1 (rs2=x5) C.NTL.ALL + +|C.SLLI |_rd_=`x0` or _imm_=0 |63 (RV32), 95 (RV64) .3+.^|_Designated for custom use_ + +|C.SRLI | _imm_=0 |8 + +|C.SRAI | _imm_=0 |8 +|=== + +=== RVC Instruction Set Listings + +<> shows a map of the major +opcodes for RVC. Each row of the table corresponds to one quadrant of +the encoding space. The last quadrant, which has the two +least-significant bits set, corresponds to instructions wider than 16 +bits, including those in the base ISAs. Several instructions are only +valid for certain operands; when invalid, they are marked either _RES_ +to indicate that the opcode is reserved for future standard extensions; +_Custom_ to indicate that the opcode is designated for custom +extensions; or _HINT_ to indicate that the opcode is reserved for +microarchitectural hints (see <>). + +<<< + +[[rvcopcodemap]] +.RVC opcode map instructions. +[%autowidth,float="center",align="center",cols=">,^,^,^,^,^,^,^,^,^,<] +|=== +2+>|inst[15:13] + +inst[1:0] ^.^s|000 ^.^s|001 ^.^s|010 ^.^s|011 ^.^s|100 ^.^s|101 ^.^s|110 ^.^s|111 | + +2+>.^|00 .^|ADDI4SPN ^.^|FLD + +FLD ^.^| LW ^.^| FLW + +LD ^.^| _Reserved_ ^.^| FSD + +FSD ^.^| SW ^.^| FSW + +SD +^.^| RV32 + +RV64 + +2+>.^|01 ^.^|ADDI ^.^|JAL + +ADDIW ^.^|LI ^.^|LUI/ADDI16SP ^.^|MISC-ALU ^.^|J ^.^|BEQZ ^.^|BNEZ ^.^|RV32 + +RV64 + +2+>.^|10 ^.^|SLLI ^.^|FLDSP + +FLDSP ^.^|LWSP ^.^|FLWSP + +LDSP ^.^|J[AL]R/MV/ADD ^.^|FSDSP + +FSDSP ^.^|SWSP ^.^|FSWSP + +SDSP ^.^|RV32 + +RV64 + +2+>.^|11 9+^|>16b +|=== + +<>, <>, and <> list the RVC instructions. + +[[rvc-instr-table0]] +.Instruction listing for RVC, Quadrant 0 +include::images/bytefield/rvc-instr-quad0.edn[] + +[[rvc-instr-table1]] +.Instruction listing for RVC, Quadrant 1 +include::images/bytefield/rvc-instr-quad1.edn[] + +[[rvc-instr-table2]] +.Instruction listing for RVC, Quadrant 2 +include::images/bytefield/rvc-instr-quad2.edn[] diff --git a/param_extraction/chunks/chunk_006.txt.license b/param_extraction/chunks/chunk_006.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_006.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_007.txt b/param_extraction/chunks/chunk_007.txt new file mode 100644 index 0000000000..733c1d49e8 --- /dev/null +++ b/param_extraction/chunks/chunk_007.txt @@ -0,0 +1,37 @@ +# Chunk: chunk_007 +# Source: calling-convention.adoc +# Lines: 1-29 (of 29) +# Content starts: line 1 +# Line count: 29 +# Sections: 1 +# == Calling Convention for Vector State (Not authoritative - Placeholder Only) +# +[appendix] +== Calling Convention for Vector State (Not authoritative - Placeholder Only) + +NOTE: This Appendix is only a placeholder to help explain the +conventions used in the code examples, and is not considered frozen or +part of the ratification process. The official RISC-V psABI document +is being expanded to specify the vector calling conventions. + +In the RISC-V psABI, the vector registers `v0`-`v31` are all caller-saved. +The `vl` and `vtype` CSRs are also caller-saved. + +Procedures may assume that `vstart` is zero upon entry. Procedures may +assume that `vstart` is zero upon return from a procedure call. + +NOTE: Application software should normally not write `vstart` explicitly. +Any procedure that does explicitly write `vstart` to a nonzero value must +zero `vstart` before either returning or calling another procedure. + +The `vxrm` and `vxsat` fields of `vcsr` have thread storage duration. + +Executing a system call causes all caller-saved vector registers +(`v0`-`v31`, `vl`, `vtype`) and `vstart` to become unspecified. + +NOTE: This scheme allows system calls that cause context switches to avoid +saving and later restoring the vector registers. + +NOTE: Most OSes will choose to either leave these registers intact or reset +them to their initial state to avoid leaking information across process +boundaries. diff --git a/param_extraction/chunks/chunk_007.txt.license b/param_extraction/chunks/chunk_007.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_007.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_008.txt b/param_extraction/chunks/chunk_008.txt new file mode 100644 index 0000000000..76843205b6 --- /dev/null +++ b/param_extraction/chunks/chunk_008.txt @@ -0,0 +1,1111 @@ +# Chunk: chunk_008 +# Source: cmo.adoc +# Lines: 1-1094 (of 1094) +# Content starts: line 1 +# Line count: 1094 +# Sections: 10 +# == "CMO" Extensions for Base Cache Management Operation ISA, Version 1.0.0 +# === Pseudocode for instruction semantics +# === Introduction +# === Background +# ==== Memory and Caches +# ==== Cache-Block Operations +# === Coherent Agents and Caches +# ==== Memory Ordering +# ===== Preserved Program Order +# ===== Load Values +# +[[cmo]] +== "CMO" Extensions for Base Cache Management Operation ISA, Version 1.0.0 + +=== Pseudocode for instruction semantics + +The semantics of each instruction in the <<#insns>> chapter is expressed in a +SAIL-like syntax. + +[#intro-cmo,reftext="Introduction"] +=== Introduction + +_Cache-management operation_ (or _CMO_) instructions perform operations on +copies of data in the memory hierarchy. In general, CMO instructions operate on +cached copies of data, but in some cases, a CMO instruction may operate on +memory locations directly. Furthermore, CMO instructions are grouped by +operation into the following classes: + +* A _management_ instruction manipulates cached copies of data with respect to a + set of agents that can access the data +* A _zero_ instruction zeros out a range of memory locations, potentially + allocating cached copies of data in one or more caches +* A _prefetch_ instruction indicates to hardware that data at a given memory + location may be accessed in the near future, potentially allocating cached + copies of data in one or more caches + +This document introduces a base set of CMO ISA extensions that operate +specifically on cache blocks or the memory locations corresponding to a cache +block; these are known as _cache-block operation_ (or _CBO_) instructions. Each +of the above classes of instructions represents an extension in this +specification: + +* The _Zicbom_ extension defines a set of cache-block management instructions: + `CBO.INVAL`, `CBO.CLEAN`, and `CBO.FLUSH` +* The _Zicboz_ extension defines a cache-block zero instruction: `CBO.ZERO` +* The _Zicbop_ extension defines a set of cache-block prefetch instructions: + `PREFETCH.R`, `PREFETCH.W`, and `PREFETCH.I` + +The execution behavior of the above instructions is also modified by CSR state +added by this specification. + +The remainder of this document provides general background information on CMO +instructions and describes each of the above ISA extensions. + +[NOTE] +==== +_The term CMO encompasses all operations on caches or resources related to +caches. The term CBO represents a subset of CMOs that operate only on cache +blocks. The first CMO extensions only define CBOs._ +==== + +[#background,reftext="Background"] +=== Background + +This chapter provides information common to all CMO extensions. + +[#memory-caches,reftext="Memory and Caches"] +==== Memory and Caches + +A _memory location_ is a physical resource in a system uniquely identified by a +_physical address_. An _agent_ is a logic block, such as a RISC-V hart, +accelerator, I/O device, etc., that can access a given memory location. + +[NOTE] +==== +_A given agent may not be able to access all memory locations in a system, and +two different agents may or may not be able to access the same set of memory +locations._ +==== + +A _load operation_ (or _store operation_) is performed by an agent to consume +(or modify) the data at a given memory location. Load and store operations are +performed as a result of explicit memory accesses to that memory location. +Additionally, a _read transfer_ from memory fetches the data at the memory +location, while a _write transfer_ to memory updates the data at the memory +location. + +A _cache_ is a structure that buffers copies of data to reduce average memory +latency. Any number of caches may be interspersed between an agent and a memory +location, and load and store operations from an agent may be satisfied by a +cache instead of the memory location. + +[NOTE] +==== +_Load and store operations are decoupled from read and write transfers by +caches. For example, a load operation may be satisfied by a cache without +performing a read transfer from memory, or a store operation may be satisfied by +a cache that first performs a read transfer from memory._ +==== + +Caches organize copies of data into _cache blocks_, each of which represents a +contiguous, naturally aligned power-of-two (or _NAPOT_) range of memory +locations. A cache block is identified by any of the physical addresses corresponding to +the underlying memory locations. The capacity and organization of a cache and +the size of a cache block are both _implementation-specific_, and the execution +environment provides software a means to discover information about the caches +and cache blocks in a system. In the initial set of CMO extensions, the size of +a cache block shall be uniform throughout the system. + +[NOTE] +==== +_In future CMO extensions, the requirement for a uniform cache block size may be +relaxed._ +==== + +Implementation techniques such as speculative execution or hardware prefetching +may cause a given cache to allocate or deallocate a copy of a cache block at any +time, provided the corresponding physical addresses are accessible according to +the supported access type PMA and are cacheable according to the cacheability +PMA. Allocating a copy of a cache block results in a read transfer from another +cache or from memory, while deallocating a copy of a cache block may result in a +write transfer to another cache or to memory depending on whether the data in +the copy were modified by a store operation. Additional details are discussed in +<<#coherent-agents-caches>>. + +==== Cache-Block Operations + +A CBO instruction causes one or more operations to be performed on the cache +blocks identified by the instruction. In general, a CBO instruction may identify +one or more cache blocks; however, in the initial set of CMO extensions, CBO +instructions identify a single cache block only. + +A cache-block management instruction performs one of the following operations, +relative to the copy of a given cache block allocated in a given cache: + +* An _invalidate operation_ deallocates the copy of the cache block + +* A _clean operation_ performs a write transfer to another cache or to memory if + the data in the copy of the cache block have been modified by a store + operation + +* A _flush operation_ atomically performs a clean operation followed by an + invalidate operation + +Additional details, including the actual operation performed by a given +cache-block management instruction, are described in <<#Zicbom>>. + +A cache-block zero instruction performs a set of store operations that write +zeros to the set of bytes corresponding to a cache block. Unless specified +otherwise, the store operations generated by a cache-block zero instruction have +the same general properties and behaviors that other store instructions in the +architecture have. An implementation may or may not update the entire set of +bytes atomically with a single store operation. Additional details are described +in <<#Zicboz>>. + +A cache-block prefetch instruction is a HINT to the hardware that software +expects to perform a particular type of memory access in the near future. +Additional details are described in <<#Zicbop>>. + +[#coherent-agents-caches,reftext="Coherent Agents and Caches"] +=== Coherent Agents and Caches + +For a given memory location, a _set of coherent agents_ consists of the agents +for which all of the following hold: + +* Store operations from all agents in the set appear to be serialized with + respect to each other +* Store operations from all agents in the set eventually appear to all other + agents in the set +* A load operation from an agent in the set returns data from a store operation + from an agent in the set (or from the initial data in memory) + +The coherent agents within such a set shall access a given memory location with +the same physical address and the same physical memory attributes; however, if +the coherence PMA for a given agent indicates a given memory location is not +coherent, that agent shall not be a member of a set of coherent agents with any +other agent for that memory location and shall be the sole member of a set of +coherent agents consisting of itself. + +An agent who is a member of a set of coherent agents is said to be _coherent_ +with respect to the other agents in the set. On the other hand, an agent who is +_not_ a member is said to be _non-coherent_ with respect to the agents in the +set. + +Caches introduce the possibility that multiple copies of a given cache block may +be present in a system at the same time. An _implementation-specific_ mechanism +keeps these copies coherent with respect to the load and store operations from +the agents in the set of coherent agents. Additionally, if a coherent agent in +the set executes a CBO instruction that specifies the cache block, the resulting +operation shall apply to any and all of the copies in the caches that can be +accessed by the load and store operations from the coherent agents. + +[NOTE] +==== +_An operation from a CBO instruction is defined to operate only on the copies of +a cache block that are cached in the caches accessible by the explicit memory +accesses performed by the set of coherent agents. This includes copies of a +cache block in caches that are accessed only indirectly by load and store +operations, e.g. coherent instruction caches._ +==== + +The set of caches subject to the above mechanism form a _set of coherent +caches_, and each coherent cache has the following behaviors, assuming all +operations are performed by the agents in a set of coherent agents: + +* A coherent cache is permitted to allocate and deallocate copies of a cache + block and perform read and write transfers as described in <<#memory-caches>> + +* A coherent cache is permitted to perform a write transfer to memory provided + that a store operation has modified the data in the cache block since the most + recent invalidate, clean, or flush operation on the cache block + +* At least one coherent cache is responsible for performing a write transfer to + memory once a store operation has modified the data in the cache block until + the next invalidate, clean, or flush operation on the cache block, after which + no coherent cache is responsible (or permitted) to perform a write transfer to + memory until the next store operation has modified the data in the cache block + +* A coherent cache is required to perform a write transfer to memory if a store + operation has modified the data in the cache block since the most recent + invalidate, clean, or flush operation on the cache block and if the next clean + or flush operation requires a write transfer to memory + +[NOTE] +==== +_The above restrictions ensure that a "clean" copy of a cache block, fetched by +a read transfer from memory and unmodified by a store operation, cannot later +overwrite the copy of the cache block in memory updated by a write transfer to +memory from a non-coherent agent._ +==== + +A non-coherent agent may initiate a cache-block operation that operates on the +set of coherent caches accessed by a set of coherent agents. The mechanism to +perform such an operation is _implementation-specific_. + +==== Memory Ordering + +===== Preserved Program Order + +The preserved program order (abbreviated _PPO_) rules are defined by the RVWMO +memory ordering model. How the operations resulting from CMO instructions fit +into these rules is described below. + +For cache-block management instructions, the resulting invalidate, clean, and +flush operations behave as stores in the PPO rules subject to one additional +overlapping address rule. Specifically, [#norm:PPO_overlap_1]#if _a_ precedes _b_ in program order, +then _a_ will precede _b_ in the global memory order if:# + +* [#norm:PPO_overlap_2]#_a_ is an invalidate, clean, or flush, _b_ is a load, and _a_ and _b_ access + overlapping memory addresses# + +[NOTE] +==== +_The above rule ensures that a subsequent load in program order never appears +in the global memory order before a preceding invalidate, clean, or flush +operation to an overlapping address._ +==== + +Additionally, invalidate, clean, and flush operations are classified as W or O +(depending on the physical memory attributes for the corresponding physical +addresses) for the purposes of predecessor and successor sets in `FENCE` +instructions. These operations are _not_ ordered by other instructions that +order stores, e.g. `FENCE.I` and `SFENCE.VMA`. + +For cache-block zero instructions, the resulting store operations behave as +stores in the PPO rules and are ordered by other instructions that order stores. + +Finally, for cache-block prefetch instructions, the resulting operations are +_not_ ordered by the PPO rules nor are they ordered by any other ordering +instructions. + +===== Load Values + +An invalidate operation may change the set of values that can be returned by a +load. In particular, an additional condition is added to the Load Value Axiom: + +* If an invalidate operation _i_ precedes a load _r_ and operates on a byte _x_ + returned by _r_, and no store to _x_ appears between _i_ and _r_ in program + order or in the global memory order, then _r_ returns any of the following + values for _x_: + +. [#norm:invalidate_load_val1]#If no clean or flush operations on _x_ precede _i_ in the global memory order, + either the initial value of _x_ or the value of any store to _x_ that precedes + _i_# + +. [#norm:invalidate_load_val2]#If no store to _x_ precedes a clean or flush operation on _x_ in the global + memory order and if the clean or flush operation on _x_ precedes _i_ in the + global memory order, either the initial value of _x_ or the value of any store + to _x_ that precedes _i_# + +. [#norm:invalidate_load_val3]#If a store to _x_ precedes a clean or flush operation on _x_ in the global + memory order and if the clean or flush operation on _x_ precedes _i_ in the + global memory order, either the value of the latest store to _x_ that precedes + the latest clean or flush operation on _x_ or the value of any store to _x_ + that both precedes _i_ and succeeds the latest clean or flush operation on _x_ + that precedes _i_# + +. [#norm:invalidate_load_val4]#The value of any store to _x_ by a non-coherent agent regardless of the above + conditions# + +[NOTE] +==== +_The first three bullets describe the possible load values at different points +in the global memory order relative to clean or flush operations. The final +bullet implies that the load value may be produced by a non-coherent agent at +any time._ +==== + +==== Traps + +Execution of certain CMO instructions may result in traps due to CSR state, +described in the <<#csr_state>> section, or due to the address translation and +protection mechanisms. The trapping behavior of CMO instructions is described in +the following sections. + +===== Illegal-Instruction and Virtual-Instruction Exceptions + +Cache-block management instructions and cache-block zero instructions may raise +illegal-instruction exceptions or virtual-instruction exceptions depending on +the current privilege mode and the state of the CMO control registers described +in the <<#csr_state>> section. + +Cache-block prefetch instructions raise neither illegal-instruction exceptions +nor virtual-instruction exceptions. + +===== Page-Fault, Guest-Page-Fault, and Access-Fault Exceptions + +Similar to load and store instructions, CMO instructions are explicit memory +access instructions that compute an effective address. The effective address is +ultimately translated into a physical address based on the privilege mode and +the enabled translation mechanisms, and the CMO extensions impose the following +constraints on the physical addresses in a given cache block: + +* [#norm:PMP_same]#The PMP access control bits shall be the same for _all_ physical addresses in + the cache block, and if write permission is granted by the PMP access control + bits, read permission shall also be granted# + +* [#norm:PMA_same]#The PMAs shall be the same for _all_ physical addresses in the cache block, + and if write permission is granted by the supported access type PMAs, read + permission shall also be granted# + +[#norm:cbo_rsv]#If the above constraints are not met, the behavior of a CBO instruction is +UNSPECIFIED.# + +[NOTE] +==== +_This specification assumes that the above constraints will typically be met for +main memory regions and may be met for certain I/O regions._ +==== + +[NOTE] +==== +The access size for CMO instructions is equal to the size of the cache +block, however in some cases that access can be decomposed into multiple +memory operations. PMP checks are applied to each memory operation +independently. For example a 64-byte *cbo.zero* that spans two 32-byte PMP +regions would succeed if it was decomposed into two 32-byte memory operations +(and the PMP access control bits are the same in both regions), but if +performed as a single 64-byte memory operation it would cause an access fault. +==== + +The Zicboz extension introduces an additional supported access type PMA for +cache-block zero instructions. Main memory regions are required to support +accesses by cache-block zero instructions; however, I/O regions may specify +whether accesses by cache-block zero instructions are supported. + +[#norm:cbm_access]#A cache-block management instruction is permitted to access the specified cache +block whenever a load instruction or store instruction is permitted to access +the corresponding physical addresses.# If neither a load instruction nor store +instruction is permitted to access the physical addresses, but an instruction +fetch is permitted to access the physical addresses, whether a cache-block +management instruction is permitted to access the cache block is UNSPECIFIED. [#norm:cbm_unperm_fault]#If +access to the cache block is not permitted, a cache-block management instruction +raises a store page-fault or store guest-page-fault exception if address +translation does not permit any access or raises a store access-fault exception +otherwise.# [#norm:cbm_unperm_translate]#During address translation, the instruction also checks the accessed +bit and may either raise an exception or set the bit as required.# + +[NOTE] +==== +_The interaction between cache-block management instructions and instruction +fetches will be specified in a future extension._ + +_As implied by omission, a cache-block management instruction does not check the +dirty bit and neither raises an exception nor sets the bit._ +==== + +[#norm:cbz_access]#A cache-block zero instruction is permitted to access the specified cache block +whenever a store instruction is permitted to access the corresponding physical +addresses and when the PMAs indicate that cache-block zero instructions are a +supported access type.# [#norm:cbz_unperm_fault]#If access to the cache block is not permitted, a +cache-block zero instruction raises a store page-fault or store guest-page-fault +exception if address translation does not permit write access or raises a store +access-fault exception otherwise.# [#norm:cbz_unperm_translate]#During address translation, the instruction +also checks the accessed and dirty bits and may either raise an exception or set +the bits as required.# + +[#norm:cbp_access]#A cache-block prefetch instruction is permitted to access the specified cache +block whenever a load instruction, store instruction, or instruction fetch is +permitted to access the corresponding physical addresses.# [#norm:cbp_unperm_noexcep]#If access to the cache +block is not permitted, a cache-block prefetch instruction does not raise any +exceptions and shall not access any caches or memory.# [#norm:cbp_unperm_translate]#During address +translation, the instruction does _not_ check the accessed and dirty bits and +neither raises an exception nor sets the bits.# + +[#norm:fault_excep_csr]#When a page-fault, guest-page-fault, or access-fault exception is taken, the +relevant *tval CSR is written with the faulting effective address (i.e. the +value of _rs1_).# + +[NOTE] +==== +_Like a load or store instruction, a CMO instruction may or may not be permitted +to access a cache block based on the states of the `MPRV`, `MPV`, and `MPP` bits +in `mstatus` and the `SUM` and `MXR` bits in `mstatus`, `sstatus`, and +`vsstatus`._ + +_This specification expects that implementations will process cache-block +management instructions like store/AMO instructions, so store/AMO exceptions are +appropriate for these instructions, regardless of the permissions required._ +==== + +===== Address-Misaligned Exceptions + +[[norm:no_addr_misaligned_excep]] +CMO instructions do _not_ generate address-misaligned exceptions. + +===== Breakpoint Exceptions and Debug Mode Entry + +Unless otherwise defined by the debug architecture specification, the behavior +of trigger modules with respect to CMO instructions is UNSPECIFIED. + +[NOTE] +==== +_For the Zicbom, Zicboz, and Zicbop extensions, this specification recommends +the following common trigger module behaviors:_ + +* Type 6 address match triggers, i.e. `tdata1.type=6` and `mcontrol6.select=0`, + should be supported + +* Type 2 address/data match triggers, i.e. `tdata1.type=2`, should be + unsupported + +* The size of a memory access equals the size of the cache block accessed, and + the compare values follow from the addresses of the NAPOT memory region + corresponding to the cache block containing the effective address + +* Unless an encoding for a cache block is added to the `mcontrol6.size` field, + an address trigger should only match a memory access from a CBO instruction if + `mcontrol6.size=0` + +_If the Zicbom extension is implemented, this specification recommends the +following additional trigger module behaviors:_ + +* Implementing address match triggers should be optional + +* Type 6 data match triggers, i.e. `tdata1.type=6` and `mcontrol6.select=1`, + should be unsupported + +* Memory accesses are considered to be stores, i.e. an address trigger matches + only if `mcontrol6.store=1` + +_If the Zicboz extension is implemented, this specification recommends the +following additional trigger module behaviors:_ + +* Implementing address match triggers should be mandatory + +* Type 6 data match triggers, i.e. `tdata1.type=6` and `mcontrol6.select=1`, + should be supported, and implementing these triggers should be optional + +* Memory accesses are considered to be stores, i.e. an address trigger matches + only if `mcontrol6.store=1` + +_If the Zicbop extension is implemented, this specification recommends the +following additional trigger module behaviors:_ + +* Implementing address match triggers should be optional + +* Type 6 data match triggers, i.e. `tdata1.type=6` and `mcontrol6.select=1`, + should be unsupported + +* Memory accesses may be considered to be loads or stores depending on the + implementation, i.e. whether an address trigger matches on these instructions + when `mcontrol6.load=1` or `mcontrol6.store=1` is _implementation-specific_ + +_This specification also recommends that the behavior of trigger modules with +respect to the Zicboz extension should be defined in version 1.0 of the debug +architecture specification. The behavior of trigger modules with respect to the +Zicbom and Zicbop extensions is expected to be defined in future extensions._ +==== + +===== Hypervisor Extension + +[[norm:h_trans_cache]] +For the purposes of writing the `mtinst` or `htinst` register on a trap, the +following standard transformation is defined for cache-block management +instructions and cache-block zero instructions: + +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 'opcode'}, + { bits: 5, name: 0x0 }, + { bits: 3, name: 'funct3'}, + { bits: 5, name: 0x0}, + { bits: 12, name: 'operation'}, +]} +.... + +The `operation` field corresponds to the 12 most significant bits of the +trapping instruction. + +[NOTE] +==== +_As described in the hypervisor extension, a zero may be written into `mtinst` +or `htinst` instead of the standard transformation defined above._ +==== + +==== Effects on Constrained LR/SC Loops + +The following event is added to the list of events that satisfy the eventuality +guarantee provided by constrained LR/SC loops, as defined in the A extension: + +* Some other hart executes a cache-block management instruction or a cache-block + zero instruction to the reservation set of the LR instruction in _H_'s + constrained LR/SC loop. + +[NOTE] +==== +_The above event has been added to accommodate cache coherence protocols that +cannot distinguish between invalidations for stores and invalidations for +cache-block management operations._ + +_Aside from the above event, CMO instructions neither change the properties of +constrained LR/SC loops nor modify the eventuality guarantee provided by them. +For example, executing a CMO instruction may cause a constrained LR/SC loop on +any hart to fail periodically or may cause a unconstrained LR/SC sequence on the +same hart to fail always. Additionally, executing a cache-block prefetch +instruction does not impact the eventuality guarantee provided by constrained +LR/SC loops executed on any hart._ +==== + +==== Software Discovery + +The initial set of CMO extensions requires the following information to be +discovered by software: + +* The size of the cache block for management and prefetch instructions +* The size of the cache block for zero instructions +* CBIE support at each privilege level + +Other general cache characteristics may also be specified in the discovery +mechanism. + +[#csr_state,reftext="Control and Status Register State"] +=== CSR controls for CMO instructions + +The x{csrname} registers control CBO instruction execution based on the current +privilege mode and the state of the appropriate CSRs, as detailed below. + +[[norm:cbo-inval]] +A `CBO.INVAL` instruction executes or raises either an illegal-instruction +exception or a virtual-instruction exception based on the state of the +`x{csrname}.CBIE` fields: + +[source,sail,subs="attributes+"] +-- + +// illegal-instruction exceptions +if (((priv_mode != M) && (m{csrname}.CBIE == 00)) || + ((priv_mode == U) && (s{csrname}.CBIE == 00))) +{ + +} +// virtual-instruction exceptions +else if (((priv_mode == VS) && (h{csrname}.CBIE == 00)) || + ((priv_mode == VU) && ((h{csrname}.CBIE == 00) || (s{csrname}.CBIE == 00)))) +{ + +} +// execute instruction +else +{ + if (((priv_mode != M) && (m{csrname}.CBIE == 01)) || + ((priv_mode == U) && (s{csrname}.CBIE == 01)) || + ((priv_mode == VS) && (h{csrname}.CBIE == 01)) || + ((priv_mode == VU) && ((h{csrname}.CBIE == 01) || (s{csrname}.CBIE == 01)))) + { + + } + else + { + + } +} + + +-- + +[NOTE] +==== +_Until a modified cache block has updated memory, a `CBO.INVAL` instruction may +expose stale data values in memory if the CSRs are programmed to perform an +invalidate operation. This behavior may result in a security hole if lower +privileged level software performs an invalidate operation and accesses +sensitive information in memory._ + +_To avoid such holes, higher privileged level software must perform either a +clean or flush operation on the cache block before permitting lower privileged +level software to perform an invalidate operation on the block. Alternatively, +higher privileged level software may program the CSRs so that `CBO.INVAL` +either traps or performs a flush operation in a lower privileged level._ +==== + +[[norm:cbo-clean_cbo-flush]] +A `CBO.CLEAN` or `CBO.FLUSH` instruction executes or raises an illegal-instruction +or virtual-instruction exception based on the state of the +`x{csrname}.CBCFE` bits: + +[source,sail,subs="attributes+"] +-- + +// illegal-instruction exceptions +if (((priv_mode != M) && !m{csrname}.CBCFE) || + ((priv_mode == U) && !s{csrname}.CBCFE)) +{ + +} +// virtual-instruction exceptions +else if (((priv_mode == VS) && !h{csrname}.CBCFE) || + ((priv_mode == VU) && !(h{csrname}.CBCFE && s{csrname}.CBCFE))) +{ + +} +// execute instruction +else +{ + +} + +-- + +[[norm:cbo-zero_basedon_xenvcfg-CBZE]] +Finally, a `CBO.ZERO` instruction executes or raises an illegal-instruction or +virtual-instruction exception based on the state of the `x{csrname}.CBZE` bits: + +[source,sail,subs="attributes+"] +-- + +// illegal-instruction exceptions +if (((priv_mode != M) && !m{csrname}.CBZE) || + ((priv_mode == U) && !s{csrname}.CBZE)) +{ + +} +// virtual-instruction exceptions +else if (((priv_mode == VS) && !h{csrname}.CBZE) || + ((priv_mode == VU) && !(h{csrname}.CBZE && s{csrname}.CBZE))) +{ + +} +// execute instruction +else +{ + +} + +-- + +[[norm:cbxe_unaffected]] +The CBIE/CBCFE/CBZE fields in each `x{csrname}` register do not affect the +read and write behavior of the same fields in the other `x{csrname}` registers. + +Each `x{csrname}` register is WARL; however, software should determine the legal +values from the execution environment discovery mechanism. + +[#extensions,reftext="Extensions"] +=== Extensions + +CMO instructions are defined in the following extensions: + +* <<#Zicbom>> +* <<#Zicboz>> +* <<#Zicbop>> + +[#Zicbom,reftext="Cache-Block Management Instructions"] +==== Cache-Block Management Instructions + +Cache-block management instructions enable software running on a set of coherent +agents to communicate with a set of non-coherent agents by performing one of the +following operations: + +* An invalidate operation makes data from store operations performed by a set of + non-coherent agents visible to the set of coherent agents at a point common to + both sets by deallocating all copies of a cache block from the set of coherent + caches up to that point + +* A clean operation makes data from store operations performed by the set of + coherent agents visible to a set of non-coherent agents at a point common to + both sets by performing a write transfer of a copy of a cache block to that + point provided a coherent agent performed a store operation that modified the + data in the cache block since the previous invalidate, clean, or flush + operation on the cache block + +* A flush operation atomically performs a clean operation followed by an + invalidate operation + +In the Zicbom extension, the instructions operate to a point common to _all_ +agents in the system. In other words, an invalidate operation ensures that store +operations from all non-coherent agents visible to agents in the set of coherent +agents, and a clean operation ensures that store operations from coherent agents +visible to all non-coherent agents. + +[NOTE] +==== +_The Zicbom extension does not prohibit agents that fall outside of the above +architectural definition; however, software cannot rely on the defined cache +operations to have the desired effects with respect to those agents._ + +_Future extensions may define different sets of agents for the purposes of +performance optimization._ +==== + +These instructions operate on the cache block whose effective address is +specified in _rs1_. The effective address is translated into a corresponding +physical address by the appropriate translation mechanisms. + +The following instructions comprise the Zicbom extension: + +[%header,cols="^1,^1,4,8"] +|=== +|RV32 +|RV64 +|Mnemonic +|Instruction + +|{check} +|{check} +|cbo.clean _base_ +|<<#insns-cbo_clean>> + +|{check} +|{check} +|cbo.flush _base_ +|<<#insns-cbo_flush>> + +|{check} +|{check} +|cbo.inval _base_ +|<<#insns-cbo_inval>> + +|=== + +[NOTE] +==== +_Cache-block management instructions ignore cacheability attributes and operate +on the cache block irrespective of the PMA cacheable attribute and any Page-Based +Memory Type (PBMT) downgrade from cacheable to non-cacheable._ +==== + +[#Zicboz,reftext="Cache-Block Zero Instructions"] +==== Cache-Block Zero Instructions + +Cache-block zero instructions store zeros to the set of bytes corresponding to a +cache block. An implementation may update the bytes in any order and with any +granularity and atomicity, including individual bytes. + +[NOTE] +==== +_Cache-block zero instructions store zeros independently of whether data from +the underlying memory locations are cacheable. In addition, this specification +does not constrain how the bytes are written._ +==== + +[#norm:cbo-zero_specified_block]#These instructions operate on the cache block, or the memory locations +corresponding to the cache block, whose effective address is specified in _rs1_.# +The effective address is translated into a corresponding physical address by the +appropriate translation mechanisms. + +The following instructions comprise the Zicboz extension: + +[%header,cols="^1,^1,4,8"] +|=== +|RV32 +|RV64 +|Mnemonic +|Instruction + +|{check} +|{check} +|cbo.zero _base_ +|<<#insns-cbo_zero>> + +|=== + +[#Zicbop,reftext="Cache-Block Prefetch Instructions"] +==== Cache-Block Prefetch Instructions + +Cache-block prefetch instructions are HINTs to the hardware to indicate that +software intends to perform a particular type of memory access in the near +future. The types of memory accesses are instruction fetch, data read (i.e. +load), and data write (i.e. store). + +[#norm:prefetch_operating_block]#These instructions operate on the cache block whose effective address is the sum +of the base address specified in _rs1_ and the sign-extended offset encoded in +_imm[11:0]_, where _imm[4:0]_ shall equal `0b00000`.# The effective address is +translated into a corresponding physical address by the appropriate translation +mechanisms. + +[NOTE] +==== +_Cache-block prefetch instructions are encoded as ORI instructions with rd equal +to `0b00000`; however, for the purposes of effective address calculation, this +field is also interpreted as imm[4:0] like a store instruction._ +==== + +The following instructions comprise the Zicbop extension: + +[%header,cols="^1,^1,4,8"] +|=== +|RV32 +|RV64 +|Mnemonic +|Instruction + +|{check} +|{check} +|prefetch.i _offset_(_base_) +|<<#insns-prefetch_i>> + +|{check} +|{check} +|prefetch.r _offset_(_base_) +|<<#insns-prefetch_r>> + +|{check} +|{check} +|prefetch.w _offset_(_base_) +|<<#insns-prefetch_w>> + +|=== + +[#insns,reftext="Instructions"] +=== Instructions + +[#insns-cbo_clean,reftext="Cache Block Clean"] +==== cbo.clean + +Synopsis:: +Perform a clean operation on a cache block + +Mnemonic:: +cbo.clean _offset_(_base_) + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0xF, attr: ['MISC-MEM'] }, + { bits: 5, name: 0x0 }, + { bits: 3, name: 0x2, attr: ['CBO'] }, + { bits: 5, name: 'rs1', attr: ['base'] }, + { bits: 12, name: 0x001, attr: ['CBO.CLEAN'] }, +]} +.... + +Description:: + +[#norm:cbo-clean_op]#A *cbo.clean* instruction performs a clean operation on the cache block whose +effective address is the base address specified in _rs1_.# [#norm:cbo-clean_offset]#The offset operand may +be omitted; otherwise, any expression that computes the offset shall evaluate to +zero.# The instruction operates on the set of coherent caches accessed by the +agent executing the instruction. + +[NOTE] +==== +_When executing a *cbo.clean* instruction, an implementation may instead perform +a flush operation, since the result of that operation is indistinguishable from +the sequence of performing a clean operation just before deallocating all cached +copies in the set of coherent caches._ +==== + +[#insns-cbo_flush,reftext="Cache Block Flush"] +==== cbo.flush + +Synopsis:: +Perform a flush operation on a cache block + +Mnemonic:: +cbo.flush _offset_(_base_) + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0xF, attr: ['MISC-MEM'] }, + { bits: 5, name: 0x0 }, + { bits: 3, name: 0x2, attr: ['CBO'] }, + { bits: 5, name: 'rs1', attr: ['base'] }, + { bits: 12, name: 0x002, attr: ['CBO.FLUSH'] }, +]} +.... + +Description:: + +[#norm:cbo-flush_op]#A *cbo.flush* instruction performs a flush operation on the cache block whose +that contains the address specified in _rs1_.# [#norm:cbo-flush_unaligned]#It is not required that _rs1_ is +aligned to the size of a cache block.# On faults, the faulting virtual address +is considered to be the value in rs1, rather than the base address of the cache +block. The instruction operates on the set of coherent caches accessed by the +agent executing the instruction. + +The assembly _offset_ operand may be omitted. If it isn't then any expression +that computes the offset shall evaluate to zero. + +[#insns-cbo_inval,reftext="Cache Block Invalidate"] +==== cbo.inval + +Synopsis:: +Perform an invalidate operation on a cache block + +Mnemonic:: +cbo.inval _offset_(_base_) + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0xF, attr: ['MISC-MEM'] }, + { bits: 5, name: 0x0 }, + { bits: 3, name: 0x2, attr: ['CBO'] }, + { bits: 5, name: 'rs1', attr: ['base'] }, + { bits: 12, name: 0x000, attr: ['CBO.INVAL'] }, +]} +.... + +Description:: + +[#norm:cbo-inval_op]#A *cbo.inval* instruction performs an invalidate operation on the cache block +that contains the address specified in _rs1_.# [#norm:cbo-inval_unaligned]#It is not required that _rs1_ is +aligned to the size of a cache block.# On faults, the faulting virtual address +is considered to be the value in rs1, rather than the base address of the cache +block. The instruction operates on the set of coherent caches accessed by the +agent executing the instruction. + +Depending on CSR programming, the instruction may perform a flush operation +instead of an invalidate operation. + +The assembly _offset_ operand may be omitted. If it isn't then any expression +that computes the offset shall evaluate to zero. + +[NOTE] +==== +_When executing a *cbo.inval* instruction, an implementation may instead perform +a flush operation, since the result of that operation is indistinguishable from +the sequence of performing a write transfer to memory just before performing an +invalidate operation._ +==== + +[#insns-cbo_zero,reftext="Cache Block Zero"] +==== cbo.zero + +Synopsis:: +Store zeros to the full set of bytes corresponding to a cache block + +Mnemonic:: +cbo.zero _offset_(_base_) + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0xF, attr: ['MISC-MEM'] }, + { bits: 5, name: 0x0 }, + { bits: 3, name: 0x2, attr: ['CBO'] }, + { bits: 5, name: 'rs1', attr: ['base'] }, + { bits: 12, name: 0x004, attr: ['CBO.ZERO'] }, +]} +.... + +Description:: + +[#norm:cbo-zero_op]#A *cbo.zero* instruction performs stores of zeros to the full set of bytes +corresponding to the cache block that contains the address specified in _rs1_.# +[#norm:cbo-zero_unaligned]#It is not required that _rs1_ is aligned to the size of a cache block.# On +faults, the faulting virtual address is considered to be the value in rs1, +rather than the base address of the cache block. An implementation may or +may not update the entire set of bytes atomically. + +[[norm:cbo-zero_offset]] +The assembly _offset_ operand may be omitted. If it isn't then any expression +that computes the offset shall evaluate to zero. + +[#insns-prefetch_i,reftext="Cache Block Prefetch for Instruction Fetch"] +==== prefetch.i + +Synopsis:: +Provide a HINT to hardware that a cache block is likely to be accessed by an +instruction fetch in the near future + +Mnemonic:: +prefetch.i _offset_(_base_) + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x13, attr: ['OP-IMM'] }, + { bits: 5, name: 0x0, attr: ['offset[4:0]'] }, + { bits: 3, name: 0x6, attr: ['ORI'] }, + { bits: 5, name: 'rs1', attr: ['base'] }, + { bits: 5, name: 0x0, attr: ['PREFETCH.I'] }, + { bits: 7, name: 'imm[11:5]', attr: ['offset[11:5]'] }, +]} +.... + +Description:: + +[[norm:prefetch-i_op]] +A *prefetch.i* instruction indicates to hardware that the cache block whose +effective address is the sum of the base address specified in _rs1_ and the +sign-extended offset encoded in _imm[11:0]_, where _imm[4:0]_ equals `0b00000`, +is likely to be accessed by an instruction fetch in the near future. + +[NOTE] +==== +_An implementation may opt to cache a copy of the cache block in a cache +accessed by an instruction fetch in order to improve memory access latency, but +this behavior is not required._ +==== + +[#insns-prefetch_r,reftext="Cache Block Prefetch for Data Read"] +==== prefetch.r + +Synopsis:: +Provide a HINT to hardware that a cache block is likely to be accessed by a data +read in the near future + +Mnemonic:: +prefetch.r _offset_(_base_) + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x13, attr: ['OP-IMM'] }, + { bits: 5, name: 0x0, attr: ['offset[4:0]'] }, + { bits: 3, name: 0x6, attr: ['ORI'] }, + { bits: 5, name: 'rs1', attr: ['base'] }, + { bits: 5, name: 0x1, attr: ['PREFETCH.R'] }, + { bits: 7, name: 'imm[11:5]', attr: ['offset[11:5]'] }, +]} +.... + +Description:: + +[[norm:prefetch-r_op]] +A *prefetch.r* instruction indicates to hardware that the cache block whose +effective address is the sum of the base address specified in _rs1_ and the +sign-extended offset encoded in _imm[11:0]_, where _imm[4:0]_ equals `0b00000`, +is likely to be accessed by a data read (i.e. load) in the near future. + +[NOTE] +==== +_An implementation may opt to cache a copy of the cache block in a cache +accessed by a data read in order to improve memory access latency, but this +behavior is not required._ +==== + +[#insns-prefetch_w,reftext="Cache Block Prefetch for Data Write"] +==== prefetch.w + +Synopsis:: +Provide a HINT to hardware that a cache block is likely to be accessed by a data +write in the near future + +Mnemonic:: +prefetch.w _offset_(_base_) + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x13, attr: ['OP-IMM'] }, + { bits: 5, name: 0x0, attr: ['offset[4:0]'] }, + { bits: 3, name: 0x6, attr: ['ORI'] }, + { bits: 5, name: 'rs1', attr: ['base'] }, + { bits: 5, name: 0x3, attr: ['PREFETCH.W'] }, + { bits: 7, name: 'imm[11:5]', attr: ['offset[11:5]'] }, +]} +.... + +Description:: + +[[norm:prefetch-w_op]] +A *prefetch.w* instruction indicates to hardware that the cache block whose +effective address is the sum of the base address specified in _rs1_ and the +sign-extended offset encoded in _imm[11:0]_, where _imm[4:0]_ equals `0b00000`, +is likely to be accessed by a data write (i.e. store) in the near future. + +[NOTE] +==== +_An implementation may opt to cache a copy of the cache block in a cache +accessed by a data write in order to improve memory access latency, but this +behavior is not required._ +==== diff --git a/param_extraction/chunks/chunk_008.txt.license b/param_extraction/chunks/chunk_008.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_008.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_009.txt b/param_extraction/chunks/chunk_009.txt new file mode 100644 index 0000000000..1a3e88255a --- /dev/null +++ b/param_extraction/chunks/chunk_009.txt @@ -0,0 +1,473 @@ +# Chunk: chunk_009 +# Source: colophon.adoc +# Lines: 1-465 (of 465) +# Content starts: line 1 +# Line count: 465 +# Sections: 1 +# == Preface +# +[colophon] +== Preface +// Had to make the above a level 1 heading (two equals signs) to avoid error when building +// the ISA manual as a book with other "parts". This is opposite to what the adoc says to do +// but otherwise asciidoctor creates the error message: +// +// asciidoctor: ERROR: ext/riscv-isa-manual/src/colophon.adoc: line 2: invalid part, must have at least one section (e.g., chapter, appendix, etc.) +// +// See asciidoctor doc which seems wrong: https://docs.asciidoctor.org/asciidoc/latest/sections/colophon/ +[.big]*_Preface to Document Version 20250508_* + +This document describes the RISC-V unprivileged architecture. + +The ISA modules marked *Ratified* have been ratified at this time. The +modules marked _Frozen_ are not expected to change significantly before +being put up for ratification. The modules marked _Draft_ are expected +to change before ratification. + +The document contains the following versions of the RISC-V ISA modules: + +[%autowidth,float="center",align="center",cols="^,<,^",options="header"] +|=== +|Base |Version |Status +|*RV32I* |*2.1* |*Ratified* +|*RV32E* |*2.0* |*Ratified* +|*RV64E* |*2.0* |*Ratified* +|*RV64I* |*2.1* |*Ratified* + +h|Extension h|Version h|Status + +|*Zifencei* |*2.0* |*Ratified* +|*Zicsr* |*2.0* |*Ratified* +|*Zicntr* |*2.0* |*Ratified* +|*Zihintntl* |*1.0* |*Ratified* +|*Zihintpause* |*2.0* |*Ratified* +|*Zimop* | *1.0* | *Ratified* +|*Zicond* | *1.0* |*Ratified* +|*Zilsd* | *1.0* |*Ratified* +|*M* |*2.0* |*Ratified* +|*Zmmul* |*1.0* |*Ratified* +|*A* |*2.1* |*Ratified* +|*Zawrs* |*1.01* |*Ratified* +|*Zacas* |*1.0* |*Ratified* +|*Zabha* |*1.0* |*Ratified* +|*Zalasr* |*1.0* |*Ratified* +|*RVWMO* |*2.0* |*Ratified* +|*Ztso* |*1.0* |*Ratified* +|*CMO* |*1.0* |*Ratified* +|*F* |*2.2* |*Ratified* +|*D* |*2.2* |*Ratified* +|*Q* |*2.2* |*Ratified* +|*Zfh* |*1.0* |*Ratified* +|*Zfhmin* |*1.0* |*Ratified* +|*BF16* |*1.0* |*Ratified* +|*Zfa* |*1.0* |*Ratified* +|*Zfinx* |*1.0* |*Ratified* +|*Zdinx* |*1.0* |*Ratified* +|*Zhinx* |*1.0* |*Ratified* +|*Zhinxmin* |*1.0* |*Ratified* +|*C* |*2.0* |*Ratified* +|*Zce* |*1.0* |*Ratified* +|*Zclsd* |*1.0* |*Ratified* +|*B* |*1.0* |*Ratified* +|*V* |*1.0* |*Ratified* +|*Zbkb* |*1.0* |*Ratified* +|*Zbkc* |*1.0* |*Ratified* +|*Zbkx* |*1.0* |*Ratified* +|*Zk* |*1.0* |*Ratified* +|*Zks* |*1.0* |*Ratified* +|*Zvbb* |*1.0* |*Ratified* +|*Zvbc* |*1.0* |*Ratified* +|*Zvkg* |*1.0* |*Ratified* +|*Zvkned* |*1.0* |*Ratified* +|*Zvknhb* |*1.0* |*Ratified* +|*Zvksed* |*1.0* |*Ratified* +|*Zvksh* |*1.0* |*Ratified* +|*Zvkt* |*1.0* |*Ratified* +|*Zicfiss* |*1.0* |*Ratified* +|*Zicfilp* |*1.0* |*Ratified* +|=== + +The changes in this version of the document include: + +* The inclusion of all ratified extensions through May 2025. +* Removal of all unratified material. +* Addition of the BFloat16-precision Floating Point extension. +* Addition of the Zabha extension for Byte and Halfword Atomic Memory Operations. + + +[.big]*_Preface to Document Version 20240411_* + +This document describes the RISC-V unprivileged architecture. +It contains the following versions of the RISC-V ISA modules: + +[%autowidth,float="center",align="center",cols="^,<,^",options="header"] +|=== +|Base |Version |Status +|*RV32I* |*2.1* |*Ratified* +|*RV32E* |*2.0* |*Ratified* +|*RV64E* |*2.0* |*Ratified* +|*RV64I* |*2.1* |*Ratified* + +h|Extension h|Version h|Status + +|*Zifencei* |*2.0* |*Ratified* +|*Zicsr* |*2.0* |*Ratified* +|*Zicntr* |*2.0* |*Ratified* +|*Zihintntl* |*1.0* |*Ratified* +|*Zihintpause* |*2.0* |*Ratified* +|*Zimop* | *1.0* | *Ratified* +|*Zicond* | *1.0* |*Ratified* +|*Zilsd* | *1.0* |*Ratified* +|*M* |*2.0* |*Ratified* +|*Zmmul* |*1.0* |*Ratified* +|*A* |*2.1* |*Ratified* +|*Zawrs* |*1.01* |*Ratified* +|*Zacas* |*1.0* |*Ratified* +|*Zabha* |*1.0* |*Ratified* +|*RVWMO* |*2.0* |*Ratified* +|*Ztso* |*1.0* |*Ratified* +|*CMO* |*1.0* |*Ratified* +|*F* |*2.2* |*Ratified* +|*D* |*2.2* |*Ratified* +|*Q* |*2.2* |*Ratified* +|*Zfh* |*1.0* |*Ratified* +|*Zfhmin* |*1.0* |*Ratified* +|*Zfa* |*1.0* |*Ratified* +|*Zfinx* |*1.0* |*Ratified* +|*Zdinx* |*1.0* |*Ratified* +|*Zhinx* |*1.0* |*Ratified* +|*Zhinxmin* |*1.0* |*Ratified* +|*C* |*2.0* |*Ratified* +|*Zce* |*1.0* |*Ratified* +|*Zclsd* |*1.0* |*Ratified* +|*B* |*1.0* |*Ratified* +|*V* |*1.0* |*Ratified* +|*Zbkb* |*1.0* |*Ratified* +|*Zbkc* |*1.0* |*Ratified* +|*Zbkx* |*1.0* |*Ratified* +|*Zk* |*1.0* |*Ratified* +|*Zks* |*1.0* |*Ratified* +|*Zvbb* |*1.0* |*Ratified* +|*Zvbc* |*1.0* |*Ratified* +|*Zvkg* |*1.0* |*Ratified* +|*Zvkned* |*1.0* |*Ratified* +|*Zvknhb* |*1.0* |*Ratified* +|*Zvksed* |*1.0* |*Ratified* +|*Zvksh* |*1.0* |*Ratified* +|*Zvkt* |*1.0* |*Ratified* +|*Zicfiss* |*1.0* |*Ratified* +|*Zicfilp* |*1.0* |*Ratified* +|=== + +The changes in this version of the document include: + +* The inclusion of all ratified extensions through February 2025. +* The draft Zam extension has been removed, in favor of the definition of a misaligned atomicity granule PMA. +* The concept of vacant memory regions has been superseded by inaccessible memory or I/O regions. +* The removal of unratified content, including the sketch of the RV128I base ISA. + +[.big]*_Preface to Document Version 20191213-Base-Ratified_* + +This document describes the RISC-V unprivileged architecture. + +The ISA modules marked *Ratified* have been ratified at this time. The +modules marked _Frozen_ are not expected to change significantly before +being put up for ratification. The modules marked _Draft_ are expected +to change before ratification. + +The document contains the following versions of the RISC-V ISA modules: + +[%autowidth,float="center",align="center",cols="^,<,^",options="header",] +|=== +|Base |Version |Status +|RVWMO |2.0 |*Ratified* +|*RV32I* |*2.1* |*Ratified* +|*RV64I* |*2.1* |*Ratified* +|_RV32E_ |_1.9_ |_Draft_ +|_RV128I_ |_1.7_ |_Draft_ +h|Extension h|Version h|Status +|*M* |*2.0* |*Ratified* +|*A* |*2.1* |*Ratified* +|*F* |*2.2* |*Ratified* +|*D* |*2.2* |*Ratified* +|*Q* |*2.2* |*Ratified* +|*C* |*2.0* |*Ratified* +|_Counters_ |_2.0_ |_Draft_ +|_L_ |_0.0_ |_Draft_ +|_B_ |_0.0_ |_Draft_ +|_J_ |_0.0_ |_Draft_ +|_T_ |_0.0_ |_Draft_ +|_P_ |_0.2_ |_Draft_ +|_V_ |_0.7_ |_Draft_ +|*Zicsr* |*2.0* |*Ratified* +|*Zifencei* |*2.0* |*Ratified* +|_Zam_ |_0.1_ |_Draft_ +|_Ztso_ |_0.1_ |_Frozen_ +|=== + +The changes in this version of the document include: + +* The A extension, now version 2.1, was ratified by the board in +December 2019. +* Defined big-endian ISA variant. +* Moved N extension for user-mode interrupts into Volume II. +* Defined PAUSE hint instruction. + +[.big]*_Preface to Document Version 20190608-Base-Ratified_* + +This document describes the RISC-V unprivileged architecture. + +The RVWMO memory model has been ratified at this time. The ISA modules +marked *Ratified*, have been ratified at this time. The modules marked +_Frozen_ are not expected to change significantly before being put up +for ratification. The modules marked _Draft_ are expected to change +before ratification. + +The document contains the following versions of the RISC-V ISA modules: + +[%autowidth,float="center",align="center",cols="^,<,^",options="header",] +|=== +|Base |Version |Status +|RVWMO |2.0 |*Ratified* +|*RV32I* |*2.1* |*Ratified* +|*RV64I* |*2.1* |*Ratified* +|_RV32E_ |_1.9_ |_Draft_ +|_RV128I_ |_1.7_ |_Draft_ +h|Extension h|Version h|Status +|*Zifencei* |*2.0* |*Ratified* +|*Zicsr* |*2.0* |*Ratified* +|*M* |*2.0* |*Ratified* +|_A_ |_2.0_ |Frozen +|*F* |*2.2* |*Ratified* +|*D* |*2.2* |*Ratified* +|*Q* |*2.2* |*Ratified* +|*C* |*2.0* |*Ratified* +|_Ztso_ |_0.1_ |_Frozen_ +|_Counters_ |_2.0_ |_Draft_ +|_L_ |_0.0_ |_Draft_ +|_B_ |_0.0_ |_Draft_ +|_J_ |_0.0_ |_Draft_ +|_T_ |_0.0_ |_Draft_ +|_P_ |_0.2_ |_Draft_ +|_V_ |_0.7_ |_Draft_ +|_Zam_ |_0.1_ |_Draft_ +|=== + +The changes in this version of the document include: + +* Moved description to *Ratified* for the ISA modules ratified by the +board in early 2019. +* Removed the A extension from ratification. +* Changed document version scheme to avoid confusion with versions of +the ISA modules. +* Incremented the version numbers of the base integer ISA to 2.1, +reflecting the presence of the ratified RVWMO memory model and exclusion +of FENCE.I, counters, and CSR instructions that were in previous base +ISA. +* Incremented the version numbers of the F and D extensions to 2.2, +reflecting that version 2.1 changed the canonical NaN, and version 2.2 +defined the NaN-boxing scheme and changed the definition of the FMIN and +FMAX instructions. +* Changed name of document to refer to "unprivileged" instructions as +part of move to separate ISA specifications from platform profile +mandates. +* Added clearer and more precise definitions of execution environments, +harts, traps, and memory accesses. +* Defined instruction-set categories: _standard_, _reserved_, _custom_, +_non-standard_, and _non-conforming_. +* Removed text implying operation under alternate endianness, as +alternate-endianness operation has not yet been defined for RISC-V. +* Changed description of misaligned load and store behavior. The +specification now allows visible misaligned address traps in execution +environment interfaces, rather than just mandating invisible handling of +misaligned loads and stores in user mode. Also, now allows access-fault +exceptions to be reported for misaligned accesses (including atomics) +that should not be emulated. +* Moved FENCE.I out of the mandatory base and into a separate extension, +with Zifencei ISA name. FENCE.I was removed from the Linux user ABI and +is problematic in implementations with large incoherent instruction and +data caches. However, it remains the only standard instruction-fetch +coherence mechanism. +* Removed prohibitions on using RV32E with other extensions. +* Removed platform-specific mandates that certain encodings produce +illegal-instruction exceptions in RV32E and RV64I chapters. +* Counter/timer instructions are now not considered part of the +mandatory base ISA, and so CSR instructions were moved into separate +chapter and marked as version 2.0, with the unprivileged counters moved +into another separate chapter. The counters are not ready for +ratification as there are outstanding issues, including counter +inaccuracies. +* A CSR-access ordering model has been added. +* Explicitly defined the 16-bit half-precision floating-point format for +floating-point instructions in the 2-bit _fmt field._ +* Defined the signed-zero behavior of FMIN._fmt_ and FMAX._fmt_, and +changed their behavior on signaling-NaN inputs to conform to the +`minimumNumber` and `maximumNumber` operations in the proposed IEEE 754-201x +specification. +* The memory consistency model, RVWMO, has been defined. +* The "Zam" extension, which permits misaligned AMOs and specifies +their semantics, has been defined. +* The "Ztso" extension, which enforces a stricter memory consistency +model than RVWMO, has been defined. +* Improvements to the description and commentary. +* Defined the term `IALIGN` as shorthand to describe the +instruction-address alignment constraint. +* Removed text of `P` extension chapter as now superseded by active task +group documents. +* Removed text of `V` extension chapter as now superseded by separate +vector extension draft document. + +[.big]*_Preface to Document Version 2.2_* + +This is version 2.2 of the document describing the RISC-V user-level +architecture. The document contains the following versions of the RISC-V +ISA modules: + +[%autowidth,float="center",align="center",cols="^,<,^",options="header",] +|=== +h|Base h|_Version_ h|_Draft Frozen?_ +|RV32I |2.0 |Y +|RV32E |1.9 |N +|RV64I |2.0 |Y +|RV128I |1.7 |N +h|Extension h|Version h|Frozen? +|M |2.0 |Y +|A |2.0 |Y +|F |2.0 |Y +|D |2.0 |Y +|Q |2.0 |Y +|L |0.0 |N +|C |2.0 |Y +|B |0.0 |N +|J |0.0 |N +|T |0.0 |N +|P |0.1 |N +|V |0.7 |N +|N |1.1 |N +|=== + +To date, no parts of the standard have been officially ratified by the +RISC-V Foundation, but the components labeled "frozen" above are not +expected to change during the ratification process beyond resolving +ambiguities and holes in the specification. + +The major changes in this version of the document include: + +* The previous version of this document was released under a Creative +Commons Attribution 4.0 International License by the original authors, +and this and future versions of this document will be released under the +same license. +* Rearranged chapters to put all extensions first in canonical order. +* Improvements to the description and commentary. +* Modified implicit hinting suggestion on `JALR` to support more efficient +macro-op fusion of `LUI/JALR` and `AUIPC/JALR` pairs. +* Clarification of constraints on load-reserved/store-conditional +sequences. +* A new table of control and status register (CSR) mappings. +* Clarified purpose and behavior of high-order bits of `fcsr`. +* Corrected the description of the `FNMADD`._fmt_ and `FNMSUB`._fmt_ +instructions, which had suggested the incorrect sign of a zero result. +* Instructions `FMV.S.X` and `FMV.X.S` were renamed to `FMV.W.X` and `FMV.X.W` +respectively to be more consistent with their semantics, which did not +change. The old names will continue to be supported in the tools. +* Specified behavior of narrower (64 bits to +avoid moving the _rd_ specifier in very long instruction formats. +* CSR instructions are now described in the base integer format where +the counter registers are introduced, as opposed to only being +introduced later in the floating-point section (and the companion +privileged architecture manual). +* The SCALL and SBREAK instructions have been renamed to `ECALL` and +`EBREAK`, respectively. Their encoding and functionality are unchanged. +* Clarification of floating-point NaN handling, and a new canonical NaN +value. +* Clarification of values returned by floating-point to integer +conversions that overflow. +* Clarification of `LR/SC` allowed successes and required failures, +including use of compressed instructions in the sequence. +* A new `RV32E` base ISA proposal for reduced integer register counts, +supports `MAC` extensions. +* A revised calling convention. +* Relaxed stack alignment for soft-float calling convention, and +description of the RV32E calling convention. +* A revised proposal for the `C` compressed extension, version 1.9 . + +[.big]*_Preface to Version 2.0_* + +This is the second release of the user ISA specification, and we intend +the specification of the base user ISA plus general extensions (i.e., +IMAFD) to remain fixed for future development. The following changes +have been made since Version 1.0 cite:[riscvtr] of this ISA specification. + +* The ISA has been divided into an integer base with several standard +extensions. +* The instruction formats have been rearranged to make immediate +encoding more efficient. +* The base ISA has been defined to have a little-endian memory system, +with big-endian or bi-endian as non-standard variants. +* Load-Reserved/Store-Conditional (`LR/SC`) instructions have been added +in the atomic instruction extension. +* `AMOs` and `LR/SC` can support the release consistency model. +* The `FENCE` instruction provides finer-grain memory and I/O orderings. +* An `AMO` for fetch-and-`XOR` (`AMOXOR`) has been added, and the encoding for +`AMOSWAP` has been changed to make room. +* The `AUIPC` instruction, which adds a 20-bit upper immediate to the `PC`, +replaces the `RDNPC` instruction, which only read the current `PC` value. +This results in significant savings for position-independent code. +* The `JAL` instruction has now moved to the `U-Type` format with an +explicit destination register, and the `J` instruction has been dropped +being replaced by `JAL` with _rd_=`x0`. This removes the only instruction +with an implicit destination register and removes the `J-Type` instruction +format from the base ISA. There is an accompanying reduction in `JAL` +reach, but a significant reduction in base ISA complexity. +* The static hints on the `JALR` instruction have been dropped. The hints +are redundant with the _rd_ and _rs1_ register specifiers for code +compliant with the standard calling convention. +* The `JALR` instruction now clears the lowest bit of the calculated +target address, to simplify hardware and to allow auxiliary information +to be stored in function pointers. +* The `MFTX.S` and `MFTX.D` instructions have been renamed to `FMV.X.S` and +`FMV.X.D`, respectively. Similarly, `MXTF.S` and `MXTF.D` instructions have +been renamed to `FMV.S.X` and `FMV.D.X`, respectively. +* The `MFFSR` and `MTFSR` instructions have been renamed to `FRCSR` and `FSCSR`, +respectively. `FRRM`, `FSRM`, `FRFLAGS`, and `FSFLAGS` instructions have been +added to individually access the rounding mode and exception flags +subfields of the `fcsr`. +* The `FMV.X.S` and `FMV.X.D` instructions now source their operands from +_rs1_, instead of _rs2_. This change simplifies datapath design. +* `FCLASS.S` and `FCLASS.D` floating-point classify instructions have been +added. +* A simpler NaN generation and propagation scheme has been adopted. +* For `RV32I`, the system performance counters have been extended to +64-bits wide, with separate read access to the upper and lower 32 bits. +* Canonical `NOP` and `MV` encodings have been defined. +* Standard instruction-length encodings have been defined for 48-bit, +64-bit, and >64-bit instructions. +* Description of a 128-bit address space variant, `RV128`, has been added. +* Major opcodes in the 32-bit base instruction format have been +allocated for user-defined custom extensions. +* A typographical error that suggested that stores source their data +from _rd_ has been corrected to refer to _rs2_. diff --git a/param_extraction/chunks/chunk_009.txt.license b/param_extraction/chunks/chunk_009.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_009.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_010.txt b/param_extraction/chunks/chunk_010.txt new file mode 100644 index 0000000000..98420a4ea7 --- /dev/null +++ b/param_extraction/chunks/chunk_010.txt @@ -0,0 +1,247 @@ +# Chunk: chunk_010 +# Source: counters.adoc +# Lines: 1-237 (of 237) +# Content starts: line 1 +# Line count: 237 +# Sections: 3 +# == "Zicntr" and "Zihpm" Extensions for Counters, Version 2.0 +# === "Zicntr" Extension for Base Counters and Timers +# === "Zihpm" Extension for Hardware Performance Counters +# +[[counters]] +== "Zicntr" and "Zihpm" Extensions for Counters, Version 2.0 + +[[norm:zihpm_op_sz_mode_acc]] +RISC-V ISAs provide a set of up to thirty-two 64-bit performance +counters and timers that are accessible via unprivileged XLEN-bit +read-only CSR registers `0xC00`–`0xC1F` (when XLEN=32, the upper 32 bits +are accessed via CSR registers `0xC80`–`0xC9F`). These counters are +divided between the "Zicntr" and "Zihpm" extensions. + +=== "Zicntr" Extension for Base Counters and Timers + +The Zicntr standard extension comprises the first three of these +counters (CYCLE, TIME, and INSTRET), which have dedicated functions +(cycle count, real-time clock, and instructions retired, respectively). +The Zicntr extension depends on the Zicsr extension. + +[NOTE] +==== +We recommend provision of these basic counters in implementations as +they are essential for basic performance analysis, adaptive and dynamic +optimization, and to allow an application to work with real-time +streams. Additional counters in the separate Zihpm extension can help +diagnose performance problems and these should be made accessible from +user-level application code with low overhead. + +Some execution environments might prohibit access to counters, for +example, to impede timing side-channel attacks. +==== + +include::images/wavedrom/counters-diag.edn[] + +For base ISAs with XLEN{ge}64, CSR instructions can access +the full 64-bit CSRs directly. In particular, the RDCYCLE, RDTIME, and +RDINSTRET pseudoinstructions read the full 64 bits of the `cycle`, +`time`, and `instret` counters. + +[NOTE] +==== +The counter pseudoinstructions are mapped to the read-only +`csrrs rd, counter, x0` canonical form, but the other read-only CSR +instruction forms (based on CSRRC/CSRRSI/CSRRCI) are also legal ways to +read these CSRs. +==== +For base ISAs with XLEN=32, the Zicntr extension enables the three +64-bit read-only counters to be accessed in 32-bit pieces. The RDCYCLE, +RDTIME, and RDINSTRET pseudoinstructions provide the lower 32 bits, and +the RDCYCLEH, RDTIMEH, and RDINSTRETH pseudoinstructions provide the +upper 32 bits of the respective counters. +[NOTE] +==== +We required the counters be 64 bits wide, even when XLEN=32, as +otherwise it is very difficult for software to determine if values have +overflowed. +The sample code +given below shows how the full 64-bit width value can be safely read +using the individual 32-bit width pseudoinstructions. +==== + +[#norm:zicntr_rdcycle_op]#The RDCYCLE pseudoinstruction reads the low XLEN bits of the `cycle` +CSR which holds a count of the number of clock cycles executed by the +processor core on which the hart is running from an arbitrary start time +in the past. RDCYCLEH is only present when XLEN=32 and reads bits 63-32 +of the same cycle counter.# The underlying 64-bit counter should never +overflow in practice. The rate at which the cycle counter advances will +depend on the implementation and operating environment. The execution +environment should provide a means to determine the current rate +(cycles/second) at which the cycle counter is incrementing. +[NOTE] +==== +RDCYCLE is intended to return the number of cycles executed by the +processor core, not the hart. Precisely defining what is a "core" is +difficult given some implementation choices (e.g., AMD Bulldozer). +Precisely defining what is a "clock cycle" is also difficult given the +range of implementations (including software emulations), but the intent +is that RDCYCLE is used for performance monitoring along with the other +performance counters. In particular, where there is one hart/core, one +would expect cycle-count/instructions-retired to measure CPI for a hart. + +Cores don't have to be exposed to software at all, and an implementer +might choose to pretend multiple harts on one physical core are running +on separate cores with one hart/core, and provide separate cycle +counters for each hart. This might make sense in a simple barrel +processor (e.g., CDC 6600 peripheral processors) where inter-hart timing +interactions are non-existent or minimal. + +Where there is more than one hart/core and dynamic multithreading, it is +not generally possible to separate out cycles per hart (especially with +SMT). It might be possible to define a separate performance counter that +tried to capture the number of cycles a particular hart was running, but +this definition would have to be very fuzzy to cover all the possible +threading implementations. For example, should we only count cycles for +which any instruction was issued to execution for this hart, and/or +cycles any instruction retired, or include cycles this hart was +occupying machine resources but couldn't execute due to stalls while +other harts went into execution? Likely, "all of the above" would be +needed to have understandable performance stats. This complexity of +defining a per-hart cycle count, and also the need in any case for a +total per-core cycle count when tuning multithreaded code led to just +standardizing the per-core cycle counter, which also happens to work +well for the common single hart/core case. + +Standardizing what happens during "sleep" is not practical given that +what "sleep" means is not standardized across execution environments, +but if the entire core is paused (entirely clock-gated or powered-down +in deep sleep), then it is not executing clock cycles, and the cycle +count shouldn't be increasing per the spec. There are many details, +e.g., whether clock cycles required to reset a processor after waking up +from a power-down event should be counted, and these are considered +execution-environment-specific details. + +Even though there is no precise definition that works for all platforms, +this is still a useful facility for most platforms, and an imprecise, +common, "usually correct" standard here is better than no standard. +The intent of RDCYCLE was primarily performance monitoring/tuning, and +the specification was written with that goal in mind. +==== +[#norm:zicntr_rdtime_op]#The RDTIME pseudoinstruction reads the low XLEN bits of the "time" CSR, +which counts wall-clock real time that has passed from an arbitrary +start time in the past. RDTIMEH is only present when XLEN=32 and reads +bits 63-32 of the same real-time counter.# The underlying 64-bit counter +increments by one with each tick of the real-time clock, and, for +realistic real-time clock frequencies, should never overflow in +practice. The execution environment should provide a means of +determining the period of a counter tick (seconds/tick). The period +should be constant within a small error bound. The environment should +provide a means to determine the accuracy of the clock (i.e., the +maximum relative error between the nominal and actual real-time clock +periods). +[NOTE] +==== +On some simple platforms, cycle count might represent a valid +implementation of RDTIME, in which case RDTIME and RDCYCLE may return +the same result. + +It is difficult to provide a strict mandate on clock period given the +wide variety of possible implementation platforms. The maximum error +bound should be set based on the requirements of the platform. +==== + +The real-time clocks of all harts must be synchronized to within one +tick of the real-time clock. +[NOTE] +==== +As with other architectural mandates, it suffices to appear "as if" +harts are synchronized to within one tick of the real-time clock, i.e., +software is unable to observe that there is a greater delta between the +real-time clock values observed on two harts. + +If, for example, the real-time clock increments at a frequency of 1 GHz, then +all harts must appear to be synchronized to within 1 nsec. +But it is also acceptable for this example implementation to only update the +real-time clock at, say, a frequency of 100 MHz with increments of 10 ticks. +As long as software cannot observe this seeming violation of the above +synchronization requirement, and software always observes time across harts to +be monotonically nondecreasing, then this implementation is compliant. + +A platform spec may then, for example, specify an apparent real-time clock +tick frequency (e.g. 1 GHz) and also a minimum update frequency (e.g. 100 MHz) +at which updated time values are guaranteed to be observable by software. +Software may read time more frequently, but it should only observe +monotonically nondecreasing values and it should observe a new value at least +once every 10 ns (corresponding to the 100 MHz update frequency in this +example). +==== +[#norm:zicntr_rdinstret_op]#The RDINSTRET pseudoinstruction reads the low XLEN bits of the +`instret` CSR, which counts the number of instructions retired by this +hart from some arbitrary start point in the past. RDINSTRETH is only +present when XLEN=32 and reads bits 63-32 of the same instruction +counter.# The underlying 64-bit counter should never overflow in +practice. +[NOTE] +==== +Instructions that cause synchronous exceptions, including ECALL and +EBREAK, are not considered to retire and hence do not increment the +`instret` CSR. +==== +The following code sequence will read a valid 64-bit cycle counter value +into `x3:x2`, even if the counter overflows its lower half between +reading its upper and lower halves. + +[source,asm.] +.Sample code for reading the 64-bit cycle counter when XLEN=32. + again: + rdcycleh x3 + rdcycle x2 + rdcycleh x4 + bne x3, x4, again + + +=== "Zihpm" Extension for Hardware Performance Counters + +[#norm:hpmcounter_op_sz_mode]#The Zihpm extension comprises up to 29 additional unprivileged 64-bit +hardware performance counters, `hpmcounter3-hpmcounter31`. When +XLEN=32, the upper 32 bits of these performance counters are accessible +via additional CSRs `hpmcounter3h- hpmcounter31h`.# The Zihpm extension +depends on the Zicsr extension. +[NOTE] +==== +In some applications, it is important to be able to read multiple +counters at the same instant in time. When run under a multitasking +environment, a user thread can suffer a context switch while attempting +to read the counters. One solution is for the user thread to read the +real-time counter before and after reading the other counters to +determine if a context switch occurred in the middle of the sequence, in +which case the reads can be retried. We considered adding output latches +to allow a user thread to snapshot the counter values atomically, but +this would increase the size of the user context, especially for +implementations with a richer set of counters. +==== + +The implemented number and width of these additional counters, and the +set of events they count, are platform-specific. Accessing an +unimplemented counter may cause an illegal-instruction exception or may +return a constant value. If the configuration used to select the events +counted by a counter is misconfigured, the counter may return a constant +value. + +The execution environment should provide a means to determine the number +and width of the implemented counters, and an interface to configure the +events to be counted by each counter. +[NOTE] +==== +For execution environments implemented on RISC-V privileged platforms, +the privileged architecture manual describes privileged CSRs controlling +access by lower privileged modes to these counters, and to set the +events to be counted. + +Alternative execution environments (e.g., user-level-only software +performance models) may provide alternative mechanisms to configure the +events counted by the performance counters. + +It would be useful to eventually standardize event settings to count +ISA-level metrics, such as the number of floating-point instructions +executed for example, and possibly a few common microarchitectural +metrics, such as "L1 instruction cache misses". +==== diff --git a/param_extraction/chunks/chunk_010.txt.license b/param_extraction/chunks/chunk_010.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_010.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_011.txt b/param_extraction/chunks/chunk_011.txt new file mode 100644 index 0000000000..5a7e39e76d --- /dev/null +++ b/param_extraction/chunks/chunk_011.txt @@ -0,0 +1,254 @@ +# Chunk: chunk_011 +# Source: d-st-ext.adoc +# Lines: 1-239 (of 239) +# Content starts: line 1 +# Line count: 239 +# Sections: 8 +# == "D" Extension for Double-Precision Floating-Point, Version 2.2 +# === D Register State +# === NaN Boxing of Narrower Values +# === Double-Precision Load and Store Instructions +# === Double-Precision Floating-Point Computational Instructions +# === Double-Precision Floating-Point Conversion and Move Instructions +# === Double-Precision Floating-Point Compare Instructions +# === Double-Precision Floating-Point Classify Instruction +# +== "D" Extension for Double-Precision Floating-Point, Version 2.2 + +This chapter describes the standard double-precision floating-point +instruction-set extension, which is named "D" and adds +double-precision floating-point computational instructions compliant +with the IEEE 754-2008 arithmetic standard. The D extension depends on +the base single-precision instruction subset F. +(((double-precision, floating point))) +(((floating point, double precision))) + +=== D Register State + +[#norm:D_flen_64]#The D extension widens the 32 floating-point registers, `f0-f31`, to +64 bits (FLEN=64 in <>#. The `f` registers can +now hold either 32-bit or 64-bit floating-point values as described +below in <>. + +[NOTE] +==== +FLEN can be 32, 64, or 128 depending on which of the F, D, and Q +extensions are supported. There can be up to four different +floating-point precisions supported, including H, F, D, and Q. +==== +(((floating-point, supported precisions))) + +[[nanboxing]] +=== NaN Boxing of Narrower Values +[[norm:fp_nan-boxing]] +When multiple floating-point precisions are supported, then valid values +of narrower _n_-bit types, _n_ +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_012.txt b/param_extraction/chunks/chunk_012.txt new file mode 100644 index 0000000000..4fa987703c --- /dev/null +++ b/param_extraction/chunks/chunk_012.txt @@ -0,0 +1,541 @@ +# Chunk: chunk_012 +# Source: f-st-ext.adoc +# Lines: 1-524 (of 524) +# Content starts: line 1 +# Line count: 524 +# Sections: 10 +# == "F" Extension for Single-Precision Floating-Point, Version 2.2 +# === F Register State +# === Floating-Point Control and Status Register +# === NaN Generation and Propagation +# === Subnormal Arithmetic +# === Single-Precision Load and Store Instructions +# === Single-Precision Floating-Point Computational Instructions +# === Single-Precision Floating-Point Conversion and Move Instructions +# === Single-Precision Floating-Point Compare Instructions +# === Single-Precision Floating-Point Classify Instruction +# +:stem: latexmath + + +[[single-float]] +== "F" Extension for Single-Precision Floating-Point, Version 2.2 + +This chapter describes the standard instruction-set extension for +single-precision floating-point, which is named "F" and adds +single-precision floating-point computational instructions compliant +with the IEEE 754-2008 arithmetic standard cite:[ieee754-2008]. The F extension depends on the "Zicsr" extension for control and status register access. + +=== F Register State + +[#norm:flen_param]#The F extension adds 32 floating-point registers, `f0-f31`, each 32 +bits wide#, and a floating-point control and status register `fcsr`, +which contains the operating mode and exception status of the +floating-point unit. This additional state is shown in +<>. We use the term FLEN to describe the width of +the floating-point registers in the RISC-V ISA, and FLEN=32 for the F +single-precision floating-point extension. Most floating-point +instructions operate on values in the floating-point register file. +Floating-point load and store instructions transfer floating-point +values between registers and memory. Instructions to transfer values to and from the integer register file are also provided. + +[NOTE] +==== +We considered a unified register file for both integer and +floating-point values as this simplifies software register allocation +and calling conventions, and reduces total user state. However, a split +organization increases the total number of registers accessible with a +given instruction width, simplifies provision of enough register file ports +for wide superscalar issue, supports decoupled floating-point-unit +architectures, and simplifies use of internal floating-point encoding +techniques. Compiler support and calling conventions for split register +file architectures are well understood, and using dirty bits on +floating-point register file state can reduce context-switch overhead. +==== + +[[fprs]] +.RISC-V standard F extension single-precision floating-point state +[cols="<,^,>",options="header",width="50%",align="center",grid="rows"] +|=== +| [.small]#FLEN-1#| >| [.small]#0# +3+^| [.small]#f0# +3+^| [.small]#f1# +3+^| [.small]#f2# +3+^| [.small]#f3# +3+^| [.small]#f4# +3+^| [.small]#f5# +3+^| [.small]#f6# +3+^| [.small]#f7# +3+^| [.small]#f8# +3+^| [.small]#f9# +3+^| [.small]#f10# +3+^| [.small]#f11# +3+^| [.small]#f12# +3+^| [.small]#f13# +3+^| [.small]#f14# +3+^| [.small]#f15# +3+^| [.small]#f16# +3+^| [.small]#f17# +3+^| [.small]#f18# +3+^| [.small]#f19# +3+^| [.small]#f20# +3+^| [.small]#f21# +3+^| [.small]#f22# +3+^| [.small]#f23# +3+^| [.small]#f24# +3+^| [.small]#f25# +3+^| [.small]#f26# +3+^| [.small]#f27# +3+^| [.small]#f28# +3+^| [.small]#f29# +3+^| [.small]#f30# +3+^| [.small]#f31# +3+^| [.small]#FLEN# +| [.small]#31#| >| [.small]#0# +3+^| [.small]#fcsr# +3+^| [.small]#32# +|=== + +=== Floating-Point Control and Status Register + +[[norm:fcsr_op_sz_acc]] +The floating-point control and status register, `fcsr`, is a RISC-V +control and status register (CSR). It is a 32-bit read/write register +that selects the dynamic rounding mode for floating-point arithmetic +operations and holds the accrued exception flags, as shown in <>. + +[[fcsr, Floating-Point Control and Status Register]] +.Floating-point control and status register +include::images/wavedrom/float-csr.edn[] + +The `fcsr` register can be read and written with the FRCSR and FSCSR +instructions, which are assembler pseudoinstructions built on the +underlying CSR access instructions. FRCSR reads `fcsr` by copying it +into integer register _rd_. FSCSR swaps the value in `fcsr` by copying +the original value into integer register _rd_, and then writing a new +value obtained from integer register _rs1_ into `fcsr`. + +[[norm:fflags_frm_op_sz_acc]] +The fields within the `fcsr` can also be accessed individually through +different CSR addresses, and separate assembler pseudoinstructions are defined +for these accesses. The FRRM instruction reads the Rounding Mode field `frm` +(`fcsr` bits 7--5) and copies it into the least-significant three bits of +integer register _rd_, with zero in all other bits. FSRM swaps the value in +`frm` by copying the original value into integer register _rd_, and then +writing a new value obtained from the three least-significant bits of integer +register _rs1_ into `frm`. FRFLAGS and FSFLAGS are defined analogously for the +Accrued Exception Flags field `fflags` (`fcsr` bits 4--0). + +[[norm:fcsr_rsv]] +Bits 31--8 of the `fcsr` are reserved for other standard extensions. If +these extensions are not present, implementations shall ignore writes to +these bits and supply a zero value when read. Standard software should +preserve the contents of these bits. + + +[#norm:roundingmode_dynamic]#Floating-point operations use either a static rounding mode encoded in +the instruction, or a dynamic rounding mode held in `frm`. Rounding +modes are encoded as shown in <>. A value of 111 in the +instruction's _rm_ field selects the dynamic rounding mode held in +`frm`#. [#norm:roundingmode_rsv]#The behavior of floating-point instructions that depend on +rounding mode when executed with a reserved rounding mode is _reserved_, including both static reserved rounding modes (101-110) and dynamic reserved rounding modes (101-111). Some instructions, including widening conversions, have the _rm_ field but are nevertheless mathematically unaffected by the rounding mode; software should set their _rm_ field to +RNE (000) but implementations must treat the _rm_ field as usual (in +particular, with regard to decoding legal vs. reserved encodings).# + +[[norm:dyn_round_enc]] +.Rounding mode encoding. +[%autowidth,float="center",align="center",cols="^,^,<",options="header"] +|=== +|Rounding Mode |Mnemonic |Meaning +|000 |RNE |Round to Nearest, ties to Even +|001 |RTZ |Round towards Zero +|010 |RDN |Round Down (towards −{inf}) +|011 |RUP |Round Up (towards +{inf}) +|100 |RMM |Round to Nearest, ties to Max Magnitude +|101 | |_Reserved for future use._ +|110 | |_Reserved for future use._ +|111 |DYN |In instruction's _rm_ field, selects dynamic rounding mode; In Rounding Mode register, _reserved_. +|=== + +[NOTE] +==== +The C99 language standard effectively mandates the provision of a +dynamic rounding mode register. In typical implementations, writes to +the dynamic rounding mode CSR state will serialize the pipeline. Static +rounding modes are used to implement specialized arithmetic operations +that often have to switch frequently between different rounding modes. + +The ratified version of the F spec mandated that an illegal-instruction +exception was raised when an instruction was executed with a reserved +dynamic rounding mode. This has been weakened to reserved, which matches +the behavior of static rounding-mode instructions. Raising an +illegal-instruction exception is still valid behavior when encountering a +reserved encoding, so implementations compatible with the ratified spec +are compatible with the weakened spec. +==== + +[#norm:fcsr-fflags_op]#The accrued exception flags indicate the exception conditions that have +arisen on any floating-point arithmetic instruction since the field was +last reset by software, as shown in <>#. The base +RISC-V ISA does not support generating a trap on the setting of a +floating-point exception flag. +(((floating-point, exception flag))) + +[[bitdef]] +.Accrued exception flag encoding. +[%autowidth,float="center",align="center",cols="^,<",options="header",] +|=== +|Flag Mnemonic |Flag Meaning +|NV |Invalid Operation +|DZ |Divide by Zero +|OF |Overflow +|UF |Underflow +|NX |Inexact +|=== + +[NOTE] +==== +As allowed by the standard, we do not support traps on floating-point +exceptions in the F extension, but instead require explicit checks of +the flags in software. We considered adding branches controlled directly +by the contents of the floating-point accrued exception flags, but +ultimately chose to omit these instructions to keep the ISA simple. +==== + +=== NaN Generation and Propagation + +[[norm:F_canonical_NaN]] +Except when otherwise stated, if the result of a floating-point +operation is NaN, it is the canonical NaN. The canonical NaN has a +positive sign and all significand bits clear except the MSB, a.k.a. the +quiet bit. For single-precision floating-point, this corresponds to the pattern `0x7fc00000`. +(((NaN, generation))) +(((NaN, propagation))) + +[NOTE] +==== +We considered propagating NaN payloads, as is recommended by the +standard, but this decision would have increased hardware cost. +Moreover, since this feature is optional in the standard, it cannot be +used in portable code. + +Implementers are free to provide a NaN payload propagation scheme as a +nonstandard extension enabled by a nonstandard operating mode. However, the canonical NaN scheme described above must always be supported and should be the default mode. +==== +''' +[NOTE] +==== +We require implementations to return the standard-mandated default +values in the case of exceptional conditions, without any further +intervention on the part of user-level software (unlike the Alpha ISA +floating-point trap barriers). We believe full hardware handling of +exceptional cases will become more common, and so wish to avoid +complicating the user-level ISA to optimize other approaches. +Implementations can always trap to machine-mode software handlers to +provide exceptional default values. +==== + +=== Subnormal Arithmetic + +[[norm:ieee_std_subnormal]] +Operations on subnormal numbers are handled in accordance with the IEEE 754-2008 standard. +(((operations, subnormal))) + +[[norm:ieee_std_tininess]] +In the parlance of the IEEE standard, tininess is detected after +rounding. +(((tininess, handling))) + +[NOTE] +==== +Detecting tininess after rounding results in fewer spurious underflow +signals. +==== + +=== Single-Precision Load and Store Instructions + +[[norm:fsw_flw_op]] +Floating-point loads and stores use the same base+offset addressing mode as the integer base ISAs, with a base address in register _rs1_ and a 12-bit signed byte offset. The FLW instruction loads a single-precision floating-point value from memory into floating-point register _rd_. FSW stores a single-precision value from floating-point register _rs2_ to memory. + +include::images/wavedrom/sp-load-store-2.edn[] +[[sp-ldst]] +//.SP load and store + +[[norm:fsw_flw_atomic_align]] +FLW and FSW are only guaranteed to execute atomically if the effective +address is naturally aligned. + +[[norm:fsw_flw_bits_maintained]] +FLW and FSW do not modify the bits being transferred; in particular, the payloads of non-canonical NaNs are preserved. + +[[norm:fp_misaligned]] +As described in <>, the execution environment defines whether misaligned floating-point loads and stores are handled invisibly or raise a contained or fatal trap. + +[[single-float-compute]] +=== Single-Precision Floating-Point Computational Instructions + +Floating-point arithmetic instructions with one or two source operands +use the R-type format with the OP-FP major opcode. [#norm:fadd-s_fmul-s_op]#FADD.S and FMUL.S +perform single-precision floating-point addition and multiplication +respectively, between _rs1_ and _rs2_#. [#norm:fsub-s_op]#FSUB.S performs the +single-precision floating-point subtraction of _rs2_ from _rs1_#. [#norm:fdiv-s_op]#FDIV.S performs the single-precision floating-point division of _rs1_ by _rs2_#. [#norm:fsqrt-s_op]#FSQRT.S computes the square root of _rs1_#. [#norm:fp_rd]#In each case, the result is written to _rd_.# + +[[norm:F_fmt_single]] +The 2-bit floating-point format field _fmt_ is encoded as shown in +<>. It is set to _S_ (00) for all instructions in the F extension. + +[[fmt]] +.Format field encoding +[%autowidth,float="center",align="center",cols="^,^,<",options="header",] +|=== +|_fmt_ field |Mnemonic |Meaning +|00 |S |32-bit single-precision +|01 |D |64-bit double-precision +|10 |H |16-bit half-precision +|11 |Q |128-bit quad-precision +|=== + +[[norm:F_rm_field]] +All floating-point operations that perform rounding can select the +rounding mode using the _rm_ field with the encoding shown in +<>. + +[#norm:fmin-s_fmax-s_op]#Floating-point minimum-number and maximum-number instructions FMIN.S and FMAX.S write, respectively, the smaller or larger of _rs1_ and _rs2_ to _rd_#. +[#norm:fmin-s_fmax-s_zero_compare]#For the purposes of these instructions only, the value −0.0 is considered to be less than the value +0.0#. +[#norm:fmin-s_fmax-s_both_nan_input]#If both inputs are NaNs, the result is the canonical NaN#. +[#norm:fmin-s_fmax-s_one_nan_input]#If only one operand is a NaN, the result is the non-NaN operand#. +[#norm:fmin-s_fmax-s_signaling_nan_nv]#Signaling NaN inputs set the invalid operation exception flag, even when the result is not NaN#. + +[NOTE] +==== +Note that in version 2.2 of the F extension, the FMIN.S and FMAX.S +instructions were amended to implement the proposed IEEE 754-201x +`minimumNumber` and `maximumNumber` operations, rather than the IEEE +754-2008 minNum and maxNum operations. These operations differ in their +handling of signaling NaNs. +==== + +include::images/wavedrom/spfloat.edn[] +[[spfloat]] +//.Single-Precision Floating-Point Computational Instructions +(((floating point, fused multiply-add))) + +[[norm:fma_rs3]] +Floating-point fused multiply-add instructions require a new standard +instruction format. R4-type instructions specify three source registers (_rs1_, _rs2_, and _rs3_) and a destination register (_rd_). This format is only used by the floating-point fused multiply-add instructions. + +[[norm:fmadd-s_op]] +FMADD.S multiplies the values in _rs1_ and _rs2_, adds the value in +_rs3_, and writes the final result to _rd_. FMADD.S computes +_(rs1×rs2)+rs3_. + +[[norm:fmsub-s_op]] +FMSUB.S multiplies the values in _rs1_ and _rs2_, subtracts the value in _rs3_, and writes the final result to _rd_. FMSUB.S computes +_(rs1×rs2)−rs3_. + +[[norm:fnmsub-s_op]] +FNMSUB.S multiplies the values in _rs1_ and _rs2_, negates the product, adds the value in _rs3_, and writes the final result to _rd_. FNMSUB.S computes _−(rs1×rs2)+rs3_. + +[[norm:fnmadd-s_op]] +FNMADD.S multiplies the values in _rs1_ and _rs2_, negates the product, subtracts the value in _rs3_, and writes the final result to _rd_. FNMADD.S computes _−(rs1×rs2)−rs3_. + +[NOTE] +==== +The FNMSUB and FNMADD instructions are counterintuitively named, owing +to the naming of the corresponding instructions in MIPS-IV. The MIPS +instructions were defined to negate the sum, rather than negating the +product as the RISC-V instructions do, so the naming scheme was more +rational at the time. The two definitions differ with respect to +signed-zero results. The RISC-V definition matches the behavior of the +x86 and ARM fused multiply-add instructions, but unfortunately the +RISC-V FNMSUB and FNMADD instruction names are swapped as compared to x86, +whereas the RISC-V FMSUB and FNMSUB instruction names are swapped as +compared to ARM. +==== + +include::images/wavedrom/spfloat2.edn[] +[[fnmaddsub]] +//.F[N]MADD/F[N]MSUB instructions + +[NOTE] +==== +The fused multiply-add (FMA) instructions consume a large part of the +32-bit instruction encoding space. Some alternatives considered were to +restrict FMA to only use dynamic rounding modes, but static rounding +modes are useful in code that exploits the lack of product rounding. +Another alternative would have been to use rd to provide rs3, but this +would require additional move instructions in some common sequences. The current design still leaves a large portion of the 32-bit encoding space open while avoiding having FMA be non-orthogonal. +==== + +[[norm:fma_nv_flag]] +The fused multiply-add instructions must set the invalid operation +exception flag when the multiplicands are {inf} and zero, even when the addend is a quiet NaN. + +[NOTE] +==== +The IEEE 754-2008 standard permits, but does not require, raising the +invalid exception for the operation {inf}×0 + qNaN. +==== + +=== Single-Precision Floating-Point Conversion and Move Instructions + +Floating-point-to-integer and integer-to-floating-point conversion +instructions are encoded in the OP-FP major opcode space. [#norm:fcvt-l-s_fcvt-w-s_op]#FCVT.W.S or +FCVT.L.S converts a floating-point number in floating-point register +_rs1_ to a signed 32-bit or 64-bit integer, respectively, in integer +register _rd_#. [#norm:fcvt-s-w_fcvt-s-l_op]#FCVT.S.W or FCVT.S.L converts a 32-bit or 64-bit signed +integer, respectively, in integer register _rs1_ into a floating-point +number in floating-point register _rd_#. [#norm:fcvt-wu-s_fcvt-lu-s_fcvt-s-wu_fcvt-s-lu_op]#FCVT.WU.S, FCVT.LU.S, FCVT.S.WU, +and FCVT.S.LU variants convert to or from unsigned integer values. For +XLEN>32, FCVT.W[U].S sign-extends the 32-bit result to the destination register width#. +[#norm:fcvt_long_float_rv64_only]#FCVT.L[U].S and FCVT.S.L[U] are RV64-only instructions#. +[#norm:fcvt_unrepresentable_nv]#If the rounded result is not representable in the +destination format, it is clipped to the nearest value and the invalid +flag is set#. [#norm:fcvt_int_float_valid_input]#<> gives the range of valid inputs +for FCVT._int_.S and the behavior for invalid inputs#. +(((floating-point, conversion))) + +[[norm:fcvt_round]] +All floating-point to integer and integer to floating-point conversion +instructions round according to the _rm_ field. A floating-point +register can be initialized to floating-point positive zero using +FCVT.S.W _rd_, `x0`, which will never set any exception flags. + +[[int_conv]] +.Domains of float-to-integer conversions and behavior for invalid inputs +[%autowidth,float="center",align="center",cols="<,>,>,>,>",options="header",] +|=== +| |FCVT.W.S |FCVT.WU.S |FCVT.L.S |FCVT.LU.S +|Minimum valid input (after rounding) |−2^31^ |0 +|−2^63^ |0 + +|Maximum valid input (after rounding) |2^31^−1 +|2^32^−1 |2^63^−1 |2^64^−1 + +|Output for out-of-range negative input |−2^31^ |0 +|−2^63^ |0 + +|Output for -{inf} |−2^31^ |0 +|−2^63^ |0 + +|Output for out-of-range positive input |2^31^−1 +|2^32^−1 |2^63^−1 |2^64^−1 + +|Output for +{inf} or NaN |2^31^−1 +|2^32^−1 |2^63^−1 |2^64^−1 +|=== + +[[norm:fcvt_nx]] +All floating-point conversion instructions set the Inexact exception +flag if the rounded result differs from the operand value and the +Invalid exception flag is not set. + +include::images/wavedrom/spfloat-cn-cmp.edn[] +[[fcvt]] +//.SP float convert and move + +[#norm:fsgnj-s_fsgnjn-s_fsgnjx-s_op]#Floating-point to floating-point sign-injection instructions, FSGNJ.S, +FSGNJN.S, and FSGNJX.S, produce a result that takes all bits except the +sign bit from _rs1_. For FSGNJ, the result's sign bit is _rs2_'s sign +bit; for FSGNJN, the result's sign bit is the opposite of _rs2_'s sign +bit; and for FSGNJX, the sign bit is the XOR of the sign bits of _rs1_ +and _rs2_. Sign-injection instructions do not set floating-point +exception flags, nor do they canonicalize NaNs#. Note, FSGNJ.S _rx, ry, +ry_ moves _ry_ to _rx_ (assembler pseudoinstruction FMV.S _rx, ry_); +FSGNJN.S _rx, ry, ry_ moves the negation of _ry_ to _rx_ (assembler +pseudoinstruction FNEG.S _rx, ry_); and FSGNJX.S _rx, ry, ry_ moves the absolute value of _ry_ to _rx_ (assembler pseudoinstruction FABS.S _rx, +ry_). + +include::images/wavedrom/spfloat-sign-inj.edn[] +[[inj]] + +[NOTE] +==== +The sign-injection instructions provide floating-point MV, ABS, and NEG, as well as supporting a few other operations, including the IEEE +`copySign` operation and sign manipulation in transcendental math function libraries. Although MV, ABS, and NEG only need a single register operand, whereas FSGNJ instructions need two, it is unlikely most microarchitectures would add optimizations to benefit from the reduced number of register reads for these relatively infrequent instructions. Even in this case, a microarchitecture can simply detect when both source registers are the same for FSGNJ instructions and only read a single copy. +==== + +Instructions are provided to move bit patterns between the +floating-point and integer registers. [#norm:fmv-x-w_op]#FMV.X.W moves the single-precision value in floating-point register _rs1_ represented in IEEE 754-2008 encoding to the lower 32 bits of integer register _rd_. The bits are not modified in the transfer, and in particular, the payloads of non-canonical NaNs are preserved. For RV64, the higher 32 bits of the destination register are filled with copies of the floating-point number's sign bit#. + +[[norm:fmv-w-x_op]] +FMV.W.X moves the single-precision value encoded in IEEE 754-2008 +standard encoding from the lower 32 bits of integer register _rs1_ to +the floating-point register _rd_. The bits are not modified in the +transfer, and in particular, the payloads of non-canonical NaNs are +preserved. + +[NOTE] +==== +The FMV.W.X and FMV.X.W instructions were previously called FMV.S.X and FMV.X.S. The use of W is more consistent with their semantics as an instruction that moves 32 bits without interpreting them. This became clearer after defining NaN-boxing. To avoid disturbing existing code, both the W and S versions will be supported by tools. +==== + +include::images/wavedrom/spfloat-mv.edn[] +[[spfloat-mv]] +//.SP floating point move + +[NOTE] +==== +The base floating-point ISA was defined so as to allow implementations +to employ an internal recoding of the floating-point format in registers to simplify handling of subnormal values and possibly to reduce functional unit latency. To this end, the F extension avoids +representing integer values in the floating-point registers by defining conversion and comparison operations that read and write the integer register file directly. This also removes many of the common cases where explicit moves between integer and floating-point registers are required, reducing instruction count and critical paths for common mixed-format code sequences. +==== + +=== Single-Precision Floating-Point Compare Instructions +[[norm:feq-s_flt-s_fle-s_op]] +Floating-point compare instructions (FEQ.S, FLT.S, FLE.S) perform the +specified comparison between floating-point registers +(_rs1_ = _rs2_, _rs1_ < _rs2_, +_rs1_ {le} _rs2_) writing 1 to the integer register _rd_ if the +condition holds, and 0 otherwise. + +[#norm:flt-s_fle-s_signaling]#FLT.S and FLE.S perform what the IEEE 754-2008 standard refers to as +_signaling_ comparisons: that is, they set the invalid operation +exception flag if either input is NaN#. [#norm:feq-s_quiet]#FEQ.S performs a _quiet_ +comparison: it only sets the invalid operation exception flag if either input is a signaling NaN#. [#norm:feq-s_flt-s_fle-s_NaN_input]#For all three instructions, the result is 0 if either operand is NaN#. + +include::images/wavedrom/spfloat-comp.edn[] +[[spfloat-comp]] +//.SP floating point compare + +[NOTE] +==== +The F extension provides a {le} comparison, whereas the +base ISAs provide a {ge} branch comparison. Because +{le} can be synthesized from {ge} and +vice-versa, there is no performance implication to this inconsistency, +but it is nevertheless an unfortunate incongruity in the ISA. +==== + +=== Single-Precision Floating-Point Classify Instruction + +[[norm:fclass-s_op]] +The FCLASS.S instruction examines the value in floating-point register +_rs1_ and writes to integer register _rd_ a 10-bit mask that indicates +the class of the floating-point number. The format of the mask is +described in <>. The corresponding bit in _rd_ will +be set if the property is true and clear otherwise. All other bits in +_rd_ are cleared. Note that exactly one bit in _rd_ will be set. +FCLASS.S does not set the floating-point exception flags. +(((floating-point, classification))) + +include::images/wavedrom/spfloat-classify.edn[] +[[spfloat-classify]] +//.SP floating point classify + +[[fclass]] +.Format of result of FCLASS instruction. +[%autowidth,float="center",align="center",cols="^,<",options="header",] +|=== +|_rd_ bit |Meaning +|0 |_rs1_ is −{inf}. +|1 |_rs1_ is a negative normal number. +|2 |_rs1_ is a negative subnormal number. +|3 |_rs1_ is −0. +|4 |_rs1_ is +0. +|5 |_rs1_ is a positive subnormal number. +|6 |_rs1_ is a positive normal number. +|7 |_rs1_ is +{inf}. +|8 |_rs1_ is a signaling NaN. +|9 |_rs1_ is a quiet NaN. +|=== diff --git a/param_extraction/chunks/chunk_012.txt.license b/param_extraction/chunks/chunk_012.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_012.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_013.txt b/param_extraction/chunks/chunk_013.txt new file mode 100644 index 0000000000..2c39115a13 --- /dev/null +++ b/param_extraction/chunks/chunk_013.txt @@ -0,0 +1,183 @@ +# Chunk: chunk_013 +# Source: fraclmul.adoc +# Lines: 1-175 (of 175) +# Content starts: line 1 +# Line count: 175 +# Sections: 1 +# === Fractional Lmul example +# +=== Fractional Lmul example + +This appendix presents a non-normative example to help explain where +compilers can make good use of the fractional LMUL feature. + +Consider the following (admittedly contrived) loop written in C: + +[source,c] +---- +void add_ref(long N, + signed char *restrict c_c, signed char *restrict c_a, signed char *restrict c_b, + long *restrict l_c, long *restrict l_a, long *restrict l_b, + long *restrict l_d, long *restrict l_e, long *restrict l_f, + long *restrict l_g, long *restrict l_h, long *restrict l_i, + long *restrict l_j, long *restrict l_k, long *restrict l_l, + long *restrict l_m) { + long i; + for (i = 0; i < N; i++) { + c_c[i] = c_a[i] + c_b[i]; // Note this 'char' addition that creates a mixed type situation + l_c[i] = l_a[i] + l_b[i]; + l_f[i] = l_d[i] + l_e[i]; + l_i[i] = l_g[i] + l_h[i]; + l_l[i] = l_k[i] + l_j[i]; + l_m[i] += l_m[i] + l_c[i] + l_f[i] + l_i[i] + l_l[i]; + } +} +---- + +The example loop has a high register pressure due to the many input variables +and temporaries required. The compiler realizes there are two datatypes within +the loop: an 8-bit 'char' and a 64-bit 'long *'. Without fractional LMUL, the +compiler would be forced to use LMUL=1 for the 8-bit computation and LMUL=8 for +the 64-bit computation(s), to have equal number of elements on all computations +within the same loop iteration. Under LMUL=8, only 4 registers are available +to the register allocator. Given the large number of 64-bit variables and +temporaries required in this loop, the compiler ends up generating a lot of +spill code. The code below demonstrates this effect: + +---- +.LBB0_4: # %vector.body + # =>This Inner Loop Header: Depth=1 + add s9, a2, s6 + vsetvli s1, zero, e8,m1,ta,mu + vle8.v v25, (s9) + add s1, a3, s6 + vle8.v v26, (s1) + vadd.vv v25, v26, v25 + add s1, a1, s6 + vse8.v v25, (s1) + add s9, a5, s10 + vsetvli s1, zero, e64,m8,ta,mu + vle64.v v8, (s9) + add s1, a6, s10 + vle64.v v16, (s1) + add s1, a7, s10 + vle64.v v24, (s1) + add s1, s3, s10 + vle64.v v0, (s1) + sd a0, -112(s0) + ld a0, -128(s0) + vs8r.v v0, (a0) # Spill LMUL=8 + add s9, t6, s10 + add s11, t5, s10 + add ra, t2, s10 + add s1, t3, s10 + vle64.v v0, (s9) + ld s9, -136(s0) + vs8r.v v0, (s9) # Spill LMUL=8 + vle64.v v0, (s11) + ld s9, -144(s0) + vs8r.v v0, (s9) # Spill LMUL=8 + vle64.v v0, (ra) + ld s9, -160(s0) + vs8r.v v0, (s9) # Spill LMUL=8 + vle64.v v0, (s1) + ld s1, -152(s0) + vs8r.v v0, (s1) # Spill LMUL=8 + vadd.vv v16, v16, v8 + ld s1, -128(s0) + vl8r.v v8, (s1) # Reload LMUL=8 + vadd.vv v8, v8, v24 + ld s1, -136(s0) + vl8r.v v24, (s1) # Reload LMUL=8 + ld s1, -144(s0) + vl8r.v v0, (s1) # Reload LMUL=8 + vadd.vv v24, v0, v24 + ld s1, -128(s0) + vs8r.v v24, (s1) # Spill LMUL=8 + ld s1, -152(s0) + vl8r.v v0, (s1) # Reload LMUL=8 + ld s1, -160(s0) + vl8r.v v24, (s1) # Reload LMUL=8 + vadd.vv v0, v0, v24 + add s1, a4, s10 + vse64.v v16, (s1) + add s1, s2, s10 + vse64.v v8, (s1) + vadd.vv v8, v8, v16 + add s1, t4, s10 + ld s9, -128(s0) + vl8r.v v16, (s9) # Reload LMUL=8 + vse64.v v16, (s1) + add s9, t0, s10 + vadd.vv v8, v8, v16 + vle64.v v16, (s9) + add s1, t1, s10 + vse64.v v0, (s1) + vadd.vv v8, v8, v0 + vsll.vi v16, v16, 1 + vadd.vv v8, v8, v16 + vse64.v v8, (s9) + add s6, s6, s7 + add s10, s10, s8 + bne s6, s4, .LBB0_4 +---- + +If instead of using LMUL=1 for the 8-bit computation, the compiler is allowed +to use a fractional LMUL=1/2, then the 64-bit computations can be performed +using LMUL=4 (note that the same ratio of 64-bit elements and 8-bit elements is +preserved as in the previous example). Now the compiler has 8 available +registers to perform register allocation, resulting in no spill code, as +shown in the loop below: + +---- +.LBB0_4: # %vector.body + # =>This Inner Loop Header: Depth=1 + add s9, a2, s6 + vsetvli s1, zero, e8,mf2,ta,mu // LMUL=1/2 ! + vle8.v v25, (s9) + add s1, a3, s6 + vle8.v v26, (s1) + vadd.vv v25, v26, v25 + add s1, a1, s6 + vse8.v v25, (s1) + add s9, a5, s10 + vsetvli s1, zero, e64,m4,ta,mu // LMUL=4 + vle64.v v28, (s9) + add s1, a6, s10 + vle64.v v8, (s1) + vadd.vv v28, v8, v28 + add s1, a7, s10 + vle64.v v8, (s1) + add s1, s3, s10 + vle64.v v12, (s1) + add s1, t6, s10 + vle64.v v16, (s1) + add s1, t5, s10 + vle64.v v20, (s1) + add s1, a4, s10 + vse64.v v28, (s1) + vadd.vv v8, v12, v8 + vadd.vv v12, v20, v16 + add s1, t2, s10 + vle64.v v16, (s1) + add s1, t3, s10 + vle64.v v20, (s1) + add s1, s2, s10 + vse64.v v8, (s1) + add s9, t4, s10 + vadd.vv v16, v20, v16 + add s11, t0, s10 + vle64.v v20, (s11) + vse64.v v12, (s9) + add s1, t1, s10 + vse64.v v16, (s1) + vsll.vi v20, v20, 1 + vadd.vv v28, v8, v28 + vadd.vv v28, v28, v12 + vadd.vv v28, v28, v16 + vadd.vv v28, v28, v20 + vse64.v v28, (s11) + add s6, s6, s7 + add s10, s10, s8 + bne s6, s4, .LBB0_4 +---- diff --git a/param_extraction/chunks/chunk_013.txt.license b/param_extraction/chunks/chunk_013.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_013.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_014.txt b/param_extraction/chunks/chunk_014.txt new file mode 100644 index 0000000000..d26361ed0f --- /dev/null +++ b/param_extraction/chunks/chunk_014.txt @@ -0,0 +1,2959 @@ +# Chunk: chunk_014 +# Source: hypervisor.adoc +# Lines: 1-2932 (of 2932) +# Content starts: line 1 +# Line count: 2932 +# Sections: 20 +# == "H" Extension for Hypervisor Support, Version 1.0 +# === Privilege Modes +# === Hypervisor and Virtual Supervisor CSRs +# ==== Hypervisor Status (`hstatus`) Register +# ==== Hypervisor Trap Delegation (`hedeleg` and `hideleg`) Registers +# ==== Hypervisor Interrupt (`hvip`, `hip`, and `hie`) Registers +# ==== Hypervisor Guest External Interrupt Registers (`hgeip` and `hgeie`) +# ==== Hypervisor Environment Configuration Register (`henvcfg`) +# ==== Hypervisor Counter-Enable (`hcounteren`) Register +# ==== Hypervisor Time Delta (`htimedelta`) Register +# ==== Hypervisor Trap Value (`htval`) Register +# ==== Hypervisor Trap Instruction (`htinst`) Register +# ==== Hypervisor Guest Address Translation and Protection (`hgatp`) Register +# ==== Virtual Supervisor Status (`vsstatus`) Register +# ==== Virtual Supervisor Interrupt (`vsip` and `vsie`) Registers +# ==== Virtual Supervisor Trap Vector Base Address (`vstvec`) Register +# ==== Virtual Supervisor Scratch (`vsscratch`) Register +# ==== Virtual Supervisor Exception Program Counter (`vsepc`) Register +# ==== Virtual Supervisor Cause (`vscause`) Register +# ==== Virtual Supervisor Trap Value (`vstval`) Register +# +[[hypervisor]] +== "H" Extension for Hypervisor Support, Version 1.0 + +This chapter describes the RISC-V hypervisor extension, which +virtualizes the supervisor-level architecture to support the efficient +hosting of guest operating systems atop a type-1 or type-2 hypervisor. +The hypervisor extension changes supervisor mode into +_hypervisor-extended supervisor mode_ (HS-mode, or _hypervisor mode_ for +short), where a hypervisor or a hosting-capable operating system runs. +The hypervisor extension also adds another stage of address translation, +from _guest physical addresses_ to supervisor physical addresses, to +virtualize the memory and memory-mapped I/O subsystems for a guest +operating system. HS-mode acts the same as S-mode, but with additional +instructions and CSRs that control the new stage of address translation +and support hosting a guest OS in virtual S-mode (VS-mode). Regular +S-mode operating systems can execute without modification either in +HS-mode or as VS-mode guests. + +In HS-mode, an OS or hypervisor interacts with the machine through the +same SBI as an OS normally does from S-mode. An HS-mode hypervisor is +expected to implement the SBI for its VS-mode guest. + +The hypervisor extension depends on an "I" base integer ISA with 32 +`x` registers (RV32I or RV64I), not RV32E or RV64E, which have only 16 `x` +registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and +[#norm:H_vm_supported]#standard +page-based address translation must be supported, either Sv32 for RV32, +or a minimum of Sv39 for RV64#. + +[#norm:misa-h_op]#The hypervisor extension is enabled by setting bit 7 in the `misa` CSR#, +which corresponds to the letter H. RISC-V harts that implement the +hypervisor extension are encouraged not to hardwire `misa`[7], so that +the extension may be disabled. + +[NOTE] +==== +The baseline privileged architecture is designed to simplify the use of +classic virtualization techniques, where a guest OS is run at +user-level, as the few privileged instructions can be easily detected +and trapped. The hypervisor extension improves virtualization +performance by reducing the frequency of these traps. + +The hypervisor extension has been designed to be efficiently emulable on +platforms that do not implement the extension, by running the hypervisor +in S-mode and trapping into M-mode for hypervisor CSR accesses and to +maintain shadow page tables. The majority of CSR accesses for type-2 +hypervisors are valid S-mode accesses so need not be trapped. +Hypervisors can support nested virtualization analogously. +==== + +=== Privilege Modes + +The current _virtualization mode_, denoted V, indicates whether the hart +is currently executing in a guest. When V=1, the hart is either in +virtual S-mode (VS-mode), or in virtual U-mode (VU-mode) atop a guest OS +running in VS-mode. When V=0, the hart is either in M-mode, in HS-mode, +or in U-mode atop an OS running in HS-mode. The virtualization mode also +indicates whether two-stage address translation is active (V=1) or +inactive (V=0). <> lists the +possible privilege modes of a RISC-V hart with the hypervisor extension. + +<<< + +[[HPrivModes]] +.Privilege modes with the hypervisor extension. +[float="center",align="center",cols="~,~,~,~,~"] +|=== +^|Virtualization + +Mode (V) ^|Nominal Privilege |Abbreviation |Name |Two-Stage Translation + +^|0 + +0 + +0 +^| U + +S + +M +|U-mode + +HS-mode + +M-mode +|User mode + +Hypervisor-extended supervisor mode + +Machine mode +|Off + +Off + +Off +^|1 + +1 +^|U + +S +|VU-mode + +VS-mode +|Virtual user mode + +Virtual supervisor mode +|On + +On +|=== + +For privilege modes U and VU, the _nominal privilege mode_ is U, and for +privilege modes HS and VS, the nominal privilege mode is S. + +HS-mode is more privileged than VS-mode, and VS-mode is more privileged +than VU-mode. VS-mode interrupts are globally disabled when executing in +U-mode. + +[NOTE] +==== +This description does not consider the possibility of U-mode or VU-mode +interrupts and will be revised if an extension for user-level interrupts +is adopted. +==== + +=== Hypervisor and Virtual Supervisor CSRs + +An OS or hypervisor running in HS-mode uses the supervisor CSRs to +interact with the exception, interrupt, and address-translation +subsystems. [#norm:H_csrs_hs_not_vs]#Additional CSRs are provided to HS-mode, but not to VS-mode, +to manage two-stage address translation and to control the behavior of a +VS-mode guest: `hstatus`, `hedeleg`, `hideleg`, `hvip`, `hip`, `hie`, +`hgeip`, `hgeie`, `henvcfg`, `henvcfgh`, `hcounteren`, `htimedelta`, +`htimedeltah`, `htval`, `htinst`, and `hgatp`.# + +Furthermore, several _virtual supervisor_ CSRs (VS CSRs) are replicas of +the normal supervisor CSRs. For example, `vsstatus` is the VS CSR that +duplicates the usual `sstatus` CSR. + +[#norm:H_vscsrs_sub]#When V=1, the VS CSRs substitute for the corresponding supervisor CSRs, +taking over all functions of the usual supervisor CSRs except as +specified otherwise. Instructions that normally read or modify a +supervisor CSR shall instead access the corresponding VS CSR.# +[#norm:H_vscsrs_acc_vs]#When V=1, +an attempt to read or write a VS CSR directly by its own separate CSR +address causes a virtual-instruction exception.# +([#norm:H_vscsrs_acc_u]#Attempts from U-mode +cause an illegal-instruction exception as usual.#) +[#norm:H_vscsrs_acc_m_hs]#The VS CSRs can be +accessed as themselves only from M-mode or HS-mode.# + +[#norm:H_vscsrs_v1]#While V=1, the normal HS-level supervisor CSRs that are replaced by VS +CSRs retain their values but do not affect the behavior of the machine +unless specifically documented to do so.# +Conversely, [#norm:H_vscsrs_v0]#when V=0, the VS +CSRs do not ordinarily affect the behavior of the machine other than +being readable and writable by CSR instructions.# + +[[norm:H_scsrs_nomatch]] +Some standard supervisor CSRs (`senvcfg`, `scounteren`, and `scontext`, +possibly others) have no matching VS CSR. These supervisor CSRs continue +to have their usual function and accessibility even when V=1, except +with VS-mode and VU-mode substituting for HS-mode and U-mode. Hypervisor +software is expected to manually swap the contents of these registers as +needed. + +[NOTE] +==== +Matching VS CSRs exist only for the supervisor CSRs that must be +duplicated, which are mainly those that get automatically written by +traps or that impact instruction execution immediately after trap entry +and/or right before SRET, when software alone is unable to swap a CSR at +exactly the right moment. Currently, most supervisor CSRs fall into this +category, but future ones might not. +==== + +In this chapter, [#norm:hsxlen_param]#we use the term _HSXLEN_ to refer to the effective XLEN +when executing in HS-mode#, and [#norm:vsxlen_param]#_VSXLEN_ to refer to the effective XLEN +when executing in VS-mode.# + +[[sec:hstatus]] +==== Hypervisor Status (`hstatus`) Register + +[[norm:hstatus_sz_acc_op]] +The `hstatus` register is an HSXLEN-bit read/write register formatted as +shown in <> when HSXLEN=32 +and <> when HSXLEN=64. The `hstatus` +register provides facilities analogous to the `mstatus` register for +tracking and controlling the exception behavior of a VS-mode guest. + +[[hstatusreg-rv32]] +.Hypervisor status register (`hstatus`) when HSXLEN=32 +[wavedrom,, svg] +.... +{reg: [ + {bits: 5, name: 'WPRI'}, + {bits: 1, name: 'VSBE'}, + {bits: 1, name: 'GVA'}, + {bits: 1, name: 'SPV'}, + {bits: 1, name: 'SPVP'}, + {bits: 1, name: 'HU'}, + {bits: 2, name: 'WPRI'}, + {bits: 6, name: 'VGEIN'}, + {bits: 2, name: 'WPRI'}, + {bits: 1, name: 'VTVM'}, + {bits: 1, name: 'VTW'}, + {bits: 1, name: 'VTSR'}, + {bits: 9, name: 'WPRI'}, +], config:{lanes: 2, hspace:1024}} +.... + +[[hstatusreg]] +.Hypervisor status register (`hstatus`) when HSXLEN=64. +[wavedrom,, svg] +.... +{reg: [ + {bits: 5, name: 'WPRI'}, + {bits: 1, name: 'VSBE'}, + {bits: 1, name: 'GVA'}, + {bits: 1, name: 'SPV'}, + {bits: 1, name: 'SPVP'}, + {bits: 1, name: 'HU'}, + {bits: 2, name: 'WPRI'}, + {bits: 6, name: 'VGEIN'}, + {bits: 2, name: 'WPRI'}, + {bits: 1, name: 'VTVM'}, + {bits: 1, name: 'VTW'}, + {bits: 1, name: 'VTSR'}, + {bits: 9, name: 'WPRI'}, + {bits: 2, name: 'VSXL'}, + {bits: 14, name: 'WPRI'}, + {bits: 2, name: 'HUPMM'}, + {bits: 14, name: 'WPRI'}, +], config:{lanes: 4, hspace:1024}} +.... + +[#norm:hstatus-vsxl_op]#The VSXL field controls the effective XLEN for VS-mode (known as +VSXLEN), which may differ from the XLEN for HS-mode (HSXLEN).# [#norm:hstatus-vsxl_32]#When +HSXLEN=32, the VSXL field does not exist, and VSXLEN=32.# [#norm:hstatus-vsxl_64]#When HSXLEN=64, +VSXL is a *WARL* field that is encoded the same as the MXL field of `misa`, +shown in <>.# [#norm:vsxl_ro_param]#In particular, an +implementation may make VSXL be a read-only field whose value always +ensures that VSXLEN=HSXLEN.# + +[[norm:hstatus-vsxl_change]] +If HSXLEN is changed from 32 to a wider width, and if field VSXL is not +restricted to a single value, it gets the value corresponding to the +widest supported width not wider than the new HSXLEN. + +The `hstatus` fields VTSR, VTW, and VTVM are defined analogously to the +`mstatus` fields TSR, TW, and TVM, but affect execution only in VS-mode, +and cause virtual-instruction exceptions instead of illegal-instruction +exceptions. +[#norm:hstatus-vtsr_op]#When VTSR=1, an attempt in VS-mode to execute SRET raises a +virtual-instruction exception.# +[#norm:hstatus-vtw_op]#When VTW=1 (and assuming `mstatus`.TW=0), +an attempt in VS-mode to execute WFI raises a virtual-instruction +exception if the WFI does not complete within an +implementation-specific, bounded time limit.# [#norm:vtw_virtinstr_param]#An implementation may have +WFI always raise a virtual-instruction exception in VS-mode when VTW=1 +(and `mstatus`.TW=0), even if there are pending globally-disabled +interrupts when the instruction is executed.# +[#norm:hstatus-vtvm_op]#When VTVM=1, an attempt in +VS-mode to execute SFENCE.VMA or SINVAL.VMA or to access CSR `satp` +raises a virtual-instruction exception.# + +[[norm:hstatus-vgein_op]] +The VGEIN (Virtual Guest External Interrupt Number) field selects a +guest external interrupt source for VS-level external interrupts. VGEIN +is a *WLRL* field that must be able to hold values between zero and the +maximum guest external interrupt number (known as GEILEN), inclusive. +When VGEIN=0, no guest external interrupt source is selected for +VS-level external interrupts. GEILEN may be zero, in which case VGEIN +may be read-only zero. Guest external interrupts are explained in +<>, and the use of VGEIN is covered +further in <>. + +[[norm:hstatus-hu_op]] +Field HU (Hypervisor in U-mode) controls whether the virtual-machine +load/store instructions, HLV, HLVX, and HSV, can be used also in U-mode. +When HU=1, these instructions can be executed in U-mode the same as in +HS-mode. When HU=0, all hypervisor instructions cause an +illegal-instruction exception in U-mode. + +[NOTE] +==== +The HU bit allows a portion of a hypervisor to be run in U-mode for +greater protection against software bugs, while still retaining access +to a virtual machine’s memory. +==== + +When Ssnpm extension is implemented, the `HUPMM` field enables or disables +pointer masking (see <>) for `HLV.\*` and `HSV.*` instructions in U-mode, +according to the values in <>, when their explicit memory +access is performed as though in VU-mode. In HS- and M-modes, pointer masking +for these instructions is enabled or disabled by `senvcfg.PMM`, when their +explicit memory access is performed as though in VU-mode. Setting `henvcfg.PMM` +enables or disables pointer masking for `HLV.\*` and `HSV.*` when their +explicit memory access is performed as though in VS-mode. When the Ssnpm +extension is not implemented, the `HUPMM` field is read-only zero. The `HUPMM` +field is read-only zero for RV32. + +[NOTE] +==== +The hypervisor should copy the value written to `senvcfg.PMM` by the guest to +the `hstatus.HUPMM` field prior to invoking `HLV.\*` or `HSV.*` instructions in +U-mode. +==== + +[#norm:hstatus-spv_op]#The SPV bit (Supervisor Previous Virtualization mode) is written by the +implementation whenever a trap is taken into HS-mode. Just as the SPP +bit in `sstatus` is set to the (nominal) privilege mode at the time of +the trap, the SPV bit in `hstatus` is set to the value of the +virtualization mode V at the time of the trap.# [#norm:hstatus-spv_sret]#When an SRET instruction +is executed when V=0, V is set to SPV.# + +[[norm:hstatus-spvp_op]] +When V=1 and a trap is taken into HS-mode, bit SPVP (Supervisor Previous +Virtual Privilege) is set to the nominal privilege mode at the time of +the trap, the same as `sstatus`.SPP. But if V=0 before a trap, SPVP is +left unchanged on trap entry. SPVP controls the effective privilege of +explicit memory accesses made by the virtual-machine load/store +instructions, HLV, HLVX, and HSV. + +[NOTE] +==== +Without SPVP, if instructions HLV, HLVX, and HSV looked instead to +`sstatus`.SPP for the effective privilege of their memory accesses, +then, even with HU=1, U-mode could not access virtual machine memory at +VS-level, because to enter U-mode using SRET always leaves SPP=0. Unlike +SPP, field SPVP is untouched by transitions back-and-forth between +HS-mode and U-mode. +==== + +[[norm:hstatus-gva_op]] +Field GVA (Guest Virtual Address) is written by the implementation +whenever a trap is taken into HS-mode. For any trap (breakpoint, address +misaligned, access fault, page fault, or guest-page fault) that writes a +guest virtual address to `stval`, GVA is set to 1. For any other trap +into HS-mode, GVA is set to 0. + +[NOTE] +==== +For breakpoint and memory access traps that write a nonzero value to +`stval`, GVA is redundant with field SPV (the two bits are set the same) +except when the explicit memory access of an HLV, HLVX, or HSV +instruction causes a fault. In that case, SPV=0 but GVA=1. +==== + +[[norm:hstatus-vsbe_op]] +The VSBE bit is a *WARL* field that controls the endianness of explicit memory +accesses made from VS-mode. If VSBE=0, explicit load and store memory +accesses made from VS-mode are little-endian, and if VSBE=1, they are +big-endian. VSBE also controls the endianness of all implicit accesses +to VS-level memory management data structures, such as page tables. An +implementation may make VSBE a read-only field that always specifies the +same endianness as HS-mode. + +==== Hypervisor Trap Delegation (`hedeleg` and `hideleg`) Registers + +[#norm:hedeleg_sz_acc]#Register `hedeleg` is a 64-bit read/write register, formatted as shown in +<>.# +[#norm:hideleg_sz_acc]#Register `hideleg` is an HSXLEN-bit read/write register, formatted as shown in +<>.# +By default, all traps at +any privilege level are handled in M-mode, though M-mode usually uses +the `medeleg` and `mideleg` CSRs to delegate some traps to HS-mode. The +`hedeleg` and `hideleg` CSRs allow these traps to be further delegated +to a VS-mode guest; their layout is the same as `medeleg` and `mideleg`. + +[[hedelegreg]] +.Hypervisor exception delegation register (`hedeleg`). +include::images/bytefield/hedelegreg.edn[] + +[[hidelegreg]] +.Hypervisor interrupt delegation register (`hideleg`). +include::images/bytefield/hidelegreg.edn[] + +[#norm:hedeleg_op]#A synchronous trap that has been delegated to HS-mode (using `medeleg`) +is further delegated to VS-mode if V=1 before the trap and the +corresponding `hedeleg` bit is set.# +[#norm:hdeleg_acc]#Each bit of `hedeleg` shall be +either writable or read-only zero. Many bits of `hedeleg` are required +specifically to be writable or zero, as enumerated in +<>. Bit 0, corresponding to +instruction address-misaligned exceptions, must be writable if +IALIGN=32.# + +[NOTE] +==== +Requiring that certain bits of `hedeleg` be writable reduces some of the +burden on a hypervisor to handle variations of implementation. +==== + +[[norm:hedelegh_sz_acc_op]] +When XLEN=32, `hedelegh` is a 32-bit read/write register +that aliases bits 63:32 of `hedeleg`. +Register `hedelegh` does not exist when XLEN=64. + +[#norm:hideleg_op]#An interrupt that has been delegated to HS-mode (using `mideleg`) is +further delegated to VS-mode if the corresponding `hideleg` bit is set.# +[#norm:hideleg_acc]#Among bits 15:0 of `hideleg`, bits 10, 6, and 2 (corresponding to the +standard VS-level interrupts) are writable, and bits 12, 9, 5, and 1 +(corresponding to the standard S-level interrupts) are read-only zeros.# + +[[norm:hideleg_trans]] +When a virtual supervisor external interrupt (code 10) is delegated to +VS-mode, it is automatically translated by the machine into a supervisor +external interrupt (code 9) for VS-mode, including the value written to +`vscause` on an interrupt trap. Likewise, a virtual supervisor timer +interrupt (6) is translated into a supervisor timer interrupt (5) for +VS-mode, and a virtual supervisor software interrupt (2) is translated +into a supervisor software interrupt (1) for VS-mode. Similar +translations may or may not be done for platform interrupt +causes (codes 16 and above). + +[[hedeleg-bits]] +.Bits of `hedeleg` that must be writable or must be read-only zero. +[%autowidth,float="center",align="center",cols=">,<,<",options="header"] +|=== +|Bit |Attribute |Corresponding Exception +|0 + +1 + +2 + +3 + +4 + +5 + +6 + +7 + +8 + +9 + +10 + +11 + +12 + +13 + +15 + +16 + +18 + +19 + +20 + +21 + +22 + +23 +|(See text) + +Writable + +Writable + +Writable + +Writable + +Writable + +Writable + +Writable + +Writable + +Read-only 0 + +Read-only 0 + +Read-only 0 + +Writable + +Writable + +Writable + +Read-only 0 + +Writable + +Writable + +Read-only 0 + +Read-only 0 + +Read-only 0 + +Read-only 0 +|Instruction address misaligned + +Instruction access fault + +Illegal instruction + +Breakpoint + +Load address misaligned + +Load access fault + +Store/AMO address misaligned + +Store/AMO access fault + +Environment call from U-mode or VU-mode + +Environment call from HS-mode + +Environment call from VS-mode + +Environment call from M-mode + +Instruction page fault + +Load page fault + +Store/AMO page fault + +Double trap + +Software check + +Hardware error + +Instruction guest-page fault + +Load guest-page fault + +Virtual instruction + +Store/AMO guest-page fault +|=== + +[[hinterruptregs]] +==== Hypervisor Interrupt (`hvip`, `hip`, and `hie`) Registers + +[[norm:hvip_sz_op]] +Register `hvip` is an HSXLEN-bit read/write register that a hypervisor +can write to indicate virtual interrupts intended for VS-mode. Bits of +`hvip` that are not writable are read-only zeros. + +[[hvipreg]] +.Hypervisor virtual-interrupt-pending register(`hvip`). +include::images/bytefield/hvipreg.edn[] + +[[norm:hvip_acc]] +The standard portion (bits 15:0) of `hvip` is formatted as shown in +<>. Bits VSEIP, VSTIP, +and VSSIP of `hvip` are writable. Setting VSEIP=1 in `hvip` asserts a +VS-level external interrupt; setting VSTIP asserts a VS-level timer +interrupt; and setting VSSIP asserts a VS-level software interrupt. + +[[hvipreg-standard]] +.Standard portion (bits 15:0) of `hvip`. +include::images/bytefield/hvipreg-standard.edn[] + +[#norm:hip_hie_sz_acc]#Registers `hip` and `hie` are HSXLEN-bit read/write registers that +supplement HS-level’s `sip` and `sie` respectively.# [#norm:hip_op]#The `hip` register +indicates pending VS-level and hypervisor-specific interrupts#, while +[#norm:hie_op]#`hie` contains enable bits for the same interrupts#. + +[[hipreg]] +.Hypervisor interrupt-pending register (`hip`). +include::images/bytefield/hipreg.edn[] + +[[hiereg]] +.Hypervisor interrupt-enable register (`hie`). +include::images/bytefield/hiereg.edn[] + +[[norm:sie_hip_hie_mutex]] +For each writable bit in `sie`, the corresponding bit shall be read-only +zero in both `hip` and `hie`. Hence, the nonzero bits in `sie` and `hie` +are always mutually exclusive, and likewise for `sip` and `hip`. + +[NOTE] +==== +The active bits of `hip` and `hie` cannot be placed in HS-level’s `sip` +and `sie` because doing so would make it impossible for software to +emulate the hypervisor extension on platforms that do not implement it +in hardware. +==== + +[[norm:hideleg_hs]] +An interrupt _i_ will trap to HS-mode whenever all of the following are +true: (a) either the current operating mode is HS-mode and the SIE bit +in the `sstatus` register is set, or the current operating mode has less +privilege than HS-mode; (b) bit _i_ is set in both `sip` and `sie`, or +in both `hip` and `hie`; and (c) bit _i_ is not set in `hideleg`. + +[[norm:hip_acc]] +If bit _i_ of `sie` is read-only zero, the same bit in register `hip` +may be writable or may be read-only. When bit _i_ in `hip` is writable, +a pending interrupt _i_ can be cleared by writing 0 to this bit. If +interrupt _i_ can become pending in `hip` but bit _i_ in `hip` is +read-only, then either the interrupt can be cleared by clearing bit _i_ +of `hvip`, or the implementation must provide some other mechanism for +clearing the pending interrupt (which may involve a call to the +execution environment). + +[[norm:hie_acc]] +A bit in `hie` shall be writable if the corresponding interrupt can ever +become pending in `hip`. Bits of `hie` that are not writable shall be +read-only zero. + +The standard portions (bits 15:0) of registers `hip` and `hie` are +formatted as shown in <> and <> respectively. + +[[hipreg-standard]] +.Standard portion (bits 15:0) of `hip`. +include::images/bytefield/hipreg-standard.edn[] + +[[hiereg-standard]] +.Standard portion (bits 15:0) of `hie`. +include::images/bytefield/hiereg-standard.edn[] + +[[norm:hip_sgeip_sgeie_acc_op]] +Bits `hip`.SGEIP and `hie`.SGEIE are the interrupt-pending and +interrupt-enable bits for guest external interrupts at supervisor level +(HS-level). SGEIP is read-only in `hip`, and is 1 if and only if the +bitwise logical-AND of CSRs `hgeip` and `hgeie` is nonzero in any bit. +(See <>.) + +[[norm:hip_vseip_vseie_op]] +Bits `hip`.VSEIP and `hie`.VSEIE are the interrupt-pending and +interrupt-enable bits for VS-level external interrupts. VSEIP is +read-only in `hip`, and is the logical-OR of these interrupt sources: + +* bit VSEIP of `hvip`; +* the bit of `hgeip` selected by `hstatus`.VGEIN; and +* any other platform-specific external interrupt signal directed to +VS-level. + +[[norm:hip_vstip_vstie_acc_op]] +Bits `hip`.VSTIP and `hie`.VSTIE are the interrupt-pending and interrupt-enable +bits for VS-level timer interrupts. VSTIP is read-only in `hip`, and is the +logical-OR of `hvip`.VSTIP and, when the Sstc extension is implemented, the +timer interrupt signal resulting from `vstimecmp`. The `hip`.VSTIP bit, in +response to timer interrupts generated by `vstimecmp`, is set by writing +`vstimecmp` with a value that is less than or equal to the sum of `time` and +`htimedelta`, truncated to 64 bits; it is cleared by writing `vstimecmp` with a +greater value. The `hip`.VSTIP bit remains defined while V=0 as well as V=1. + +[[norm:hip_vssip_vssie_op]] +Bits `hip`.VSSIP and `hie`.VSSIE are the interrupt-pending and +interrupt-enable bits for VS-level software interrupts. VSSIP in `hip` +is an alias (writable) of the same bit in `hvip`. + +[[norm:hsint_priority]] +Multiple simultaneous interrupts destined for HS-mode are handled in the +following decreasing priority order: SEI, SSI, STI, SGEI, VSEI, VSSI, +VSTI, LCOFI. + +[[hgeinterruptregs]] +==== Hypervisor Guest External Interrupt Registers (`hgeip` and `hgeie`) + +[#norm:hgeip_sz_acc_op]#The `hgeip` register is an HSXLEN-bit read-only register, formatted as +shown in <>, that indicates pending guest +external interrupts for this hart.# +[#norm:hgeie_sz_acc_op]#The `hgeie` register is an HSXLEN-bit +read/write register, formatted as shown in +<>, that contains enable bits for the +guest external interrupts at this hart.# [#norm:hgeip_hgeie_fields]#Guest external interrupt number +_i_ corresponds with bit _i_ in both `hgeip` and `hgeie`.# + +[[hgeipreg]] +.Hypervisor guest external interrupt-pending register (`hgeip`). +include::images/bytefield/hgeipreg.edn[] + + +[[hgeiereg]] +.Hypervisor guest external interrupt-enable register (`hgeie`). +include::images/bytefield/hgeiereg.edn[] + +Guest external interrupts represent interrupts directed to individual +virtual machines at VS-level. If a RISC-V platform supports placing a +physical device under the direct control of a guest OS with minimal +hypervisor intervention (known as _pass-through_ or _direct assignment_ +between a virtual machine and the physical device), then, in such +circumstance, interrupts from the device are intended for a specific +virtual machine. Each bit of `hgeip` summarizes _all_ pending interrupts +directed to one virtual hart, as collected and reported by an interrupt +controller. To distinguish specific pending interrupts from multiple +devices, software must query the interrupt controller. + +[NOTE] +==== +Support for guest external interrupts requires an interrupt controller +that can collect virtual-machine-directed interrupts separately from +other interrupts. +==== + +[[norm:geilen_param]] +The number of bits implemented in `hgeip` and `hgeie` for guest external +interrupts is UNSPECIFIED and may be zero. This number is known as _GEILEN_. The +least-significant bits are implemented first, apart from bit 0. Hence, +if GEILEN is nonzero, bits GEILEN:1 shall be writable in `hgeie`, and +all other bit positions shall be read-only zeros in both `hgeip` and +`hgeie`. + +[NOTE] +==== +The set of guest external interrupts received and handled at one +physical hart may differ from those received at other harts. Guest +external interrupt number _i_ at one physical hart is typically expected +not to be the same as guest external interrupt _i_ at any other hart. +For any one physical hart, the maximum number of virtual harts that may +directly receive guest external interrupts is limited by GEILEN. The +maximum this number can be for any implementation is 31 for RV32 and 63 +for RV64, per physical hart. + +A hypervisor is always free to _emulate_ devices for any number of +virtual harts without being limited by GEILEN. Only direct pass-through +(direct assignment) of interrupts is affected by the GEILEN limit, and +the limit is on the number of virtual harts receiving such interrupts, +not the number of distinct interrupts received. The number of distinct +interrupts a single virtual hart may receive is determined by the +interrupt controller. +==== + +[[norm:hgeie_op]] +Register `hgeie` selects the subset of guest external interrupts that +cause a supervisor-level (HS-level) guest external interrupt. The enable +bits in `hgeie` do not affect the VS-level external interrupt signal +selected from `hgeip` by `hstatus`.VGEIN. + +[[sec:henvcfg]] +==== Hypervisor Environment Configuration Register (`henvcfg`) + +[[norm:henvcfg_sz_acc_op]] +The `henvcfg` CSR is a 64-bit read/write register, formatted +as shown in <>, that controls +certain characteristics of the execution environment when virtualization +mode V=1. + +[[henvcfg]] +.Hypervisor environment configuration register (`henvcfg`). +[wavedrom, ,svg] +.... +{reg: [ + {bits: 1, name: 'FIOM'}, + {bits: 1, name: 'WPRI'}, + {bits: 1, name: 'LPE'}, + {bits: 1, name: 'SSE'}, + {bits: 2, name: 'CBIE'}, + {bits: 1, name: 'CBCFE'}, + {bits: 1, name: 'CBZE'}, + {bits: 24, name: 'WPRI'}, + {bits: 2, name: 'PMM'}, + {bits: 25, name: 'WPRI'}, + {bits: 1, name: 'DTE'}, + {bits: 1, name: 'WPRI'}, + {bits: 1, name: 'ADUE'}, + {bits: 1, name: 'PBMTE'}, + {bits: 1, name: 'STCE'}, +], config:{lanes: 4, hspace:1024}} +.... + +[[norm:henvcfg-fiom_op]] +If bit FIOM (Fence of I/O implies Memory) is set to one in `henvcfg`, +FENCE instructions executed when V=1 are modified so the requirement to +order accesses to device I/O implies also the requirement to order main +memory accesses. <> details the modified +interpretation of FENCE instruction bits PI, PO, SI, and SO when FIOM=1 +and V=1. + +[[norm:henvcfg-fiom_order]] +Similarly, when FIOM=1 and V=1, if an atomic instruction that accesses a +region ordered as device I/O has its _aq_ and/or _rl_ bit set, then that +instruction is ordered as though it accesses both device I/O and memory. + +[[henvcfg-FIOM]] +.Modified interpretation of FENCE predecessor and successor sets when FIOM=1 and virtualization mode V=1. +[%autowidth,float="center",align="center",cols="^,<",options="header"] +|=== +|Instruction bit |Meaning when set +|PI + +PO +|Predecessor device input and memory reads (PR implied) + +Predecessor device output and memory writes (PW implied) +|SI + +SO +|Successor device input and memory reads (SR implied) + +Successor device output and memory writes (SW implied) +|=== + +[[norm:henvcfg-pbmte_op]] +The PBMTE bit controls whether the Svpbmt extension is available for use +in VS-stage address translation. When PBMTE=1, Svpbmt is available for +VS-stage address translation. When PBMTE=0, the implementation behaves +as though Svpbmt were not implemented for VS-stage address translation. +If Svpbmt is not implemented, PBMTE is read-only zero. + +[[norm:henvcfg-adue_op]] +If the Svadu extension is implemented, the ADUE bit controls whether hardware +updating of PTE A/D bits is enabled for VS-stage address translation. +When ADUE=1, hardware updating of PTE A/D bits is enabled during VS-stage +address translation, and the implementation behaves as though the Svade +extension were not implemented for VS-mode address translation. +When ADUE=0, the implementation behaves as though Svade were implemented for +VS-stage address translation. +If Svadu is not implemented, ADUE is read-only zero. + +[[norm:henvcfg-stce]] +The Sstc extension adds the `STCE` (STimecmp Enable) bit to `henvcfg` CSR. When +the Sstc extension is not implemented, `STCE` is read-only zero. The `STCE` bit +enables `vstimecmp` for VS-mode when set to one. When `STCE` bit is `henvcfg` is +zero, an attempt to access `stimecmp` (really `vstimecmp`) when V=1 raises a +virtual-instruction exception, and `VSTIP` in `hip` reverts to its defined behavior +as if this extension is not implemented. + +[[norm:henvcfg-cbze]] +The Zicboz extension adds the `CBZE` (Cache Block Zero instruction enable) field +to `henvcfg`. The `CBZE` field applies to execution of the cache block zero +instruction (`CBO.ZERO`) in privilege modes VS and VU, and only when the +instruction is HS-qualified. If the instruction is not HS-qualified, it raises +an illegal-instruction exception. If the instruction is HS-qualified and the +`CBZE` field is set to 1, the instruction is enabled for execution; otherwise, +if the `CBZE` field is set to 0, it raises a virtual-instruction exception. When +the Zicboz extension is not implemented, `CBZE` is read-only zero. + +[[norm:henvcfg-cbcfe]] +The Zicbom extension adds the `CBCFE` (Cache Block Clean and Flush instruction +Enable) field to `henvcfg`. When V=1, if the `CBO.CLEAN` and `CBO.FLUSH` +instructions are not HS-qualified, they raise an illegal-instruction exception. +If the instructions are HS-qualified and the `CBCFE` field is set to 1, the +instructions are enabled for execution; otherwise, if the `CBCFE` field is set +to 0, they raise a virtual-instruction exception. When the Zicbom extension is +not implemented, `CBCFE` is read-only zero. + +[[norm:henvcfg-cbie]] +The Zicbom extension adds the `CBIE` (Cache Block Invalidate instruction Enable) +WARL field to `henvcfg`. The `CBIE` field controls execution of the cache block +invalidate instruction (`CBO.INVAL`) in privilege modes VS and VU. The encoding +`10b` is reserved. When the Zicbom extension is not implemented, `CBIE` is +read-only zero. + +[[norm:cbo-inval_h-mode_veq1_op]] +When V=1, if the `CBO.INVAL` instruction is not HS-qualified, it raises an +illegal-instruction exception. If the instruction is HS-qualified and the +`CBIE` field is set to `01b` or `11b`, the instruction is enabled for execution; +otherwise, it raises a virtual-instruction exception. + +[#norm:cbo-inval_h-mode_op0]#If `CBO.INVAL` is enabled in HS-mode to perform a flush operation, then when the +instruction is enabled in VS- or VU-mode it performs a flush operation, even if +`CBIE` is set to `11b`. Otherwise, when the instruction is enabled for +execution, its behavior depends on the `CBIE` encoding, as follows:# + +* [[norm:cbo-inval_h-mode_op1]]`01b` -- The instruction is executed and performs a flush operation, even if + configured by VS-mode to perform an invalidate operation. +* [[norm:cbo-inval_h-mode_op2]]`11b` -- The instruction is executed and performs an invalidate operation, + unless configured by VS-mode to perform a flush operation. + +[[norm:henvcfg-pmm_op]] +If the Ssnpm extension is implemented, the `PMM` field enables or disables +pointer masking (see <>) for VS-mode, according to the values in +<>. When the Ssnpm extension is not implemented, the `PMM` +field is read-only zero. The `PMM` field is read-only zero for RV32. + +[[henvcfg-pmm-values]] + +[%header, cols="25%,75%", options="header"] +.Legal values of `PMM` WARL field +|=== +|Value|Description +|00|Pointer masking is disabled (PMLEN = 0) +|01|Reserved +|10|Pointer masking is enabled with PMLEN = XLEN - 57 (PMLEN = 7 on RV64) +|11|Pointer masking is enabled with PMLEN = XLEN - 48 (PMLEN = 16 on RV64) +|=== + +[[norm:henvcfg-lpe_op]] +The Zicfilp extension adds the `LPE` field in `henvcfg`. When the `LPE` field +is set to 1, the Zicfilp extension is enabled in VS-mode. When the `LPE` field +is 0, the Zicfilp extension is not enabled in VS-mode and the following rules +apply to VS-mode: + +* The hart does not update the `ELP` state; it remains as `NO_LP_EXPECTED`. +* The `LPAD` instruction operates as a no-op. + +[[norm:henvcfg-sse_op]] +The Zicfiss extension adds the `SSE` field in `henvcfg`. If the `SSE` field is +set to 1, the Zicfiss extension is activated in VS-mode. When the `SSE` field is +0, the Zicfiss extension remains inactive in VS-mode, and the following rules +apply when `V=1`: + +* 32-bit Zicfiss instructions will revert to their behavior as defined by Zimop. +* 16-bit Zicfiss instructions will revert to their behavior as defined by Zcmop. +* The `pte.xwr=010b` encoding in VS-stage page tables becomes reserved. +* The `senvcfg.SSE` field will read as zero and is read-only. +* When `menvcfg.SSE` is one, `SSAMOSWAP.W/D` raises a virtual-instruction + exception. + +[[norm:henvcfg-dte_op]] +The Ssdbltrp extension adds the double-trap-enable (`DTE`) field in `henvcfg`. +When `henvcfg.DTE` is zero, the implementation behaves as though Ssdbltrp is not +implemented for VS-mode and the `vsstatus.SDT` bit is read-only zero. + +[[norm:henvcfgh_sz_acc_op]] +When XLEN=32, `henvcfgh` is a +32-bit read/write register that aliases bits 63:32 +of `henvcfg`. Register `henvcfgh` does not exist when +XLEN=64. + +==== Hypervisor Counter-Enable (`hcounteren`) Register + +[[norm:hcounteren_sz]] +The counter-enable register `hcounteren` is a 32-bit register that +controls the availability of the hardware performance monitoring +counters to the guest virtual machine. + +.Hypervisor counter-enable register (`hcounteren`). +include::images/bytefield/hcounterenreg.edn[] + +[[norm:hcounteren_op]] +When the CY, TM, IR, or HPM__n__ bit in the `hcounteren` register is +clear, attempts to read the `cycle`, `time`, `instret`, or +`hpmcounter` _n_ register while V=1 will cause a virtual-instruction +exception if the same bit in `mcounteren` is 1. When one of these bits +is set, access to the corresponding register is permitted when V=1, +unless prevented for some other reason. In VU-mode, a counter is not +readable unless the applicable bits are set in both `hcounteren` and +`scounteren`. + +[[norm:hcounteren_acc]] +In addition, when the TM bit in the `hcounteren` register is clear, attempts to +access the `vstimecmp` register (via `stimecmp`) while executing in VS-mode will +cause a virtual-instruction exception if the same bit in `mcounteren` is set. +When this bit and the same bit in `mcounteren` are both set, access to the +`vstimecmp` register (if implemented) is permitted in VS-mode. + +[[norm:hcounteren_warl]] +`hcounteren` must be implemented. However, any of the bits may be +read-only zero, indicating reads to the corresponding counter will cause +an exception when V=1. Hence, they are effectively *WARL* fields. + +==== Hypervisor Time Delta (`htimedelta`) Register + +[#norm:htimedelta_sz_acc_op]#The `htimedelta` CSR is a 64-bit read/write register +that contains the delta +between the value of the `time` CSR and the value returned in VS-mode or +VU-mode. That is, reading the `time` CSR in VS or VU mode returns the +sum of the contents of `htimedelta` and the actual value of `time`.# + +[NOTE] +==== +Because overflow is ignored when summing `htimedelta` and `time`, large +values of `htimedelta` may be used to represent negative time offsets. +==== + +.Hypervisor time delta register. +include::images/bytefield/htimedelta.edn[] + +[[norm:htimedeltah_sz_acc_op]] +When XLEN=32, `htimedeltah` is a 32-bit read/write register +that aliases bits 63:32 of `htimedelta`. +Register `htimedeltah` does not exist when XLEN=64. + +[[norm:time_htimedelta_req]] +If the `time` CSR is implemented, `htimedelta` (and `htimedeltah` for XLEN=32) +must be implemented. + +==== Hypervisor Trap Value (`htval`) Register + +[[norm:htval_sz_acc_op]] +The `htval` register is an HSXLEN-bit read/write register formatted as +shown in <>. When a trap is taken into +HS-mode, `htval` is written with additional exception-specific +information, alongside `stval`, to assist software in handling the trap. + +[[htvalreg]] +.Hypervisor trap value register (`htval`). +include::images/bytefield/htvalreg.edn[] + +[[norm:htval_trapval_param]] +When a guest-page-fault trap is taken into HS-mode, `htval` is written +with either zero or the guest physical address that faulted, shifted +right by 2 bits. For other traps, `htval` is set to zero, but a future +standard or extension may redefine `htval's` setting for other traps. + +A guest-page fault may arise due to an implicit memory access during +first-stage (VS-stage) address translation, in which case a guest +physical address written to `htval` is that of the implicit memory +access that faulted—for example, the address of a VS-level page table +entry that could not be read. (The guest physical address corresponding +to the original virtual address is unknown when VS-stage translation +fails to complete.) Additional information is provided in CSR `htinst` +to disambiguate such situations. + +Otherwise, for misaligned loads and stores that cause guest-page faults, +a nonzero guest physical address in `htval` corresponds to the faulting +portion of the access as indicated by the virtual address in `stval`. +For instruction guest-page faults on systems with variable-length +instructions, a nonzero `htval` corresponds to the faulting portion of +the instruction as indicated by the virtual address in `stval`. + +[NOTE] +==== +A guest physical address written to `htval` is shifted right by 2 bits +to accommodate addresses wider than the current XLEN. For RV32, the +hypervisor extension permits guest physical addresses as wide as 34 +bits, and `htval` reports bits 33:2 of the address. This shift-by-2 +encoding of guest physical addresses matches the encoding of physical +addresses in PMP address registers (<>) and in +page table entries (<>, <>, <>, and <>). + +If the least-significant two bits of a faulting guest physical address +are needed, these bits are ordinarily the same as the least-significant +two bits of the faulting virtual address in `stval`. For faults due to +implicit memory accesses for VS-stage address translation, the +least-significant two bits are instead zeros. These cases can be +distinguished using the value provided in register `htinst`. +==== + +[[norm:htval_val]] +`htval` is a *WARL* register that must be able to hold zero and may be capable +of holding only an arbitrary subset of other 2-bit-shifted guest +physical addresses, if any. + +[NOTE] +==== +Unless it has reason to assume otherwise (such as a platform standard), +software that writes a value to `htval` should read back from `htval` to +confirm the stored value. +==== + +==== Hypervisor Trap Instruction (`htinst`) Register + +[[norm:htinst_sz_acc_op]] +The `htinst` register is an HSXLEN-bit read/write register formatted as +shown in <>. When a trap is taken into +HS-mode, `htinst` is written with a value that, if nonzero, provides +information about the instruction that trapped, to assist software in +handling the trap. The values that may be written to `htinst` on a trap +are documented in <>. + +[[htinstreg]] +.Hypervisor trap instruction (`htinst`) register. +include::images/bytefield/htinstreg.edn[] + +[[norm:htinst_val]] +`htinst` is a *WARL* register that need only be able to hold the values that +the implementation may automatically write to it on a trap. + +[[hgatp]] +==== Hypervisor Guest Address Translation and Protection (`hgatp`) Register + +[#norm:hgatp_sz_acc_op]#The `hgatp` register is an HSXLEN-bit read/write register, formatted as +shown in <> for HSXLEN=32 and +<> for HSXLEN=64, which controls +G-stage address translation and protection, the second stage of +two-stage translation for guest virtual addresses (see +<>).# Similar to CSR `satp`, this +register holds the physical page number (PPN) of the guest-physical root +page table; a virtual machine identifier (VMID), which facilitates +address-translation fences on a per-virtual-machine basis; and the MODE +field, which selects the address-translation scheme for guest physical +addresses. [#norm:hgatp_tvm_illegal]#When `mstatus`.TVM=1, attempts to read or write `hgatp` while +executing in HS-mode will raise an illegal-instruction exception.# + +[[rv32hgatp]] +.Hypervisor guest address translation and protection register `hgatp` when HSXLEN=32. +include::images/bytefield/rv32hgatp.edn[] + +[[rv64hgatp]] +.Hypervisor guest address translation and protection register `hgatp` when HSXLEN=64 for MODE values Bare, Sv39x4, Sv48x4, and Sv57x4. +include::images/bytefield/rv64hgatp.edn[] + +[#norm:hgatp-mode_bare]#<> shows the encodings of the MODE field when +HSXLEN=32 and HSXLEN=64. When MODE=Bare, guest physical addresses are +equal to supervisor physical addresses, and there is no further memory +protection for a guest virtual machine beyond the physical memory +protection scheme described in <>. In this +case, software must write zero to the remaining fields in `hgatp`.# +Attempting to select MODE=Bare with a nonzero pattern in the remaining fields +has an UNSPECIFIED effect on the value that the remaining fields assume and an +UNSPECIFIED effect on G-stage address translation and protection behavior. + +[[norm:hgatp-mode_sv]] +When HSXLEN=32, the only other valid setting for MODE is Sv32x4, which +is a modification of the usual Sv32 paged virtual-memory scheme, +extended to support 34-bit guest physical addresses. When HSXLEN=64, +modes Sv39x4, Sv48x4, and Sv57x4 are defined as modifications of the +Sv39, Sv48, and Sv57 paged virtual-memory schemes. All of these paged +virtual-memory schemes are described in +<>. + +The remaining MODE settings when HSXLEN=64 are reserved for future use +and may define different interpretations of the other fields in `hgatp`. + +[[hgatp-mode]] +.Encoding of `hgatp` MODE field. +[%autowidth,float="center",align="center",cols="^,^,<",options="header"] +|=== +3+|HSXLEN=32 +|Value |Name |Description +|0 + +1 +|Bare + +Sv32x4 +|No translation or protection. + +Page-based 34-bit virtual addressing (2-bit extension of +Sv32). +3+s|HSXLEN=64 +|Value |Name |Description +|0 + +1-7 + +8 + +9 + +10 + +11-15 +|Bare + +— + +Sv39x4 + +Sv48x4 + +Sv57x4 + +— +|No translation or protection. + +_Reserved_ + +Page-based 41-bit virtual addressing (2-bit extension of +Sv39). + +Page-based 50-bit virtual addressing (2-bit extension of +Sv48). + +Page-based 59-bit virtual addressing (2-bit extension of +Sv57). + +_Reserved_ +|=== + +Implementations are not required to support all defined MODE settings +when HSXLEN=64. + +[[norm:hgatp-mode_warl]] +A write to `hgatp` with an unsupported MODE value is not ignored as it +is for `satp`. Instead, the fields of `hgatp` are *WARL* in the normal way, +when so indicated. + +[[norm:hgatp-ppn_op]] +As explained in <>, for the +paged virtual-memory schemes (Sv32x4, Sv39x4, Sv48x4, and Sv57x4), the +root page table is 16 KiB and must be aligned to a 16-KiB boundary. In +these modes, the lowest two bits of the physical page number (PPN) in +`hgatp` always read as zeros. An implementation that supports only the +defined paged virtual-memory schemes and/or Bare may make PPN[1:0] +read-only zero. + +[#norm:hgatp-vmid_param]#The number of VMID bits is UNSPECIFIED and may be zero.# The number of implemented +VMID bits, termed _VMIDLEN_, may be determined by writing one to every +bit position in the VMID field, then reading back the value in `hgatp` +to see which bit positions in the VMID field hold a one. [#norm:hgatp-vmid_lsbs]#The +least-significant bits of VMID are implemented first: that is, if +VMIDLEN > 0, VMID[VMIDLEN-1:0] is writable. The maximal +value of VMIDLEN, termed VMIDMAX, is 7 for Sv32x4 or 14 for Sv39x4, +Sv48x4, and Sv57x4.# + +The `hgatp` register is considered _active_ for the purposes of the +address-translation algorithm _unless_ the effective privilege mode is U +and `hstatus`.HU=0. + +[NOTE] +==== +This definition simplifies the implementation of speculative execution +of HLV, HLVX, and HSV instructions. +==== + +Note that writing `hgatp` does not imply any ordering constraints +between page-table updates and subsequent G-stage address translations. +If the new virtual machine’s guest physical page tables have been +modified, or if a VMID is reused, it may be necessary to execute an +HFENCE.GVMA instruction (see <>) before or +after writing `hgatp`. + +[[vsstatus]] +==== Virtual Supervisor Status (`vsstatus`) Register + +[[norm:vsstatus_sz_acc_op]] +The `vsstatus` register is a VSXLEN-bit read/write register that is +VS-mode’s version of supervisor register `sstatus`, formatted as shown +in <> when VSXLEN=32 and +<> when VSXLEN=64. When V=1, +`vsstatus` substitutes for the usual `sstatus`, so instructions that +normally read or modify `sstatus` actually access `vsstatus` instead. + +[[vsstatusreg-rv32]] +.Virtual supervisor status (`vsstatus`) register when VSXLEN=32. +[wavedrom, ,svg] +.... +{reg: [ + {bits: 1, name: 'WPRI'}, + {bits: 1, name: 'SIE'}, + {bits: 3, name: 'WPRI'}, + {bits: 1, name: 'SPIE'}, + {bits: 1, name: 'UBE'}, + {bits: 1, name: 'WPRI'}, + {bits: 1, name: 'SPP'}, + {bits: 2, name: 'VS[1:0]'}, + {bits: 2, name: 'WPRI'}, + {bits: 2, name: 'FS[1:0]'}, + {bits: 2, name: 'XS[1:0]'}, + {bits: 1, name: 'WPRI'}, + {bits: 1, name: 'SUM'}, + {bits: 1, name: 'MXR'}, + {bits: 3, name: 'WPRI'}, + {bits: 1, name: 'SPELP'}, + {bits: 1, name: 'SDT'}, + {bits: 6, name: 'WPRI'}, + {bits: 1, name: 'SD'}, +], config:{lanes: 2, hspace:1024}} +.... + +[[vsstatusreg]] +.Virtual supervisor status (`vsstatus`) register when VSXLEN=64. +[wavedrom, ,svg] +.... +{reg: [ + {bits: 1, name: 'WPRI'}, + {bits: 1, name: 'SIE'}, + {bits: 3, name: 'WPRI'}, + {bits: 1, name: 'SPIE'}, + {bits: 1, name: 'UBE'}, + {bits: 1, name: 'WPRI'}, + {bits: 1, name: 'SPP'}, + {bits: 2, name: 'VS[1:0]'}, + {bits: 2, name: 'WPRI'}, + {bits: 2, name: 'FS[1:0]'}, + {bits: 2, name: 'XS[1:0]'}, + {bits: 1, name: 'WPRI'}, + {bits: 1, name: 'SUM'}, + {bits: 1, name: 'MXR'}, + {bits: 3, name: 'WPRI'}, + {bits: 1, name: 'SPELP'}, + {bits: 1, name: 'SDT'}, + {bits: 7, name: 'WPRI'}, + {bits: 2, name: 'UXL[1:0]'}, + {bits: 29, name: 'WPRI'}, + {bits: 1, name: 'SD'}, +], config:{lanes: 4, hspace:1024}} +.... + +[[norm:vsstatus-uxl_op]] +The UXL field controls the effective XLEN for VU-mode, which may differ +from the XLEN for VS-mode (VSXLEN). When VSXLEN=32, the UXL field does +not exist, and VU-mode XLEN=32. When VSXLEN=64, UXL is a *WARL* field that is +encoded the same as the MXL field of `misa`, shown in <>. In particular, an implementation may make UXL be a read-only copy of field VSXL of `hstatus`, forcing VU-mode XLEN=VSXLEN. + +[[norm:vsstatus-uxl_change]] +If VSXLEN is changed from 32 to a wider width, and if field UXL is not +restricted to a single value, it gets the value corresponding to the +widest supported width not wider than the new VSXLEN. + +[[norm:vsstatus-fs_op]] +When V=1, both `vsstatus`.FS and the HS-level `sstatus`.FS are in +effect. Attempts to execute a floating-point instruction when either +field is 0 (Off) raise an illegal-instruction exception. Modifying the +floating-point state when V=1 causes both fields to be set to 3 (Dirty). + +[NOTE] +==== +For a hypervisor to benefit from the extension context status, it must +have its own copy in the HS-level `sstatus`, maintained independently of +a guest OS running in VS-mode. While a version of the extension context +status obviously must exist in `vsstatus` for VS-mode, a hypervisor +cannot rely on this version being maintained correctly, given that +VS-level software can change `vsstatus`.FS arbitrarily. If the HS-level +`sstatus`.FS were not independently active and maintained by the +hardware in parallel with `vsstatus`.FS while V=1, hypervisors would +always be forced to conservatively swap all floating-point state when +context-switching between virtual machines. +==== + +[[norm:vsstatus-vs_op]] +Similarly, when V=1, both `vsstatus`.VS and the HS-level `sstatus`.VS +are in effect. Attempts to execute a vector instruction when either +field is 0 (Off) raise an illegal-instruction exception. Modifying the +vector state when V=1 causes both fields to be set to 3 (Dirty). + +[[norm:vsstatus-sd_xs_op]] +Read-only fields SD and XS summarize the extension context status as it +is visible to VS-mode only. For example, the value of the HS-level +`sstatus`.FS does not affect `vsstatus`.SD. + +[[norm:vsstatus-ube_param]] +An implementation may make field UBE be a read-only copy of +`hstatus`.VSBE. + +[[norm:vsstatus_v0]] +When V=0, `vsstatus` does not directly affect the behavior of the +machine, unless a virtual-machine load/store (HLV, HLVX, or HSV) or the +MPRV feature in the `mstatus` register is used to execute a load or +store _as though_ V=1. + +[[norm:vsstatus-spelp_op]] +The Zicfilp extension adds the `SPELP` field that holds the previous `ELP`, and +is updated as specified in <>. The `SPELP` field is +encoded as follows: + +* 0 - `NO_LP_EXPECTED` - no landing pad instruction expected. +* 1 - `LP_EXPECTED` - a landing pad instruction is expected. + +[[norm:vsstatus-sdt_op]] +The Ssdbltrp adds an S-mode-disable-trap (`SDT`) field extension to address +double trap (See <>) in VS-mode. + +==== Virtual Supervisor Interrupt (`vsip` and `vsie`) Registers + +[[norm:vsip_vsie_sz_acc_op]] +The `vsip` and `vsie` registers are VSXLEN-bit read/write registers that +are VS-mode’s versions of supervisor CSRs `sip` and `sie`, formatted as +shown in <> and <> +respectively. When V=1, `vsip` and `vsie` substitute for the usual `sip` +and `sie`, so instructions that normally read or modify `sip`/`sie` +actually access `vsip`/`vsie` instead. However, interrupts directed to +HS-level continue to be indicated in the HS-level `sip` register, not in +`vsip`, when V=1. + +[[vsipreg]] +.Virtual supervisor interrupt-pending register (`vsip`). +include::images/bytefield/vsipreg.edn[] + +[[vsiereg]] +.Virtual supervisor interrupt-enable register (`vsie`). +include::images/bytefield/vsiereg.edn[] + +The standard portions (bits 15:0) of registers `vsip` and `vsie` are +formatted as shown in <> +and <> respectively. + +[[vsipreg-standard]] +.Standard portion (bits 15:0) of `vsip`. +include::images/bytefield/vsipreg-standard.edn[] + +[[vsiereg-standard]] +.Standard portion (bits 15:0) of `vsie`. +include::images/bytefield/vsiereg-standard.edn[] + +[[norm:vsip_vsie-lcofi]] +Extension Shlcofideleg supports delegating LCOFI interrupts to VS-mode. +If the Shlcofideleg extension is implemented, `hideleg` bit 13 is +writable; otherwise, it is read-only zero. +When bit 13 of `hideleg` is zero, `vsip`.LCOFIP and `vsie`.LCOFIE +are read-only zeros. +Else, `vsip`.LCOFIP and `vsie`.LCOFIE are aliases of `sip`.LCOFIP +and `sie`.LCOFIE. + +[[norm:vsip_vsie-sei]] +When bit 10 of `hideleg` is zero, `vsip`.SEIP and `vsie`.SEIE are +read-only zeros. Else, `vsip`.SEIP and `vsie`.SEIE are aliases of +`hip`.VSEIP and `hie`.VSEIE. + +[[norm:vsip_vsie-sti]] +When bit 6 of `hideleg` is zero, `vsip`.STIP and `vsie`.STIE are +read-only zeros. Else, `vsip`.STIP and `vsie`.STIE are aliases of +`hip`.VSTIP and `hie`.VSTIE. + +[[norm:vsip_vsie-ssi]] +When bit 2 of `hideleg` is zero, `vsip`.SSIP and `vsie`.SSIE are +read-only zeros. Else, `vsip`.SSIP and `vsie`.SSIE are aliases of +`hip`.VSSIP and `hie`.VSSIE. + +==== Virtual Supervisor Trap Vector Base Address (`vstvec`) Register + +[[norm:vstvec_sz_acc_op]] +The `vstvec` register is a VSXLEN-bit read/write register that is +VS-mode’s version of supervisor register `stvec`, formatted as shown in +<>. When V=1, `vstvec` substitutes for +the usual `stvec`, so instructions that normally read or modify `stvec` +actually access `vstvec` instead. When V=0, `vstvec` does not directly +affect the behavior of the machine. + +[[vstvecreg]] +.Virtual supervisor trap vector base address register `vstvec`. +include::images/bytefield/vstvecreg.edn[] + +==== Virtual Supervisor Scratch (`vsscratch`) Register + +[[norm:vsscratch_sz_acc_op]] +The `vsscratch` register is a VSXLEN-bit read/write register that is +VS-mode’s version of supervisor register `sscratch`, formatted as shown +in <>. When V=1, `vsscratch` +substitutes for the usual `sscratch`, so instructions that normally read +or modify `sscratch` actually access `vsscratch` instead. The contents +of `vsscratch` never directly affect the behavior of the machine. + +[[vsscratchreg]] +.Virtual supervisor scratch register `vsscratch`. +include::images/bytefield/vsscratchreg.edn[] + +==== Virtual Supervisor Exception Program Counter (`vsepc`) Register + +[[norm:vspec_sz_acc_op]] +The `vsepc` register is a VSXLEN-bit read/write register that is +VS-mode’s version of supervisor register `sepc`, formatted as shown in +<>. When V=1, `vsepc` substitutes for the +usual `sepc`, so instructions that normally read or modify `sepc` +actually access `vsepc` instead. When V=0, `vsepc` does not directly +affect the behavior of the machine. + +[[norm:vsepc_warl]] +`vsepc` is a *WARL* register that must be able to hold the same set of values +that `sepc` can hold. + +[[vsepcreg]] +.Virtual supervisor exception program counter (`vsepc`). +include::images/bytefield/vsepcreg.edn[] + +==== Virtual Supervisor Cause (`vscause`) Register + +[[norm:vscause_sz_acc_op]] +The `vscause` register is a VSXLEN-bit read/write register that is +VS-mode’s version of supervisor register `scause`, formatted as shown in +<>. When V=1, `vscause` substitutes +for the usual `scause`, so instructions that normally read or modify +`scause` actually access `vscause` instead. When V=0, `vscause` does not +directly affect the behavior of the machine. + +[[norm:vscause_warl]] +`vscause` is a *WLRL* register that must be able to hold the same set of +values that `scause` can hold. + +[[vscausereg]] +.Virtual supervisor cause register (`vscause`). +include::images/bytefield/vscausereg.edn[] + +==== Virtual Supervisor Trap Value (`vstval`) Register + +[[norm:vstval_sz_acc_op]] +The `vstval` register is a VSXLEN-bit read/write register that is +VS-mode’s version of supervisor register `stval`, formatted as shown in +<>. When V=1, `vstval` substitutes for +the usual `stval`, so instructions that normally read or modify `stval` +actually access `vstval` instead. When V=0, `vstval` does not directly +affect the behavior of the machine. + +[[norm:vstval_warl]] +`vstval` is a *WARL* register that must be able to hold the same set of values +that `stval` can hold. + +[[vstvalreg]] +.Virtual supervisor trap value register (`vstval`). +include::images/bytefield/vstvalreg.edn[] + +==== Virtual Supervisor Address Translation and Protection (`vsatp`) Register + +[[norm:vsatp_sz_acc_op]] +The `vsatp` register is a VSXLEN-bit read/write register that is +VS-mode’s version of supervisor register `satp`, formatted as shown in +<> for VSXLEN=32 and <> for VSXLEN=64. When V=1, +`vsatp` substitutes for the usual `satp`, so instructions that normally +read or modify `satp` actually access `vsatp` instead. `vsatp` controls +VS-stage address translation, the first stage of two-stage translation +for guest virtual addresses (see +<>). + +[[rv32vsatpreg]] +.Virtual supervisor address translation and protection `vsatp` register when VSXLEN=32. +include::images/bytefield/rv32vsatpreg.edn[] + +[[rv64vsatpreg]] +.Virtual supervisor address translation and protection `vsatp` register when VSXLEN=64. +include::images/bytefield/rv64vsatpreg.edn[] + +The `vsatp` register is considered _active_ for the purposes of the +address-translation algorithm _unless_ the effective privilege mode is U +and `hstatus`.HU=0. However, even when `vsatp` is active, VS-stage +page-table entries’ A bits must not be set as a result of speculative +execution, unless the effective privilege mode is VS or VU. + +[NOTE] +==== +In particular, virtual-machine load/store (HLV, HLVX, or HSV) +instructions that are mispredicted must not cause VS-stage +A bits to be set. +==== + +[#norm:vsatp_mode_unsupported_v0]#When V=0, a write to `vsatp` with an unsupported MODE value is either +ignored as it is for `satp`, or the fields of `vsatp` are treated as *WARL* in +the normal way.# [#norm:vsatp_mode_unsupported_v1]#However, when V=1, a write to `satp` with an unsupported +MODE value _is_ ignored and no write to `vsatp` is effected.# + +[[norm:vsatp_v0]] +When V=0, `vsatp` does not directly affect the behavior of the machine, +unless a virtual-machine load/store (HLV, HLVX, or HSV) or the MPRV +feature in the `mstatus` register is used to execute a load or store _as +though_ V=1. + +[[vstimecmp]] +==== Virtual Supervisor Timer (`vstimecmp`) Register + +[#norm:vstimecmp_sz]#The `vstimecmp` CSR is a 64-bit register and has 64-bit precision on all RV32 +and RV64 systems.# [#norm:vstimecmp_acc]#In RV32 only, accesses to the `vstimecmp` CSR access the low +32 bits, while accesses to the `vstimecmph` CSR access the high 32 bits of +`vstimecmp`.# + +[#norm:hip-vstip_op]#A virtual supervisor timer interrupt becomes pending, as reflected in the +VSTIP bit in the `hip` register, whenever (`time` + `htimedelta`), truncated +to 64 bits, contains a value greater than or equal to `vstimecmp`, treating +the values as unsigned integers.# +[#norm:hip-vstip_clear]#If the result of this comparison changes, it is guaranteed to be reflected in +VSTIP eventually, but not necessarily immediately. +The interrupt remains posted until `vstimecmp` becomes greater than (`time` ++ `htimedelta`), typically as a result of writing `vstimecmp`.# +[#norm:hip-vstip_enable]#The interrupt will be taken based on the standard interrupt enable and +delegation rules while V=1.# + +[NOTE] +==== +In systems in which a supervisor execution environment (SEE) implemented by an +HS-mode hypervisor provides timer facilities via an SBI function call, this SBI +call will continue to support requests to schedule a timer interrupt. The SEE +will simply make use of vstimecmp, changing its value as appropriate. This +ensures compatibility with existing guest VS-mode software that uses this SEE +facility, while new VS-mode software takes advantage of vstimecmp directly.) +==== + +=== Hypervisor Instructions + +The hypervisor extension adds virtual-machine load and store +instructions and two privileged fence instructions. + +==== Hypervisor Virtual-Machine Load and Store Instructions + +include::images/wavedrom/hypv-virt-load-and-store.edn[] + +[#norm:hlsv_mode]#The hypervisor virtual-machine load and store instructions are valid +only in M-mode or HS-mode, or in U-mode when `hstatus`.HU=1.# +[#norm:hlsv_priv]#Each +instruction performs an explicit memory access with an effective privilege mode +of VS or VU. The effective privilege mode of the explicit memory access is VU +when `hstatus`.SPVP=0, and VS when `hstatus`.SPVP=1.# +[#norm:hlsv_trans]#As usual for VS-mode and +VU-mode, two-stage address translation is applied, and +the HS-level `sstatus`.SUM is ignored.# +[#norm:hlsv_sstatus-mxr]#HS-level `sstatus`.MXR makes +execute-only pages readable by explicit loads for both stages of address translation +(VS-stage and G-stage)#, whereas +[#norm:hlsv_vsstatus-mxr]#`vsstatus`.MXR affects only the first +translation stage (VS-stage).# + +[[norm:hlsv_op]] +For every RV32I or RV64I load instruction, LB, LBU, LH, LHU, LW, LWU, +and LD, there is a corresponding virtual-machine load instruction: +HLV.B, HLV.BU, HLV.H, HLV.HU, HLV.W, HLV.WU, and HLV.D. For every RV32I +or RV64I store instruction, SB, SH, SW, and SD, there is a corresponding +virtual-machine store instruction: HSV.B, HSV.H, HSV.W, and HSV.D. +Instructions HLV.WU, HLV.D, and HSV.D are not valid for RV32, of course. + +[[norm:hlsv_u_op]] +Instructions HLVX.HU and HLVX.WU are the same as HLV.HU and HLV.WU, +except that _execute_ permission takes the place of _read_ permission +during address translation. That is, the memory being read must be +executable in both stages of address translation, but read permission is +not required. For the supervisor physical address that results from +address translation, the supervisor physical memory attributes must +grant both _execute_ and _read_ permissions. (The _supervisor physical +memory attributes_ are the machine’s physical memory attributes as +modified by physical memory protection, <>, for +supervisor level.) + +[NOTE] +==== +HLVX cannot override machine-level physical memory protection (PMP), so +attempting to read memory that PMP designates as execute-only still +results in an access-fault exception. + +Although HLVX instructions’ explicit memory accesses require execute +permissions, they still raise the same exceptions as other load +instructions, rather than raising fetch exceptions instead. +==== + +[[norm:hlvx-wu_valid32]] +HLVX.WU is valid for RV32, even though LWU and HLV.WU are not. (For +RV32, HLVX.WU can be considered a variant of HLV.W, as sign extension is +irrelevant for 32-bit values.) + +The memory accesses performed by the `HLVX.*` instructions are not subject to +pointer masking (see <>). + +[NOTE] +==== +`HLVX.*` instructions, designed for emulating implicit access to fetch +instructions from guest memory, perform memory accesses that are exempt from +pointer masking to facilitate this emulation. For the same reason, pointer +masking does not apply when MXR is set. +==== + +[#norm:hlsv_virtinst]#Attempts to execute a virtual-machine load/store instruction (HLV, HLVX, +or HSV) when V=1 cause a virtual-instruction exception.# +[#norm:hlsv_illegalinst]#Attempts to execute one of these same instructions from U-mode when `hstatus`.HU=0 cause an +illegal-instruction exception.# + +[[hfence.vma]] +==== Hypervisor Memory-Management Fence Instructions + +include::images/wavedrom/hypv-mm-fence.edn[] + +[[norm:hfence-vvma_hfence-gvma_op]] +The hypervisor memory-management fence instructions, HFENCE.VVMA and +HFENCE.GVMA, perform a function similar to SFENCE.VMA +(<>), except applying to the +VS-level memory-management data structures controlled by CSR `vsatp` +(HFENCE.VVMA) or the guest-physical memory-management data structures +controlled by CSR `hgatp` (HFENCE.GVMA). Instruction SFENCE.VMA applies +only to the memory-management data structures controlled by the current +`satp` (either the HS-level `satp` when V=0 or `vsatp` when V=1). + +[[norm:hfence-vvma_mode]] +HFENCE.VVMA is valid only in M-mode or HS-mode. Its effect is much the +same as temporarily entering VS-mode and executing SFENCE.VMA. Executing +an HFENCE.VVMA guarantees that any previous stores already visible to +the current hart are ordered before all implicit reads by that hart done +for VS-stage address translation for instructions that + +* are subsequent to the HFENCE.VVMA, and +* execute when `hgatp`.VMID has the same setting as it did when +HFENCE.VVMA executed. + +[[norm:hfence-vvma_limits]] +Implicit reads need not be ordered when `hgatp`.VMID is different than +at the time HFENCE.VVMA executed. If operand __rs1__≠`x0`, it specifies a single guest virtual address, and if operand __rs2__≠`x0`, it specifies a single guest address-space identifier (ASID). + +[NOTE] +==== +An HFENCE.VVMA instruction applies only to a single virtual machine, +identified by the setting of `hgatp`.VMID when HFENCE.VVMA executes. +==== + +[[norm:hfence-vvma_asid]] +When __rs2__≠`x0`, bits XLEN-1:ASIDMAX of the value held +in _rs2_ are reserved for future standard use. Until their use is +defined by a standard extension, they should be zeroed by software and +ignored by current implementations. Furthermore, if +ASIDLEN < ASIDMAX, the implementation shall ignore bits +ASIDMAX-1:ASIDLEN of the value held in _rs2_. + +[NOTE] +==== +Simpler implementations of HFENCE.VVMA can ignore the guest virtual +address in _rs1_ and the guest ASID value in _rs2_, as well as +`hgatp`.VMID, and always perform a global fence for the VS-level memory +management of all virtual machines, or even a global fence for all +memory-management data structures. +==== + +[[norm:hfence-vvma_tvm]] +Neither `mstatus`.TVM nor `hstatus`.VTVM causes HFENCE.VVMA to trap. + +[[norm:hfence-gvma_op]] +HFENCE.GVMA is valid only in HS-mode when `mstatus`.TVM=0, or in M-mode +(irrespective of `mstatus`.TVM). Executing an HFENCE.GVMA instruction +guarantees that any previous stores already visible to the current hart +are ordered before all implicit reads by that hart done for G-stage +address translation for instructions that follow the HFENCE.GVMA. If +operand __rs1__≠`x0`, it specifies a single guest +physical address, shifted right by 2 bits, and if operand +__rs2__≠`x0`, it specifies a single virtual machine +identifier (VMID). + +[NOTE] +==== +Conceptually, an implementation might contain two address-translation +caches: one that maps guest virtual addresses to guest physical +addresses, and another that maps guest physical addresses to supervisor +physical addresses. HFENCE.GVMA need not flush the former cache, but it +must flush entries from the latter cache that match the HFENCE.GVMA’s +address and VMID arguments. + +More commonly, implementations contain address-translation caches that +map guest virtual addresses directly to supervisor physical addresses, +removing a level of indirection. For such implementations, any entry +whose guest virtual address maps to a guest physical address that +matches the HFENCE.GVMA’s address and VMID arguments must be flushed. +Selectively flushing entries in this fashion requires tagging them with +the guest physical address, which is costly, and so a common technique +is to flush all entries that match the HFENCE.GVMA’s VMID argument, +regardless of the address argument. + +*** + +Like for a guest physical address written to `htval` on a trap, a guest +physical address specified in _rs1_ is shifted right by 2 bits to +accommodate addresses wider than the current XLEN. +==== + +[[norm:hfence-gvma_vmid]] +When __rs2__≠`x0`, bits XLEN-1:VMIDMAX of the value held +in _rs2_ are reserved for future standard use. Until their use is +defined by a standard extension, they should be zeroed by software and +ignored by current implementations. Furthermore, if +VMIDLEN < VMIDMAX, the implementation shall ignore bits +VMIDMAX-1:VMIDLEN of the value held in _rs2_. + +[NOTE] +==== +Simpler implementations of HFENCE.GVMA can ignore the guest physical +address in _rs1_ and the VMID value in _rs2_ and always perform a global +fence for the guest-physical memory management of all virtual machines, +or even a global fence for all memory-management data structures. +==== + +[[norm:hfence-gvma_mode]] +If `hgatp`.MODE is changed for a given VMID, an HFENCE.GVMA with +_rs1_=`x0` (and _rs2_ set to either `x0` or the VMID) must be executed +to order subsequent guest translations with the MODE change—even if the +old MODE or new MODE is Bare. + +[[norm:hfence-vvma_hfence-gvma_exceptions]] +Attempts to execute HFENCE.VVMA or HFENCE.GVMA when V=1 cause a +virtual-instruction exception, while attempts to do the same in U-mode cause an +illegal-instruction exception. Attempting to execute HFENCE.GVMA in HS-mode +when `mstatus`.TVM=1 also causes an illegal-instruction exception. + +=== Machine-Level CSRs + +The hypervisor extension augments or modifies machine CSRs `mstatus`, +`mstatush`, `mideleg`, `mip`, and `mie`, and adds CSRs `mtval2` and +`mtinst`. + +==== Machine Status (`mstatus` and `mstatush`) Registers + +The hypervisor extension adds two fields, MPV and GVA, to the +machine-level `mstatus` or `mstatush` CSR, and modifies the behavior of +several existing `mstatus` fields. +<> shows the modified +`mstatus` register when the hypervisor extension is implemented and +MXLEN=64. When MXLEN=32, the hypervisor extension adds MPV and GVA not +to `mstatus` but to `mstatush`. +<> shows the +`mstatush` register when the hypervisor extension is implemented and +MXLEN=32. + +[[hypervisor-mstatus]] +.Machine status (`mstatus`) register for RV64 when the hypervisor extension is implemented. +include::images/bytefield/hypv-mstatus.edn[] + +[[hypervisor-mstatush]] +.Additional machine status (`mstatush`) register for RV32 when the hypervisor extension is implemented. The format of `mstatus` is unchanged for RV32. +include::images/bytefield/hypv-mstatush.edn[] + +[[norm:mstatus_mpv_op]] +The MPV bit (Machine Previous Virtualization Mode) is written by the +implementation whenever a trap is taken into M-mode. Just as the MPP +field is set to the (nominal) privilege mode at the time of the trap, +the MPV bit is set to the value of the virtualization mode V at the time +of the trap. When an MRET instruction is executed, the virtualization +mode V is set to MPV, unless MPP=3, in which case V remains 0. + +[[norm:mstatus_gva_op]] +Field GVA (Guest Virtual Address) is written by the implementation +whenever a trap is taken into M-mode. For any trap (breakpoint, address +misaligned, access fault, page fault, or guest-page fault) that writes a +guest virtual address to `mtval`, GVA is set to 1. For any other trap +into M-mode, GVA is set to 0. + +[[norm:mstatus_modes]] +The TSR and TVM fields of `mstatus` affect execution only in HS-mode, +not in VS-mode. The TW field affects execution in all modes except +M-mode. + +[[norm:mstatus_tvm_hs]] +Setting TVM=1 prevents HS-mode from accessing `hgatp` or executing +HFENCE.GVMA or HINVAL.GVMA, but has no effect on accesses to `vsatp` or +instructions HFENCE.VVMA or HINVAL.VVMA. + +[NOTE] +==== +TVM exists in `mstatus` to allow machine-level software to modify the +address translations managed by a supervisor-level OS, usually for the +purpose of inserting another stage of address translation below that +controlled by the OS. The instruction traps enabled by TVM=1 permit +machine level to co-opt both `satp` and `hgatp` and substitute _shadow +page tables_ that merge the OS’s chosen page translations with M-level’s +lower-stage translations, all without the OS being aware. M-level +software needs this ability not only to emulate the hypervisor extension +if not already supported, but also to emulate any future RISC-V +extensions that may modify or add address translation stages, perhaps, +for example, to improve support for nested hypervisors, i.e., running +hypervisors atop other hypervisors. + +However, setting TVM=1 does not cause traps for accesses to `vsatp` or +instructions HFENCE.VVMA or HINVAL.VVMA, or for any actions taken in +VS-mode, because M-level software is not expected to need to involve +itself in VS-stage address translation. For virtual machines, it should +be sufficient, and in all likelihood faster as well, to leave VS-stage +address translation alone and merge all other translation stages into +G-stage shadow page tables controlled by `hgatp`. This assumption does +place some constraints on possible future RISC-V extensions that current +machines will be able to emulate efficiently. +==== + +[[norm:mstatus_mprv_hypervisor]] +The hypervisor extension changes the behavior of the Modify Privilege +field, MPRV, of `mstatus`. When MPRV=0, translation and protection +behave as normal. When MPRV=1, explicit memory accesses are translated +and protected, and endianness is applied, as though the current +virtualization mode were set to MPV and the current nominal privilege +mode were set to MPP. <> enumerates the cases. + +[[h-mprv]] +.Effect of MPRV on the translation and protection of explicit memory accesses. +[float="center",align="center",cols="^15,^10,^10,<70",options="header"] +|=== +|MPRV |MPV |MPP |Effect +|0 |- |- |Normal access; current privilege mode applies. + +|1 |0 |0 |U-level access with HS-level translation and protection only. + +|1 |0 |1 |HS-level access with HS-level translation and protection only. + +|1 |- |3 |M-level access with no translation. + +|1 |1 |0 |VU-level access with two-stage translation and protection. The +HS-level MXR bit makes any executable page readable. `vsstatus`.MXR +makes readable those pages marked executable at the VS translation +stage, but only if readable at the guest-physical translation stage. + +|1 |1 |1 |VS-level access with two-stage translation and protection. The +HS-level MXR bit makes any executable page readable. `vsstatus`.MXR +makes readable those pages marked executable at the VS translation +stage, but only if readable at the guest-physical translation stage. +`vsstatus`.SUM applies instead of the HS-level SUM bit. +|=== + +[[norm:mstatus_mprv_hlsv]] +MPRV does not affect the virtual-machine load/store instructions, HLV, +HLVX, and HSV. The explicit loads and stores of these instructions +always act as though V=1 and the nominal privilege mode were +`hstatus`.SPVP, overriding MPRV. + +The `mstatus` register is a superset of the HS-level `sstatus` register +but is not a superset of `vsstatus`. + +==== Machine Interrupt Delegation (`mideleg`) Register + +[[norm:mideleg_acc_h]] +When the hypervisor extension is implemented, bits 10, 6, and 2 of +`mideleg` (corresponding to the standard VS-level interrupts) are each +read-only one. Furthermore, if any guest external interrupts are +implemented (GEILEN is nonzero), bit 12 of `mideleg` (corresponding to +supervisor-level guest external interrupts) is also read-only one. +VS-level interrupts and guest external interrupts are always delegated +past M-mode to HS-mode. + +[[norm:mideleg_hroz]] +For bits of `mideleg` that are zero, the corresponding bits in +`hideleg`, `hip`, and `hie` are read-only zeros. + +==== Machine Interrupt (`mip` and `mie`) Registers + +[[norm:mip_mie_vs]] +The hypervisor extension gives registers `mip` and `mie` additional +active bits for the hypervisor-added interrupts. <> and <> show the +standard portions (bits 15:0) of registers `mip` and `mie` when the +hypervisor extension is implemented. + +[[hypervisor-mipreg-standard]] +.Standard portion (bits 15:0) of `mip`. +include::images/bytefield/hypv-mipreg-standard.edn[] + +[[hypervisor-miereg-standard]] +.Standard portion (bits 15:0) of `mie`. +include::images/bytefield/hypv-miereg-standard.edn[] + +[[norm:mip_mie_alias]] +Bits SGEIP, VSEIP, VSTIP, and VSSIP in `mip` are aliases for the same +bits in hypervisor CSR `hip`, while SGEIE, VSEIE, VSTIE, and VSSIE in +`mie` are aliases for the same bits in `hie`. + +==== Machine Second Trap Value (`mtval2`) Register + +[[norm:mtval2_sz_acc_op]] +The `mtval2` register is an MXLEN-bit read/write register formatted as +shown in <>. When a trap is taken into +M-mode, `mtval2` is written with additional exception-specific +information, alongside `mtval`, to assist software in handling the trap. + +[[mtval2reg]] +.Machine second trap value register (`mtval2`). +include::images/bytefield/mtval2reg.edn[] + + +[[norm:mtval2_trapval_param]] +When a guest-page-fault trap is taken into M-mode, `mtval2` is written +with either zero or the guest physical address that faulted, shifted +right by 2 bits. For other traps, `mtval2` is set to zero, but a future +standard or extension may redefine `mtval2's` setting for other traps. + +[[norm:mtval2_trapval_vstrans]] +If a guest-page fault is due to an implicit memory access during +first-stage (VS-stage) address translation, a guest physical address +written to `mtval2` is that of the implicit memory access that faulted. +Additional information is provided in CSR `mtinst` to disambiguate such +situations. + +[[norm:mtval2_trapval_other]] +Otherwise, for misaligned loads and stores that cause guest-page faults, +a nonzero guest physical address in `mtval2` corresponds to the faulting +portion of the access as indicated by the virtual address in `mtval`. +For instruction guest-page faults on systems with variable-length +instructions, a nonzero `mtval2` corresponds to the faulting portion of +the instruction as indicated by the virtual address in `mtval`. + +[[norm:mtval2_val]] +`mtval2` is a *WARL* register that must be able to hold zero and may be +capable of holding only an arbitrary subset of other 2-bit-shifted guest +physical addresses, if any. + +[[norm:mtval2_Ssdbltrap]] +The Ssdbltrap extension (See <>) requires the implementation of +the `mtval2` CSR. + +==== Machine Trap Instruction (`mtinst`) Register + +[[norm:mtinst_sz_acc_op]] +The `mtinst` register is an MXLEN-bit read/write register formatted as +shown in <>. When a trap is taken into +M-mode, `mtinst` is written with a value that, if nonzero, provides +information about the instruction that trapped, to assist software in +handling the trap. The values that may be written to `mtinst` on a trap +are documented in <>. + +[[mtinstreg]] +.Machine trap instruction (`mtinst`) register. +include::images/bytefield/mtinstreg.edn[] + +[[norm:mtinst_val]] +`mtinst` is a *WARL* register that need only be able to hold the values that +the implementation may automatically write to it on a trap. + +[[two-stage-translation]] +=== Two-Stage Address Translation + +[[norm:H_vm_twostage]] +Whenever the current virtualization mode V is 1, two-stage address +translation and protection is in effect. For any virtual memory access, +the original virtual address is converted in the first stage by VS-level +address translation, as controlled by the `vsatp` register, into a +_guest physical address_. The guest physical address is then converted +in the second stage by guest physical address translation, as controlled +by the `hgatp` register, into a supervisor physical address. The two +stages are known also as VS-stage and G-stage translation. Although +there is no option to disable two-stage address translation when V=1, +either stage of translation can be effectively disabled by zeroing the +corresponding `vsatp` or `hgatp` register. + +[#norm:vsstatus-mxr_vm]#The `vsstatus` field MXR, which makes execute-only pages readable by explicit loads, only +overrides VS-stage page protection. Setting MXR at VS-level does not +override guest-physical page protections.# +[#norm:sstatus-mxr_vm]#Setting MXR at HS-level, +however, overrides both VS-stage and G-stage execute-only permissions.# + +[[norm:H_vm_gstagetrans]] +When V=1, memory accesses that would normally bypass address translation +are subject to G-stage address translation alone. This includes memory +accesses made in support of VS-stage address translation, such as reads +and writes of VS-level page tables. + +[[norm:H_pmp]] +Machine-level physical memory protection applies to supervisor physical +addresses and is in effect regardless of virtualization mode. + +[[guest-addr-translation]] +==== Guest Physical Address Translation + +The mapping of guest physical addresses to supervisor physical addresses +is controlled by CSR `hgatp` (<>). + +[[norm:hgatp-mode_bare_trans]] +When the address translation scheme selected by the MODE field of +`hgatp` is Bare, guest physical addresses are equal to supervisor +physical addresses without modification, and no memory protection +applies in the trivial translation of guest physical addresses to +supervisor physical addresses. + +[[norm:hgatp-mode_x4]] +When `hgatp`.MODE specifies a translation scheme of Sv32x4, Sv39x4, +Sv48x4, or Sv57x4, G-stage address translation is a variation on the +usual page-based virtual address translation scheme of Sv32, Sv39, Sv48, +or Sv57, respectively. In each case, the size of the incoming address is +widened by 2 bits (to 34, 41, 50, or 59 bits). To accommodate the +2 extra bits, the root page table (only) is expanded by a factor of four +to be 16 KiB instead of the usual 4 KiB. Matching its larger size, the +root page table also must be aligned to a 16 KiB boundary instead of the +usual 4 KiB page boundary. Except as noted, all other aspects of Sv32, +Sv39, Sv48, or Sv57 are adopted unchanged for G-stage translation. +Non-root page tables and all page table entries (PTEs) have the same +formats as documented in <>, <>, <>, and <>. + +[[norm:hgatp-mode_sv32x4]] +For Sv32x4, an incoming guest physical address is partitioned into a +virtual page number (VPN) and page offset as shown in +<>. This partitioning is identical to +that for an Sv32 virtual address as depicted in +<>, except with 2 more bits at the +high end in VPN[1]. (Note that the fields of a partitioned guest +physical address also correspond one-for-one with the structure that +Sv32 assigns to a physical address, depicted in +<>.) + +[[sv32x4va]] +.Sv32x4 virtual address (guest physical address). +include::images/bytefield/sv32x4va.edn[] + +[[norm:hgatp-mode_sv39x4]] +For Sv39x4, an incoming guest physical address is partitioned as shown +in <>. This partitioning is identical to that for an Sv39 virtual address as depicted in <>, except with 2 more bits at the +high end in VPN[2]. Address bits 63:41 must all be zeros, or else a +guest-page-fault exception occurs. + +[[sv39x4va]] +.Sv39x4 virtual address (guest physical address). +include::images/bytefield/sv39x4va.edn[] + +[[norm:hgatp-mode_sv48x4]] +For Sv48x4, an incoming guest physical address is partitioned as shown +in <>. This partitioning is identical to +that for an Sv48 virtual address as depicted in +<>, except with 2 more bits at the +high end in VPN[3]. Address bits 63:50 must all be zeros, or else a +guest-page-fault exception occurs. + +[[sv48x4va]] +.Sv48x4 virtual address (guest physical address). +include::images/bytefield/sv48x4va.edn[] + +[[norm:hgatp-mode_sv57x4]] +For Sv57x4, an incoming guest physical address is partitioned as shown +in <>. This partitioning is identical to +that for an Sv57 virtual address as depicted in +<>, except with 2 more bits at the +high end in VPN[4]. Address bits 63:59 must all be zeros, or else a +guest-page-fault exception occurs. + +[[sv57x4va]] +.Sv57x4 virtual address (guest physical address). +include::images/bytefield/sv57x4va.edn[] + +[NOTE] +==== +The page-based G-stage address translation scheme for RV32, Sv32x4, is +defined to support a 34-bit guest physical address so that an RV32 +hypervisor need not be limited in its ability to virtualize real 32-bit +RISC-V machines, even those with 33-bit or 34-bit physical addresses. +This may include the possibility of a machine virtualizing itself, if it +happens to use 33-bit or 34-bit physical addresses. Multiplying the size +and alignment of the root page table by a factor of four is the cheapest +way to extend Sv32 to cover a 34-bit address. The possible wastage of +12 KiB for an unnecessarily large root page table is expected to be of +negligible consequence for most (maybe all) real uses. + +A consistent ability to virtualize machines having as much as four times +the physical address space as virtual address space is believed to be of +some utility also for RV64. For a machine implementing 39-bit virtual +addresses (Sv39), for example, this allows the hypervisor extension to +support up to a 41-bit guest physical address space without either +necessitating hardware support for 48-bit virtual addresses (Sv48) or +falling back to emulating the larger address space using shadow page +tables. +==== + +[[norm:H_vm_gpatrans]] +The conversion of an Sv32x4, Sv39x4, Sv48x4, or Sv57x4 guest physical +address is accomplished with the same algorithm used for Sv32, Sv39, +Sv48, or Sv57, as presented in +<>, except that: + +* `hgatp` substitutes for the usual `satp`; +* for the translation to begin, the effective privilege mode must be +VS-mode or VU-mode; +* when checking the U bit, the current privilege mode is always taken to +be U-mode; and +* guest-page-fault exceptions are raised instead of regular page-fault +exceptions. + +[[norm:H_vm_gpapriv]] +For G-stage address translation, all memory accesses (including those +made to access data structures for VS-stage address translation) are +considered to be user-level accesses, as though executed in U-mode. +Access type permissions—readable, writable, or executable—are checked +during G-stage translation the same as for VS-stage translation. For a +memory access made to support VS-stage address translation (such as to +read/write a VS-level page table), permissions and the need to set A +and/or D bits at the G-stage level are checked as though for an implicit +load or store, not for the original access type. However, any exception +is always reported for the original access type (instruction, load, or +store/AMO). + +[[norm:H_vm_gpa_g]] +The G bit in all G-stage PTEs is currently not used. Until +its use is defined by a standard extension, it should be cleared by +software for forward compatibility, and must be ignored by hardware. + +[NOTE] +==== +G-stage address translation uses the identical format for PTEs as +regular address translation, even including the U bit, due to the +possibility of sharing some (or all) page tables between G-stage +translation and regular HS-level address translation. Regardless of +whether this usage will ever become common, we chose not to preclude it. +==== + +==== Guest-Page Faults + +[[norm:H_guest_page_fault]] +Guest-page-fault traps may be delegated from M-mode to HS-mode under the +control of CSR `medeleg`, but cannot be delegated to other privilege +modes. On a guest-page fault, CSR `mtval` or `stval` is written with the +faulting guest virtual address as usual, and `mtval2` or `htval` is +written either with zero or with the faulting guest physical address, +shifted right by 2 bits. CSR `mtinst` or `htinst` may also be written +with information about the faulting instruction or other reason for the +access, as explained in <>. + +[[norm:H_straddle]] +When an instruction fetch or a misaligned memory access straddles a page +boundary, two different address translations are involved. When a +guest-page fault occurs in such a circumstance, the faulting virtual +address written to `mtval`/`stval` is the same as would be required for +a regular page fault. Thus, the faulting virtual address may be a +page-boundary address that is higher than the instruction's original +virtual address, if the byte at that page boundary is among the accessed +bytes. + +[[norm:mtval2_htval_virtaddr]] +When a guest-page fault is not due to an implicit memory access for +VS-stage address translation, a nonzero guest physical address written +to `mtval2`/`htval` shall correspond to the exact virtual address +written to `mtval`/`stval`. + +[[hyp-mm-fences]] +==== Memory-Management Fences + +[[norm:sfence-vma_v0]] +The behavior of the SFENCE.VMA instruction is affected by the current +virtualization mode V. When V=0, the virtual-address argument is an +HS-level virtual address, and the ASID argument is an HS-level ASID. The +instruction orders stores only to HS-level address-translation +structures with subsequent HS-level address translations. + +[[norm:sfence-vma_v1]] +When V=1, the virtual-address argument to SFENCE.VMA is a guest virtual +address within the current virtual machine, and the ASID argument is a +VS-level ASID within the current virtual machine. The current virtual +machine is identified by the VMID field of CSR `hgatp`, and the +effective ASID can be considered to be the combination of this VMID with +the VS-level ASID. The SFENCE.VMA instruction orders stores only to the +VS-level address-translation structures with subsequent VS-stage address +translations for the same virtual machine, i.e., only when `hgatp`.VMID +is the same as when the SFENCE.VMA executed. + +Hypervisor instructions HFENCE.VVMA and HFENCE.GVMA provide additional +memory-management fences to complement SFENCE.VMA. These instructions +are described in <>. + +<> discusses the intersection between +physical memory protection (PMP) and page-based address translation. It +is noted there that, when PMP settings are modified in a manner that +affects either the physical memory that holds page tables or the +physical memory to which page tables point, M-mode software must +synchronize the PMP settings with the virtual memory system. For +HS-level address translation, this is accomplished by executing in +M-mode an SFENCE.VMA instruction with _rs1_=`x0` and _rs2_=`x0`, after +the PMP CSRs are written. Synchronization with G-stage and VS-stage data +structures is also needed. Executing an HFENCE.GVMA instruction with +_rs1_=`x0` and _rs2_=`x0` suffices to flush all G-stage or VS-stage +address-translation cache entries that have cached PMP settings +corresponding to the final translated supervisor physical address. An +HFENCE.VVMA instruction is not required. + +Similarly, if the setting of the PBMTE or ADUE bits in `menvcfg` are changed, an +HFENCE.GVMA instruction with _rs1_=`x0` and _rs2_=`x0` suffices to synchronize +with respect to the altered interpretation of G-stage and VS-stage PTEs' PBMT +and A/D bit fields, respectively. + +By contrast, if the PBMTE or ADUE bits in `henvcfg` are changed, executing an +HFENCE.VVMA with _rs1_=`x0` and _rs2_=`x0` suffices to synchronize with +respect to the altered interpretation of VS-stage PTEs' PBMT and A/D bit fields +for the currently active VMID. + +NOTE: No mechanism is provided to atomically change `vsatp` and `hgatp` +together. Hence, to prevent speculative execution causing one guest's +VS-stage translations to be cached under another guest's VMID, world-switch +code should zero `vsatp`, then swap `hgatp`, then finally write the new +`vsatp` value. Similarly, if `henvcfg`.PBMTE/ADUE need be world-switched, they +should be switched after zeroing `vsatp` but before writing the new `vsatp` +value, obviating the need to execute an HFENCE.VVMA instruction. + +[[pm-two-stage]] +==== Interaction with Pointer Masking + +Guest physical addresses (GPAs) are 2 bits wider than the corresponding virtual +address translation modes, resulting in additional address translation schemes +Sv32x4, Sv39x4, Sv48x4, and Sv57x4 for translating guest physical addresses to +supervisor physical addresses. When running with virtualization in VS/VU mode +with `vsatp.MODE` = Bare, this means that those two bits may be subject to +pointer masking, depending on `hgatp.MODE` and `senvcfg.PMM`/`henvcfg.PMM` (for +VU/VS mode). If `vsatp.MODE` != BARE, this issue does *not* apply. + +[NOTE] +==== +An implementation could mask those two bits on the TLB access path, but this can +have a significant timing impact. Alternatively, an implementation may choose to +"waste" TLB capacity by having up to 4 duplicate entries for each page. In this +case, the pointer masking operation can be applied on the TLB refill path, where +it is unlikely to affect timing. To support this approach, some TLB entries need +to be flushed when PMLEN changes in a way that may affect these duplicate +entries. +==== + +To support implementations where (XLEN-PMLEN) can be less than the GPA width +supported by `hgatp.MODE`, hypervisors should execute an `HFENCE.GVMA` with +_rs1_=`x0` if the `henvcfg.PMM` is changed from or to a value where (XLEN-PMLEN) +is less than GPA width supported by the `hgatp` translation mode of that guest. +Specifically, these cases are: + +* `PMLEN=7` and `hgatp.MODE=sv57x4` +* `PMLEN=16` and `hgatp.MODE=sv57x4` +* `PMLEN=16` and `hgatp.MODE=sv48x4` + +Implementation of an address-specific `HFENCE.GVMA` should either ignore the +address argument, or should ignore the top masked GPA bits of entries when +comparing for an address match. + +=== Traps + +[[sec:hcauses]] +==== Trap Cause Codes + +[[norm:H_cause]] +The hypervisor extension augments the trap cause encoding. +<> lists the possible M-mode and HS-mode +trap cause codes when the hypervisor extension is implemented. Codes are +added for VS-level interrupts (interrupts 2, 6, 10), for +supervisor-level guest external interrupts (interrupt 12), for +virtual-instruction exceptions (exception 22), and for guest-page faults +(exceptions 20, 21, 23). Furthermore, environment calls from VS-mode are +assigned cause 10, whereas those from HS-mode or S-mode use cause 9 as +usual. + +[[hcauses]] +.Machine and supervisor cause register (`mcause` and `scause`) values when the hypervisor extension is implemented. +[%autowidth,float="center",align="center",cols=">,>,<",options="header"] +|=== +|Interrupt |Exception Code |Description +|1 + +1 + +1 + +1 +|0 + +1 + +2 + +3 +|_Reserved_ + +Supervisor software interrupt + +Virtual supervisor software interrupt + +Machine software interrupt +|1 + +1 + +1 + +1 +|4 + +5 + +6 + +7 +|_Reserved_ + +Supervisor timer interrupt + +Virtual supervisor timer interrupt + +Machine timer interrupt +|1 + +1 + +1 + +1 +|8 + +9 + +10 + +11 +|_Reserved_ + +Supervisor external interrupt + +Virtual supervisor external interrupt + +Machine external interrupt +|1 + +1 + +1 + +1 +|12 + +13 + +14-15 + +{ge}16 +|Supervisor guest external interrupt + +Counter-overflow interrupt + +_Reserved_ + +_Designated for platform use_ +|0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +|0 + +1 + +2 + +3 + +4 + +5 + +6 + +7 + +8 + +9 + +10 + +11 + +12 + +13 + +14 + +15 + +16 + +17 + +18 + +19 + +20 + +21 + +22 + +23 + +24-31 + +32-47 + +48-63 + +{ge}64 +|Instruction address misaligned + +Instruction access fault + +Illegal instruction + +Breakpoint + +Load address misaligned + +Load access fault + +Store/AMO address misaligned + +Store/AMO access fault + +Environment call from U-mode or VU-mode + +Environment call from HS-mode + +Environment call from VS-mode + +Environment call from M-mode + +Instruction page fault + +Load page fault + +_Reserved_ + +Store/AMO page fault + +Double trap + +_Reserved_ + +Software check + +Hardware error + +Instruction guest-page fault + +Load guest-page fault + +Virtual instruction + +Store/AMO guest-page fault + +_Designated for custom use_ + +_Reserved_ + +_Designated for custom use_ + +_Reserved_ +|=== + +[[norm:H_cause_ecall]] +HS-mode and VS-mode ECALLs use different cause values so they can be +delegated separately. + +[[norm:H_cause_virtual_instruction]] +When V=1, a virtual-instruction exception (code 22) is normally raised +instead of an illegal-instruction exception if the attempted instruction +is _HS-qualified_ but is prevented from executing when V=1 either due to +insufficient privilege or because the instruction is expressly disabled +by a supervisor or hypervisor CSR such as `scounteren` or `hcounteren`. +An instruction is _HS-qualified_ if it would be valid to execute in +HS-mode (for some values of the instruction's register operands), +assuming fields TSR and TVM of CSR `mstatus` are both zero. + +[[norm:H_cause_virtual_instruction_high]] +A special rule applies for CSR instructions that access 32-bit high-half +CSRs such as `cycleh` and `htimedeltah`. When V=1 and +XLEN=32, an invalid attempt to access a high-half CSR +raises a virtual-instruction +exception instead of an illegal-instruction exception if the same CSR +instruction for the corresponding _low-half_ CSR (e.g.`cycle` or +`htimedelta`) is HS-qualified. + +[NOTE] +==== +[[norm:H_illegal_high_half]] +When XLEN>32, an attempt to access a high-half CSR +always raises an illegal-instruction exception. +==== + +Specifically, a virtual-instruction exception is raised for the +following cases: + +* [#norm:H_virtinst_vs_nonhighctr_h0_m1]#in VS-mode, attempts to access a non-high-half counter CSR when the +corresponding bit in `hcounteren` is 0 and the same bit in `mcounteren` +is 1;# + +* [#norm:H_virtinst_vs32_highctr_h0_m1]#in VS-mode, if XLEN=32, attempts to access a high-half counter CSR +when the corresponding bit in `hcounteren` is 0 and the same bit in +`mcounteren` is 1;# + +* [#norm:H_virtinst_vu_nonhighctr_h0_s0_m1]#in VU-mode, attempts to access a non-high-half counter CSR when the +corresponding bit in either `hcounteren` or `scounteren` is 0 and the +same bit in `mcounteren` is 1;# + +* [#norm:H_virtinst_vu32_highctr_h0_s0_m1]#in VU-mode, if XLEN=32, attempts to access a high-half counter CSR +when the corresponding bit in either `hcounteren` or `scounteren` is 0 +and the same bit in `mcounteren` is 1;# + +* [#norm:H_virtinst_vu_vs_hinst]#in VS-mode or VU-mode, attempts to execute a hypervisor instruction +(HLV, HLVX, HSV, or HFENCE);# + +* [#norm:H_virtinst_vu_vs_nonhigh_allowedhs_tvm0]#in VS-mode or VU-mode, attempts to access an implemented non-high-half +hypervisor CSR or VS CSR when the same access (read/write) would be +allowed in HS-mode, assuming `mstatus`.TVM=0;# + +* [#norm:H_virtinst_vu_vs32_high_allowedhs_tvm0]#in VS-mode or VU-mode, if XLEN=32, attempts to access an implemented +high-half hypervisor CSR or high-half VS CSR when the same access +(read/write) to the CSR"s low-half partner would be allowed in HS-mode, +assuming `mstatus`.TVM=0;# + +* [#norm:H_virtinst_vu_wfi_tw0]#in VU-mode, attempts to execute WFI when `mstatus`.TW=0#, +[#norm:H_virtinst_vu_sret_sfence]#or to execute +a supervisor instruction (SRET or SFENCE);# + +* [#norm:H_virtinst_vu_nonhigh_supervisor_allowedhs_tvm0]#in VU-mode, attempts to access an implemented non-high-half supervisor +CSR when the same access (read/write) would be allowed in HS-mode, +assuming `mstatus`.TVM=0;# + +* [#norm:H_virtinst_vu32_high_supervisor_allowedhs_tvm0]#in VU-mode, if XLEN=32, attempts to access an implemented high-half +supervisor CSR when the same access to the CSR's low-half partner would +be allowed in HS-mode, assuming `mstatus`.TVM=0;# + +* [#norm:H_virtinst_wfi_vtw1_tw0]#in VS-mode, attempts to execute WFI when `hstatus`.VTW=1 and +`mstatus`.TW=0, unless the instruction completes within an +implementation-specific, bounded time;# + +* [#norm:H_virtinst_vs_sret_vtsr1]#in VS-mode, attempts to execute SRET when `hstatus`.VTSR=1#; and + +* [#norm:H_virtinst_vs_sfence_sinval_satp_vtvm1]#in VS-mode, attempts to execute an SFENCE.VMA or SINVAL.VMA +instruction or to access `satp`, when `hstatus`.VTVM=1.# + +Other extensions to the RISC-V Privileged Architecture may add to the +set of circumstances that cause a virtual-instruction exception when +V=1. + +[[norm:H_virtinst_xtval]] +On a virtual-instruction trap, `mtval` or `stval` is written the same as +for an illegal-instruction trap. + +[NOTE] +==== +It is not unusual that hypervisors must emulate the instructions that +raise virtual-instruction exceptions, to support nested hypervisors or +for other reasons. Machine level is expected ordinarily to delegate +virtual-instruction traps directly to HS-level, whereas +illegal-instruction traps are likely to be processed first in M-mode before +being conditionally delegated (by software) to HS-level. Consequently, +virtual-instruction traps are expected typically to be handled faster +than illegal-instruction traps. + +When not emulating the trapping instruction, a hypervisor should convert +a virtual-instruction trap into an illegal-instruction exception for the +guest virtual machine. + +*** + +Because TSR and TVM in `mstatus` are intended to impact only S-mode +(HS-mode), they are ignored for determining exceptions in VS-mode. +==== + +[[norm:H_illegalinst_xstatus_fs_vs]] +Fields FS and VS in registers `sstatus` and `vsstatus` deviate from the usual +_HS-qualified_ rule. +If an instruction is prevented from executing because FS or VS is zero in +either `sstatus` or `vsstatus`, the exception raised is always an +illegal-instruction exception, never a virtual-instruction exception. + +[NOTE] +==== +Early implementations of the H extension treated FS and VS in `sstatus` and +`vsstatus` specially this way, and the behavior has been codified to maintain +compatibility for software. +==== + +<<< + +[[HSyncExcPrio]] +.Synchronous exception priority when the hypervisor extension is implemented. +[%autowidth,float="center",align="center",cols="<,>,<",options="header"] +|=== +|Priority |Exc.Code |Description +|_Highest_ |3 |Instruction address breakpoint + +| .>|12, 20, 1 |During instruction address translation: + +{nbsp}{nbsp}{nbsp}First encountered page fault, guest-page fault, or access +fault + +| .>|1 |With physical address for instruction: + +{nbsp}{nbsp}{nbsp}Instruction access fault + +| |2 + +22 + +0 + +8, 9, 10, 11 + +3 + +3|Illegal instruction + +Virtual instruction + +Instruction address misaligned + +Environment call + +Environment break + +{nbsp}{nbsp}{nbsp}Load/store/AMO address breakpoint + +| .>|4,6 |Optionally: + +{nbsp}{nbsp}{nbsp}Load/store/AMO address misaligned + +| .>|13, 15, 21, 23, 5, 7 |During address translation for an explicit memory access: + +{nbsp}{nbsp}{nbsp}First encountered page fault, guest-page fault, +or access fault + +| .>|5, 7 |With physical address for an explicit memory access: + +{nbsp}{nbsp}{nbsp}Load/store/AMO access fault + +.>|_Lowest_ .>|4, 6 |If not higher priority: + +{nbsp}{nbsp}{nbsp}Load/store/AMO address misaligned +|=== + +[[norm:H_exception_priority]] +If an instruction may raise multiple synchronous exceptions, the +decreasing priority order of <> +indicates which exception is taken and reported in `mcause` or `scause`. + +==== Trap Entry + +[[norm:H_trap_deleg]] +When a trap occurs in HS-mode or U-mode, it goes to M-mode, unless +delegated by `medeleg` or `mideleg`, in which case it goes to HS-mode. +When a trap occurs in VS-mode or VU-mode, it goes to M-mode, unless +delegated by `medeleg` or `mideleg`, in which case it goes to HS-mode, +unless further delegated by `hedeleg` or `hideleg`, in which case it +goes to VS-mode. + +[[norm:H_trap_m_csrwrites]] +When a trap is taken into M-mode, virtualization mode V gets set to 0, +and fields MPV and MPP in `mstatus` (or `mstatush`) are set according to +<>. A trap into M-mode also writes fields GVA, +MPIE, and MIE in `mstatus`/`mstatush` and writes CSRs `mepc`, `mcause`, +`mtval`, `mtval2`, and `mtinst`. + +[[h-mpp]] +.Value of `mstatus`/`mstatush` fields MPV and MPP after a trap into M-mode. Upon trap return, MPV is ignored when MPP=3. +[%autowidth,float="center",align="center",cols="<,^,^",options="header"] +|=== +|Previous Mode |MPV |MPP +|U-mode + +HS-mode + +M-mode|0 + +0 + +0|0 + +1 + +3 +|VU-mode + +VS-mode|1 + +1|0 + +1 +|=== + +[[norm:H_trap_hs_csrwrites]] +When a trap is taken into HS-mode, virtualization mode V is set to 0, +and `hstatus`.SPV and `sstatus`.SPP are set according to +<>. If V was 1 before the trap, field SPVP in +`hstatus` is set the same as `sstatus`.SPP; otherwise, SPVP is left +unchanged. A trap into HS-mode also writes field GVA in `hstatus`, +fields SPIE and SIE in `sstatus`, and CSRs `sepc`, `scause`, `stval`, +`htval`, and `htinst`. + +[[h-spp]] +.Value of `hstatus` field SPV and `sstatus` field SPP after a trap into HS-mode. +[%autowidth,float="center",align="center",cols="<,^,^",options="header"] +|=== +|Previous Mode |SPV |SPP +|U-mode + +HS-mode + |0 + +0 |0 + +1 +|VU-mode + +VS-mode|1 + +1 |0 + +1 +|=== + +[[norm:H_trap_vs_csrwrites]] +When a trap is taken into VS-mode, `vsstatus`.SPP is set according to +<>. Register `hstatus` and the HS-level +`sstatus` are not modified, and the virtualization mode V remains 1. A +trap into VS-mode also writes fields SPIE and SIE in `vsstatus` and +writes CSRs `vsepc`, `vscause`, and `vstval`. + +[[h-vspp]] +.Value of `vsstatus` field SPP after a trap into VS-mode. +[%autowidth,float="center",align="center",cols="<,^",options="header"] +|=== +|Previous Mode |SPP +|VU-mode + +VS-mode |0 + +1 +|=== + +[[tinst-vals]] +==== Transformed Instruction or Pseudoinstruction for `mtinst` or `htinst` + +[[norm:H_trap_xtinst]] +On any trap into M-mode or HS-mode, one of these values is written +automatically into the appropriate trap instruction CSR, `mtinst` or +`htinst`: + +* zero; +* a transformation of the trapping instruction; +* a custom value (allowed only if the trapping instruction is +non-standard); or +* a special pseudoinstruction. + +Except when a pseudoinstruction value is required (described later), the +value written to `mtinst` or `htinst` may always be zero, indicating +that the hardware is providing no information in the register for this +particular trap. + +[NOTE] +==== +The value written to the trap instruction CSR serves two purposes. The +first is to improve the speed of instruction emulation in a trap +handler, partly by allowing the handler to skip loading the trapping +instruction from memory, and partly by obviating some of the work of +decoding and executing the instruction. The second purpose is to supply, +via pseudoinstructions, additional information about guest-page-fault +exceptions caused by implicit memory accesses done for VS-stage address +translation. + +A _transformation_ of the trapping instruction is written instead of +simply a copy of the original instruction in order to minimize the +burden for hardware yet still provide to a trap handler the information +needed to emulate the instruction. An implementation may at any time +reduce its effort by substituting zero in place of the transformed +instruction. +==== + +[#norm:H_trap_xtinst_interrupt]#On an interrupt, the value written to the trap instruction register is +always zero.# +[#norm:H_trap_xtinst_exception_lead-in]#On a synchronous exception, if a nonzero value is written, +one of the following shall be true about the value:# + +[[norm:H_trap_xtinst_exception_list]] +* Bit 0 is `1`, and replacing bit 1 with `1` makes the value into a +valid encoding of a standard instruction. ++ +In this case, the instruction that trapped is the same kind as indicated +by the register value, and the register value is the transformation of +the trapping instruction, as defined later. For example, if bits 1:0 are +binary `11` and the register value is the encoding of a standard LW +(load word) instruction, then the trapping instruction is LW, and the +register value is the transformation of the trapping LW instruction. +* Bit 0 is `1`, and replacing bit 1 with `1` makes the value into an +instruction encoding that is explicitly designated for a custom +instruction (_not_ an unused reserved encoding). ++ +This is a _custom value_. The instruction that trapped is a non-standard +instruction. The interpretation of a custom value is not otherwise +specified by this standard. +* The value is one of the special pseudoinstructions defined later, all +of which have bits 1:0 equal to `00`. + +These three cases exclude a large number of other possible values, such +as all those having bits 1:0 equal to binary `10`. A future standard or +extension may define additional cases, thus allowing values that are +currently excluded. Software may safely treat an unrecognized value in a +trap instruction register the same as zero. + +[NOTE] +==== +To be forward-compatible with future revisions of this standard, +software that interprets a nonzero value from `mtinst` or `htinst` must +fully verify that the value conforms to one of the cases listed above. +For instance, for RV64, discovering that bits 6:0 of `mtinst` are +`0000011` and bits 14:12 are `010` is not sufficient to establish that +the first case applies and the trapping instruction is a standard LW +instruction; rather, software must also confirm that bits 63:32 of +`mtinst` are all zeros. A future standard might define new values for +64-bit `mtinst` that are nonzero in bits 63:32 yet may coincidentally +have in bits 31:0 the same bit patterns as standard RV64 instructions. + +*** + +Unlike for standard instructions, there is no requirement that the +instruction encoding of a custom value be of the same ``kind'' as the +instruction that trapped (or even have any correlation with the trapping +instruction). +==== + +[[norm:H_trap_xtinst_val]] +<> shows the values that may be +automatically written to the trap instruction register for each standard +exception cause. For exceptions that prevent the fetching of an +instruction, only zero or a pseudoinstruction value may be written. A +custom value may be automatically written only if the instruction that +traps is non-standard. A future standard or extension may permit other +values to be written, chosen from the set of allowed values established +earlier. + +<<< + +[[tinst-values]] +.Values that may be automatically written to the trap instruction (`mtinst` or `htinst`) register on an exception trap. +[float="center",align="center",cols="2,^,^,^,^",options="header"] +|=== +<.>|Exception +^.>|Zero +|Transformed + +Standard + +Instruction +^.>|Custom Value +^.>|Pseudoinstruction Value +|Instruction address misaligned |Yes |No |Yes |No +|Instruction access fault + +Illegal instruction + +Breakpoint + +Virtual instruction +|Yes + +Yes + +Yes + +Yes +|No + +No + +No + +No + +|No + +No + +Yes + +Yes +|No + +No + +No + +No +|Load address misaligned + +Load access fault + +Store/AMO address misaligned + +Store/AMO access fault +|Yes + +Yes + +Yes + +Yes +|Yes + +Yes + +Yes + +Yes +|Yes + +Yes + +Yes + +Yes +|No + +No + +No + +No +|Environment call |Yes |No |Yes |No +|Instruction page fault + +Load page fault + +Store/AMO page fault +|Yes + +Yes + +Yes +|No + +Yes + +Yes +|No + +Yes + +Yes +|No + +No + +No +|Instruction guest-page fault + +Load guest-page fault + +Store/AMO guest-page fault +|Yes + +Yes + +Yes +|No + +Yes + +Yes +|No + +Yes + +Yes +|Yes + +Yes + +Yes +|=== + +As enumerated in the table, a synchronous exception may write to the +trap instruction register a standard transformation of the trapping +instruction only for exceptions that arise from explicit memory accesses +(from loads, stores, and AMO instructions). Accordingly, standard +transformations are currently defined only for these memory-access +instructions. If a synchronous trap occurs for a standard instruction +for which no transformation has been defined, the trap instruction +register shall be written with zero (or, under certain circumstances, +with a special pseudoinstruction value). + +For a standard load instruction that is not a compressed instruction and +is one of LB, LBU, LH, LHU, LW, LWU, LD, FLW, FLD, FLQ, or FLH, the +transformed instruction has the format shown in +<>. + +[[transformedloadinst]] +.Transformed load instruction (LB, LBU, LH, LHU, LW, LWU, LD, FLW, FLD, FLQ, or FLH). Fields funct3, rd, and opcode are the same as the trapping load instruction. +include::images/wavedrom/transformedloadinst.edn[] + +For a standard store instruction that is not a compressed instruction +and is one of SB, SH, SW, SD, FSW, FSD, FSQ, or FSH, the transformed +instruction has the format shown in +<>. + +[[transformedstoreinst]] +.Transformed store instruction (SB, SH, SW, SD, FSW, FSD, FSQ, or FSH). Fields rs2, funct3, and opcode are the same as the trapping store instruction. +include::images/wavedrom/transformedstoreinst.edn[] + +For a standard atomic instruction (load-reserved, store-conditional, or AMO instruction), the transformed instruction has the format shown in <>. + +[[transformedatomicinst]] +.Transformed atomic instruction (load-reserved, store-conditional, or AMO instruction). All fields are the same as the trapping instruction except bits 19:15, Addr. Offset. +include::images/wavedrom/transformedatomicinst.edn[] + +For a standard virtual-machine load/store instruction (HLV, HLVX, or HSV), the transformed instruction has the format shown in <>. + +[[transformedvmaccessinst]] +.Transformed virtual-machine load/store instruction (HLV, HLVX, HSV). All fields are the same as the trapping instruction except bits 19:15, Addr. Offset +include::images/wavedrom/transformedvmaccessinst.edn[] + +In all the transformed instructions above, the Addr. Offset field that +replaces the instruction’s rs1 field in bits 19:15 is the positive +difference between the faulting virtual address (written to `mtval` or +`stval`) and the original virtual address. This difference can be +nonzero only for a misaligned memory access. Note also that, for basic +loads and stores, the transformations replace the instruction’s +immediate offset fields with zero. + +For a standard compressed instruction (16-bit size), the transformed +instruction is found as follows: + +. Expand the compressed instruction to its 32-bit equivalent. +. Transform the 32-bit equivalent instruction. +. Replace bit 1 with a `0`. + +Bits 1:0 of a transformed standard instruction will be binary `01` if +the trapping instruction is compressed and `11` if not. +[NOTE] +==== +In decoding the contents of `mtinst` or `htinst`, once software has +determined that the register contains the encoding of a standard basic +load (LB, LBU, LH, LHU, LW, LWU, LD, FLW, FLD, FLQ, or FLH) or basic +store (SB, SH, SW, SD, FSW, FSD, FSQ, or FSH), it is not necessary to +confirm also that the immediate offset fields (31:25, and 24:20 or 11:7) +are zeros. The knowledge that the register’s value is the encoding of a +basic load/store is sufficient to prove that the trapping instruction is +of the same kind. + +A future version of this standard may add information to the fields that +are currently zeros. However, for backwards compatibility, any such +information will be for performance purposes only and can safely be +ignored. +==== + +[[norm:H_trap_xtinst_guestpage]] +For guest-page faults, the trap instruction register is written with a +special pseudoinstruction value if: (a) the fault is caused by an +implicit memory access for VS-stage address translation, and (b) a +nonzero value (the faulting guest physical address) is written to +`mtval2` or `htval`. If both conditions are met, the value written to +`mtinst` or `htinst` must be taken from +<>; zero is not allowed. + +[[pseudoinsts]] +.Special pseudoinstruction values for guest-page faults. The RV32 values are used when VSXLEN=32, and the RV64 values when VSXLEN=64. +[%autowidth,float="center",align="center",cols="<,<",options="header"] +|=== +|Value |Meaning +|`0x00002000` + +`0x00002020` +|32-bit read for VS-stage address translation (RV32) + +32-bit write for VS-stage address translation (RV32) + +|`0x00003000` + +`0x00003020` +|64-bit read for VS-stage address translation (RV64) + +64-bit write for VS-stage address translation (RV64) +|=== + +The defined pseudoinstruction values are designed to correspond closely +with the encodings of basic loads and stores, as illustrated by +<>. + +[[pseudoinsts-basis]] +.Standard instructions corresponding to the special pseudoinstructions of <>. +[%autowidth,float="center",align="center",cols="<,<",options="header"] +|=== +|Encoding |Instruction +|`0x00002003` + +`0x00002023` +|`lw x0,0(x0)` + +`sw x0,0(x0)` + +|`0x00003003` + +`0x00003023` +|`ld x0,0(x0)` + +`sd x0,0(x0)` +|=== + +[[norm:H_trap_xtinst_guestpage_rw]] +A _write_ pseudoinstruction (`0x00002020` or `0x00003020`) is used for +the case that the machine is attempting automatically to update bits A +and/or D in VS-level page tables. All other implicit memory accesses for +VS-stage address translation will be reads. If a machine never +automatically updates bits A or D in VS-level page tables (leaving this +to software), the _write_ case will never arise. The fact that such a +page table update must actually be atomic, not just a simple write, is +ignored for the pseudoinstruction. + +[NOTE] +==== +If the conditions that necessitate a pseudoinstruction value can ever +occur for M-mode, then `mtinst` cannot be entirely read-only zero; and +likewise for HS-mode and `htinst`. However, in that case, the trap +instruction registers may minimally support only values 0 and +`0x00002000` or `0x00003000`, and possibly `0x00002020` or `0x00003020`, +requiring as few as one or two flip-flops in hardware, per register. + +*** + +There is no harm here in ignoring the atomicity requirement for page +table updates, because a hypervisor is not expected in these +circumstances to emulate an implicit memory access that fails. Rather, +the hypervisor is given enough information about the faulting access to +be able to make the memory accessible (e.g. by restoring a missing page +of virtual memory) before resuming execution by retrying the faulting +instruction. +==== + +==== Trap Return + +[[norm:mret_h]] +The MRET instruction is used to return from a trap taken into M-mode. +MRET first determines what the new privilege mode will be according to +the values of MPP and MPV in `mstatus` or `mstatush`, as encoded in +<>. MRET then in `mstatus`/`mstatush` sets +MPV=0, MPP=0, MIE=MPIE, and MPIE=1. Lastly, MRET sets the privilege mode +as previously determined, and sets `pc`=`mepc`. + +[[norm:sret_h]] +The SRET instruction is used to return from a trap taken into HS-mode or +VS-mode. Its behavior depends on the current virtualization mode. + +[[norm:mret_v0]] +When executed in M-mode or HS-mode (i.e., V=0), SRET first determines +what the new privilege mode will be according to the values in +`hstatus`.SPV and `sstatus`.SPP, as encoded in +<>. SRET then sets `hstatus`.SPV=0, and in +`sstatus` sets SPP=0, SIE=SPIE, and SPIE=1. Lastly, SRET sets the +privilege mode as previously determined, and sets `pc`=`sepc`. + +[[norm:mret_v1]] +When executed in VS-mode (i.e., V=1), SRET sets the privilege mode +according to <>, in `vsstatus` sets SPP=0, +SIE=SPIE, and SPIE=1, and lastly sets `pc`=`vsepc`. + +[[norm:mret_dt]] +If the Ssdbltrp extension is implemented, when `SRET` is executed in HS-mode, +if the new privilege mode is VU, the `SRET` instruction sets `vsstatus.SDT` +to 0. When executed in VS-mode, `vsstatus.SDT` is set to 0. diff --git a/param_extraction/chunks/chunk_014.txt.license b/param_extraction/chunks/chunk_014.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_014.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_015.txt b/param_extraction/chunks/chunk_015.txt new file mode 100644 index 0000000000..2a43967570 --- /dev/null +++ b/param_extraction/chunks/chunk_015.txt @@ -0,0 +1,10 @@ +# Chunk: chunk_015 +# Source: index.adoc +# Lines: 1-2 (of 2) +# Content starts: line 1 +# Line count: 2 +# Sections: 1 +# == Index +# +[index] +== Index diff --git a/param_extraction/chunks/chunk_015.txt.license b/param_extraction/chunks/chunk_015.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_015.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_016.txt b/param_extraction/chunks/chunk_016.txt new file mode 100644 index 0000000000..b701869564 --- /dev/null +++ b/param_extraction/chunks/chunk_016.txt @@ -0,0 +1,346 @@ +# Chunk: chunk_016 +# Source: indirect-csr.adoc +# Lines: 1-333 (of 333) +# Content starts: line 1 +# Line count: 333 +# Sections: 6 +# == "Smcsrind/Sscsrind" Indirect CSR Access, Version 1.0 +# === Introduction +# === Machine-level CSRs +# === Supervisor-level CSRs +# === Virtual Supervisor-level CSRs +# === Access control by the state-enable CSRs +# +[[indirect-csr]] +== "Smcsrind/Sscsrind" Indirect CSR Access, Version 1.0 + +=== Introduction + +Smcsrind/Sscsrind is an ISA extension that extends the indirect CSR +access mechanism originally defined as part of the +https://github.com/riscv/riscv-aia[[.underline]#Smaia/Ssaia +extensions#], in order to make it available for use by other extensions +without creating an unnecessary dependence on Smaia/Ssaia. + +This extension confers two benefits: + +. It provides a means to access an array of registers via CSRs without +requiring allocation of large chunks of the limited CSR address space. + +. It enables software to access each of an array of registers by index, +without requiring a switch statement with a case for each register. + +[%unbreakable] +[NOTE] +==== +CSRs are accessed indirectly via this extension using select values, in +contrast to being accessed directly using standard CSR numbers. A CSR +accessible via one method may or may not be accessible via the other +method. Select values are a separate address space from CSR numbers, and +from tselect values in the Sdtrig extension. If a CSR is both directly +and indirectly accessible, the CSR's select value is unrelated to its +CSR number. + +Further, Machine-level and Supervisor-level select values are separate +address spaces from each other; however, Machine-level and +Supervisor-level CSRs with the same select value may be defined by an +extension as partial or full aliases with respect to each other. This +typically would be done for CSRs that can be delegated from +Machine-level to Supervisor-level. +==== + +The machine-level extension *Smcsrind* encompasses all added CSRs and +all behavior modifications for a hart, over all privilege levels. For a +supervisor-level environment, extension *Sscsrind* is essentially the +same as Smcsrind except excluding the machine-level CSRs and behavior +not directly visible to supervisor level. + +[[body]] +=== Machine-level CSRs + +[width="100%",cols="15%,12%,12%,15%,46%",options="header",] +|=== +|*Number* |*Privilege* |*Width* |*Name* |*Description* +|0x350 |MRW |XLEN |`miselect` |Machine indirect register select +|0x351 |MRW |XLEN |`mireg` |Machine indirect register alias +|0x352 |MRW |XLEN |`mireg2` |Machine indirect register alias 2 +|0x353 |MRW |XLEN |`mireg3` |Machine indirect register alias 3 +|0x355 |MRW |XLEN |`mireg4` |Machine indirect register alias 4 +|0x356 |MRW |XLEN |`mireg5` |Machine indirect register alias 5 +|0x357 |MRW |XLEN |`mireg6` |Machine indirect register alias 6 +|=== + +[%unbreakable] +[NOTE] +==== +The `mireg*` CSR numbers are not consecutive because miph is CSR number +0x354. +==== + +The CSRs listed in the table above provide a window for accessing +register state indirectly. The value of `miselect` determines which +register is accessed upon read or write of each of the machine indirect alias +CSRs (`mireg*`). `miselect` value ranges are allocated to dependent +extensions, which specify the register state accessible via each +`mireg__i__` register, for each `miselect` value. `miselect` is a WARL +register. + +The `miselect` register implements at least enough bits to support all +implemented `miselect` values (corresponding to the implemented extensions +that utilize `miselect`/`mireg*` to indirectly access register state). The +`miselect` register may be read-only zero if there are no extensions +implemented that utilize it. + +Values of `miselect` with the most-significant bit set (bit XLEN - 1 = 1) +are designated only for custom use, presumably for accessing custom +registers through the alias CSRs. Values of `miselect` with the +most-significant bit clear are designated only for standard use and are +reserved until allocated to a standard architecture extension. If XLEN +is changed, the most-significant bit of `miselect` moves to the new +position, retaining its value from before. + +[%unbreakable] +[NOTE] +==== +An implementation is not required to support any custom values for +`miselect`. +==== + +The behavior upon accessing `mireg*` from M-mode, while `miselect` holds a +value that is not implemented, is UNSPECIFIED. + +[%unbreakable] +[NOTE] +==== +It is expected that implementations will typically raise an illegal-instruction +exception for such accesses, so that, for example, they can +be identified as software bugs. Platform specs, profile specs, and/or +the Privileged ISA spec may place more restrictions on behavior for such +accesses. +==== + +Attempts to access `mireg*` while `miselect` holds a number in an allocated +and implemented range results in a specific behavior that, for each +combination of `miselect` and `mireg__i__`, is defined by the extension to +which the `miselect` value is allocated. + +[%unbreakable] +[NOTE] +==== +Ordinarily, each `mireg`*_i_* will access register state, access +read-only 0 state, or raise an illegal-instruction exception. + +For RV32, if an extension defines an indirectly accessed register as 64 bits wide, it is recommended that the lower 32 bits of the register are accessed through one of `mireg`, `mireg2`, or `mireg3`, while the upper 32 bits are accessed through `mireg4`, `mireg5`, or `mireg6`, respectively. +==== + +[%unbreakable] +[NOTE] +==== +Six `\*ireg*` registers are defined in order to ensure that the needs of extensions in development are covered, with some room for growth. For example, for an `siselect` value associated with counter X, `sireg`/`sireg2` could be used to access `mhpmcounterX`/`mhpmeventX`, while `sireg4`/`sireg5` could access `mhpmcounterXh`/`mhpmeventXh`. Six `\*ireg*` registers allows for accessing up to 3 CSR arrays per index (`*iselect`) with RV32-only CSRs, or up to 6 CSR arrays per index value without RV32-only CSRs. +==== + +=== Supervisor-level CSRs + +[width="100%",cols="15%,12%,12%,15%,46%",options="header",] +|=== +|*Number* |*Privilege* |*Width* |*Name* |*Description* +|0x150 |SRW |XLEN |`siselect` |Supervisor indirect register select +|0x151 |SRW |XLEN |`sireg` |Supervisor indirect register alias +|0x152 |SRW |XLEN |`sireg2` |Supervisor indirect register alias 2 +|0x153 |SRW |XLEN |`sireg3` |Supervisor indirect register alias 3 +|0x155 |SRW |XLEN |`sireg4` |Supervisor indirect register alias 4 +|0x156 |SRW |XLEN |`sireg5` |Supervisor indirect register alias 5 +|0x157 |SRW |XLEN |`sireg6` |Supervisor indirect register alias 6 +|=== + +The CSRs in the table above are required if S-mode is implemented. + +The `siselect` register will support the value range 0..0xFFF at a +minimum. A future extension may define a value range outside of this +minimum range. Only if such an extension is implemented will `siselect` be +required to support larger values. + +[%unbreakable] +[NOTE] +==== +Requiring a range of 0–0xFFF for `siselect`, even though most or +all of the space may be reserved or inaccessible, permits M-mode to +emulate indirectly accessed registers in this implemented range, +including registers that may be standardized in the future. +==== + +Values of `siselect` with the most-significant bit set (bit XLEN - 1 = 1) +are designated only for custom use, presumably for accessing custom registers through the alias +CSRs. Values of `siselect` with the most-significant bit clear are +designated only for standard use and are reserved until allocated to a +standard architecture extension. If XLEN is changed, the +most-significant bit of `siselect` moves to the new position, retaining +its value from before. + +The behavior upon accessing `sireg*` from M-mode or S-mode, while `siselect` +holds a value that is not implemented at supervisor level, is UNSPECIFIED. + +[%unbreakable] +[NOTE] +==== +It is recommended that implementations raise an illegal-instruction +exception for such accesses, to facilitate possible emulation (by +M-mode) of these accesses. +==== + +[%unbreakable] +[NOTE] +==== +An extension is considered not to be implemented at supervisor level if +machine level has disabled the extension for S-mode, such as by the +settings of certain fields in CSR `menvcfg`, for example. +==== + +Otherwise, attempts to access `sireg*` from M-mode or S-mode while +`siselect` holds a number in a standard-defined and implemented range +result in specific behavior that, for each combination of `siselect` and +`sireg__i__`, is defined by the extension to which the `siselect` value is +allocated. + +[%unbreakable] +[NOTE] +==== +Ordinarily, each `sireg`*_i_* will access register state, access +read-only 0 state, or, unless executing in a virtual machine (covered in +the next section), raise an illegal-instruction exception. +==== + +Note that the widths of `siselect` and `sireg*` are always the +current XLEN rather than SXLEN. Hence, for example, if MXLEN = 64 and +SXLEN = 32, then these registers are 64 bits when the current privilege +mode is M (running RV64 code) but 32 bits when the privilege mode is S +(RV32 code). + +=== Virtual Supervisor-level CSRs + +[width="100%",cols="15%,12%,12%,15%,46%",options="header",] +|=== +|*Number* |*Privilege* |*Width* |*Name* |*Description* +|0x250 |HRW |XLEN |`vsiselect` |Virtual supervisor indirect register +select + +|0x251 |HRW |XLEN |`vsireg` |Virtual supervisor indirect register alias + +|0x252 |HRW |XLEN |`vsireg2` |Virtual supervisor indirect register alias 2 + +|0x253 |HRW |XLEN |`vsireg3` |Virtual supervisor indirect register alias 3 + +|0x255 |HRW |XLEN |`vsireg4` |Virtual supervisor indirect register alias 4 + +|0x256 |HRW |XLEN |`vsireg5` |Virtual supervisor indirect register alias 5 + +|0x257 |HRW |XLEN |`vsireg6` |Virtual supervisor indirect register alias 6 +|=== + +The CSRs in the table above are required if the hypervisor extension is +implemented. These VS CSRs all match supervisor CSRs, and substitute for +those supervisor CSRs when executing in a virtual machine (in VS-mode or +VU-mode). + +The `vsiselect` register will support the value range 0..0xFFF at a +minimum. A future extension may define a value range outside of this +minimum range. Only if such an extension is implemented will `vsiselect` +be required to support larger values. + +[%unbreakable] +[NOTE] +==== +Requiring a range of 0–0xFFF for `vsiselect`, even though most or all of +the space may be reserved or inaccessible, permits a hypervisor to +emulate indirectly accessed registers in this implemented range, +including registers that may be standardized in the future. + +More generally it is recommended that `vsiselect` and `siselect` be +implemented with the same number of bits. This also avoids creation of a +virtualization hole due to observable differences between `vsiselect` and +`siselect` widths. +==== + +Values of `vsiselect` with the most-significant bit set (bit XLEN - 1 = 1) +are designated only for custom use, presumably for accessing custom registers through the alias +CSRs. Values of `vsiselect` with the most-significant bit clear are +designated only for standard use and are reserved until allocated to a +standard architecture extension. If XLEN is changed, the +most-significant bit of `vsiselect` moves to the new position, retaining +its value from before. + +For alias CSRs `sireg*` and `vsireg*`, the hypervisor extension’s usual +rules for when to raise a virtual-instruction exception (based on +whether an instruction is HS-qualified) are not applicable. The +rules given in this section for `sireg` and `vsireg` apply instead, unless +overridden by the requirements specified in the section below, which +take precedence over this section when extension Smstateen is also +implemented. + +A virtual-instruction exception is raised for attempts from VS-mode or VU-mode to directly access `vsiselect` or `vsireg*`, or attempts from VU-mode to access `siselect` or `sireg*`. + +The behavior upon accessing `vsireg*` from M-mode or HS-mode, or accessing `sireg*` (really `vsireg*`) from VS-mode, while `vsiselect` holds a value that is not implemented at HS level, is UNSPECIFIED. + +[%unbreakable] +[NOTE] +==== +It is recommended that implementations raise an illegal-instruction exception for such accesses, to facilitate possible emulation (by M-mode) of these accesses. +==== + +Otherwise, while `vsiselect` holds a number in a standard-defined and +implemented range, attempts to access `vsireg*` from a sufficiently +privileged mode, or to access `sireg*` (really `vsireg*`) from VS-mode, +result in specific behavior that, for each combination of `vsiselect` and +`vsireg__i__`, is defined by the extension to which the `vsiselect` value is +allocated. + +[%unbreakable] +[NOTE] +==== +Ordinarily, each `vsireg`*_i_* will access register state, access read-only 0 state, or raise an exception (either an illegal-instruction exception or, for select accesses from VS-mode, a virtual-instruction exception). When `vsiselect` holds a value that is implemented at HS level but not at VS level, attempts to access `sireg*` (really `vsireg*`) from VS-mode will typically raise a virtual-instruction exception. But there may be cases specific to an extension where different behavior is more appropriate. +==== + +Like `siselect` and `sireg*`, the widths of `vsiselect` and `vsireg*` are always +the current XLEN rather than VSXLEN. Hence, for example, if HSXLEN = 64 +and VSXLEN = 32, then these registers are 64 bits when accessed by a +hypervisor in HS-mode (running RV64 code) but 32 bits for a guest OS in +VS-mode (RV32 code). + +=== Access control by the state-enable CSRs + +If extension Smstateen is implemented together with Smcsrind, bit 60 of +state-enable register `mstateen0` controls access to `siselect`, `sireg*`, +`vsiselect`, and `vsireg*`. When `mstateen0`[60]=0, an attempt to access one +of these CSRs from a privilege mode less privileged than M-mode results +in an illegal-instruction exception. As always, the state-enable CSRs do +not affect the accessibility of any state when in M-mode, only in less +privileged modes. For more explanation, see the documentation for +extension +https://github.com/riscv/riscv-state-enable/releases/download/v1.0.0/Smstateen.pdf[[.underline]#Smstateen#]. + +Other extensions may specify that certain mstateen bits control access +to registers accessed indirectly through `siselect` + `sireg*`, and/or +`vsiselect` + `vsireg*`. However, regardless of any other mstateen bits, if +`mstateen0`[60] = 1, a virtual-instruction exception is raised as +described in the previous section for all attempts from VS-mode or +VU-mode to directly access `vsiselect` or `vsireg*`, and for all attempts +from VU-mode to access `siselect` or `sireg*`. + +If the hypervisor extension is implemented, the same bit is defined also +in hypervisor CSR `hstateen0`, but controls access to only `siselect` and `sireg*` +(really `vsiselect` and `vsireg*`), which is the state potentially +accessible to a virtual machine executing in VS or VU-mode. When +`hstateen0`[60]=0 and `mstateen0`[60]=1, all attempts from VS or VU-mode to +access `siselect` or `sireg*` raise a virtual-instruction exception, not an +illegal-instruction exception, regardless of the value of `vsiselect` or +any other mstateen bit. + +Extension Ssstateen is defined as the supervisor-level view of +Smstateen. Therefore, the combination of Sscsrind and Ssstateen +incorporates the bit defined above for `hstateen0` but not that for +`mstateen0`, since machine-level CSRs are not visible to supervisor level. + +[NOTE] +==== +CSR address space is reserved for a possible future "Sucsrind" extension that extends indirect CSR access to user mode. +==== diff --git a/param_extraction/chunks/chunk_016.txt.license b/param_extraction/chunks/chunk_016.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_016.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_017.txt b/param_extraction/chunks/chunk_017.txt new file mode 100644 index 0000000000..9ab456083b --- /dev/null +++ b/param_extraction/chunks/chunk_017.txt @@ -0,0 +1,711 @@ +# Chunk: chunk_017 +# Source: intro.adoc +# Lines: 1-696 (of 696) +# Content starts: line 1 +# Line count: 696 +# Sections: 8 +# == Introduction +# === RISC-V Hardware Platform Terminology +# === RISC-V Software Execution Environments and Harts +# === RISC-V ISA Overview +# === Memory +# === Base Instruction-Length Encoding +# === Exceptions, Traps, and Interrupts +# === UNSPECIFIED Behaviors and Values +# +== Introduction + + +RISC-V (pronounced "risk-five") is a new instruction-set architecture +(ISA) that was originally designed to support computer architecture +research and education, but which we now hope will also become a +standard free and open architecture for industry implementations. Our +goals in defining RISC-V include: + +* A completely _open_ ISA that is freely available to academia and +industry. +* A _real_ ISA suitable for direct native hardware implementation, not +just simulation or binary translation. +* An ISA that avoids "over-architecting" for a particular +microarchitecture style (e.g., microcoded, in-order, decoupled, +out-of-order) or implementation technology (e.g., full-custom, ASIC, +FPGA), but which allows efficient implementation in any of these. +* An ISA separated into a _small_ base integer ISA, usable by itself as +a base for customized accelerators or for educational purposes, and +optional standard extensions, to support general-purpose software +development. +* Support for the revised 2008 IEEE-754 floating-point standard. cite:[ieee754-2008] +* An ISA supporting extensive ISA extensions and specialized variants. +* Both 32-bit and 64-bit address space variants for applications, +operating system kernels, and hardware implementations. +* An ISA with support for highly parallel multicore or manycore +implementations, including heterogeneous multiprocessors. +* Optional _variable-length instructions_ to both expand available +instruction encoding space and to support an optional _dense instruction +encoding_ for improved performance, static code size, and energy +efficiency. +* A fully virtualizable ISA to ease hypervisor development. +* An ISA that simplifies experiments with new privileged architecture +designs. + +[NOTE] +==== +Commentary on our design decisions is formatted as in this paragraph. +This non-normative text can be skipped if the reader is only interested +in the specification itself. +==== + +[NOTE] +==== +The name RISC-V was chosen to represent the fifth major RISC ISA design +from UC Berkeley (RISC-I cite:[riscI-isca1981], RISC-II cite:[Katevenis:1983], SOAR cite:[Ungar:1984], and SPUR cite:[spur-jsscc1989] were the first +four). We also pun on the use of the Roman numeral "V" to signify +"variations" and "vectors", as support for a range of architecture +research, including various data-parallel accelerators, is an explicit +goal of the ISA design. +==== +(((ISA, definition))) +The RISC-V ISA is defined avoiding implementation details as much as +possible (although commentary is included on implementation-driven +decisions) and should be read as the software-visible interface to a +wide variety of implementations rather than as the design of a +particular hardware artifact. The RISC-V manual is structured in two +volumes. This volume covers the design of the base _unprivileged_ +instructions, including optional unprivileged ISA extensions. +Unprivileged instructions are those that are generally usable in all +privilege modes in all privileged architectures, though behavior might +vary depending on privilege mode and privilege architecture. The second +volume provides the design of the first ("classic") privileged +architecture. The manuals use IEC 80000-13:2008 conventions, with a byte +of 8 bits. + +[NOTE] +==== +In the unprivileged ISA design, we tried to remove any dependence on +particular microarchitectural features, such as cache line size, or on +privileged architecture details, such as page translation. This is both +for simplicity and to allow maximum flexibility for alternative +microarchitectures or alternative privileged architectures. +==== + +=== RISC-V Hardware Platform Terminology + + +A RISC-V hardware platform can contain one or more RISC-V-compatible +processing cores together with other non-RISC-V-compatible cores, +fixed-function accelerators, various physical memory structures, I/O +devices, and an interconnect structure to allow the components to +communicate. +(((core, component))) + +A component is termed a _core_ if it contains an independent instruction +fetch unit. A RISC-V-compatible core might support multiple +RISC-V-compatible hardware threads, or _harts_, through multithreading. +(((core, extensions, coprocessor))) + +A RISC-V core might have additional specialized instruction-set +extensions or an added _coprocessor_. We use the term _coprocessor_ to +refer to a unit that is attached to a RISC-V core and is mostly +sequenced by a RISC-V instruction stream, but which contains additional +architectural state and instruction-set extensions, and possibly some +limited autonomy relative to the primary RISC-V instruction stream. + +We use the term _accelerator_ to refer to either a non-programmable +fixed-function unit or a core that can operate autonomously but is +specialized for certain tasks. In RISC-V systems, we expect many +programmable accelerators will be RISC-V-based cores with specialized +instruction-set extensions and/or customized coprocessors. An important +class of RISC-V accelerators are I/O accelerators, which offload I/O +processing tasks from the main application cores. +(((core, accelerator))) + +The system-level organization of a RISC-V hardware platform can range +from a single-core microcontroller to a many-thousand-node cluster of +shared-memory manycore server nodes. Even small systems-on-a-chip might +be structured as a hierarchy of multicomputers and/or multiprocessors to +modularize development effort or to provide secure isolation between +subsystems. +(((core, cluster, multiprocessors))) + +=== RISC-V Software Execution Environments and Harts + + +The behavior of a RISC-V program depends on the execution environment in +which it runs. A RISC-V execution environment interface (EEI) defines +the initial state of the program, the number and type of harts in the +environment including the privilege modes supported by the harts, the +accessibility and attributes of memory and I/O regions, the behavior of +all legal instructions executed on each hart (i.e., the ISA is one +component of the EEI), and the handling of any interrupts or exceptions +raised during execution including environment calls. Examples of EEIs +include the Linux application binary interface (ABI), or the RISC-V +supervisor binary interface (SBI). The implementation of a RISC-V +execution environment can be pure hardware, pure software, or a +combination of hardware and software. For example, opcode traps and +software emulation can be used to implement functionality not provided +in hardware. Examples of execution environment implementations include: + +* "Bare metal" hardware platforms where harts are directly implemented +by physical processor threads and instructions have full access to the +physical address space. The hardware platform defines an execution +environment that begins at power-on reset. +* RISC-V operating systems that provide multiple user-level execution +environments by multiplexing user-level harts onto available physical +processor threads and by controlling access to memory via virtual +memory. +* RISC-V hypervisors that provide multiple supervisor-level execution +environments for guest operating systems. +* RISC-V emulators, such as Spike, QEMU or rv8, which emulate RISC-V +harts on an underlying x86 system, and which can provide either a +user-level or a supervisor-level execution environment. + +[NOTE] +==== +A bare hardware platform can be considered to define an EEI, where the +accessible harts, memory, and other devices populate the environment, +and the initial state is that at power-on reset. Generally, most +software is designed to use a more abstract interface to the hardware, +as more abstract EEIs provide greater portability across different +hardware platforms. Often EEIs are layered on top of one another, where +one higher-level EEI uses another lower-level EEI. +==== +(((hart, execution environment))) +From the perspective of software running in a given execution +environment, a hart is a resource that autonomously fetches and executes +RISC-V instructions within that execution environment. In this respect, +a hart behaves like a hardware thread resource even if time-multiplexed +onto real hardware by the execution environment. Some EEIs support the +creation and destruction of additional harts, for example, via +environment calls to fork new harts. + +The execution environment is responsible for ensuring the eventual +forward progress of each of its harts. For a given hart, that +responsibility is suspended while the hart is exercising a mechanism +that explicitly waits for an event, such as the wait-for-interrupt +instruction defined in Volume II of this specification; and that +responsibility ends if the hart is terminated. The following events +constitute forward progress: + +* The retirement of an instruction. +* A trap, as defined in <>. +* Any other event defined by an extension to constitute forward +progress. + +[NOTE] +==== +The term hart was introduced in the work on Lithe cite:[lithe-pan-hotpar09] and cite:[lithe-pan-pldi10] to provide a term to +represent an abstract execution resource as opposed to a software thread +programming abstraction. + +The important distinction between a hardware thread (hart) and a +software thread context is that the software running inside an execution +environment is not responsible for causing progress of each of its +harts; that is the responsibility of the outer execution environment. So +the environment's harts operate like hardware threads from the +perspective of the software inside the execution environment. + +An execution environment implementation might time-multiplex a set of +guest harts onto fewer host harts provided by its own execution +environment but must do so in a way that guest harts operate like +independent hardware threads. In particular, if there are more guest +harts than host harts then the execution environment must be able to +preempt the guest harts and must not wait indefinitely for guest +software on a guest hart to "yield" control of the guest hart. +==== + +=== RISC-V ISA Overview + + +A RISC-V ISA is defined as a base integer ISA, which must be present in +any implementation, plus optional extensions to the base ISA. The base +integer ISAs are very similar to that of the early RISC processors +except with no branch delay slots and with support for optional +variable-length instruction encodings. A base is carefully restricted to +a minimal set of instructions sufficient to provide a reasonable target +for compilers, assemblers, linkers, and operating systems (with +additional privileged operations), and so provides a convenient ISA and +software toolchain "skeleton" around which more customized processor +ISAs can be built. + +Although it is convenient to speak of _the_ RISC-V ISA, RISC-V is +actually a family of related ISAs, of which there are currently four +base ISAs. Each base integer instruction set is characterized by the +width of the integer registers and the corresponding size of the address +space and by the number of integer registers. There are two primary base +integer variants, RV32I and RV64I, described in +<> and <>, which provide 32-bit +or 64-bit address spaces respectively. We use the term XLEN to refer to +the width of an integer register in bits (either 32 or 64). +<> describes the RV32E and RV64E subset variants of the +RV32I or RV64I base instruction sets respectively, which have been added to support small +microcontrollers, and which have half the number of integer registers. +The base integer instruction sets use a two's-complement +representation for signed integer values. + + +[NOTE] +==== +Although 64-bit address spaces are a requirement for larger systems, we +believe 32-bit address spaces will remain adequate for many embedded and +client devices for decades to come and will be desirable to lower memory +traffic and energy consumption. In addition, 32-bit address spaces are +sufficient for educational purposes. A larger flat 128-bit address space +might eventually be required and could be accommodated with a new RV128I +base ISA within the existing RISC-V ISA framework. +==== + +[NOTE] +==== +The four base ISAs in RISC-V are treated as distinct base ISAs. A common +question is why is there not a single ISA, and in particular, why is +RV32I not a strict subset of RV64I? Some earlier ISA designs (SPARC, +MIPS) adopted a strict superset policy when increasing address space +size to support running existing 32-bit binaries on new 64-bit hardware. + +The main advantage of explicitly separating base ISAs is that each base +ISA can be optimized for its needs without requiring to support all the +operations needed for other base ISAs. For example, RV64I can omit +instructions and CSRs that are only needed to cope with the narrower +registers in RV32I. The RV32I variants can use encoding space otherwise +reserved for instructions only required by wider address-space variants. + +The main disadvantage of not treating the design as a single ISA is that +it complicates the hardware needed to emulate one base ISA on another +(e.g., RV32I on RV64I). However, differences in addressing and +illegal-instruction traps generally mean some mode switch would be required in +hardware in any case even with full superset instruction encodings, and +the different RISC-V base ISAs are similar enough that supporting +multiple versions is relatively low cost. Although some have proposed +that the strict superset design would allow legacy 32-bit libraries to +be linked with 64-bit code, this is impractical in practice, even with +compatible encodings, due to the differences in software calling +conventions and system-call interfaces. + +The RISC-V privileged architecture provides fields in `misa` to control +the unprivileged ISA at each level to support emulating different base +ISAs on the same hardware. We note that newer SPARC and MIPS ISA +revisions have deprecated support for running 32-bit code unchanged on +64-bit systems. + +A related question is why there is a different encoding for 32-bit adds +in RV32I (ADD) and RV64I (ADDW)? The ADDW opcode could be used for +32-bit adds in RV32I and ADDD for 64-bit adds in RV64I, instead of the +existing design which uses the same opcode ADD for 32-bit adds in RV32I +and 64-bit adds in RV64I with a different opcode ADDW for 32-bit adds in +RV64I. This would also be more consistent with the use of the same LW +opcode for 32-bit load in both RV32I and RV64I. The very first versions +of RISC-V ISA did have a variant of this alternate design, but the +RISC-V design was changed to the current choice in January 2011. Our +focus was on supporting 32-bit integers in the 64-bit ISA, not on +providing compatibility with the 32-bit ISA, and the motivation was to +remove the asymmetry that arose from having not all opcodes in RV32I +have a *W suffix (e.g., ADDW, but AND not ANDW). In hindsight, this was +perhaps not well-justified and a consequence of designing both ISAs at +the same time as opposed to adding one later to sit on top of another, +and also from a belief we had to fold platform requirements into the ISA +spec which would imply that all the RV32I instructions would have been +required in RV64I. It is too late to change the encoding now, but this +is also of little practical consequence for the reasons stated above. + +It has been noted we could enable the *W variants as an extension to +RV32I systems to provide a common encoding across RV64I and a future +RV32 variant. +==== + +RISC-V has been designed to support extensive customization and +specialization. Each base integer ISA can be extended with one or more +optional instruction-set extensions. An extension may be categorized as +either standard, custom, or non-conforming. For this purpose, we divide +each RISC-V instruction-set encoding space (and related encoding spaces +such as the CSRs) into three disjoint categories: _standard_, +_reserved_, and _custom_. Standard extensions and encodings are defined +by RISC-V International; any extensions not defined by RISC-V International are +_non-standard_. Each base ISA and its standard extensions use only +standard encodings, and shall not conflict with each other in their uses +of these encodings. Reserved encodings are currently not defined but are +saved for future standard extensions; once thus used, they become +standard encodings. Custom encodings shall never be used for standard +extensions and are made available for vendor-specific non-standard +extensions. Non-standard extensions are either custom extensions, that +use only custom encodings, or _non-conforming_ extensions, that use any +standard or reserved encoding. Instruction-set extensions are generally +shared but may provide slightly different functionality depending on the +base ISA. We have also developed a naming convention +for RISC-V base instructions and instruction-set extensions, described +in detail in <>. + +To support more general software development, a set of standard +extensions are defined to provide integer multiply/divide, atomic +operations, and single and double-precision floating-point arithmetic. +The base integer ISA is named "I" (prefixed by RV32 or RV64 depending +on integer register width), and contains integer computational +instructions, integer loads, integer stores, and control-flow +instructions. The standard integer multiplication and division extension +is named "M", and adds instructions to multiply and divide values held +in the integer registers. The standard atomic instruction extension, +denoted by "A", adds instructions that atomically read, modify, and +write memory for inter-processor synchronization. The standard +single-precision floating-point extension, denoted by "F", adds +floating-point registers, single-precision computational instructions, +and single-precision loads and stores. The standard double-precision +floating-point extension, denoted by "D", expands the floating-point +registers, and adds double-precision computational instructions, loads, +and stores. The standard "C" compressed instruction extension provides +narrower 16-bit forms of common instructions. + +Beyond the base integer ISA and these standard extensions, we believe +it is rare that a new instruction will provide a significant benefit for +all applications, although it may be very beneficial for a certain +domain. As energy efficiency concerns are forcing greater +specialization, we believe it is important to simplify the required +portion of an ISA specification. Whereas other architectures usually +treat their ISA as a single entity, which changes to a new version as +instructions are added over time, RISC-V will endeavor to keep the base +and each standard extension constant over time, and instead layer new +instructions as further optional extensions. For example, the base +integer ISAs will continue as fully supported standalone ISAs, +regardless of any subsequent extensions. + +=== Memory + + +A RISC-V hart has a single byte-addressable address space of +2^XLEN^ bytes for all memory accesses. A _word_ of +memory is defined as 32{nbsp}bits (4{nbsp}bytes). Correspondingly, a _halfword_ is 16{nbsp}bits (2{nbsp}bytes), a +_doubleword_ is 64{nbsp}bits (8{nbsp}bytes), and a _quadword_ is 128{nbsp}bits (16{nbsp}bytes). The memory address space is +circular, so that the byte at address 2^XLEN^−1 is +adjacent to the byte at address zero. Accordingly, memory address +computations done by the hardware ignore overflow and instead wrap +around modulo 2^XLEN^. + +The execution environment determines the mapping of hardware resources +into a hart's address space. Different address ranges of a hart's +address space may (1) contain _main memory_, or +(2) contain one or more _I/O devices_. Reads and writes of I/O devices +may have visible side effects, but accesses to main memory cannot. +Vacant address ranges are not a separate category but can be represented as +either main memory or I/O regions that are not accessible. +Although it is possible for the execution environment to call everything +in a hart's address space an I/O device, it is usually expected that +some portion will be specified as main memory. + +When a RISC-V platform has multiple harts, the address spaces of any two +harts may be entirely the same, or entirely different, or may be partly +different but sharing some subset of resources, mapped into the same or +different address ranges. + +[NOTE] +==== +For a purely "bare metal" environment, all harts may see an identical +address space, accessed entirely by physical addresses. However, when +the execution environment includes an operating system employing address +translation, it is common for each hart to be given a virtual address +space that is largely or entirely its own. +==== +(((memory access, implicit and explicit))) + +Executing each RISC-V machine instruction entails one or more memory +accesses, subdivided into _implicit_ and _explicit_ accesses. For each +instruction executed, an _implicit_ memory read (instruction fetch) is +done to obtain the encoded instruction to execute. Many RISC-V +instructions perform no further memory accesses beyond instruction +fetch. Specific load and store instructions perform an _explicit_ read +or write of memory at an address determined by the instruction. The +execution environment may dictate that instruction execution performs +other _implicit_ memory accesses (such as to implement address +translation) beyond those documented for the unprivileged ISA. + +The execution environment determines what portions of the +address space are accessible for each kind of memory access. For +example, the set of locations that can be implicitly read for +instruction fetch may or may not have any overlap with the set of +locations that can be explicitly read by a load instruction; and the set +of locations that can be explicitly written by a store instruction may +be only a subset of locations that can be read. Ordinarily, if an +instruction attempts to access memory at an inaccessible address, an +exception is raised for the instruction. + +Except when specified otherwise, implicit reads that do not raise an +exception and that have no side effects may occur arbitrarily early and +speculatively, even before the machine could possibly prove that the +read will be needed. For instance, a valid implementation could attempt +to read all of main memory at the earliest opportunity, cache as many +fetchable (executable) bytes as possible for later instruction fetches, +and avoid reading main memory for instruction fetches ever again. To +ensure that certain implicit reads are ordered only after writes to the +same memory locations, software must execute specific fence or +cache-control instructions defined for this purpose (such as the FENCE.I +instruction defined in <>). +(((memory access, implicit and explicit))) + +The memory accesses (implicit or explicit) made by a hart may appear to +occur in a different order as perceived by another hart or by any other +agent that can access the same memory. This perceived reordering of +memory accesses is always constrained, however, by the applicable memory +consistency model. The default memory consistency model for RISC-V is +the RISC-V Weak Memory Ordering (RVWMO), defined in +<> and in appendices. Optionally, +an implementation may adopt the stronger model of Total Store Ordering, +as defined in <>. The execution environment +may also add constraints that further limit the perceived reordering of +memory accesses. Since the RVWMO model is the weakest model allowed for +any RISC-V implementation, software written for this model is compatible +with the actual memory consistency rules of all RISC-V implementations. +As with implicit reads, software must execute fence or cache-control +instructions to ensure specific ordering of memory accesses beyond the +requirements of the assumed memory consistency model and execution +environment. + +=== Base Instruction-Length Encoding + +The base RISC-V ISA has fixed-length 32-bit instructions that must be +naturally aligned on 32-bit boundaries. However, the standard RISC-V +encoding scheme is designed to support ISA extensions with +variable-length instructions, where each instruction can be any number +of 16-bit instruction _parcels_ in length and parcels are naturally +aligned on 16-bit boundaries. The standard compressed ISA extension +described in <> reduces code size by +providing compressed 16-bit instructions and relaxes the alignment +constraints to allow all instructions (16 bit and 32 bit) to be aligned +on any 16-bit boundary to improve code density. + +We use the term IALIGN (measured in bits) to refer to the +instruction-address alignment constraint the implementation enforces. +IALIGN is 32 bits in the base ISA, but some ISA extensions, including +the compressed ISA extension, relax IALIGN to 16 bits. IALIGN may not +take on any value other than 16 or 32. +(((ILEN))) + +We use the term ILEN (measured in bits) to refer to the maximum +instruction length supported by an implementation, and which is always a +multiple of IALIGN. For implementations supporting only a base +instruction set, ILEN is 32 bits. Implementations supporting longer +instructions have larger values of ILEN. + +All the 32-bit +instructions in the base ISA have their lowest two bits set to `11`. The +optional compressed 16-bit instruction-set extensions have their lowest +two bits equal to `00`, `01`, or `10`. + +[NOTE] +==== +Given the code size and energy savings of a compressed format, we wanted +to build in support for a compressed format to the ISA encoding scheme +rather than adding this as an afterthought, but to allow simpler +implementations we didn't want to make the compressed format mandatory. +We also wanted to optionally allow longer instructions to support +experimentation and larger instruction-set extensions. Although our +encoding convention required a tighter encoding of the core RISC-V ISA, +this has several beneficial effects. +(((IMAFD))) + +An implementation of the standard IMAFD ISA need only hold the +most-significant 30 bits in instruction caches (a 6.25% saving). On +instruction cache refills, any instructions encountered with either low +bit clear should be recoded into illegal 30-bit instructions before +storing in the cache to preserve illegal-instruction exception behavior. + +Perhaps more importantly, by condensing our base ISA into a subset of +the 32-bit instruction word, we leave more space available for +non-standard and custom extensions. In particular, the base RV32I ISA +uses less than 1/8 of the encoding space in the 32-bit instruction word. +An implementation that does not require support +for the standard compressed instruction extension can map 3 additional non-conforming +30-bit instruction spaces into the 32-bit fixed-width format, while preserving +support for standard {ge}32-bit instruction-set +extensions. +==== + +Encodings with bits [15:0] all zeros are defined as illegal +instructions. These instructions are considered to be of minimal length: +16 bits if any 16-bit instruction-set extension is present, otherwise 32 +bits. The encoding with bits [ILEN-1:0] all ones is also illegal; this +instruction is considered to be ILEN bits long. + +[NOTE] +==== +We consider it a feature that any length of instruction containing all +zero bits is not legal, as this quickly traps erroneous jumps into +zeroed memory regions. Similarly, we also reserve the instruction +encoding containing all ones to be an illegal instruction, to catch the +other common pattern observed with unprogrammed non-volatile memory +devices, disconnected memory buses, or broken memory devices. + +Software can rely on a naturally aligned 32-bit word containing zero to +act as an illegal instruction on all RISC-V implementations, to be used +by software where an illegal instruction is explicitly desired. Defining +a corresponding known illegal value for all ones is more difficult due +to the variable-length encoding. Software cannot generally use the +illegal value of ILEN bits of all 1s, as software might not know ILEN +for the eventual target machine (e.g., if software is compiled into a +standard binary library used by many different machines). Defining a +32-bit word of all ones as illegal was also considered, as all machines +must support a 32-bit instruction size, but this requires the +instruction-fetch unit on machines with ILEN >32 report an +illegal-instruction exception rather than an access-fault exception when +such an instruction borders a protection boundary, complicating +variable-instruction-length fetch and decode. +==== +(((endian, little and big))) +RISC-V base ISAs have either little-endian or big-endian memory systems, +with the privileged architecture further defining bi-endian operation. +Instructions are stored in memory as a sequence of 16-bit little-endian +parcels, regardless of memory system endianness. Parcels forming one +instruction are stored at increasing halfword addresses, with the +lowest-addressed parcel holding the lowest-numbered bits in the +instruction specification. +(((bi-endian))) +(((endian, bi-))) + +[NOTE] +==== +We originally chose little-endian byte ordering for the RISC-V memory +system because little-endian systems are currently dominant commercially +(all x86 systems; iOS, Android, and Windows for ARM). A minor point is +that we have also found little-endian memory systems to be more natural +for hardware designers. However, certain application areas, such as IP +networking, operate on big-endian data structures, and certain legacy +code bases have been built assuming big-endian processors, so we have +defined big-endian and bi-endian variants of RISC-V. + +We have to fix the order in which instruction parcels are stored in +memory, independent of memory system endianness, to ensure that the +length-encoding bits always appear first in halfword address order. This +allows the length of a variable-length instruction to be quickly +determined by an instruction-fetch unit by examining only the first few +bits of the first 16-bit instruction parcel. + +We further make the instruction parcels themselves little-endian to +decouple the instruction encoding from the memory system endianness +altogether. This design benefits both software tooling and bi-endian +hardware. Otherwise, for instance, a RISC-V assembler or disassembler +would always need to know the intended active endianness, despite that +in bi-endian systems, the endianness mode might change dynamically +during execution. In contrast, by giving instructions a fixed +endianness, it is sometimes possible for carefully written software to +be endianness-agnostic even in binary form, much like +position-independent code. + +The choice to have instructions be only little-endian does have +consequences, however, for RISC-V software that encodes or decodes +machine instructions. Big-endian JIT compilers, for example, must swap +the byte order when storing to instruction memory. + +Once we had decided to fix on a little-endian instruction encoding, this +naturally led to placing the length-encoding bits in the LSB positions +of the instruction format to avoid breaking up opcode fields. +==== + +[[trap-defn]] +=== Exceptions, Traps, and Interrupts + +We use the term _exception_ to refer to an unusual condition occurring +at run time associated with an instruction in the current RISC-V hart. +We use the term _interrupt_ to refer to an external asynchronous event +that may cause a RISC-V hart to experience an unexpected transfer of +control. We use the term _trap_ to refer to the transfer of control to a +trap handler caused by either an exception or an interrupt. +(((exceptions))) +(((traps))) +(((interrupts))) + +The instruction descriptions in following chapters describe conditions +that can raise an exception during execution. The general behavior of +most RISC-V EEIs is that a trap to some handler occurs when an exception +is signaled on an instruction (except for floating-point exceptions, +which, in the standard floating-point extensions, do not cause traps). +The manner in which interrupts are generated, routed to, and enabled by +a hart depends on the EEI. + +[NOTE] +==== +Our use of "exception" and "trap" is compatible with that in the +IEEE-754 floating-point standard. +==== + +How traps are handled and made visible to software running on the hart +depends on the enclosing execution environment. From the perspective of +software running inside an execution environment, traps encountered by a +hart at runtime can have four different effects: + +Contained Trap::: + The trap is visible to, and handled by, software running inside the + execution environment. For example, in an EEI providing both + supervisor and user mode on harts, an ECALL by a user-mode hart will + generally result in a transfer of control to a supervisor-mode handler + running on the same hart. Similarly, in the same environment, when a + hart is interrupted, an interrupt handler will be run in supervisor + mode on the hart. +Requested Trap::: + The trap is a synchronous exception that is an explicit call to the + execution environment requesting an action on behalf of software + inside the execution environment. An example is a system call. In this + case, execution may or may not resume on the hart after the requested + action is taken by the execution environment. For example, a system + call could remove the hart or cause an orderly termination of the + entire execution environment. +Invisible Trap::: + The trap is handled transparently by the execution environment and + execution resumes normally after the trap is handled. Examples include + emulating missing instructions, handling non-resident page faults in a + demand-paged virtual-memory system, or handling device interrupts for + a different job in a multiprogrammed machine. In these cases, the + software running inside the execution environment is not aware of the + trap (we ignore timing effects in these definitions). +Fatal Trap::: + The trap represents a fatal failure and causes the execution + environment to terminate execution. Examples include failing a + virtual-memory page-protection check or allowing a watchdog timer to + expire. Each EEI should define how execution is terminated and + reported to an external environment. + +<> shows the characteristics of each kind of trap. + +[[trapcharacteristics]] +.Characteristics of traps +[%autowidth,float="center",align="center",cols="<,^,^,^,^",options="header",] +|=== +| |Contained |Requested |Invisible |Fatal +|Execution terminates |No |No^1^|No |Yes +|Software is oblivious |No |No |Yes |Yes^2^|Handled by environment |No |Yes |Yes |Yes +|=== + +^1^ Termination may be requested + +^2^ Imprecise fatal traps might be observable by software + +The EEI defines for each trap whether it is handled precisely, though +the recommendation is to maintain preciseness where possible. Contained +and requested traps can be observed to be imprecise by software inside +the execution environment. Invisible traps, by definition, cannot be +observed to be precise or imprecise by software running inside the +execution environment. Fatal traps can be observed to be imprecise by +software running inside the execution environment, if known-errorful +instructions do not cause immediate termination. + +Because this document describes unprivileged instructions, traps are +rarely mentioned. Architectural means to handle contained traps are +defined in the privileged architecture manual, along with other features +to support richer EEIs. Unprivileged instructions that are defined +solely to cause requested traps are documented here. Invisible traps +are, by their nature, out of scope for this document. Instruction +encodings that are not defined here and not defined by some other means +may cause a fatal trap. + +=== UNSPECIFIED Behaviors and Values +The architecture fully describes what implementations must do and any +constraints on what they may do. In cases where the architecture +intentionally does not constrain implementations, the term UNSPECIFIED is +explicitly used. +(((unspecified, behaviors))) +(((unspecified, values))) + +The term UNSPECIFIED refers to a behavior or value that is intentionally +unconstrained. The definition of these behaviors or values is open to +extensions, platform standards, or implementations. Extensions, platform +standards, or implementation documentation may provide normative content +to further constrain cases that the base architecture defines as UNSPECIFIED. + +Like the base architecture, extensions should fully describe allowable +behavior and values and use the term UNSPECIFIED for cases that are intentionally +unconstrained. These cases may be constrained or defined by other +extensions, platform standards, or implementations. diff --git a/param_extraction/chunks/chunk_017.txt.license b/param_extraction/chunks/chunk_017.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_017.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_018.txt b/param_extraction/chunks/chunk_018.txt new file mode 100644 index 0000000000..7dc0ddd335 --- /dev/null +++ b/param_extraction/chunks/chunk_018.txt @@ -0,0 +1,168 @@ +# Chunk: chunk_018 +# Source: m-st-ext.adoc +# Lines: 1-157 (of 157) +# Content starts: line 1 +# Line count: 157 +# Sections: 4 +# == "M" Extension for Integer Multiplication and Division, Version 2.0 +# === Multiplication Operations +# === Division Operations +# === `Zmmul` Extension, Version 1.0 +# +[[mstandard]] +== "M" Extension for Integer Multiplication and Division, Version 2.0 + +This chapter describes the standard integer multiplication and division +instruction extension, which is named `M` and contains instructions +that multiply or divide values held in two integer registers. + +[NOTE] +==== +We separate integer multiply and divide out from the base to simplify +low-end implementations, or for applications where integer multiply and +divide operations are either infrequent or better handled in attached +accelerators. +==== + +=== Multiplication Operations + +include::images/wavedrom/m-st-ext-for-int-mult.edn[] +[[m-st-ext-for-int-mult]] +//.Multiplication operation instructions +(((MUL, MULH))) +(((MUL, MULHU))) +(((MUL, MULHSU))) + +[#norm:mul_op]#MUL performs an XLEN-bit×XLEN-bit multiplication of +`rs1` by `rs2` and places the lower XLEN bits in the destination +register.# [#norm:mulh_mulhu_mulhsu_op]#MULH, MULHU, and MULHSU perform the same multiplication but +return the upper XLEN bits of the full 2×XLEN-bit +product, for signed×signed, +unsigned×unsigned, and `rs1`×unsigned `rs2` multiplication.# +If both the high and low bits of the same product are required, then the recommended code sequence is: `MULH[[S]U] rdh, rs1, rs2; MUL rdl, rs1, rs2` (source register specifiers must be in same order and `rdh` cannot be the same as `rs1` or `rs2`). Microarchitectures can then fuse these into a single multiply operation instead of performing two separate multiplies. + +[NOTE] +==== +MULHSU is used in multi-word signed multiplication to multiply the +most-significant word of the multiplicand (which contains the sign bit) +with the less-significant words of the multiplier (which are unsigned). +==== + +[#norm:mulw_op]#MULW is an RV64 instruction that multiplies the lower 32 bits of the +source registers, placing the sign extension of the lower 32 bits of the +result into the destination register.# + +[NOTE] +==== +In RV64, MUL can be used to obtain the upper 32 bits of the 64-bit +product, but signed arguments must be proper 32-bit signed values, +whereas unsigned arguments must have their upper 32 bits clear. If the +arguments are not known to be sign- or zero-extended, an alternative is +to shift both arguments left by 32 bits, then use MULH[[S]U]. +==== + +=== Division Operations + +include::images/wavedrom/division-op.edn[] +[[division-op]] +//.Division operation instructions +(((MUL, DIV))) +(((MUL, DIVU))) + +[#norm:div_divu_op]#DIV and DIVU perform an XLEN bits by XLEN bits signed and unsigned +integer division of `rs1` by `rs2`, rounding towards zero.# [#norm:rem_remu_op]#REM and REMU +provide the remainder of the corresponding division operation.# [#norm:rem_result_sign]#For REM, +the sign of a nonzero result equals the sign of the dividend.# + +[NOTE] +==== +For both signed and unsigned division, except in the case of overflow, it holds +that dividend = divisor {times} quotient + remainder. +==== + +If both the quotient and remainder are required from the same division, +the recommended code sequence is: `DIV[U] rdq, rs1, rs2; REM[U] rdr,` +`rs1, rs2` (`rdq` cannot be the same as `rs1` or `rs2`). +Microarchitectures can then fuse these into a single divide operation +instead of performing two separate divides. + +[#norm:divw_divuw_op]#DIVW and DIVUW are RV64 instructions that divide the lower 32 bits of +`rs1` by the lower 32 bits of `rs2`, treating them as signed and +unsigned integers, placing the 32-bit quotient in `rd`, +sign-extended to 64 bits.# [#norm:remw_remuw_op]#REMW and REMUW are RV64 instructions that +provide the corresponding signed and unsigned remainder +operations.# [#norm:remw_remuw_result_sign]#Both REMW and REMUW always sign-extend the 32-bit result +to 64 bits, including on a divide by zero.# +(((MUL, div by zero))) + +The semantics for division by zero and division overflow are summarized +in <>. [#norm:div_by_zero]#The quotient of division by zero has all bits +set#, and [#norm:rem_by_zero]#the remainder of division by zero equals the dividend.# +[#norm:signed_div_overflow]#Signed division overflow occurs only when the most-negative integer is divided +by −1. The quotient of a signed division with overflow is +equal to the dividend, and the remainder is zero.# Unsigned division +overflow cannot occur. + +[[divby0]] +.Semantics for division by zero and division overflow. L is the width of the operation in bits: XLEN for DIV[U] and REM[U], or 32 for DIV[U]W and REM[U]W. +[cols="<2,^,^,^,^,^,^",options="header",] +|=== +|Condition |Dividend |Divisor |DIVU[W] |REMU[W] |DIV[W] |REM[W] + +|Division by zero + +Overflow (signed only) |_x_ + +-2^L-1^ |0 + +−1 |2^L^-1 + + - |_x_ + + - |−1 + + -2^L-1^ + + |_x_ + + 0 +|=== + +//|Overflow (signed only) |−2^L−1^ |−1 |– |– |−2^L−1^ |0 +//|=== + +[NOTE] +==== +We considered raising exceptions on integer divide by zero, with these +exceptions causing a trap in most execution environments. However, this +would be the only arithmetic trap in the standard ISA (floating-point +exceptions set flags and write default values, but do not cause traps) +and would require language implementers to interact with the execution +environment's trap handlers for this case. Further, where language +standards mandate that a divide-by-zero exception must cause an +immediate control flow change, only a single branch instruction needs to +be added to each divide operation, and this branch instruction can be +inserted after the divide and should normally be very predictably not +taken, adding little runtime overhead. + +The value of all bits set is returned for both unsigned and signed +divide by zero to simplify the divider circuitry. The value of all 1s is +both the natural value to return for unsigned divide, representing the +largest unsigned number, and also the natural result for simple unsigned +divider implementations. Signed division is often implemented using an +unsigned division circuit and specifying the same overflow result +simplifies the hardware. +==== + +=== `Zmmul` Extension, Version 1.0 + +The `Zmmul` extension implements the multiplication subset of the M +extension. It adds all of the instructions defined in +<>, namely: MUL, MULH, MULHU, +MULHSU, and (for RV64 only) MULW. The encodings are identical to those +of the corresponding M-extension instructions. `M` implies `Zmmul`. +(((MUL, Zmmul))) + +[NOTE] +==== +The `Zmmul` extension enables low-cost implementations that require +multiplication operations but not division. For many microcontroller +applications, division operations are too infrequent to justify the cost +of divider hardware. By contrast, multiplication operations are more +frequent, making the cost of multiplier hardware more justifiable. +Simple FPGA soft cores particularly benefit from eliminating division +but retaining multiplication, since many FPGAs provide hardwired +multipliers but require dividers be implemented in soft logic. +==== diff --git a/param_extraction/chunks/chunk_018.txt.license b/param_extraction/chunks/chunk_018.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_018.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_019.txt b/param_extraction/chunks/chunk_019.txt new file mode 100644 index 0000000000..83a857c6b4 --- /dev/null +++ b/param_extraction/chunks/chunk_019.txt @@ -0,0 +1,3360 @@ +# Chunk: chunk_019 +# Source: machine.adoc +# Lines: 1-3334 (of 3629) +# Content starts: line 1 +# Line count: 3334 +# Sections: 20 +# == Machine-Level ISA, Version 1.13 +# === Machine-Level CSRs +# ==== Machine ISA (`misa`) Register +# ==== Machine Vendor ID (`mvendorid`) Register +# ==== Machine Architecture ID (`marchid`) Register +# ==== Machine Implementation ID (`mimpid`) Register +# ==== Hart ID (`mhartid`) Register +# ==== Machine Status (`mstatus` and `mstatush`) Registers +# ===== Privilege and Global Interrupt-Enable Stack in `mstatus` register +# ===== Double Trap Control in `mstatus` Register +# ===== Base ISA Control in `mstatus` Register +# ===== Memory Privilege in `mstatus` Register +# ===== Endianness Control in `mstatus` and `mstatush` Registers +# ===== Virtualization Support in `mstatus` Register +# ===== Extension Context Status in `mstatus` Register +# ===== Previous Expected Landing Pad (ELP) State in `mstatus` Register +# ==== Machine Trap-Vector Base-Address (`mtvec`) Register +# ==== Machine Trap Delegation (`medeleg` and `mideleg`) Registers +# ==== Machine Interrupt (`mip` and `mie`) Registers +# ==== Hardware Performance Monitor +# +[[machine]] +== Machine-Level ISA, Version 1.13 + +This chapter describes the machine-level operations available in +[#norm:M_highest_priv_mode]#machine-mode (M-mode), which is the highest privilege mode in a RISC-V +hart.# [#norm:M_mode_at_reset]#M-mode is used for low-level access to a hardware platform and +is the first mode entered at reset.# M-mode can also be used to implement +features that are too difficult or expensive to implement in hardware +directly. The RISC-V machine-level ISA contains a common core that is +extended depending on which other privilege levels are supported and +other details of the hardware implementation. + +=== Machine-Level CSRs + +In addition to the machine-level CSRs described in this section, +[#norm:M_access_all_lower_priv_CSRs]#M-mode code can access all CSRs at lower privilege levels.# + +[[misa]] +==== Machine ISA (`misa`) Register + +[#norm:misa_acc]#The `misa` CSR is a *WARL* read-write register# reporting the ISA supported by the hart. +[#norm:misa_always_rd]#This register must be readable in any implementation#, +but [#norm:misa_csr_implemented]#a value of zero can be returned to indicate the `misa` register has not been implemented#, requiring that CPU capabilities be determined through a separate non-standard mechanism. + +[[norm:misa_enc_img]] +.Machine ISA register (misa) +include::images/bytefield/misareg.edn[] + +[#norm:misa_mxl_op_isa]#The MXL (Machine XLEN) field encodes the native base integer ISA width as +shown in <>.# +[#norm:misa_mxl_acc]#The MXL field is read-only.# +[#norm:misa_mxl_op_nz]#If `misa` is nonzero, the +MXL field indicates the effective XLEN in M-mode, a constant termed _MXLEN_.# +[#norm:xlen_le_mxlen]#XLEN is never greater than MXLEN, but XLEN might be smaller than MXLEN in +less-privileged modes.# + +[[norm:misa_mxl_enc]] +.Encoding of MXL field in `misa` +[%autowidth,float="center",align="center",cols=">,>",options="header",] +|=== +|MXL |XLEN +|1 + +2 + +3 +|32 + +64 + +_Reserved_ +|=== + +[#norm:misa_sz]#The `misa` CSR is MXLEN bits wide.# + +[NOTE] +==== +The base width can be quickly ascertained using branches on the sign of +the returned `misa` value, and possibly a shift left by one and a second +branch on the sign. These checks can be written in assembly code without +knowing the register width (MXLEN) of the hart. The base width is +given by __MXLEN=2^MXL+4^__. + +The base width can also be found if `misa` is zero, by placing the +immediate 2 in a register, then shifting the register left by 31 bits. +If zero, the hart is RV32, else it is RV64. +==== + +[#norm:misa_extensions_enc_txt]#The Extensions field encodes the presence of the standard extensions, +with a single bit per letter of the alphabet (bit 0 encodes presence of +extension "A" , bit 1 encodes presence of extension "B", through to +bit 25 which encodes "Z").# +[#norm:misa_i_op]#The "I" bit will be set for the RV32I and RV64I base ISAs#, +and [#norm:misa_e_op]#the "E" bit will be set for RV32E and RV64E.# +[#norm:misa_extensions_warl_op]#The Extensions field is a *WARL* field that can contain writable bits where the +implementation allows the supported ISA to be modified.# +[#norm:misa_extensions_rst]#At reset, the Extensions field shall contain the maximal set of supported extensions, +and "I" shall be selected over "E" if both are available.# + +[[norm:misa_extensions_disabling]] +When a standard extension is disabled by clearing its bit in `misa`, the +instructions and CSRs defined or modified by the extension revert to +their defined or reserved behaviors as if the extension is not +implemented. + +[NOTE] +==== +[[norm:misa_extensions_impl_def]] +For a given RISC-V execution environment, an instruction, extension, or +other feature of the RISC-V ISA is ordinarily judged to be _implemented_ +or not by the observable execution behavior in that environment. For +example, the F extension is said to be implemented for an execution +environment if and only if the instructions that the RISC-V Unprivileged +ISA defines for F execute as specified. + +[[norm:misa_extensions_disabling_def]] +With this definition of _implemented_, disabling an extension by +clearing its bit in `misa` results in the extension being considered +_not implemented_ in M-mode. For example, setting `misa`.F=0 results in +the F extension being not implemented for M-mode, because the F +extension's instructions will not act as the Unprivileged ISA requires +but may instead raise an illegal-instruction exception. + +Defining the term _implemented_ based strictly on the observable +behavior might conflict with other common understandings of the same +word. In particular, although common usage may allow for the combination +"implemented but disabled," in this document it is considered a +contradiction of terms, because _disabled_ implies execution will not +behave as required for the feature to be considered _implemented_. In +the same vein, "implemented and enabled" is redundant here; +"implemented" suffices. +==== + +[#norm:misa_extensions_rsv_ret_0]#All bits that are reserved for future use must return zero when read.# + +[[norm:misa_extensions_enc_tbl]] +.Encoding of Extensions field in `misa`. +[%autowidth,float="center",align="center",cols=">,>,<",options="header",] +|=== +|Bit |Character |Description +|0 + +1 + +2 + +3 + +4 + +5 + +6 + +7 + +8 + +9 + +10 + +11 + +12 + +13 + +14 + +15 + +16 + +17 + +18 + +19 + +20 + +21 + +22 + +23 + +24 + +25 + +|A + +B + +C + +D + +E + +F + +G + +H + +I + +J + +K + +L + +M + +N + +O + +P + +Q + +R + +S + +T + +U + +V + +W + +X + +Y + +Z +|Atomic extension + +B extension + +Compressed extension + +Double-precision floating-point extension + +RV32E/64E base ISA + +Single-precision floating-point extension + +_Reserved_ + +Hypervisor extension + +RV32I/64I base ISA + +_Reserved_ + +_Reserved_ + +_Reserved_ + +Integer Multiply/Divide extension + +_Tentatively reserved for User-Level Interrupts extension_ + +_Reserved_ + +_Tentatively reserved for Packed-SIMD extension_ + +Quad-precision floating-point extension + +_Reserved_ + +Supervisor mode implemented + +_Reserved_ + +User mode implemented + +Vector extension + +_Reserved_ + +Non-standard extensions present + +_Reserved_ + +_Reserved_ +|=== + +[#norm:misa_x_op]#The "X" bit will be set if there are any non-standard extensions.# + +[#norm:misa_b_op]#When the "B" bit is 1, the implementation supports the instructions provided by the +Zba, Zbb, and Zbs extensions.# When the "B" bit is 0, it indicates that the +implementation might not support one or more of the Zba, Zbb, or Zbs extensions. + +[#norm:misa_m_op]#When the "M" bit is 1, the implementation supports all multiply and +division instructions defined by the M extension.# When the "M" bit +is 0, it indicates that the implementation might not support those +instructions. However [#norm:Zmmul_misa_m]#if the Zmmul extension is supported then +the multiply instructions it specifies are supported irrespective +of the value of the "M" bit.# + +[#norm:misa_s_op]#When the "S" bit is 1, the implementation supports supervisor mode.# +When the "S" bit is 0, the implementation might not support supervisor mode. + +[#norm:misa_u_op]#When the "U" bit is 1, the implementation supports user mode.# +When the "U" bit is 0, the implementation might not support user mode. + +[NOTE] +==== +The `misa` CSR exposes a rudimentary catalog of CPU features to +machine-mode code. More extensive information can be obtained in machine +mode by probing other machine registers, and examining other ROM storage +in the system as part of the boot process. + +We require that lower privilege levels execute environment calls instead +of reading CPU registers to determine features available at each +privilege level. This enables virtualization layers to alter the ISA +observed at any level, and supports a much richer command interface +without burdening hardware designs. +==== + +[#norm:misa_e_acc]#The "E" bit is read-only.# +[#norm:misa_e_not_i]#Unless `misa` is all read-only zero, the +"E" bit always reads as the complement of the "I" bit.# +If an execution environment supports both RV32E and RV32I, software can select +RV32E by clearing the "I" bit. + +[#norm:misa_extensions_dependencies]#If an ISA feature _x_ depends on an ISA feature _y_, then attempting to +enable feature _x_ but disable feature _y_ results in both features +being disabled.# +For example, setting "F"=0 and "D"=1 results in both "F" and "D" being cleared. +Similarly, setting "U"=0 and "S"=1" results in both "U" and "S" being cleared. + +An implementation may impose additional constraints on the collective +setting of two or more `misa` fields, in which case they function +collectively as a single *WARL* field. An attempt to write an unsupported combination causes those bits to be set to some supported combination. + +[#norm:misa_inc_ialign]#Writing `misa` may increase IALIGN, e.g., by disabling the "C" +extension. If an instruction that would write `misa` increases IALIGN, +and the subsequent instruction's address is not IALIGN-bit aligned, the +write to `misa` is suppressed, leaving `misa` unchanged.# + +When software enables an extension that was previously disabled, then +all state uniquely associated with that extension is UNSPECIFIED, unless otherwise specified by that extension. + +NOTE: Although one of the bits 25--0 in `misa` being set to 1 implies that +the corresponding feature is implemented, the inverse is not necessarily +true: one of these bits being clear does not necessarily imply that the +corresponding feature is not implemented. This follows from the fact that, +when a feature is not implemented, the corresponding opcodes and CSRs become +reserved, not necessarily illegal. + +==== Machine Vendor ID (`mvendorid`) Register + +[#norm:mvendorid_sz_acc_op]#The `mvendorid` CSR is a 32-bit read-only register providing the JEDEC +manufacturer ID of the provider of the core.# +[#norm:mvendorid_always_rd]#This register must be readable in any implementation, but a value of 0 can be returned to +indicate the field is not implemented or that this is a non-commercial implementation.# + +//.Vendor ID register (`mvendorid`) +//image::png/mvendorid.png[align="center"] + +.Vendor ID register (`mvendorid`) +include::images/bytefield/mvendorid.edn[] + +[#norm:mvendorid_enc]#JEDEC manufacturer IDs are ordinarily encoded as a sequence of one-byte +continuation codes `0x7f`, terminated by a one-byte ID not equal to +`0x7f`, with an odd parity bit in the most-significant bit of each byte. +`mvendorid` encodes the number of one-byte continuation codes in the +Bank field, and encodes the final byte in the Offset field, discarding +the parity bit.# For example, the JEDEC manufacturer ID +`0x7f 0x7f 0x7f 0x7f 0x7f 0x7f 0x7f 0x7f 0x7f 0x7f 0x7f 0x7f 0x8a` +(twelve continuation codes followed by `0x8a`) would be encoded in the +`mvendorid` CSR as `0x60a`. + +[NOTE] +==== +In JEDEC's parlance, the bank number is one greater than the number of +continuation codes; hence, the `mvendorid` Bank field encodes a value +that is one less than the JEDEC bank number. + +*** +Previously the vendor ID was to be a number allocated by RISC-V +International, but this duplicates the work of JEDEC in maintaining a +manufacturer ID standard. At time of writing, registering a manufacturer +ID with JEDEC has a one-time cost of $500. +==== + +==== Machine Architecture ID (`marchid`) Register + +[#norm:marchid_sz_acc_op]#The `marchid` CSR is an MXLEN-bit read-only register encoding the base +microarchitecture of the hart.# +[#norm:marchid_always_rd]#This register must be readable in any +implementation, but a value of 0 can be returned to indicate the field is not implemented.# +The combination of `mvendorid` and `marchid` should uniquely identify the type of hart microarchitecture that is implemented. + +.Machine Architecture ID (`marchid`) register +include::images/bytefield/marchid.edn[] + +Open-source project architecture IDs are allocated globally by RISC-V +International, and have non-zero architecture IDs with a zero +most-significant-bit (MSB). Commercial architecture IDs are allocated by +each commercial vendor independently, but must have the MSB set and +cannot contain zero in the remaining MXLEN-1 bits. + +[NOTE] +==== +The intent is for the architecture ID to represent the microarchitecture +associated with the project around which development occurs rather than a +particular organization. Commercial fabrications of open-source designs +should (and might be required by the license to) retain the original +architecture ID. This will aid in reducing fragmentation and tool +support costs, as well as provide attribution. Open-source architecture +IDs are administered by RISC-V International and should only be +allocated to released, functioning open-source projects. Commercial +architecture IDs can be managed independently by any registered vendor +but are required to have IDs disjoint from the open-source architecture +IDs (MSB set) to prevent collisions if a vendor wishes to use both +closed-source and open-source microarchitectures. + +The convention adopted within the following Implementation field can be +used to segregate branches of the same architecture design, including by +organization. The `misa` register also helps distinguish different +variants of a design. +==== + +==== Machine Implementation ID (`mimpid`) Register + +[#norm:mimpid_op]#The `mimpid` CSR provides a unique encoding of the version of the +processor implementation.# +[#norm:mimpid_always_rd]#This register must be readable in any +implementation, but a value of 0 can be returned to indicate that the field is not implemented.# +The Implementation value should reflect the design of the RISC-V processor itself and not any surrounding system. + +.Machine Implementation ID (`mimpid`) register +include::images/bytefield/mimpid.edn[] + +[NOTE] +==== +The format of this field is left to the provider of the architecture +source code, but will often be printed by standard tools as a +hexadecimal string without any leading or trailing zeros, so the +Implementation value can be left-justified (i.e., filled in from +most-significant nibble down) with subfields aligned on nibble +boundaries to ease human readability. +==== + +==== Hart ID (`mhartid`) Register + +[#norm:mhartid_sz_acc_op]#The `mhartid` CSR is an MXLEN-bit read-only register containing the +integer ID of the hardware thread running the code.# +[#norm:mhartid_always_rd]#This register must be readable in any implementation.# +Hart IDs might not necessarily be numbered contiguously in a multiprocessor system, but +[#norm:mhartid_one_is_zero]#one hart must have a hart ID of zero.# +[#norm:mhartid_unique]#Hart IDs must be unique within the execution environment.# + +.Hart ID (`mhartid`) register +include::images/bytefield/mhartid.edn[] + +[NOTE] +==== +In certain cases, we must ensure exactly one hart runs some code (e.g., +at reset), and so require one hart to have a known hart ID of zero. + +For efficiency, system implementers should aim to reduce the magnitude +of the largest hart ID used in a system. +==== + +==== Machine Status (`mstatus` and `mstatush`) Registers + +[#norm:mstatus_sz_acc]#The `mstatus` register is an MXLEN-bit read/write register formatted as +shown in <> for RV32 and <> for RV64.# +The `mstatus` register keeps track of and controls the hart’s current operating state. A +restricted view of `mstatus` appears as the `sstatus` register in the S-level ISA. + +[[mstatusreg-rv32]] +.Machine-mode status (`mstatus`) register for RV32 +include::images/wavedrom/mstatusreg-rv321.edn[] + +[[mstatusreg]] +.Machine-mode status (`mstatus`) register for RV64 +include::images/wavedrom/mstatusreg.edn[] + +[#norm:mstatush_sz_acc]#For RV32 only, `mstatush` is a 32-bit read/write register formatted as shown in <>.# +[#norm:mstatush_enc]#Bits 30:4 of `mstatush` generally contain the same fields found in bits 62:36 of `mstatus` for RV64. Fields SD, SXL, and UXL do not exist in `mstatush`.# + +[[mstatushreg]] +.Additional machine-mode status (`mstatush`) register for RV32. +include::images/wavedrom/mstatushreg.edn[] + +[[privstack]] +===== Privilege and Global Interrupt-Enable Stack in `mstatus` register + +[#norm:mstatus_mie_sie_op1]#Global interrupt-enable bits, MIE and SIE, are provided for M-mode and +S-mode respectively.# These bits are primarily used to guarantee +atomicity with respect to interrupt handlers in the current privilege mode. + +[NOTE] +==== +The global __x__IE bits are located in the low-order bits of `mstatus`, +allowing them to be atomically set or cleared with a single CSR +instruction. +==== + +[#norm:mstatus_mie_sie_op2]#When a hart is executing in privilege mode _x_, interrupts are globally +enabled when __x__IE=1 and globally disabled when __x__IE=0.# +[#norm:mstatus_xie_intr_en_dis]#Interrupts for lower-privilege modes, __w__<__x__, +are always globally disabled regardless of the setting of any global __w__IE bit for the +lower-privilege mode. Interrupts for higher-privilege modes, __y__>__x__, +are always globally enabled regardless of the +setting of the global __y__IE bit for the higher-privilege mode.# +Higher-privilege-level code can use separate per-interrupt enable bits +to disable selected higher-privilege-mode interrupts before ceding +control to a lower-privilege mode. +[#norm:mstatus_sie_spie_rdonly0]#If supervisor mode is not implemented, then SIE and SPIE are read-only 0.# + +[NOTE] +==== +A higher-privilege mode _y_ could disable all of its interrupts before +ceding control to a lower-privilege mode but this would be unusual as it +would leave only a synchronous trap, non-maskable interrupt, or reset as +means to regain control of the hart. +==== + +To support nested traps, [#norm:mstatus_xpie_xpp_op]#each privilege mode _x_ that can respond to +interrupts has a two-level stack of interrupt-enable bits and privilege modes. +__x__PIE holds the value of the interrupt-enable bit active prior +to the trap, and __x__PP holds the previous privilege mode.# +[#norm:mstatus_xpp_enc]#The __x__PP fields can only hold privilege modes up to _x_#, so +[#norm:mstatus_mpp_sz]#MPP is two bits wide# and [#norm:mstatus_spp_sz]#SPP is one bit wide.# +[#norm:mstatus_xpie_xie_xpp_trap_op]#When a trap is taken from privilege mode _y_ +into privilege mode _x_, __x__PIE is set to the value of __x__IE; __x__IE is +set to 0; and __x__PP is set to _y_.# + +[NOTE] +==== +For lower privilege modes, any trap (synchronous or asynchronous) is +usually taken at a higher privilege mode with interrupts disabled upon +entry. The higher-level trap handler will either service the trap and +return using the stacked information, or, if not returning immediately +to the interrupted context, will save the privilege stack before +re-enabling interrupts, so only one entry per stack is required. +==== + +An MRET or SRET instruction is used to return from a trap in M-mode or S-mode respectively. +[#norm:mstatus_xret_op]#When executing an __x__RET instruction, supposing +__x__PP holds the value _y_, __x__IE is set to __x__PIE; the privilege mode is +changed to _y_; __x__PIE is set to 1; and __x__PP is set to the +least-privileged supported mode (U if U-mode is implemented, else M). If +__y__{ne}M, __x__RET also sets MPRV=0.# + +[NOTE] +==== +Setting __x__PP to the least-privileged supported mode on an __x__RET helps identify software bugs in the management of the two-level privilege-mode stack. +==== + +[NOTE] +==== +Trap handlers must be designed to neither enable interrupts nor cause exceptions +during the phase of handling where the trap handler preserves the critical state +information required to handle and resume from the trap. An exception or +interrupt in this critical phase of trap handling may lead to a trap that can +overwrite such critical state. This could result in the loss of data needed to +recover from the initial trap. Further, if an exception occurs in the code path +needed to handle traps, then such a situation may lead to an infinite loop of +traps. To prevent this, trap handlers must be meticulously designed to identify +and safely manage exceptions within their operational flow. +==== + +[#norm:mstatus_xpp_warl]#__x__PP fields are *WARL* fields that can hold only privilege mode _x_ and any implemented privilege mode lower than _x_.# +[#norm:mstatus_xpp_rdonly0]#If privilege mode _x_ is not implemented, then __x__PP must be read-only 0.# + +[NOTE] +==== +M-mode software can determine whether a privilege mode is implemented by +writing that mode to MPP then reading it back. + +If the machine provides only U and M modes, then only a single hardware +storage bit is required to represent either 00 or 11 in MPP. +==== + +[[machine-double-trap]] +===== Double Trap Control in `mstatus` Register + +A double trap typically arises during a sensitive phase in trap handling +operations -- when an exception or interrupt occurs while the trap handler (the +component responsible for managing these events) is in a non-reentrant state. +This non-reentrancy usually occurs in the early phase of trap handling, wherein +the trap handler has not yet preserved the necessary state to handle and resume +from the trap. The occurrence of a trap during this phase can lead to an +overwrite of critical state information, resulting in the loss of data needed to +recover from the initial trap. The trap that caused this critical error +condition is henceforth called the _unexpected trap_. Trap handlers are designed +to neither enable interrupts nor cause exceptions during this phase of handling. +However, managing Hardware-Error exceptions, which may occur unpredictably, +presents significant challenges in trap handler implementation due to the +potential risk of a double trap. + +[#norm:mstatus_mdt_sz_warl]#The M-mode-disable-trap (`MDT`) bit is a WARL field introduced by the Smdbltrp extension.# +[#norm:mstatus_mdt_rst]#Upon reset, the `MDT` field is set to 1.# +[#norm:mstatus_mie_clr_by_mdt]#When the `MDT` bit is set to 1 by an explicit CSR write, +the `MIE` (Machine Interrupt Enable) bit is cleared to 0.# +[#norm:mstatus_mie_clr_by_mdt_rv64]#For RV64, this clearing occurs regardless of the value written, if any, to the `MIE` bit by the same write.# +[#norm:mstatus_mie_set_mdt_0]#The `MIE` bit can only be set to 1 by an +explicit CSR write if the `MDT` bit is already 0# +[#norm:mstatus_mie_set_mdt_0_rv64]#or, for RV64, is being set to 0 by the same write# +(For RV32, the `MDT` bit is in `mstatush` and the `MIE` bit in `mstatus` register). + +[#norm:trap_exp]#When a trap is to be taken into M-mode, if the `MDT` bit is currently 0, it is then set to 1, and the trap is delivered as expected.# +[#norm:trap_unexp_mdt_1]#However, if `MDT` is already set to 1, then this is an _unexpected trap_.# +[#norm:trap_unexp_rnmi]#When the Smrnmi extension +is implemented, a trap caused by an RNMI is not considered an _unexpected trap_ +irrespective of the state of the `MDT` bit.# +[#norm:mstatus_mdt_not_set_rnmi]#A trap caused by an RNMI does not set the `MDT` bit.# However, +[#norm:trap_unexp_mnstatus_nmie_0]#a trap that occurs when executing in M-mode with +`mnstatus.NMIE` set to 0 is an _unexpected trap_.# + +[#norm:trap_unexp_hndl_lead-in]#In the event of a _unexpected trap_, the handling is as follows:# + +* [#norm:trap_unexp_hndl_rnmi]#When the Smrnmi extension is implemented and `mnstatus.NMIE` is 1, the hart + traps to the RNMI handler. To deliver this trap, the `mnepc` and `mncause` + registers are written with the values that the _unexpected trap_ would have + written to the `mepc` and `mcause` registers respectively. The privilege + mode information fields in the `mnstatus` register are written to indicate + M-mode and its `NMIE` field is set to 0.# + +[NOTE] +==== +The consequence of this specification is that on occurrence of double trap the +RNMI handler is not provided with information that a trap reports in the +`mtval` and the `mtval2` registers. This information, if needed, can be obtained +by the RNMI handler by decoding the instruction at the address in `mnepc` and +examining its source register contents. +==== + +* [#norm:trap_unexp_hndl_no_rnmi]#When the Smrnmi extension is not implemented, or if the Smrnmi extension is + implemented and `mnstatus.NMIE` is 0, the hart enters a critical-error state + without updating any architectural state, including the `pc`. This state + involves ceasing execution, disabling all interrupts (including NMIs), and + asserting a `critical-error` signal to the platform.# Whether performance + counters and timers are updated in the critical-error state is UNSPECIFIED. + +[NOTE] +==== +[#norm:critical-error]#The actions performed by the platform when a hart asserts a `critical-error` signal +are platform-specific. The range of possible actions include restarting +the affected hart or restarting the entire platform, among others.# +==== + +[#norm:mstatus_mdt_clr_mret_sret]#The `MRET` and `SRET` instructions, when executed in M-mode, set the `MDT` bit to 0.# +[#norm:sstatus_sdt_clr_mret_sret]#If the new privilege mode is U, VS, or VU, then `sstatus.SDT` is also set to 0.# +[#norm:vsstatus_sdt_clr_mret_sret]#Additionally, if it is VU, then `vsstatus.SDT` is also set to 0.# + +[#norm:mstatus_mdt_clr_mnret]#The `MNRET` instruction, provided by the Smrnmi extension, sets the `MDT` bit to 0 if the new privilege mode is not M.# +[#norm:sstatus_sdt_clr_mnret]#If it is U, VS, or VU, then `sstatus.SDT` is also set to 0.# +[#norm:vsstatus_sdt_clr_mnret]#Additionally, if it is VU, then `vsstatus.SDT` is also set to 0.# + +[[xlen-control]] +===== Base ISA Control in `mstatus` Register + +[#norm:mstatus_sxl_uxl_warl_op]#For RV64 harts, the SXL and UXL fields are *WARL* fields that control the +value of XLEN for S-mode and U-mode, respectively.# +[#norm:mstatus_sxl_uxl_enc]#The encoding of these fields is the same as the MXL field of `misa`, shown in <>.# +[#norm:sxlen_uxlen]#The effective XLEN in S-mode and U-mode are termed _SXLEN_ and _UXLEN_, respectively.# + +[[norm:mstatus_sxl_uxl_sxlen_uxlen_mxlen32]] +When MXLEN=32, the SXL and UXL fields do not exist, and SXLEN=32 and UXLEN=32. + +[#norm:mstatus_sxl_acc_mxlen64]#When MXLEN=64, if S-mode is not supported, then SXL is read-only zero. +Otherwise, it is a *WARL* field that encodes the current value of SXLEN.# +In particular, [#norm:mstatus_sxl_rdonly_mxlen64]#an implementation may make SXL be a read-only field whose +value always ensures that SXLEN=MXLEN.# + +[#norm:mstatus_uxl_acc_mxlen64]#When MXLEN=64, if U-mode is not supported, then UXL is read-only zero. +Otherwise, it is a *WARL* field that encodes the current value of UXLEN.# +In particular, [#norm:mstatus_uxl_rdonly_mxlen64]#an implementation may make UXL be a read-only field whose +value always ensures that UXLEN=MXLEN or UXLEN=SXLEN.# + +[[norm:mstatus_uxl_legal_vals_smode]] +If S-mode is implemented, the set of legal values that the UXL field may +assume excludes those that would cause UXLEN to be greater than SXLEN. + +[[norm:xlen_reduction_op]] +Whenever XLEN in any mode is set to a value less than the widest +supported XLEN, all operations must ignore source operand register bits +above the configured XLEN, and must sign-extend results to fill the +entire widest supported XLEN in the destination register. +Similarly, `pc` bits above XLEN are ignored, and when the `pc` is written, it is +sign-extended to fill the widest supported XLEN. + +[NOTE] +==== +We require that operations always fill the entire underlying hardware +registers with defined values to avoid implementation-defined behavior. + +To reduce hardware complexity, the architecture imposes no checks that +lower-privilege modes have XLEN settings less than or equal to the +next-higher privilege mode. In practice, such settings would almost +always be a software bug, but machine operation is well-defined even in +this case. +==== + +[[norm:xlen_reduction_hint_op1]] +Some HINT instructions are encoded as integer computational instructions that +overwrite their destination register with its current value, e.g., +`c.addi x8, 0`. +When such a HINT is executed with XLEN < MXLEN and bits MXLEN..XLEN of the +destination register not all equal to bit XLEN-1, it is implementation-defined +whether bits MXLEN..XLEN of the destination register are unchanged or are +overwritten with copies of bit XLEN-1. + +[[norm:xlen_reduction_hint_op2]] +NOTE: This definition allows implementations to elide register write-back for +some HINTs, while allowing them to execute other HINTs in the same manner as +other integer computational instructions. +The implementation choice is observable only by privilege modes with an XLEN +setting greater than the current XLEN; it is invisible to the current +privilege mode. + +===== Memory Privilege in `mstatus` Register + +The MPRV (Modify PRiVilege) bit modifies the _effective privilege mode_, +i.e., the privilege level at which explicit memory accesses execute. +[#norm:mstatus_mprv_ldst_op]#When MPRV=0, explicit memory accesses +behave as normal, using the translation and +protection mechanisms of the current privilege mode. When MPRV=1, load +and store memory addresses are translated and protected, and endianness +is applied, as though the current privilege mode were set to MPP.# +[#norm:mstatus_mprv_inst_xlat_op]#Instruction address-translation and protection are unaffected by the +setting of MPRV.# +[#norm:mstatus_mprv_rdonly0_no_umode]#MPRV is read-only 0 if U-mode is not supported.# + +[#norm:mstatus_mprv_clr_mret_sret_less_priv]#An MRET or SRET instruction that changes the privilege mode to a mode +less privileged than M also sets MPRV=0.# + +The MXR (Make eXecutable Readable) bit modifies the privilege with which loads access virtual memory. +[#norm:mstatus_mxr_op]#When MXR=0, only loads from pages marked readable (R=1 in <>) will succeed. +When MXR=1, loads from pages marked either readable or executable (R=1 or +X=1) will succeed. MXR has no effect when page-based virtual memory is not in effect.# +[#norm:mstatus_mxr_rdonly0_no_smode]#MXR is read-only 0 if S-mode is not supported.# + +[NOTE] +==== +The MPRV and MXR mechanisms were conceived to improve the efficiency of +M-mode routines that emulate missing hardware features, e.g., misaligned +loads and stores. MPRV obviates the need to perform address translation +in software. MXR allows instruction words to be loaded from pages marked +execute-only. + +The current privilege mode and the privilege mode specified by MPP might +have different XLEN settings. When MPRV=1, load and store memory +addresses are treated as though the current XLEN were set to MPP’s XLEN, +following the rules in <>. +==== +The SUM (permit Supervisor User Memory access) bit modifies the +privilege with which S-mode loads and stores access virtual memory. +[#norm:mstatus_sum_op]#When SUM=0, S-mode memory accesses to pages that are accessible by U-mode +(U=1 in <>) will fault. When SUM=1, these accesses are permitted.# +[#norm:mstatus_sum_op_no-vm]#SUM has no effect when page-based virtual memory is not in effect.# +Note that, [#norm:mstatus_sum_op_mprv_mpp]#while SUM is ordinarily ignored when not +executing in S-mode, it _is_ in effect when MPRV=1 and MPP=S.# +[#norm:mstatus_sum_rdonly0]#SUM is read-only 0 if S-mode is not supported or if `satp`.MODE is read-only 0.# + +[[norm:mstatus_mxr_sum_op_acc_fault]] +The MXR and SUM mechanisms only affect the interpretation of permissions +encoded in page-table entries. In particular, they have no impact on +whether access-fault exceptions are raised due to PMAs or PMP. + +===== Endianness Control in `mstatus` and `mstatush` Registers + +[#norm:mstatus_mstatush_xbe_warl]#The MBE, SBE, and UBE bits in `mstatus` and `mstatush` are *WARL* fields# that +control the endianness of memory accesses other than instruction fetches. +[#norm:endianness_inst_fetch_little]#Instruction fetches are always little-endian.# + +[[norm:mstatus_mbe_op]] +MBE controls whether non-instruction-fetch memory accesses made from +M-mode (assuming `mstatus`.MPRV=0) are little-endian (MBE=0) or +big-endian (MBE=1). + +[[norm:mstatus_sbe_op]] +If S-mode is not supported, SBE is read-only 0. Otherwise, SBE controls +whether explicit load and store memory accesses made from S-mode are +little-endian (SBE=0) or big-endian (SBE=1). + +[[norm:mstatus_ube_op]] +If U-mode is not supported, UBE is read-only 0. Otherwise, UBE controls +whether explicit load and store memory accesses made from U-mode are +little-endian (UBE=0) or big-endian (UBE=1). + +[#norm:mstatus_sbe_implicit]#For _implicit_ accesses to supervisor-level memory management data +structures, such as page tables, endianness is always controlled by SBE.# +[#norm:mstatus_sbe_change_fence]#Since changing SBE alters the implementation’s interpretation of these +data structures, if any such data structures remain in use across a +change to SBE, M-mode software must follow such a change to SBE by +executing an SFENCE.VMA instruction with _rs1_=`x0` and _rs2_=`x0`.# + +[NOTE] +==== +Only in contrived scenarios will a given memory-management data +structure be interpreted as both little-endian and big-endian. In +practice, SBE will only be changed at runtime on world switches, in +which case neither the old nor new memory-management data structure will +be reinterpreted in a different endianness. In this case, no additional +SFENCE.VMA is necessary, beyond what would ordinarily be required for a +world switch. +==== + +[#norm:mstatus_sbe_rocopy]#If S-mode is supported, an implementation may make SBE be a read-only +copy of MBE.# +[#norm:mstatus_ube_rocopy]#If U-mode is supported, an implementation may make UBE be a +read-only copy of either MBE or SBE.# + +[NOTE] +==== +An implementation supports only little-endian memory accesses if fields +MBE, SBE, and UBE are all read-only 0. An implementation supports only +big-endian memory accesses (aside from instruction fetches) if MBE is +read-only 1 and SBE and UBE are each read-only 1 when S-mode and U-mode +are supported. + +''' + +Volume I defines a hart’s address space as a circular sequence of +2^XLEN^ bytes at consecutive addresses. The +correspondence between addresses and byte locations is fixed and not +affected by any endianness mode. Rather, the applicable endianness mode +determines the order of mapping between memory bytes and a multibyte +quantity (halfword, word, etc.). + +--- + +Standard RISC-V ABIs are expected to be purely little-endian-only or +big-endian-only, with no accommodation for mixing endianness. +Nevertheless, endianness control has been defined so as to permit, for +instance, an OS of one endianness to execute user-mode programs of the +opposite endianness. Consideration has been given also to the +possibility of non-standard usages whereby software flips the endianness +of memory accesses as needed. + +*** + +RISC-V instructions are uniformly little-endian to decouple instruction +encoding from the current endianness settings, for the benefit of both +hardware and software. Otherwise, for instance, a RISC-V assembler or +disassembler would always need to know the intended active endianness, +despite that the endianness mode might change dynamically during +execution. In contrast, by giving instructions a fixed endianness, it is +sometimes possible for carefully written software to be +endianness-agnostic even in binary form, much like position-independent +code. + +The choice to have instructions be only little-endian does have +consequences, however, for RISC-V software that encodes or decodes +machine instructions. In big-endian mode, such software must account for +the fact that explicit loads and stores have endianness opposite that of +instructions, for example by swapping byte order after loads and before +stores. +==== + +[[virt-control]] +===== Virtualization Support in `mstatus` Register + +[[norm:mstatus_tvm_warl_op]] +The TVM (Trap Virtual Memory) bit is a *WARL* field that supports intercepting +supervisor virtual-memory management operations. When TVM=1, attempts to +read or write the `satp` CSR or execute an SFENCE.VMA or SINVAL.VMA +instruction while executing in S-mode will raise an illegal-instruction +exception. When TVM=0, these operations are permitted in S-mode. TVM is +read-only 0 when S-mode is not supported. + +[NOTE] +==== +The TVM mechanism improves virtualization efficiency by permitting guest +operating systems to execute in S-mode, rather than classically +virtualizing them in U-mode. This approach obviates the need to trap +accesses to most S-mode CSRs. + +Trapping `satp` accesses and the SFENCE.VMA and SINVAL.VMA instructions +provides the hooks necessary to lazily populate shadow page tables. +==== + +[#norm:mstatus_tw_warl]#The TW (Timeout Wait) bit is a *WARL* field that supports intercepting the WFI +instruction (see <>).# +[#norm:mstatus_tw_op]#When TW=0, the WFI +instruction may execute in modes less privileged than M when not prevented for +some other reason. When TW=1, then if WFI is executed in any +less-privileged mode, and it does not complete within an +implementation-specific, bounded time limit, the WFI instruction causes +an illegal-instruction exception.# +[#norm:mstatus_tw_always_illegal]#An implementation may have WFI always +raise an illegal-instruction exception in modes less privileged than M when +TW=1, even if there are pending globally-disabled interrupts when the +instruction is executed.# +[#norm:mstatus_tw_acc]#TW is read-only 0 when there are no modes less privileged than M.# + +[NOTE] +==== +Trapping the WFI instruction can trigger a world switch to another guest +OS, rather than wastefully idling in the current guest. +==== + +[#norm:mstatus_tw_umode_op]#When S-mode is implemented, then executing WFI in U-mode causes an +illegal-instruction exception, regardless of the value of the TW bit, unless the +instruction completes within an implementation-specific, bounded time limit.# + +[#norm:mstatus_tsr_warl]#The TSR (Trap SRET) bit is a *WARL* field that supports intercepting the +supervisor exception return instruction, SRET.# +[#norm:mstatus_tsr_op]#When TSR=1, attempts to +execute SRET while executing in S-mode will raise an illegal-instruction +exception. When TSR=0, this operation is permitted in S-mode.# +[#norm:mstatus_tsr_acc]#TSR is read-only 0 when S-mode is not supported.# + +[NOTE] +==== +Trapping SRET is necessary to emulate the hypervisor extension (see +<>) on implementations that do not +provide it. +==== + +===== Extension Context Status in `mstatus` Register + +Supporting substantial extensions is one of the primary goals of RISC-V, +and hence we define a standard interface to allow unchanged +privileged-mode code, particularly a supervisor-level OS, to support +arbitrary user-mode state extensions. + +[NOTE] +==== +To date, the V extension is the only standard extension that defines +additional state beyond the floating-point CSR and data registers. +==== + +[#norm:mstatus_fs_vs_warl]#The FS[1:0] and VS[1:0] *WARL* fields# +and the XS[1:0] read-only field are used +to reduce the cost of context save and restore by setting and tracking +the current state of the floating-point unit and any other user-mode +extensions respectively. +[#norm:mstatus_fs_op]#The FS field encodes the status of the +floating-point unit state, including the floating-point registers +`f0`–`f31` and the CSRs `fcsr`, `frm`, and `fflags`.# +[#norm:mstatus_vs_op]#The VS field encodes the status of the +vector extension state, including the vector +registers `v0`–`v31` and the CSRs `vcsr`, `vxrm`, `vxsat`, `vstart`, +`vl`, `vtype`, and `vlenb`.# +[#norm:mstatus_xs_op1]#The XS field encodes the status of +additional user-mode extensions and associated state.# +These fields can be checked by a context switch routine to quickly determine whether a +state save or restore is required. If a save or restore is required, +additional instructions and CSRs are typically required to effect and +optimize the process. + +[NOTE] +==== +The design anticipates that most context switches will not need to +save/restore state in either or both of the floating-point unit or other +extensions, so provides a fast check via the SD bit. +==== + +The FS, VS, and XS fields use the same status encoding as shown in +<>, with the four possible status +values being Off, Initial, Clean, and Dirty. + +[[norm:mstatus_fs_vs_xs_enc]] +.Encoding of FS[1:0], VS[1:0], and XS[1:0] status fields +[%autowidth,float="center",align="center",cols=">,<,<",options="header",] +|=== +|Status |FS and VS Meaning |XS Meaning +|0 + +1 + +2 + +3 +|Off + +Initial + +Clean + +Dirty +|All off + +None dirty or clean, some on + +None dirty, some clean + +Some dirty +|=== + +[[norm:mstatus_fs_acc1]] +If the F extension is implemented, the FS field shall not be read-only zero. + +[#norm:mstatus_fs_acc2]#If neither the F extension nor S-mode is implemented, then FS is read-only zero.# +[#norm:mstatus_fs_rdonly0_s-no-f]#If S-mode is implemented but the F extension is not, FS +may optionally be read-only zero.# + +[NOTE] +==== +Implementations with S-mode but without the F extension are permitted, +but not required, to make the FS field be read-only zero. Some such +implementations will choose _not_ to have the FS field be read-only +zero, so as to enable emulation of the F extension for both S-mode and +U-mode via invisible traps into M-mode. +==== + +[[norm:mstatus_vs_acc1]] +If the `v` registers are implemented, the VS field shall not be read-only zero. + +[#norm:mstatus_vs_acc2]#If neither the `v` registers nor S-mode is implemented, then VS is +read-only zero.# +[#norm:mstatus_vs_rdonly0_s-no-v]#If S-mode is implemented but the `v` registers are not, +VS may optionally be read-only zero.# + +[#norm:mstatus_xs_acc]#In harts without additional user extensions requiring new state, the +XS field is read-only zero.# +[#norm:mstatus_xs_equiv]#Every additional extension with state +provides a CSR field that encodes the equivalent of the XS states.# +[#norm:mstatus_xs_op2]#The XS field represents a summary of all extensions' status as shown in +<>.# + +[NOTE] +==== +The XS field effectively reports the maximum status value across all +user-extension status fields, though individual extensions can use a +different encoding than XS. +==== + +[#norm:mstatus_sd_acc]#The SD bit is a read-only bit# that +[#norm:mstatus_sd_op]#summarizes whether either the FS, VS, +or XS fields signal the presence of some dirty state that will require +saving extended user context to memory.# +[#norm:mstatus_sd_rdonly0]#If FS, XS, and VS are all read-only zero, then SD is also always zero.# + +[#norm:mstatus_fs_vs_xs_off_op]#When an extension's status is set to Off, any instruction that attempts +to read or write the corresponding state will cause an +illegal-instruction exception.# +[#norm:mstatus_fs_vs_xs_initial_op]#When the status is Initial, the corresponding +state should have an initial constant value.# +[#norm:mstatus_fs_vs_xs_clean_op]#When the status is Clean, +the corresponding state is potentially different from the initial value, +but matches the last value stored on a context swap.# +[#norm:mstatus_fs_vs_xs_dirty_op]#When the status is Dirty, +the corresponding state has potentially been modified since the last context save.# + +During a context save, the responsible privileged code need only write +out the corresponding state if its status is Dirty, and can then reset +the extension's status to Clean. During a context restore, the context +need only be loaded from memory if the status is Clean (it should never +be Dirty at restore). If the status is Initial, the context must be set +to an initial constant value on context restore to avoid a security +hole, but this can be done without accessing memory. For example, the +floating-point registers can all be initialized to the immediate value +0. + +The FS and XS fields are read by the privileged code before saving the +context. The FS field is set directly by privileged code when resuming a +user context, while the XS field is set indirectly by writing to the +status register of the individual extensions. +[#norm:mstatus_fs_vs_xs_update_indep_priv]#The status fields will +also be updated during execution of instructions, regardless of privilege mode.# + +Extensions to the user-mode ISA often include additional user-mode +state, and this state can be considerably larger than the base integer +registers. The extensions might only be used for some applications, or +might only be needed for short phases within a single application. To +improve performance, the user-mode extension can define additional +instructions to allow user-mode software to return the unit to an +initial state or even to turn off the unit. + +For example, a coprocessor might require to be configured before use and +can be "unconfigured" after use. The unconfigured state would be +represented as the Initial state for context save. If the same +application remains running between the unconfigure and the next +configure (which would set status to Dirty), there is no need to +actually reinitialize the state at the unconfigure instruction, as all +state is local to the user process, i.e., the Initial state may only +cause the coprocessor state to be initialized to a constant value at +context restore, not at every unconfigure. + +Executing a user-mode instruction to disable a unit and place it into +the Off state will cause an illegal-instruction exception to be raised +if any subsequent instruction tries to use the unit before it is turned +back on. A user-mode instruction to turn a unit on must also ensure the +unit's state is properly initialized, as the unit might have been used +by another context meantime. + +[#norm:mstatus_fs_wr]#Changing the setting of FS has no effect on the contents of the +floating-point register state. In particular, setting FS=Off does not +destroy the state, nor does setting FS=Initial clear the contents.# Similarly, +[#norm:mstatus_vs_wr]#the setting of VS has no effect on the contents of the vector +register state.# +Other extensions, however, might not preserve state when set to Off. + +[#norm:mstatus_fs_imprecise]#Implementations may choose to track the dirtiness of the floating-point +register state imprecisely by reporting the state to be dirty even when +it has not been modified. +On some implementations, some instructions +that do not mutate the floating-point state may cause the state to +transition from Initial or Clean to Dirty.# +On other implementations, +[#norm:mstatus_fs_no_dirty_track]#dirtiness might not be tracked at all, in which case the valid FS states +are Off and Dirty, and an attempt to set FS to Initial or Clean causes +it to be set to Dirty.# + +[NOTE] +==== +This definition of FS does not disallow setting FS to Dirty as a result +of errant speculation. Some platforms may choose to disallow +speculatively writing FS to close a potential side channel. +==== + +[#norm:mstatus_fs_no_change_dirty]#If an instruction explicitly or implicitly writes a floating-point +register or the `fcsr` but does not alter its contents, and FS=Initial +or FS=Clean, it is implementation-defined whether FS transitions to +Dirty.# + +[#norm:mstatus_vs_imprecise]#Implementations may choose to track the dirtiness of the vector register +state in an analogous imprecise fashion, including possibly setting VS +to Dirty when software attempts to set VS=Initial or VS=Clean.# +[#norm:mstatus_vs_no_change_dirty]#When VS=Initial or VS=Clean, it is implementation-defined whether an +instruction that writes a vector register or vector CSR but does not +alter its contents causes VS to transition to Dirty.# + +<> shows all the possible state +transitions for the FS, VS, or XS status bits. Note that the standard +floating-point and vector extensions do not support user-mode +unconfigure or disable/enable instructions. + +<<< + +[[fsxsstates]] +.FS, VS, and XS state transitions. +[width=75,align=center,float=center,cols="<,<,<,<,<"] +|=== +|Current State + +Action |Off |Initial |Clean |Dirty +|=== + +[width=75,align=center,float=center,cols="<,<,<,<,<"] +|=== +5+^|At context save in privileged code + +|Save state? + +Next state +|No + +Off +|No + +Initial +|No + +Clean +|Yes + +Clean +|=== + +[width=75,align=center,float=center,cols="<,<,<,<,<"] +|=== +5+^|At context restore in privileged code + +|Restore state? + +Next state +|No + +Off +|Yes, to initial + +Initial +|Yes, from memory + +Clean +|N/A + +N/A +|=== + +[width=75,align=center,float=center,cols="<,<,<,<,<"] +|=== +5+^|Execute instruction to read state + +|Action? + +Next state +|Exception + +Off +|Execute + +Initial +|Execute + +Clean +|Execute + +Dirty +|=== + +[width=75,align=center,float=center,cols="<,<,<,<,<"] +|=== +5+^|Execute instruction that possibly modifies state, including configuration + +|Action? + +Next state +|Exception + +Off +|Execute + +Dirty +|Execute + +Dirty +|Execute + +Dirty +|=== + +[width=75,align=center,float=center,cols="<,<,<,<,<"] +|=== +5+^|Execute instruction to unconfigure unit + +|Action? + +Next state +|Exception + +Off +|Execute + +Initial +|Execute + +Initial +|Execute + +Initial +|=== + +[width=75,align=center,float=center,cols="<,<,<,<,<"] +|=== +5+^|Execute instruction to disable unit + +|Action? + +Next state +|Execute + +Off +|Execute + +Off +|Execute + +Off +|Execute + +Off +|=== + +[width=75,align=center,float=center,cols="<,<,<,<,<"] +|=== +5+^|Execute instruction to enable unit + +|Action? + +Next state +|Execute + +Initial +|Execute + +Initial +|Execute + +Initial +|Execute + +Initial +|=== + +Standard privileged instructions to initialize, save, and restore +extension state are provided to insulate privileged code from details of +the added extension state by treating the state as an opaque object. + +[NOTE] +==== +Many coprocessor extensions are only used in limited contexts that +allows software to safely unconfigure or even disable units when done. +This reduces the context-switch overhead of large stateful coprocessors. + +We separate out floating-point state from other extension state, as when +a floating-point unit is present the floating-point registers are part +of the standard calling convention, and so user-mode software cannot +know when it is safe to disable the floating-point unit. +==== + +The XS field provides a summary of all added extension state, but +additional microarchitectural bits might be maintained in the extension +to further reduce context save and restore overhead. + +The SD bit is read-only and is set when either the FS, VS, or XS bits +encode a Dirty state (i.e., `SD=(FS==0b11 OR XS==0b11 OR VS==0b11)`). This +allows privileged code to quickly determine when no additional context +save is required beyond the integer register set and `pc`. + +The floating-point unit state is always initialized, saved, and restored +using standard instructions (F, D, and/or Q), and privileged code must +be aware of FLEN to determine the appropriate space to reserve for each +`f` register. + +Machine and Supervisor modes share a single copy of the FS, VS, and XS +bits. Supervisor-level software normally uses the FS, VS, and XS bits +directly to record the status with respect to the supervisor-level saved +context. Machine-level software must be more conservative in saving and +restoring the extension state in their corresponding version of the +context. + +[NOTE] +==== +In any reasonable use case, the number of context switches between user +and supervisor level should far outweigh the number of context switches +to other privilege levels. Note that coprocessors should not require +their context to be saved and restored to service asynchronous +interrupts, unless the interrupt results in a user-level context swap. +==== + +===== Previous Expected Landing Pad (ELP) State in `mstatus` Register + +[#norm:mstatus_spelp_mpelp_op]#The Zicfilp extension adds the `SPELP` and `MPELP` fields that hold the previous +`ELP`, and are updated as specified in <>.# +[#norm:mstatus_spelp_mpelp_enc_lead-in]#The *__x__*`PELP` fields are encoded as follows:# + +[[norm:mstatus_spelp_mpelp_enc_list]] +* 0 - `NO_LP_EXPECTED` - no landing pad instruction expected. +* 1 - `LP_EXPECTED` - a landing pad instruction is expected. + +==== Machine Trap-Vector Base-Address (`mtvec`) Register + +[#norm:mtvec_sz_warl_acc]#The `mtvec` register is an MXLEN-bit *WARL* read/write register that holds +trap vector configuration, consisting of a vector base address (BASE) +and a vector mode (MODE).# + +[[norm:mtvec_enc]] +.Encoding of mtvec MODE field. +include::images/bytefield/mtvec.edn[] + +[#norm:mtvec_mandatory]#The `mtvec` register must always be implemented#, but +[#norm:mtvec_rdonly]#can contain a read-only value.# +If `mtvec` is writable, the set of values the register +may hold can vary by implementation. +[#norm:mtvec_base_align_4B]#The value in the BASE field must +always be aligned on a 4-byte boundary#, and +[#norm:mtvec_base_align_func_mode]#the MODE setting may impose +additional alignment constraints on the value in the BASE field.# +Note that the CSR contains only bits XLEN-1 through 2 of the address BASE. +When used as an address, the lower two bits are filled with zeroes to obtain +an XLEN-bit address that is always aligned on a 4-byte boundary. + +[NOTE] +==== +We allow for considerable flexibility in implementation of the trap +vector base address. On the one hand, we do not wish to burden low-end +implementations with a large number of state bits, but on the other +hand, we wish to allow flexibility for larger systems. +==== + +[[norm:mtvec_mode_enc]] +.Encoding of mtvec MODE field. +[%autowidth,float="center",align="center",cols=">,^,<",options="header"] +|=== +|Value |Name |Description +|0 + +1 + +{ge}2 +|Direct + +Vectored + +--- +|All traps set `pc` to BASE. + +Asynchronous interrupts set `pc` to BASE+4{times}cause. + +_Reserved_ +|=== + +The encoding of the MODE field is shown in <>. +[#norm:mtvec_mode_direct_op]#When MODE=Direct, all traps into +machine mode cause the `pc` to be set to the address in the BASE field.# +[#norm:mtvec_mode_vectored_op]#When MODE=Vectored, all synchronous exceptions into machine mode cause +the `pc` to be set to the address in the BASE field, whereas interrupts +cause the `pc` to be set to the address in the BASE field plus four +times the interrupt cause number.# +For example, a machine-mode timer interrupt (see <>) causes the `pc` to be set to BASE+`0x1c`. + +An implementation may have different alignment constraints for different +modes. In particular, MODE=Vectored may have stricter alignment +constraints than MODE=Direct. + +[NOTE] +==== +Allowing coarser alignments in Vectored mode enables vectoring to be +implemented without a hardware adder circuit. + +*** + +[#norm:reset_nmi_addr]#Reset and NMI vector locations are given in a platform specification.# +==== + +==== Machine Trap Delegation (`medeleg` and `mideleg`) Registers + +[#norm:trap_def_M-mode]#By default, all traps at any privilege level are handled in machine +mode#, though a machine-mode handler can redirect traps back to the +appropriate level with the MRET instruction (<>). To increase performance, +[#norm:medeleg_mideleg_op1]#implementations can provide individual read/write bits within `medeleg` +and `mideleg` to indicate that certain exceptions and interrupts should +be processed directly by a lower privilege level.# +[#norm:medeleg_sz_acc]#The machine exception delegation register (`medeleg`) is a 64-bit read/write register.# +[#norm:mideleg_sz_acc]#The machine interrupt delegation (`mideleg`) register is an MXLEN-bit +read/write register.# + +[#norm:medeleg_mideleg_mandatory_S-mode]#In harts with S-mode, the `medeleg` and `mideleg` registers must +exist#, and [#norm:medeleg_mideleg_op2]#setting a bit in `medeleg` or `mideleg` will delegate the +corresponding trap, when occurring in S-mode or U-mode, to the S-mode +trap handler.# +[#norm:medeleg_mideleg_omit_wo_S-mode]#In harts without S-mode, the `medeleg` and `mideleg` registers should not exist.# + +[NOTE] +==== +In versions 1.9.1 and earlier , these registers existed but were +hardwired to zero in M-mode only, or M/U without N harts. There is no +reason to require they return zero in those cases, as the `misa` +register indicates whether they exist. +==== + +[#norm:trap_del_S-mode]#When a trap is delegated to S-mode#, +[#norm:trap_del_S-mode_op]#the `scause` register is written +with the trap cause; the `sepc` register is written with the virtual +address of the instruction that took the trap; the `stval` register is +written with an exception-specific datum; the SPP field of `mstatus` is +written with the active privilege mode at the time of the trap; the SPIE +field of `mstatus` is written with the value of the SIE field at the +time of the trap; and the SIE field of `mstatus` is cleared.# +[#norm:trap_del_S-mode_no_M-mode]#The `mcause`, `mepc`, and `mtval` registers and the MPP and MPIE fields of +`mstatus` are not written.# + +[#norm:medeleg_mideleg_warl]#An implementation can choose to subset the delegatable traps, with the +supported delegatable bits found by writing one to every bit location, +then reading back the value in `medeleg` or `mideleg` to see which bit +positions hold a one.# + +[#norm:medeleg_no_rd1]#An implementation shall not have any bits of `medeleg` be read-only one#, +i.e., any synchronous trap that can be delegated must support not being delegated. +Similarly, +[#norm:mideleg_no_rd1]#an implementation shall not fix as read-only one +any bits of `mideleg` corresponding to machine-level interrupts# +(but [#norm:mideleg_rd1_lower_level]#may do so for lower-level interrupts#). + +[NOTE] +==== +Version 1.11 and earlier prohibited having any bits of `mideleg` be +read-only one. Platform standards may always add such restrictions. +==== + +[#norm:trap_never_trans_lower]#Traps never transition from a more-privileged mode to a less-privileged mode. +For example, if M-mode has delegated illegal-instruction +exceptions to S-mode, and M-mode software later executes an illegal +instruction, the trap is taken in M-mode, rather than being delegated to S-mode.# +By contrast, [#norm:trap_horiz]#traps may be taken horizontally. Using the same +example, if M-mode has delegated illegal-instruction exceptions to +S-mode, and S-mode software later executes an illegal instruction, the +trap is taken in S-mode.# + +[#norm:trap_del_intr_priv_lvl]#Delegated interrupts result in the interrupt being masked at the +delegator privilege level. For example, if the supervisor timer +interrupt (STI) is delegated to S-mode by setting `mideleg`[5], STIs +will not be taken when executing in M-mode. By contrast, if `mideleg`[5] +is clear, STIs can be taken in any mode and regardless of current mode +will transfer control to M-mode.# + +[[norm:medeleg_enc_img]] +.Machine Exception Delegation (`medeleg`) register. +include::images/bytefield/medeleg.edn[] + +[#norm:medeleg_enc_txt]#`medeleg` has a bit position allocated for every synchronous exception +shown in <>, with the index of the +bit position equal to the value returned in the `mcause` register# +(i.e., setting bit 8 allows user-mode environment calls to be delegated to a +lower-privilege trap handler). + +[#norm:medelegh_sz_acc_enc_xlen32]#When XLEN=32, `medelegh` is a 32-bit read/write register +that aliases bits 63:32 of `medeleg`.# +[#norm:medelegh_omit_xlen64]#The `medelegh` register does not exist when XLEN=64.# + +[[norm:mideleg_enc_img]] +.Machine Interrupt Delegation (`mideleg`) Register. +include::images/bytefield/mideleg.edn[] + +[#norm:mideleg_enc_txt]#`mideleg` holds trap delegation bits for individual interrupts, with the +layout of bits matching those in the `mip` register# (i.e., STIP +interrupt delegation control is located in bit 5). + +[#norm:medeleg_when_rd0]#For exceptions that cannot occur in less privileged modes, the +corresponding `medeleg` bits should be read-only zero. In particular, +`medeleg`[11] is read-only zero.# + +[#norm:medeleg_16_no_rd0]#The `medeleg`[16] is read-only zero as double trap is not delegatable.# + +==== Machine Interrupt (`mip` and `mie`) Registers + +[#norm:mip_sz_acc]#The `mip` register is an MXLEN-bit read/write register containing +information on pending interrupts#, while [#norm:mie_sz_acc]#`mie` is the corresponding +MXLEN-bit read/write register containing interrupt enable bits.# +[#norm:mip_mie_enc_txt]#Interrupt cause number _i_ (as reported in CSR `mcause`, +<>) corresponds with bit _i_ in both `mip` and `mie`. +Bits 15:0 are allocated to standard interrupt causes only, while +bits 16 and above are designated for platform use.# + +NOTE: Interrupts designated for platform use may be designated for custom use +at the platform's discretion. + +[[norm:mip_enc_img]] +.Machine Interrupt-Pending (`mip`) register. +include::images/bytefield/mideleg.edn[] + +[[norm:mie_enc_img]] +.Machine Interrupt-Enable (`mie`) register +include::images/bytefield/mideleg.edn[] + +[#norm:intr_mip_mie_op]#An interrupt _i_ will trap to M-mode (causing the privilege mode to +change to M-mode) if all of the following are true: (a) either the +current privilege mode is M and the MIE bit in the `mstatus` register is +set, or the current privilege mode has less privilege than M-mode; +(b) bit _i_ is set in both `mip` and `mie`; and (c) if register +`mideleg` exists, bit _i_ is not set in `mideleg`.# + +[#norm:intr_mip_mie_bounded_time]#These conditions for an interrupt trap to occur must be evaluated in a +bounded amount of time from when an interrupt becomes, or ceases to be, +pending in `mip`,# and must also [#norm:intr_mip_mie_xret_csrwr]#be evaluated immediately following the +execution of an __x__RET instruction or an explicit write to a CSR on +which these interrupt trap conditions expressly depend (including `mip`, +`mie`, `mstatus`, and `mideleg`).# + +[[norm:intr_M-mode_highest_pri]] +Interrupts to M-mode take priority over any interrupts to lower privilege modes. + +[#norm:mip_bits_wr_or_rdonly]#Each individual bit in register `mip` may be writable or may be read-only.# +[#norm:mip_bits_wr_op]#When bit _i_ in `mip` is writable, a pending interrupt _i_ +can be cleared by writing 0 to this bit.# +[#norm:mip_bits_rdonly_op]#If interrupt _i_ can become pending but bit _i_ in `mip` is read-only, the implementation must +provide some other mechanism for clearing the pending interrupt.# + +[#norm:mie_bits_wr]#A bit in `mie` must be writable if the corresponding interrupt can ever become pending.# +[#norm:mie_bits_rdonly0]#Bits of `mie` that are not writable must be read-only zero.# + +[#norm:mip_mie_std_enc_txt]#The standard portions (bits 15:0) of the `mip` and `mie` registers are +formatted as shown in <> and <> respectively.# + +[[norm:mip_std_enc_img]] +.Standard portion (bits 15:0) of `mip`. +include::images/bytefield/mipreg-standard.edn[] + +[[norm:mie_std_enc_img]] +.Standard portion (bits 15:0) of `mie`. +include::images/bytefield/miereg-standard.edn[] + +[NOTE] +==== +The machine-level interrupt registers handle a few root interrupt +sources which are assigned a fixed service priority for simplicity, +while separate external interrupt controllers can implement a more +complex prioritization scheme over a much larger set of interrupts that +are then multiplexed into the machine-level interrupt sources. + +''' + +The non-maskable interrupt is not made visible via the `mip` register as +its presence is implicitly known when executing the NMI trap handler. +==== + +[#norm:mip_meip_mie_meie_op]#Bits `mip`.MEIP and `mie`.MEIE are the interrupt-pending and +interrupt-enable bits for machine-level external interrupts.# +[#norm:mip_meip_rdonly]#MEIP is read-only in `mip`, and is set and cleared by a platform-specific +interrupt controller.# + +[#norm:mip_mtip_mie_mtie_op]#Bits `mip`.MTIP and `mie`.MTIE are the interrupt-pending and +interrupt-enable bits for machine timer interrupts.# +[#norm:mip_mtip_rdonly]#MTIP is read-only in the `mip` register, and is cleared by writing to +the memory-mapped machine-mode timer compare register.# + +[#norm:mip_msip_mie_msie_op]#Bits `mip`.MSIP and `mie`.MSIE are the interrupt-pending and +interrupt-enable bits for machine-level software interrupts.# +[#norm:mip_msip_rdonly]#MSIP is read-only in `mip`, and is written by accesses to memory-mapped control +registers, which are used to provide machine-level interprocessor interrupts.# + +[#norm:msip_sz_acc]#A hart's memory-mapped `msip` register is a 32-bit read/write register#, +where [#norm:msip_enc]#bits 31--1 read as zero and bit 0 contains the MSIP bit.# +[#norm:msip_update_max_time]#When the memory-mapped `msip` register changes, it is guaranteed to be +reflected in `mip`.MSIP eventually, but not necessarily immediately.# +[#norm:mip_msip_mie_msie_maybe_rdonly0]#If a system has only one hart, or +if a platform standard supports the delivery of machine-level +interprocessor interrupts through external interrupts (MEI) instead, +then `mip`.MSIP and `mie`.MSIE may both be read-only zeros.# + +[#norm:mip_sxip_mie_sxie_rdonly0]#If supervisor mode is not implemented, bits SEIP, STIP, and SSIP of +`mip` and SEIE, STIE, and SSIE of `mie` are read-only zeros.# + +[#norm:mip_seip_mie_seie_op]#If supervisor mode is implemented, bits `mip`.SEIP and `mie`.SEIE are +the interrupt-pending and interrupt-enable bits for supervisor-level external interrupts.# +[#norm:mip_seip_acc]#SEIP is writable in `mip`#, and may be written by +M-mode software to indicate to S-mode that an external interrupt is +pending. Additionally, the platform-level interrupt controller may +generate supervisor-level external interrupts. +[#norm:intr_sei_op]#Supervisor-level external interrupts are made pending based on the logical-OR of the +software-writable SEIP bit and the signal from the external interrupt controller.# +[#norm:mip_seip_rdcsr]#When `mip` is read with a CSR instruction, the value of the +SEIP bit returned in the `rd` destination register is the logical-OR of +the software-writable bit and the interrupt signal from the interrupt +controller#, but [#norm:mip_seip_wrcsr]#the signal from the interrupt controller is not used to +calculate the value written to SEIP. Only the software-writable SEIP bit +participates in the read-modify-write sequence of a CSRRS or CSRRC instruction.# + +[NOTE] +==== +For example, if we name the software-writable SEIP bit `B` and the +signal from the external interrupt controller `E`, then if +`csrrs t0, mip, t1` is executed, `t0[9]` is written with `B || E`, then +`B` is written with `B || t1[9]`. If `csrrw t0, mip, t1` is executed, +then `t0[9]` is written with `B || E`, and `B` is simply written with +`t1[9]`. In neither case does `B` depend upon `E`. + +The SEIP field behavior is designed to allow a higher privilege layer to +mimic external interrupts cleanly, without losing any real external +interrupts. The behavior of the CSR instructions is slightly modified +from regular CSR accesses as a result. +==== + +[#norm:mip_stip_mie_stie_op]#If supervisor mode is implemented, its `mip`.STIP and `mie`.STIE are +the interrupt-pending and interrupt-enable bits for supervisor-level timer interrupts.# +[#norm:mip_stip_no-stimecmp_acc]#If the stimecmp register is not implemented, STIP is writable in +mip#, and [#norm:mip_stip_no-stimecmp_op2]#may be written by M-mode software to deliver timer interrupts to +S-mode.# [#norm:mip_stip_stimecmp_acc]#If the `stimecmp` (supervisor-mode timer compare) register is +implemented, STIP is read-only in mip# and [#norm:mip_stip_stimecmp_op2]#reflects the supervisor-level timer +interrupt signal resulting from stimecmp.# [#norm:mip_stip_stimecmp_clr]#This timer interrupt signal is +cleared by writing `stimecmp` with a value greater than the current time value.# + +[#norm:mip_ssip_mie_ssie_op]#If supervisor mode is implemented, bits `mip`.SSIP and `mie`.SSIE are +the interrupt-pending and interrupt-enable bits for supervisor-level software interrupts.# +[#norm:mip_ssip_acc]#SSIP is writable in `mip`# and [#norm:mip_ssip_intr_ctrl]#may also be set to 1 +by a platform-specific interrupt controller.# + +[#norm:mip_lcofip_mie_lcofie_op]#If the Sscofpmf extension is implemented, bits `mip`.LCOFIP and `mie`.LCOFIE +are the interrupt-pending and interrupt-enable bits for local-counter-overflow interrupts.# +[#norm:mip_lcofip_acc]#LCOFIP is read-write in `mip`# and [#norm:mip_lcofip_op2]#reflects the occurrence of a local +counter-overflow overflow interrupt request resulting from any of the `mhpmevent__n__`.OF bits being set.# +[#norm:mip_lcofip_mie_lcofie_rdonly0]#If the Sscofpmf extension is not implemented, `mip`.LCOFIP and `mie`.LCOFIE are +read-only zeros.# + +[#norm:intr_M-mode_pri]#Multiple simultaneous interrupts destined for M-mode are handled in the +following decreasing priority order: MEI, MSI, MTI, SEI, SSI, STI, LCOFI.# + +[NOTE] +==== +The machine-level interrupt fixed-priority ordering rules were developed +with the following rationale. + +Interrupts for higher privilege modes must be serviced before interrupts +for lower privilege modes to support preemption. + +The platform-specific machine-level interrupt sources in bits 16 and +above have platform-specific priority, but are typically chosen to have +the highest service priority to support very fast local vectored +interrupts. + +External interrupts are handled before internal (timer/software) +interrupts as external interrupts are usually generated by devices that +might require low interrupt service times. + +Software interrupts are handled before internal timer interrupts, +because internal timer interrupts are usually intended for time slicing, +where time precision is less important, whereas software interrupts are +used for inter-processor messaging. Software interrupts can be avoided +when high-precision timing is required, or high-precision timer +interrupts can be routed via a different interrupt path. Software +interrupts are located in the lowest four bits of `mip` as these are +often written by software, and this position allows the use of a single +CSR instruction with a five-bit immediate. +==== + +Restricted views of the `mip` and `mie` registers appear as the `sip` +and `sie` registers for supervisor level. If an interrupt is delegated +to S-mode by setting a bit in the `mideleg` register, it becomes visible +in the `sip` register and is maskable using the `sie` register. +Otherwise, the corresponding bits in `sip` and `sie` are read-only zero. + +==== Hardware Performance Monitor + +M-mode includes a basic hardware performance-monitoring facility. +[#norm:mcycle_op]#The `mcycle` CSR counts the number of clock cycles executed by the processor +core on which the hart is running.# +[#norm:minstret_op]#The `minstret` CSR counts the number of instructions the hart has retired.# +[#norm:mcycle_minstret_sz]#The `mcycle` and `minstret` registers have 64-bit precision on all RV32 and RV64 harts.# + +[#norm:mcycle_minstret_rst]#The counter registers have an arbitrary value after the hart is reset, +and can be written with a given value.# +[#norm:mcycle_minstret_wr]#Any CSR write takes effect after the writing instruction has otherwise completed.# +[#norm:mcycle_shared]#The `mcycle` CSR may be +shared between harts on the same core, in which case writes to `mcycle` +will be visible to those harts.# The platform should provide a mechanism +to indicate which harts share an `mcycle` CSR. + +[#norm:mhpmcounter_num]#The hardware performance monitor includes 29 additional 64-bit event +counters, `mhpmcounter3`-`mhpmcounter31`.# +[#norm:mhpmevent_sz_warl_op]#The event selector CSRs, +`mhpmevent3`-`mhpmevent31`, are 64-bit *WARL* registers that control which +event causes the corresponding counter to increment.# +[#norm:mhpmevent_enc]#The meaning of these events is defined by the platform, +but event 0 is defined to mean "no event."# +[#norm:mhpmcounter_mandatory]#All counters should be implemented#, but +[#norm:mhpmcounter_mhpmevent_rdonly0]#a legal implementation is to make both the counter and its corresponding event selector be read-only 0.# + +.Hardware performance monitor counters. +include::images/bytefield/hpmevents.edn[] + +[#norm:mhpmcounter_warl]#The `mhpmcounters` are *WARL* registers# that +[#norm:mhpmcounter_sz]#support up to 64 bits of precision on RV32 and RV64.# + +When XLEN=32, reads of the `mcycle`, `minstret`, `mhpmcounter__n__`, and `mhpmevent__n__` +CSRs return bitj 31-0 of the corresponding register, and writes change only bits 31-0; +[#norm:mcycleh_minstreth_mhpmh_op]#reads of the `mcycleh`, `minstreth`, `mhpmcounter__n__h`, and `mhpmevent__n__h` +CSRs return bits 63-32 of the corresponding register, and writes change only bits 63-32.# +[#norm:mhpmeventh_presence]#The `mhpmevent__n__h` CSRs are provided only if the Sscofpmf extension is implemented.# + +[[mcounteren]] +==== Machine Counter-Enable (`mcounteren`) Register + +[#norm:mcounteren_sz]#The counter-enable `mcounteren` register is a 32-bit register# that +[#norm:mcounteren_op]#controls the availability of the hardware performance-monitoring +counters to the next-lower privileged mode.# + +[[norm:mcounteren_enc_img]] +.Counter-enable (`mcounteren`) register. +include::images/bytefield/counteren.edn[] + +[#norm:mcounteren_inc_inaccessible]#The settings in this register only control accessibility. The act of +reading or writing this register does not affect the underlying +counters, which continue to increment even when not accessible.# + +[#norm:mcounteren_clr_ill_inst_exc]#When the CY, TM, IR, or HPM__n__ bit in the `mcounteren` register is +clear, attempts to read the `cycle`, `time`, `instret`, or +`hpmcountern` register while executing in S-mode or U-mode will cause an +illegal-instruction exception.# +[#norm:mcounteren_set_nxt_priv]#When one of these bits is set, access to +the corresponding register is permitted in the next implemented +privilege mode (S-mode if implemented, otherwise U-mode).# + +[NOTE] +==== +The counter-enable bits support two common use cases with minimal +hardware. For harts that do not need high-performance timers and +counters, machine-mode software can trap accesses and implement all +features in software. For harts that need high-performance timers and +counters but are not concerned with obfuscating the underlying hardware +counters, the counters can be directly exposed to lower privilege modes. +==== + +In addition, [#norm:mcounteren_tm_clr]#when the TM bit in the `mcounteren` register is clear, attempts to +access the `stimecmp` or `vstimecmp` register while executing in a mode less +privileged than M will cause an illegal-instruction exception.# +[#norm:mcounteren_tm_set]#When this bit is set, access to the `stimecmp` or `vstimecmp` register is permitted in S-mode +if implemented, and access to the `vstimecmp` register (via `stimecmp`) is +permitted in VS-mode if implemented and not otherwise prevented by the TM bit in +`hcounteren`.# + +[#norm:cycle_instret_hpmcounter_op_rdonly]#The `cycle`, `instret`, and `hpmcountern` CSRs are read-only shadows of `mcycle`, `minstret`, and `mhpmcounter n`, respectively.# +[#norm:time_op_rdonly]#The `time` CSR is a read-only shadow of the memory-mapped `mtime` register.# +Analogously, [#norm:cycleh_instreth_hpmcounternh_op_rdonly]#when XLEN=32, the `cycleh`, `instreth` and `hpmcounternh` CSRs +are read-only shadows of `mcycleh`, `minstreth` and `mhpmcounternh`, respectively.# +[#norm:timeh_op_rdonly]#When XLEN=32, the `timeh` CSR is a read-only shadow of the +upper 32 bits of the memory-mapped `mtime` register#, while `time` +shadows only the lower 32 bits of `mtime`. + +[NOTE] +==== +Implementations can convert reads of the `time` and `timeh` CSRs into +loads to the memory-mapped `mtime` register, or emulate this +functionality on behalf of less-privileged modes in M-mode software. +==== + +[#norm:mcounteren_flds_mandatory_warl]#In harts with U-mode, the `mcounteren` must be +implemented, but all fields are *WARL*# and +[#norm:mcounteren_flds_rdonly0]#may be read-only zero, indicating reads to the +corresponding counter will cause an illegal-instruction exception when +executing in a less-privileged mode.# +[#norm:mcounteren_presence]#In harts without U-mode, the `mcounteren` register should not exist.# + +==== Machine Counter-Inhibit (`mcountinhibit`) Register + +[[norm:mcountinhibit_enc_img]] +.Counter-inhibit `mcountinhibit` register +include::images/bytefield/counterinh.edn[] + +[#norm:mcountinhibit_sz_warl_op1]#The counter-inhibit register `mcountinhibit` is a 32-bit +*WARL* register that controls which of the hardware performance-monitoring counters increment.# +[#norm:mcountinhibit_only_inc]#The settings in this register only control whether the +counters increment; their accessibility is not affected by the setting +of this register.# + +[#norm:mcountinhibit_op2]#When the CY, IR, or HPM__n__ bit in the `mcountinhibit` register is clear, +the `mcycle`, `minstret`, or `mhpmcountern` register increments as usual. +When the CY, IR, or HPM__n__ bit is set, the corresponding counter does +not increment.# + +[#norm:mcountinhibit_cy_shared]#The `mcycle` CSR may be shared between harts on the same core, +in which case the `mcountinhibit.CY` field is also shared between those harts, +and so writes to `mcountinhibit.CY` will be visible to those harts.# + +[#norm:mcountinhibit_not_impl]#If the `mcountinhibit` register is not implemented, the implementation +behaves as though the register were set to zero.# + +[NOTE] +==== +When the `mcycle` and `minstret` counters are not needed, it is desirable +to conditionally inhibit them to reduce energy consumption. Providing a +single CSR to inhibit all counters also allows the counters to be +atomically sampled. + +Because the `mtime` counter can be shared between multiple cores, it +cannot be inhibited with the `mcountinhibit` mechanism. +==== + +==== Machine Scratch (`mscratch`) Register + +[#norm:mscratch_sz_acc]#The `mscratch` register is an MXLEN-bit read/write register dedicated +for use by machine mode.# Typically, it is used to hold a pointer to a +machine-mode hart-local context space and swapped with a user register +upon entry to an M-mode trap handler. + +[[norm:mscratch_enc_img]] +.Machine-mode scratch register. +include::images/bytefield/mscratch.edn[] + +[NOTE] +==== +The MIPS ISA allocated two user registers (`k0`/`k1`) for use by the +operating system. Although the MIPS scheme provides a fast and simple +implementation, it also reduces available user registers, and does not +scale to further privilege levels, or nested traps. It can also require +both registers are cleared before returning to user level to avoid a +potential security hole and to provide deterministic debugging behavior. + +The RISC-V user ISA was designed to support many possible privileged +system environments and so we did not want to infect the user-level ISA +with any OS-dependent features. The RISC-V CSR swap instructions can +quickly save/restore values to the `mscratch` register. Unlike the MIPS +design, the OS can rely on holding a value in the `mscratch` register +while the user context is running. +==== + +==== Machine Exception Program Counter (`mepc`) Register + +[#norm:mepc_sz_acc]#`mepc` is an MXLEN-bit read/write register# formatted as shown in <>. +[#norm:mepc_align]#The low bit of `mepc` (`mepc[0]`) is always zero. On implementations that support only IALIGN=32, the two low bits (`mepc[1:0]`) are always zero.# + +[#norm:mepc_bit1_dyn_ialign_op]#If an implementation allows IALIGN to be either 16 or 32 (by changing +CSR `misa`, for example), then, whenever IALIGN=32, bit `mepc[1]` is +masked on reads so that it appears to be 0. This masking occurs also for +the implicit read by the MRET instruction. Though masked, `mepc[1]` +remains writable when IALIGN=32.# + +[#norm:mepc_warl]#`mepc` is a *WARL* register# that must be able to hold all valid virtual +addresses. It need not be capable of holding all possible invalid addresses. +[#norm:mepc_inv_addr_conv]#Prior to writing `mepc`, implementations may convert an +invalid address into some other invalid address that `mepc` is capable of holding.# + +[NOTE] +==== +When address translation is not in effect, virtual addresses and +physical addresses are equal. Hence, the set of addresses `mepc` must be +able to represent includes the set of physical addresses that can be +used as a valid `pc` or effective address. +==== + +[#norm:mepc_op]#When a trap is taken into M-mode, `mepc` is written with the virtual +address of the instruction that was interrupted or that encountered the +exception. Otherwise, `mepc` is never written by the implementation, +though it may be explicitly written by software.# + +[[norm:mepc_enc_img]] +.Machine exception program counter register. +include::images/bytefield/mepcreg.edn[] + +[[mcause]] +==== Machine Cause (`mcause`) Register + +[#norm:mcause_sz_acc]#The `mcause` register is an MXLEN-bit read-write register# formatted as +shown in <>. +[#norm:mcause_op]#When a trap is taken into +M-mode, `mcause` is written with a code indicating the event that +caused the trap. Otherwise, `mcause` is never written by the +implementation, though it may be explicitly written by software.# + +[#norm:mcause_intr_op]#The Interrupt bit in the `mcause` register is set if the trap was +caused by an interrupt.# +[#norm:mcause_exccode_op]#The Exception Code field contains a code identifying +the last exception or interrupt.# +<> lists the possible machine-level exception codes.# +[#norm:mcause_exccode_wlrl]#The Exception Code is a *WLRL* field, so is only guaranteed to hold supported exception codes.# + +[[norm:mcause_enc_img]] +.Machine Cause (`mcause`) register. +include::images/bytefield/mcausereg.edn[] + +[#norm:mcause_exccode_ld_ldrsv]#Note that load and load-reserved instructions generate load exceptions#, whereas +[#norm:mcause_exccode_st_sc_amo]#store, store-conditional, and AMO instructions generate +store/AMO exceptions.# + +[NOTE] +==== +Interrupts can be separated from other traps with a single branch on the +sign of the `mcause` register value. A shift left can remove the +interrupt bit and scale the exception codes to index into a trap vector +table. + +*** + +We do not distinguish privileged instruction exceptions from +illegal-instruction exceptions. This simplifies the architecture and also hides +details of which higher-privilege instructions are supported by an +implementation. The privilege level servicing the trap can implement a +policy on whether these need to be distinguished, and if so, whether a +given opcode should be treated as illegal or privileged. +==== + +[#norm:mcause_exccode_pri1]#If an instruction may raise multiple synchronous exceptions, the +decreasing priority order of <> indicates which +exception is taken and reported in `mcause`.# +The priority of any custom synchronous exceptions is implementation-defined. + +<<< + +[[norm:mcause_exccode_enc_img]] +.Machine cause (`mcause`) register values after trap. +[%autowidth,float="center",align="center",cols=">,>,<",options="header",] +|=== +|Interrupt |Exception Code |Description +|1 + +1 + +1 + +1 +|0 + +1 + +2 + +3 +|_Reserved_ + +Supervisor software interrupt + +_Reserved_ + +Machine software interrupt + +|1 + +1 + +1 + +1 +|4 + +5 + +6 + +7 +|_Reserved_ + +Supervisor timer interrupt + +_Reserved_ + +Machine timer interrupt +|1 + +1 + +1 + +1 +|8 + +9 + +10 + +11 +|_Reserved_ + +Supervisor external interrupt + +_Reserved_ + +Machine external interrupt +|1 + +1 + +1 + +1 +|12 + +13 + +14-15 + +{ge}16 +|_Reserved_ + +Counter-overflow interrupt + +_Reserved_ + +_Designated for platform use_ +|0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 +|0 + +1 + +2 + +3 + +4 + +5 + +6 + +7 + +8 + +9 + +10 + +11 + +12 + +13 + +14 + +15 + +16 + +17 + +18 + +19 + +20-23 + +24-31 + +32-47 + +48-63 + +{ge}64 +|Instruction address misaligned + +Instruction access fault + +Illegal instruction + +Breakpoint + +Load address misaligned + +Load access fault + +Store/AMO address misaligned + +Store/AMO access fault + +Environment call from U-mode + +Environment call from S-mode + +_Reserved_ + +Environment call from M-mode + +Instruction page fault + +Load page fault + +_Reserved_ + +Store/AMO page fault + +Double trap + +_Reserved_ + +Software check + +Hardware error + +_Reserved_ + +_Designated for custom use_ + +_Reserved_ + +_Designated for custom use_ + +_Reserved_ +|=== + +<<< + +[[norm:exc_priority]] +.Synchronous exception priority in decreasing priority order. +[%autowidth,float="center",align="center",cols="<,>,<",options="header",] +|=== +|Priority |Exc.Code |Description +|_Highest_ |3 |Instruction address breakpoint +| .>|12, 1 .<|During instruction address translation: + +First encountered page fault or access fault +| .>|1 .<|With physical address for instruction: + +Instruction access fault + +| .>|2 + +0 + +8,9,11 + +3 + +3 .<|Illegal instruction + +Instruction address misaligned + +Environment call + +Environment break + +Load/store/AMO address breakpoint + +| .>|4,6 .<|Optionally: + +Load/store/AMO address misaligned +| .>|13, 15, 5, 7 .<|During address translation for an explicit memory access: + +First encountered page fault or access fault +| .>|5,7 .<|With physical address for an explicit memory access: + +Load/store/AMO access fault +.>|_Lowest_ .>|4,6 .<|If not higher priority: + +Load/store/AMO address misaligned +|=== + +When a virtual address is translated into a physical address, the +address translation algorithm determines what specific exception may be +raised. + +[#norm:mcause_exccode_pri2]#Load/store/AMO address-misaligned exceptions may have either higher or +lower priority than load/store/AMO page-fault and access-fault exceptions.# + +[NOTE] +==== +The relative priority of load/store/AMO address-misaligned and +page-fault exceptions is implementation-defined to flexibly cater to two +design points. Implementations that never support misaligned accesses +can unconditionally raise the misaligned-address exception without +performing address translation or protection checks. Implementations +that support misaligned accesses only to some physical addresses must +translate and check the address before determining whether the +misaligned access may proceed, in which case raising the page-fault +exception or access is more appropriate. + +*** + +Instruction address breakpoints have the same cause value as, but +different priority than, data address breakpoints (a.k.a. watchpoints) +and environment break exceptions (which are raised by the EBREAK +instruction). + +*** + +Instruction address-misaligned exceptions are raised by control-flow +instructions with misaligned targets, rather than by the act of fetching +an instruction. Therefore, these exceptions have lower priority than +other instruction address exceptions. +==== + +[NOTE] +==== +A software-check exception is a synchronous exception that is triggered when +there are violations of checks and assertions defined by ISA extensions that +aim to safeguard the integrity of software assets, including e.g. control-flow +and memory-access constraints. When this exception is raised, the `__x__tval` +register is set either to 0 or to an informative value defined by the extension +that stipulated the exception be raised. The priority of this exception, +relative to other synchronous exceptions, depends on the cause of this exception +and is defined by the extension that stipulated the exception be raised. + +A hardware-error exception is a synchronous exception triggered when corrupted or +uncorrectable data is accessed explicitly or implicitly by an instruction. In +this context, "data" encompasses all types of information used within a RISC-V +hart. Upon a hardware-error exception, the `__x__epc` register is set to the +address of the instruction that attempted to access corrupted data, while the +`__x__tval` register is set either to 0 or to the virtual address of an +instruction fetch, load, or store that attempted to access corrupted data. The +priority of hardware-error exception is implementation-defined, but any given +occurrence is generally expected to be recognized at the point in the overall +priority order at which the hardware error is discovered. +==== + +==== Machine Trap Value (`mtval`) Register + +The `mtval` register is an MXLEN-bit read-write register formatted as +shown in <>. When a trap is taken into +M-mode, `mtval` is either set to zero or written with exception-specific +information to assist software in handling the trap. Otherwise, `mtval` +is never written by the implementation, though it may be explicitly +written by software. The hardware platform will specify which exceptions +must set `mtval` informatively, which may unconditionally set it to +zero, and which may exhibit either behavior, depending on the underlying event +that caused the exception. +If the hardware platform specifies that no exceptions set `mtval` +to a nonzero value, then `mtval` is read-only zero. + +If `mtval` is written with a nonzero value when a breakpoint, +address-misaligned, access-fault, page-fault, or hardware-error exception +occurs on an +instruction fetch, load, or store, then `mtval` will contain the +faulting virtual address. + +On a breakpoint exception raised by an EBREAK or C.EBREAK instruction, `mtval` +is written with either zero or the virtual address of the instruction. + +NOTE: For breakpoint exceptions raised by [C.]EBREAK, the virtual address of +the instruction is already recorded in `mepc`. +Recording the same address in `mtval` is redundant; the option is provided for +backwards compatibility. + +When page-based virtual memory is enabled, `mtval` is written with the +faulting virtual address, even for physical-memory access-fault +exceptions. This design reduces datapath cost for most implementations, +particularly those with hardware page-table walkers. + +[[mtvalreg]] +.Machine Trap Value (`mtval`) register. +include::images/bytefield/mtvalreg.edn[] + + +If `mtval` is written with a nonzero value when a misaligned load or +store causes an access-fault, page-fault, or hardware-error exception, +then `mtval` will +contain the virtual address of the portion of the access that caused the +fault. + +If `mtval` is written with a nonzero value when an instruction +access-fault, page-fault, or hardware-error exception occurs on a hart with +variable-length instructions, then `mtval` will contain the virtual +address of the portion of the instruction that caused the fault, while +`mepc` will point to the beginning of the instruction. + +The `mtval` register can optionally also be used to return the faulting +instruction bits on an illegal-instruction exception (`mepc` points to +the faulting instruction in memory). If `mtval` is written with a +nonzero value when an illegal-instruction exception occurs, then `mtval` +will contain the shortest of: + +* the actual faulting instruction + +* the first ILEN bits of the faulting instruction + +* the first MXLEN bits of the faulting instruction + +The value loaded into `mtval` on an illegal-instruction exception is +right-justified and all unused upper bits are cleared to zero. + +[NOTE] +==== +Capturing the faulting instruction in `mtval` reduces the overhead of +instruction emulation, potentially avoiding several partial instruction +loads if the instruction is misaligned, and likely data cache misses or +slow uncached accesses when loads are used to fetch the instruction into +a data register. There is also a problem of atomicity if another agent +is manipulating the instruction memory, as might occur in a dynamic +translation system. + +A requirement is that the entire instruction (or at least the first +MXLEN bits) are fetched into `mtval` before taking the trap. This should +not constrain implementations, which would typically fetch the entire +instruction before attempting to decode the instruction, and avoids +complicating software handlers. + +A value of zero in `mtval` signifies either that the feature is not +supported, or an illegal zero instruction was fetched. A load from the +instruction memory pointed to by `mepc` can be used to distinguish these +two cases (or alternatively, the system configuration information can be +interrogated to install the appropriate trap handling before runtime). +==== + +On a trap caused by a software-check exception, the `mtval` register holds +the cause for the exception. The following encodings are defined: + +* 0 - No information provided. +* 2 - Landing Pad Fault. Defined by the Zicfilp extension (<>). +* 3 - Shadow Stack Fault. Defined by the Zicfiss extension (<>). + +For other traps, `mtval` is set to zero, but a future standard may +redefine `mtval`’s setting for other traps. + +If `mtval` is not read-only zero, it is a *WARL* register that must be able to +hold all valid virtual addresses and the value zero. It need not be +capable of holding all possible invalid addresses. Prior to writing +`mtval`, implementations may convert an invalid address into some other +invalid address that `mtval` is capable of holding. If the feature to +return the faulting instruction bits is implemented, `mtval` must also +be able to hold all values less than 2^__N__^, where +_N_ is the smaller of MXLEN and ILEN. + +==== Machine Configuration Pointer (`mconfigptr`) Register + +The `mconfigptr` register is an MXLEN-bit read-only CSR, formatted as shown in +<>, that holds the physical +address of a configuration data structure. Software can traverse this +data structure to discover information about the harts, the platform, +and their configuration. + +[[mconfigptrreg]] +.Machine Configuration Pointer (`mconfigptr`) register. +include::images/bytefield/mconfigptrreg.edn[] + + +The pointer alignment in bits must be no smaller than MXLEN: +i.e., if MXLEN is +8{times}__n__, then `mconfigptr`[log~2n~-1:0] +must be zero. + +The `mconfigptr` register must be implemented, but it may be zero to indicate the +configuration data structure does not exist or that an alternative +mechanism must be used to locate it. + +[NOTE] +==== +The format and schema of the configuration data structure have yet to be +standardized. + +*** + +While the `mconfigptr` register will simply be hardwired in some implementations, +other implementations may provide a means to configure the value +returned on CSR reads. For example, `mconfigptr` might present the value +of a memory-mapped register that is programmed by the platform or by +M-mode software towards the beginning of the boot process. +==== + +[[sec:menvcfg]] +==== Machine Environment Configuration (`menvcfg`) Register + +The `menvcfg` CSR is a 64-bit read/write register, formatted +as shown in <>, that controls +certain characteristics of the execution environment for modes less +privileged than M. + +[[menvcfgreg]] +.Machine environment configuration (`menvcfg`) register. +include::images/wavedrom/menvcfgreg.edn[] + + +If bit FIOM (Fence of I/O implies Memory) is set to one in `menvcfg`, +FENCE instructions executed in modes less privileged than M are modified +so the requirement to order accesses to device I/O implies also the +requirement to order main memory accesses. <> +details the modified interpretation of FENCE instruction bits PI, PO, +SI, and SO for modes less privileged than M when FIOM=1. + +Similarly, for modes less privileged than M when FIOM=1, if an atomic +instruction that accesses a region ordered as device I/O has its _aq_ +and/or _rl_ bit set, then that instruction is ordered as though it +accesses both device I/O and memory. + +If S-mode is not supported, or if `satp`.MODE is read-only zero (always +Bare), the implementation may make FIOM read-only zero. + +[[menvcfg-FIOM]] +.Modified interpretation of FENCE predecessor and successor sets for modes less privileged than M when FIOM=1. +[%autowidth,float="center",align="center",cols="^,<",options="header"] +|=== +|Instruction bit |Meaning when set +|PI + +PO +|Predecessor device input and memory reads (PR implied) + +Predecessor device output and memory writes (PW implied) +|SI + +SO +|Successor device input and memory reads (SR implied) + +Successor device output and memory writes (SW implied) +|=== + +[NOTE] +==== +Bit FIOM is needed in `menvcfg` so M-mode can emulate the hypervisor +extension of <>, which has an +equivalent FIOM bit in the hypervisor CSR `henvcfg`. +==== + +The PBMTE bit controls whether the Svpbmt extension is available for use +in S-mode and G-stage address translation (i.e., for page tables pointed +to by `satp` or `hgatp`). When PBMTE=1, Svpbmt is available for S-mode +and G-stage address translation. When PBMTE=0, the implementation +behaves as though Svpbmt were not implemented. If Svpbmt is not +implemented, PBMTE is read-only zero. Furthermore, for implementations +with the hypervisor extension, `henvcfg`.PBMTE is read-only zero if +`menvcfg`.PBMTE is zero. + +After changing `menvcfg`.PBMTE, executing an SFENCE.VMA instruction with +_rs1_=`x0` and _rs2_=`x0` suffices to synchronize address-translation caches +with respect to the altered interpretation of page-table entries' PBMT fields. +See <> for additional synchronization requirements when the +hypervisor extension is implemented. + +If the Svadu extension is implemented, the ADUE bit controls whether hardware +updating of PTE A/D bits is enabled for S-mode and G-stage address +translations. +When ADUE=1, hardware updating of PTE A/D bits is enabled during S-mode +address translation, and the implementation behaves as though the Svade +extension were not implemented for S-mode address translation. +When the hypervisor extension is implemented, if ADUE=1, hardware updating of +PTE A/D bits is enabled during G-stage address translation, and the +implementation behaves as though the Svade extension were not implemented for +G-stage address translation. +When ADUE=0, the implementation behaves as though Svade were implemented for +S-mode and G-stage address translation. +If Svadu is not implemented, ADUE is read-only zero. +Furthermore, for implementations with the hypervisor extension, `henvcfg`.ADUE +is read-only zero if `menvcfg`.ADUE is zero. + +After changing `menvcfg`.ADUE, executing an SFENCE.VMA instruction with +_rs1_=`x0` and _rs2_=`x0` suffices to synchronize address-translation caches +with respect to the altered interpretation of page-table entries' A/D bits. +See <> for additional synchronization requirements when the +hypervisor extension is implemented. + +NOTE: The Svade extension requires page-fault exceptions be raised when PTE +A/D bits need be set, hence Svade is implemented when ADUE=0. + +If the Smcdeleg extension is implemented, the CDE (Counter Delegation Enable) bit controls whether Zicntr and Zihpm counters can be delegated to S-mode. When CDE=1, the Smcdeleg extension is enabled, see <>. When CDE=0, the Smcdeleg and Ssccfg extensions appear to be not implemented. If Smcdeleg is not implemented, CDE is read-only zero. + +[[norm:menvcfg-stce]] +The Sstc extension adds the `STCE` (STimecmp Enable) bit to `menvcfg` CSR. When +the Sstc extension is not implemented, `STCE` is read-only zero. The `STCE` bit +enables `stimecmp` for S-mode when set to one. When this extension is +implemented and `STCE` in `menvcfg` is zero, an attempt to access `stimecmp` +in a mode other than M-mode raises an illegal-instruction exception, `STCE` in +`henvcfg` is read-only zero, and `STIP` in `mip` and `sip` reverts to its +defined behavior as if this extension is not implemented. Further, if the H +extension is implemented, then `hip`.VSTIP also reverts its defined behavior as +if this extension is not implemented. + +[[norm:menvcfg-cbze]] +The Zicboz extension adds the `CBZE` (Cache Block Zero instruction enable) field +to `menvcfg`. When the `CBZE` field is set to 1, it enables execution of the +cache block zero instruction, `CBO.ZERO`, in modes less privileged than M. +Otherwise, the instruction raises an illegal-instruction exception in modes less +privileged than M. When the Zicboz extension is not implemented, `CBZE` is +read-only zero. + +[[norm:menvcfg-cbcfe]] +The Zicbom extension adds the `CBCFE` (Cache Block Clean and Flush instruction +Enable) field to `menvcfg`. When the `CBCFE` field is set to 1, it enables +execution of the cache block clean instruction (`CBO.CLEAN`) and the cache block +flush instruction (`CBO.FLUSH`) in modes less privileged than M. Otherwise, these +instructions raise an illegal-instruction exception in modes less privileged +than M. When the Zicbom extension is not implemented, `CBCFE` is read-only zero. + +[#norm:menvcfg-cbie]#The Zicbom extension adds the `CBIE` (Cache Block Invalidate instruction Enable) +WARL field to `menvcfg` to control execution of the cache block invalidate +instruction (`CBO.INVAL`) in modes less privileged than M. When `CBIE` is set to +`00b`, the instruction raises an illegal-instruction exception in modes less +privileged than M. When the Zicbom extension is not implemented, `CBIE` is +read-only zero. The encoding `10b` is reserved.# +[#norm:cbo-inval_m-mode_op0]#When `CBIE` is set to `01b` +or `11b`, and when enabled for execution in modes less privileged than M, it +behaves as follows:# + +* [[norm:cbo-inval_m-mode_op1]]`01b` -- The instruction is executed and performs a flush operation, even if + configured by a mode less privileged than M to perform an invalidate operation. +* [[norm:cbo-inval_m-mode_op2]]`11b` -- The instruction is executed and performs an invalidate operation, + unless configured by a mode less privileged than M to perform a flush + operation. + +If the Smnpm extension is implemented, the `PMM` field enables or disables +pointer masking (see <>) for the next-lower privilege mode (S-/HS-mode if +S-mode is implemented, or U-mode otherwise), according to the values in +<>. If Smnpm is not implemented, `PMM` is read-only zero. +The `PMM` field is read-only zero for RV32. + +[[menvcfg-pmm-values]] + +[%header, cols="25%,75%", options="header"] +.Legal values of `PMM` WARL field +|=== +|Value|Description +|00|Pointer masking is disabled (PMLEN = 0) +|01|Reserved +|10|Pointer masking is enabled with PMLEN = XLEN - 57 (PMLEN = 7 on RV64) +|11|Pointer masking is enabled with PMLEN = XLEN - 48 (PMLEN = 16 on RV64) +|=== + +The Zicfilp extension adds the `LPE` field in `menvcfg`. When the `LPE` field is +set to 1 and S-mode is implemented, the Zicfilp extension is enabled in S-mode. +If `LPE` field is set to 1 and S-mode is not implemented, the Zicfilp extension +is enabled in U-mode. When the `LPE` field is 0, the Zicfilp extension is not +enabled in S-mode, and the following rules apply to S-mode. If the `LPE` field +is 0 and S-mode is not implemented, then the same rules apply to U-mode. + +* The hart does not update the `ELP` state; it remains as `NO_LP_EXPECTED`. +* The `LPAD` instruction operates as a no-op. + +The Zicfiss extension adds the `SSE` field to `menvcfg`. When the `SSE` field is +set to 1 the Zicfiss extension is activated in S-mode. When `SSE` field is 0, +the following rules apply to privilege modes that are less than M: + +* 32-bit Zicfiss instructions will revert to their behavior as defined by Zimop. +* 16-bit Zicfiss instructions will revert to their behavior as defined by Zcmop. +* The `pte.xwr=010b` encoding in VS/S-stage page tables becomes reserved. +* `SSAMOSWAP.W/D` raises an illegal-instruction exception. + +When `menvcfg.SSE` is 0, the `henvcfg.SSE` and `senvcfg.SSE` fields are +read-only zero. + +The Ssdbltrp extension adds the double-trap-enable (`DTE`) field in `menvcfg`. +When `menvcfg.DTE` is zero, the implementation behaves as though Ssdbltrp is not +implemented. When Ssdbltrp is not implemented `sstatus.SDT`, `vsstatus.SDT`, and +`henvcfg.DTE` bits are read-only zero. + +When XLEN=32, `menvcfgh` is a 32-bit read/write register +that aliases bits 63:32 of `menvcfg`. +The `menvcfgh` register does not exist when XLEN=64. + +If U-mode is not supported, then registers `menvcfg` and `menvcfgh` do +not exist. + +[[sec:mseccfg]] +==== Machine Security Configuration (`mseccfg`) Register + +`mseccfg` is a 64-bit read/write register, formatted as shown in <>, +that controls security features. It exists if any extension that adds a field +to `mseccfg` is implemented. Otherwise, it is reserved. + +[[mseccfg]] +.Machine security configuration (`mseccfg`) register. +include::images/wavedrom/mseccfg.edn[] + +The Zkr extension adds the `SSEED` and `USEED` fields to the `mseccfg` CSR to +control access to the `seed` CSR from modes less privileged than M. + +When `USEED` is 0, access to the `seed` CSR in U-mode raises an +illegal-instruction exception. When `USEED` is 1, read-write access to the +`seed` CSR from U-mode is allowed; all other types of accesses raise an +illegal-instruction exception. If Zkr or U-mode is not implemented, `USEED` is +read-only zero. + +When `SSEED` is 0, access to the `seed` CSR from S-/HS-mode raises an +illegal-instruction exception. When `SSEED` is 1, read-write access to the +`seed` CSR from S-/HS-mode is allowed; all other types of accesses raise an +illegal-instruction exception. If Zkr or S-mode is not implemented, `SSEED` is +read-only zero. + +When the H extension is also implemented, access to the `seed` CSR from an +HS-qualified instruction leads to a virtual-instruction exception in VS and +VU modes; all other types of accesses raise an illegal-instruction exception. + +.Entropy Source Access Control. + +[cols="1,1,1,7",options="header",] +|======================================================================= +|Mode | `SSEED` | `USEED` | Description +| M | - | - | The `seed` CSR is always available in machine + mode as normal (with a CSR read-write + instruction.) Attempted read without a write + raises an illegal-instruction exception + regardless of mode and access control bits. +| U | - | `0` | Any `seed` CSR access raises an + illegal-instruction exception. +| U | - | `1` | The `seed` CSR is accessible as normal. No + exception is raised for read-write. +| S/HS | `0` | - | Any `seed` CSR access raises an + illegal-instruction exception. +| S/HS | `1` | - | The `seed` CSR is accessible as normal. No + exception is raised for read-write. +| VS/VU | `0` | - | Any `seed` CSR access raises an + illegal-instruction exception. +| VS/VU | `1` | - | A read-write `seed` access raises a + virtual-instruction exception, while other access + conditions raise an illegal-instruction exception. +|======================================================================= + +The Smepmp extension adds the `RLB`, `MMWP`, and the `MML` fields in +`mseccfg`. + +When `mseccfg.RLB` (Rule Locking Bypass) a WARL field that provides a mechanism +to temporarily modify *Locked* PMP rules. When `mseccfg.RLB` is 1, locked PMP +rules may be removed or modified and locked PMP rules may be edited. When +`mseccfg.RLB` is 0 and `pmpcfg.L` is 1 in any rule or entry (including disabled +entries), then `mseccfg.RLB` remains 0 and any further modifications to +`mseccfg.RLB` are ignored until a *PMP reset*. + +[NOTE] +==== +This feature is intended to be used as a debug mechanism, or as a temporary +workaround during the boot process for simplifying software, and optimizing the +allocation of memory and PMP rules. Using this functionality under normal +operation, after the boot process is completed, should be avoided since it +weakens the protection of _M-mode-only_ rules. Vendors who don’t need this +functionality may hardwire this field to 0. + +The terminology used to specify the fields introduced by the Smepmp extension +is listed in <>. +==== + +The `mseccfg.MMWP` (Machine-Mode Allowlist Policy) is a WARL field. This field +changes the default PMP policy for Machine mode when accessing memory regions +that don't have a matching PMP rule. This is a sticky bit, meaning that once +set it cannot be unset until a *PMP reset*. When set it changes the default +PMP policy for M-mode when accessing memory regions that don’t have a matching +*PMP rule*, to *denied* instead of *ignored*. + +The `mseccfg.MML` (Machine Mode Lockdown) is a WARL field. The `MML` bit changes +the interpretation of the `pmpcfg.L` bit defined in <>. This is a +sticky bit, meaning that once set it cannot be unset until a *PMP reset*. When +`mseccfg.MML` is set the system's behavior changes in the following way: + +. The meaning of `pmpcfg.L` changes: Instead of marking a rule as *locked* and + *enforced* in all modes, it now marks a rule as *M-mode-only* when set and + *S/U-mode-only* when unset. The formerly reserved encoding of `pmpcfg.RW=01`, + and the encoding `pmpcfg.LRWX=1111`, now encode a *Shared-Region*. + + + + An _M-mode-only_ rule is *enforced* on Machine mode and *denied* in Supervisor + or User mode. It also remains *locked* so that any further modifications to + its associated configuration or address registers are ignored until a *PMP + reset*, unless `mseccfg.RLB` is set. + + + + An _S/U-mode-only_ rule is *enforced* on Supervisor and User modes and + *denied* on Machine mode. + + + + A _Shared-Region_ rule is *enforced* on all modes, with restrictions depending + on the `pmpcfg.L` and `pmpcfg.X` bits: + + + + + * A _Shared-Region_ rule where `pmpcfg.L` is not set can be used for sharing + data between M-mode and S/U-mode, so is not executable. M-mode has + read/write access to that region, and S/U-mode has read access if `pmpcfg.X` + is not set, or read/write access if `pmpcfg.X` is set. ++ + * A _Shared-Region_ rule where `pmpcfg.L` is set can be used for sharing code + between M-mode and S/U-mode, so is not writable. Both M-mode and S/U-mode + have execute access on the region, and M-mode also has read access if + `pmpcfg.X` is set. The rule remains *locked* so that any further + modifications to its associated configuration or address registers are + ignored until a *PMP reset*, unless `mseccfg.RLB` is set. ++ + * The encoding `pmpcfg.LRWX=1111` can be used for sharing data between M-mode + and S/U mode, where both modes only have read-only access to the region. The + rule remains *locked* so that any further modifications to its associated + configuration or address registers are ignored until a *PMP reset*, unless + `mseccfg.RLB` is set. + +. Adding a rule with executable privileges that either is *M-mode-only* or a + *locked* *Shared-Region* is not possible and such `pmpcfg` writes are + ignored, leaving `pmpcfg` unchanged. This restriction can be temporarily + lifted by setting `mseccfg.RLB` e.g. during the boot process. + +. Executing code with Machine mode privileges is only possible from memory + regions with a matching *M-mode-only* rule or a *locked* *Shared-Region* rule + with executable privileges. Executing code from a region without a matching + rule or with a matching _S/U-mode-only_ rule is *denied*. + +. If `mseccfg.MML` is not set, the combination of `pmpcfg.RW=01` remains + reserved for future standard use. + +If the Smmpm extension is implemented, the `PMM` field enables or disables +pointer masking (see <>) for M-mode according to the values in +<>. If Smmpm is not implemented, `PMM` is read-only zero. +The `PMM` field is read-only zero for RV32. + +[[mseccfg-pmm-values]] + +[%header, cols="25%,75%", options="header"] +.Legal values of `PMM` WARL field +|=== +|Value|Description +|00|Pointer masking is disabled (PMLEN = 0) +|01|Reserved +|10|Pointer masking is enabled with PMLEN = XLEN - 57 (PMLEN = 7 on RV64) +|11|Pointer masking is enabled with PMLEN = XLEN - 48 (PMLEN = 16 on RV64) +|=== + +[NOTE] +==== +`Smmpm` implementations need to satisfy max(largest supported virtual address +size, largest supported supervisor physical address size) <= (XLEN - PMLEN) +bits to avoid any masking logic on the TLB access path. +==== + +The Zicfilp extension adds the `MLPE` field in `mseccfg`. When `MLPE` field is +1, Zicfilp extension is enabled in M-mode. When the `MLPE` field is 0, the +Zicfilp extension is not enabled in M-mode and the following rules apply to +M-mode. + +* The hart does not update the `ELP` state; it remains as `NO_LP_EXPECTED`. +* The `LPAD` instruction operates as a no-op. + +When XLEN=32 only, `mseccfgh` is a 32-bit read/write register that +aliases bits 63:32 of `mseccfg`. +Register `mseccfgh` exists when XLEN=32 and `mseccfg` is implemented; +it does not exist when XLEN=64. + +=== Machine-Level Memory-Mapped Registers + +==== Machine Timer (`mtime` and `mtimecmp`) Registers + +Platforms provide a real-time counter, exposed as a memory-mapped +machine-mode read-write register, `mtime`. `mtime` must increment at +constant frequency, and the platform must provide a mechanism for +determining the period of an `mtime` tick. The `mtime` register will +wrap around if the count overflows. + +The `mtime` register has a 64-bit precision on all RV32 and RV64 +systems. Platforms provide a 64-bit memory-mapped machine-mode timer +compare register (`mtimecmp`). A machine timer interrupt becomes pending +whenever `mtime` contains a value greater than or equal to `mtimecmp`, +treating the values as unsigned integers. The interrupt remains posted +until `mtimecmp` becomes greater than `mtime` (typically as a result of +writing `mtimecmp`). The interrupt will only be taken if interrupts are +enabled and the MTIE bit is set in the `mie` register. + +.Machine time register (memory-mapped control register). +include::images/bytefield/mtime.edn[] + +.Machine time compare register (memory-mapped control register). +include::images/bytefield/mtimecmp.edn[] + +[NOTE] +==== +The timer facility is defined to use wall-clock time rather than a cycle +counter to support modern processors that run with a highly variable +clock frequency to save energy through dynamic voltage and frequency +scaling. + +Accurate real-time clocks (RTCs) are relatively expensive to provide +(requiring a crystal or MEMS oscillator) and have to run even when the +rest of system is powered down, and so there is usually only one in a +system located in a different frequency/voltage domain from the +processors. Hence, the RTC must be shared by all the harts in a system +and accesses to the RTC will potentially incur the penalty of a +voltage-level-shifter and clock-domain crossing. It is thus more natural +to expose `mtime` as a memory-mapped register than as a CSR. + +Lower privilege levels do not have their own `timecmp` registers. +Instead, machine-mode software can implement any number of virtual +timers on a hart by multiplexing the next timer interrupt into the +`mtimecmp` register. + +Simple fixed-frequency systems can use a single clock for both cycle +counting and wall-clock time. +==== + +If the result of the comparison between `mtime` and `mtimecmp` changes, it is +guaranteed to be reflected in MTIP eventually, but not necessarily +immediately. + +[NOTE] +==== +A spurious timer interrupt might occur if an interrupt handler +increments `mtimecmp` then immediately returns, because MTIP might not +yet have fallen in the interim. All software should be written to assume +this event is possible, but most software should assume this event is +extremely unlikely. It is almost always more performant to incur an +occasional spurious timer interrupt than to poll MTIP until it falls. +==== + +In RV32, memory-mapped writes to `mtimecmp` modify only one 32-bit part +of the register. The following code sequence sets a 64-bit `mtimecmp` +value without spuriously generating a timer interrupt due to the +intermediate value of the comparand: + +For RV64, naturally aligned 64-bit memory accesses to the `mtime` and +`mtimecmp` registers are additionally supported and are atomic. + +.Sample code for setting the 64-bit time comparand in RV32 assuming a little-endian memory system and that the registers live in a strongly ordered I/O region. Storing -1 to the low-order bits of `mtimecmp` prevents `mtimecmp` from temporarily becoming smaller than the lesser of the old and new values. +.... + # New comparand is in a1:a0. + li t0, -1 + la t1, mtimecmp + sw t0, 0(t1) # No smaller than old value. + sw a1, 4(t1) # No smaller than new value. + sw a0, 0(t1) # New value. +.... + + +The `time` CSR is a read-only shadow of the memory-mapped `mtime` register. +When XLEN=32, the `timeh` CSR is a read-only shadow of the upper 32 bits of the +memory-mapped `mtime` register, while `time` shadows only the lower 32 bits of +`mtime`. +When `mtime` changes, it is guaranteed to be reflected in `time` and `timeh` +eventually, but not necessarily immediately. + + +=== Machine-Mode Privileged Instructions + +==== Environment Call and Breakpoint + +include::images/wavedrom/mm-env-call.edn[] + +The ECALL instruction is used to make a request to the supporting +execution environment. When executed in U-mode, S-mode, or M-mode, it +generates an environment-call-from-U-mode exception, +environment-call-from-S-mode exception, or environment-call-from-M-mode +exception, respectively, and performs no other operation. + +[NOTE] +==== +ECALL generates a different exception for each originating privilege +mode so that environment call exceptions can be selectively delegated. A +typical use case for Unix-like operating systems is to delegate to +S-mode the environment-call-from-U-mode exception but not the others. +==== + +The EBREAK instruction is used by debuggers to cause control to be +transferred back to a debugging environment. +Unless overridden by an external debug environment, EBREAK raises +a breakpoint exception and performs no other operation. + +[NOTE] +==== +As described in the "C" Standard Extension for Compressed Instructions +in Volume I of this manual, the C.EBREAK instruction performs the same +operation as the EBREAK instruction. +==== + +ECALL and EBREAK cause the receiving privilege mode’s `epc` register to +be set to the address of the ECALL or EBREAK instruction itself, _not_ +the address of the following instruction. As ECALL and EBREAK cause +synchronous exceptions, they are not considered to retire, and should +not increment the `minstret` CSR. + +[[otherpriv]] +==== Trap-Return Instructions + +Instructions to return from trap are encoded under the PRIV minor +opcode. + +include::images/wavedrom/trap-return.edn[] + +To return after handling a trap, there are separate trap return +instructions per privilege level, MRET and SRET. MRET is always +provided. SRET must be provided if supervisor mode is supported, and +should raise an illegal-instruction exception otherwise. SRET should +also raise an illegal-instruction exception when TSR=1 in `mstatus`, as +described in <>. An __x__RET instruction +can be executed in privilege mode _x_ or higher, where executing a +lower-privilege __x__RET instruction will pop the relevant lower-privilege +interrupt enable and privilege mode stack. Attempting to execute an __x__RET +instruction in a mode less privileged than _x_ will raise an +illegal-instruction exception. In addition to manipulating +the privilege stack as described in <>, +__x__RET sets the `pc` to the value stored in the `__x__epc` register. + +If the A extension is supported, the __x__RET instruction is allowed to +clear any outstanding LR address reservation but is not required to. +Trap handlers should explicitly clear the reservation if required (e.g., +by using a dummy SC) before executing the __x__RET. + +[NOTE] +==== +If __x__RET instructions always cleared LR reservations, it would be +impossible to single-step through LR/SC sequences using a debugger. +==== + +[[wfi]] +==== Wait for Interrupt + +The Wait for Interrupt instruction (WFI) informs the +implementation that the current hart can be stalled until an interrupt +might need servicing. Execution of the WFI instruction can also be used +to inform the hardware platform that suitable interrupts should +preferentially be routed to this hart. WFI is available in all +privileged modes, and optionally available to U-mode. This instruction +may raise an illegal-instruction exception when TW=1 in `mstatus`, as +described in <>. + +include::images/wavedrom/wfi.edn[] + +If an enabled interrupt is present or later becomes present while the +hart is stalled, the interrupt trap will be taken on the following +instruction, i.e., execution resumes in the trap handler and `mepc` = +`pc` + 4. + +[NOTE] +==== +The following instruction takes the interrupt trap so that a simple +return from the trap handler will execute code after the WFI +instruction. +==== + +Implementations are permitted to resume execution for any reason, even if an +enabled interrupt has not become pending. Hence, a legal implementation is to +simply implement the WFI instruction as a NOP. + +[NOTE] +==== +If the implementation does not stall the hart on execution of the +instruction, then the interrupt will be taken on some instruction in the +idle loop containing the WFI, and on a simple return from the handler, +the idle loop will resume execution. +==== + +The WFI instruction can also be executed when interrupts are disabled. +The operation of WFI must be unaffected by the global interrupt bits in +`mstatus` (MIE and SIE) and the delegation register `mideleg` (i.e., +the hart must resume if a locally enabled interrupt becomes pending, +even if it has been delegated to a less-privileged mode), but should +honor the individual interrupt enables (e.g, MTIE) (i.e., +implementations should avoid resuming the hart if the interrupt is +pending but not individually enabled). WFI is also required to resume +execution for locally enabled interrupts pending at any privilege level, +regardless of the global interrupt enable at each privilege level. + +If the event that causes the hart to resume execution does not cause an +interrupt to be taken, execution will resume at `pc` + 4, and software +must determine what action to take, including looping back to repeat the +WFI if there was no actionable event. + +[NOTE] +==== +By allowing wake-up when interrupts are disabled, an alternate entry +point to an interrupt handler can be called that does not require saving +the current context, as the current context can be saved or discarded +before the WFI is executed. + +As implementations are free to implement WFI as a NOP, software must +explicitly check for any relevant pending but disabled interrupts in the +code following an WFI, and should loop back to the WFI if no suitable +interrupt was detected. The `mip` or `sip` registers can be interrogated +to determine the presence of any interrupt in machine or supervisor mode +respectively. + +The operation of WFI is unaffected by the delegation register settings. + +WFI is defined so that an implementation can trap into a higher +privilege mode, either immediately on encountering the WFI or after some +interval to initiate a machine-mode transition to a lower power state, +for example. + +*** + +The same "wait-for-event" template might be used for possible future +extensions that wait on memory locations changing, or message arrival. +==== + +==== Custom SYSTEM Instructions + +The subspace of the SYSTEM major opcode shown in <> is designated for custom use. It is recommended that these instructions use bits 29:28 to designate the +minimum required privilege mode, as do other SYSTEM instructions. + +[[customsys]] +.SYSTEM instruction encodings designated for custom use. +include::images/bytefield/cust-sys-instr.edn[] + +[[reset]] +=== Reset + +Upon reset, a hart’s privilege mode is set to M. The `mstatus` fields +MIE and MPRV are reset to 0. If little-endian memory accesses are +supported, the `mstatus`/`mstatush` field MBE is reset to 0. The `misa` +register is reset to enable the maximal set of supported extensions, +as described in <>. For +implementations with the "A" standard extension, there is no valid +load reservation. The `pc` is set to an implementation-defined reset +vector. The `mcause` register is set to a value indicating the cause of +the reset. Writable PMP registers’ A and L fields are set to 0, unless +the platform mandates a different reset value for some PMP registers’ A +and L fields. If the hypervisor extension is implemented, the +`hgatp`.MODE and `vsatp`.MODE fields are reset to 0. If the Smrnmi +extension is implemented, the `mnstatus`.NMIE field is reset to 0. No + *WARL* field contains an illegal value. If the Zicfilp extension is +implemented, the `mseccfg`.MLPE field is reset to 0. All other hart +state is UNSPECIFIED. + +The `MML`, `MMWP`, and `RLB` fields of the `mseccfg` register are set to 0, +unless the platform mandates a different reset value. + +The `mcause` values after reset have implementation-specific +interpretation, but the value 0 should be returned on implementations +that do not distinguish different reset conditions. Implementations that +distinguish different reset conditions should only use 0 to indicate the +most complete reset. + +The `USEED` and `SSEED` fields of the `mseccfg` CSR must have defined +reset values. The system must not allow them to be in an undefined state +after reset. + +[NOTE] +==== +Some designs may have multiple causes of reset (e.g., power-on reset, +external hard reset, brownout detected, watchdog timer elapse, +sleep-mode wake-up), which machine-mode software and debuggers may wish +to distinguish. + +`mcause` reset values may alias `mcause` values following synchronous +exceptions. There should be no ambiguity in this overlap, since on reset +the `pc` is typically set to a different value than on other traps. +==== + +[[nmi]] +=== Non-Maskable Interrupts + +Non-maskable interrupts (NMIs) are only used for hardware error +conditions, and cause an immediate jump to an implementation-defined NMI +vector running in M-mode regardless of the state of a hart’s interrupt +enable bits. The `mepc` register is written with the virtual address of +the instruction that was interrupted, and `mcause` is set to a value +indicating the source of the NMI. The NMI can thus overwrite state in an +active machine-mode interrupt handler. + +The values written to `mcause` on an NMI are implementation-defined. The +high Interrupt bit of `mcause` should be set to indicate that this was +an interrupt. An Exception Code of 0 is reserved to mean "unknown +cause" and implementations that do not distinguish sources of NMIs via +the `mcause` register should return 0 in the Exception Code. + +Unlike resets, NMIs do not reset processor state, enabling diagnosis, +reporting, and possible containment of the hardware error. + +[[pma]] +=== Physical Memory Attributes + +The physical memory map for a complete system includes various address +ranges, some corresponding to memory regions and some to memory-mapped +control registers, portions of which might not be accessible. Some +memory regions might not support reads, writes, or execution; some might +not support subword or subblock accesses; some might not support atomic +operations; and some might not support cache coherence or might have +different memory models. Similarly, memory-mapped control registers vary +in their supported access widths, support for atomic operations, and +whether read and write accesses have associated side effects. In RISC-V +systems, these properties and capabilities of each region of the +machine's physical address space are termed _physical memory attributes_ +(PMAs). This section describes RISC-V PMA terminology and how RISC-V +systems implement and check PMAs. + +PMAs are inherent properties of the underlying hardware and rarely +change during system operation. Unlike physical memory protection values +described in <>, PMAs do not vary by execution +context. The PMAs of some memory regions are fixed at chip design +time—for example, for an on-chip ROM. Others are fixed at board design +time, depending, for example, on which other chips are connected to +off-chip buses. Off-chip buses might also support devices that could be +changed on every power cycle (cold pluggable) or dynamically while the +system is running (hot pluggable). Some devices might be configurable at +run time to support different uses that imply different PMAs—for +example, an on-chip scratchpad RAM might be cached privately by one core +in one end-application, or accessed as a shared non-cached memory in +another end-application. + +Most systems will require that at least some PMAs are dynamically +checked in hardware later in the execution pipeline after the physical +address is known, as some operations will not be supported at all +physical memory addresses, and some operations require knowing the +current setting of a configurable PMA attribute. While many other +architectures specify some PMAs in the virtual memory page tables and +use the TLB to inform the pipeline of these properties, this approach +injects platform-specific information into a virtualized layer and can +cause system errors unless attributes are correctly initialized in each +page-table entry for each physical memory region. In addition, the +available page sizes might not be optimal for specifying attributes in +the physical memory space, leading to address-space fragmentation and +inefficient use of expensive TLB entries. + +For RISC-V, we separate out specification and checking of PMAs into a +separate hardware structure, the _PMA checker_. In many cases, the +attributes are known at system design time for each physical address +region, and can be hardwired into the PMA checker. Where the attributes +are run-time configurable, platform-specific memory-mapped control +registers can be provided to specify these attributes at a granularity +appropriate to each region on the platform (e.g., for an on-chip SRAM +that can be flexibly divided between cacheable and uncacheable uses). +PMAs are checked for any access to physical memory, including accesses +that have undergone virtual to physical memory translation. To aid in +system debugging, we strongly recommend that, where possible, RISC-V +processors precisely trap physical memory accesses that fail PMA checks. +Precisely trapped PMA violations manifest as instruction, load, or store +access-fault exceptions, distinct from virtual-memory page-fault +exceptions. Precise PMA traps might not always be possible, for example, +when probing a legacy bus architecture that uses access failures as part +of the discovery mechanism. In this case, error responses from +peripheral devices will be reported as imprecise bus-error interrupts. + +PMAs must also be readable by software to correctly access certain +devices or to correctly configure other hardware components that access +memory, such as DMA engines. As PMAs are tightly tied to a given +physical platform’s organization, many details are inherently +platform-specific, as is the means by which software can learn the PMA +values for a platform. Some devices, particularly legacy buses, do not +support discovery of PMAs and so will give error responses or time out +if an unsupported access is attempted. Typically, platform-specific +machine-mode code will extract PMAs and ultimately present this +information to higher-level less-privileged software using some standard +representation. + +Where platforms support dynamic reconfiguration of PMAs, an interface +will be provided to set the attributes by passing requests to a +machine-mode driver that can correctly reconfigure the platform. For +example, switching cacheability attributes on some memory regions might +involve platform-specific operations, such as cache flushes, that are +available only to machine-mode. + +==== Main Memory versus I/O Regions + +The most important characterization of a given memory address range is +whether it holds regular main memory or I/O devices. +Regular main memory is required to have a number of properties, +specified below, whereas I/O devices can have a much broader range of +attributes. Memory regions that do not fit into regular main memory, for +example, device scratchpad RAMs, are categorized as I/O regions. + +NOTE: What previous versions of this specification termed _vacant_ regions are +no longer a distinct category; they are now described as I/O regions that are +not accessible (i.e. lacking read, write, and execute permissions). +Main memory regions that are not accessible are also allowed. + +==== Supported Access Type PMAs + +Access types specify which access widths, from 8-bit byte to long +multi-word burst, are supported, and also whether misaligned accesses +are supported for each access width. + +[NOTE] +==== +Although software running on a RISC-V hart cannot directly generate +bursts to memory, software might have to program DMA engines to access +I/O devices and might therefore need to know which access sizes are +supported. +==== + +Main memory regions always support read and write of all access widths +required by the attached devices, and can specify whether instruction +fetch is supported. + +[NOTE] +==== +Some platforms might mandate that all of main memory support instruction +fetch. Other platforms might prohibit instruction fetch from some main +memory regions. + +*** + +In some cases, the design of a processor or device accessing main memory +might support other widths, but must be able to function with the types +supported by the main memory. +==== + +I/O regions can specify which combinations of read, write, or execute +accesses to which data widths are supported. + +For systems with page-based virtual memory, I/O and memory regions can +specify which combinations of hardware page-table reads and hardware +page-table writes are supported. + +[NOTE] +==== +Unix-like operating systems generally require that all of cacheable main +memory supports page-table walks. +==== + +==== Atomicity PMAs + +Atomicity PMAs describes which atomic instructions are supported in this +address region. Support for atomic instructions is divided into two +categories: _LR/SC_ and _AMOs_. + +[NOTE] +==== +Some platforms might mandate that all of cacheable main memory support +all atomic operations required by the attached processors. +==== + +===== AMO PMA + +Within AMOs, there are four levels of support: _AMONone_, _AMOSwap_, +_AMOLogical_, and _AMOArithmetic_. AMONone indicates that no AMO +operations are supported. AMOSwap indicates that only `amoswap` +instructions are supported in this address range. AMOLogical indicates +that swap instructions plus all the logical AMOs (`amoand`, `amoor`, +`amoxor`) are supported. AMOArithmetic indicates that all RISC-V AMOs defined by +the A extension are supported. For each level of support, naturally aligned AMOs of a +given width are supported if the underlying memory region supports reads +and writes of that width. Main memory and I/O regions may only support a +subset or none of the processor-supported atomic operations. + +.Classes of AMOs supported by I/O regions. +[i%autowidth,float="center",align="center",cols="<,<",options="header"] +|=== +|AMO Class |Supported Operations +|AMONone + +AMOSwap + +AMOLogical + +AMOArithmetic +|_None_ + +`amoswap` + +above + `amoand`, `amoor`, `amoxor` + +above + `amoadd`, `amomin`, `amomax`, `amominu`, +`amomaxu` +|=== + +[NOTE] +==== +We recommend providing at least AMOLogical support for I/O regions where +possible. +==== + +The Zacas extension defines three additional levels of support: AMOCASW, +AMOCASD, and AMOCASQ. + +AMOCASW indicates that in addition to instructions indicated by AMOArithmetic +level support, the `AMOCAS.W` instruction is supported. AMOCASD indicates that +in addition to instructions indicated by AMOCASW level support, the `AMOCAS.D` +instruction is supported. AMOCASQ indicates that in addition to instructions +indicated by AMOCASD level support, the `AMOCAS.Q` instruction is supported. + +[NOTE] +==== +`AMOCASW/D/Q` require AMOArithmetic level support as the `AMOCAS.W/D/Q` +instructions require ability to perform an arithmetic comparison and a swap +operation. +==== + +The AMOs specified by the Zabha extension require the same level of support as +the corresponding instructions in the A standard extension or the Zacas +extension. + +===== Reservability PMA + +For _LR/SC_, there are three levels of support indicating combinations +of the reservability and eventuality properties: _RsrvNone_, +_RsrvNonEventual_, and _RsrvEventual_. RsrvNone indicates that no LR/SC +operations are supported (the location is non-reservable). +RsrvNonEventual indicates that the operations are supported (the +location is reservable), but without the eventual success guarantee +described in the unprivileged ISA specification. RsrvEventual indicates +that the operations are supported and provide the eventual success +guarantee. + +[NOTE] +==== +We recommend providing RsrvEventual support for main memory regions +where possible. Most I/O regions will not support LR/SC accesses, as +these are most conveniently built on top of a cache-coherence scheme, +but some may support RsrvNonEventual or RsrvEventual. + +*** + +When LR/SC is used for memory locations marked RsrvNonEventual, software +should provide alternative fall-back mechanisms used when lack of +progress is detected. +==== + +==== Misaligned Atomicity Granule PMA + +The misaligned atomicity granule PMA provides constrained support for +misaligned AMOs. +This PMA, if present, specifies the size of a _misaligned atomicity granule_, +a naturally aligned power-of-two number of bytes. +Specific supported values for this PMA are represented by MAG__NN__, e.g., +MAG16 indicates the misaligned atomicity granule is at least 16 bytes. + +The misaligned atomicity granule PMA applies only to AMOs, loads and stores +defined in the base ISAs, and loads and stores of no more than XLEN bits +defined in the F, D, and Q extensions, and compressed encodings thereof. +For an instruction in that set, if all accessed bytes lie within the same +misaligned atomicity granule, the instruction will not raise an exception for +reasons of address alignment, and the instruction will give rise to only one +memory operation for the purposes of RVWMO--i.e., it will execute atomically. + +If a misaligned AMO accesses a region that does not specify a misaligned +atomicity granule PMA, or if not all accessed bytes lie within the same +misaligned atomicity granule, then an exception is raised. +For regular loads and stores that access such a region or for which not all +accessed bytes lie within the same atomicity granule, then either an exception +is raised, or the access proceeds but is not guaranteed to be atomic. +Implementations may raise access-fault exceptions instead of +address-misaligned exceptions for some misaligned accesses, indicating the +instruction should not be emulated by a trap handler. + +NOTE: LR/SC instructions are unaffected by this PMA and so always raise an +exception when misaligned. Vector memory accesses are also unaffected, so +might execute non-atomically even when contained within a misaligned atomicity +granule. Implicit accesses are similarly unaffected by this PMA. + +==== Memory-Ordering PMAs + +Regions of the address space are classified as either _main memory_ or +_I/O_ for the purposes of ordering by the FENCE instruction and +atomic-instruction ordering bits. + +Accesses by one hart to main memory regions are observable not only by +other harts but also by other devices with the capability to initiate +requests in the main memory system (e.g., DMA engines). Coherent main +memory regions always have either the RVWMO or RVTSO memory model. +Incoherent main memory regions have an implementation-defined memory +model. + +Accesses by one hart to an I/O region are observable not only by other +harts and bus mastering devices but also by the targeted I/O devices, +and I/O regions may be accessed with either _relaxed_ or _strong_ +ordering. Accesses to an I/O region with relaxed ordering are generally +observed by other harts and bus mastering devices in a manner similar to +the ordering of accesses to an RVWMO memory region, as discussed in +the I/O Ordering section in the RVWMO Explanatory Material appendix +of Volume I of this specification. +By contrast, accesses +to an I/O region with strong ordering are generally observed by other +harts and bus mastering devices in program order. + +Each strongly ordered I/O region specifies a numbered ordering channel, +which is a mechanism by which ordering guarantees can be provided +between different I/O regions. Channel 0 is used to indicate +point-to-point strong ordering only, where only accesses by the hart to +the single associated I/O region are strongly ordered. + +Channel 1 is used to provide global strong ordering across all I/O +regions. Any accesses by a hart to any I/O region associated with +channel 1 can only be observed to have occurred in program order by all +other harts and I/O devices, including relative to accesses made by that +hart to relaxed I/O regions or strongly ordered I/O regions with +different channel numbers. In other words, any access to a region in +channel 1 is equivalent to executing a `fence io,io` instruction before +and after the instruction. + +Other larger channel numbers provide program ordering to accesses by +that hart across any regions with the same channel number. + +Systems might support dynamic configuration of ordering properties on +each memory region. + +[NOTE] +==== +Strong ordering can be used to improve compatibility with legacy device +driver code, or to enable increased performance compared to insertion of +explicit ordering instructions when the implementation is known to not +reorder accesses. + +Local strong ordering (channel 0) is the default form of strong ordering +as it is often straightforward to provide if there is only a single +in-order communication path between the hart and the I/O device. + +Generally, different strongly ordered I/O regions can share the same +ordering channel without additional ordering hardware if they share the +same interconnect path and the path does not reorder requests. +==== + +==== Coherence and Cacheability PMAs + +Coherence is a property defined for a single physical address, and +indicates that writes to that address by one agent will eventually be +made visible to other coherent agents in the system. Coherence is not to be +confused with the memory consistency model of a system, which defines +what values a memory read can return given the previous history of reads +and writes to the entire memory system. In RISC-V platforms, the use of +hardware-incoherent regions is discouraged due to software complexity, +performance, and energy impacts. + +The cacheability of a memory region should not affect the software view +of the region except for differences reflected in other PMAs, such as +main memory versus I/O classification, memory ordering, supported +accesses and atomic operations, and coherence. For this reason, we treat +cacheability as a platform-level setting managed by machine-mode +software only. + +Where a platform supports configurable cacheability settings for a +memory region, a platform-specific machine-mode routine will change the +settings and flush caches if necessary, so the system is only incoherent +during the transition between cacheability settings. This transitory +state should not be visible to lower privilege levels. + +[NOTE] +==== +Coherence is straightforward to provide for a shared memory region that +is not cached by any agent. The PMA for such a region would simply +indicate it should not be cached in a private or shared cache. + +Coherence is also straightforward for read-only regions, which can be +safely cached by multiple agents without requiring a cache-coherence +scheme. The PMA for this region would indicate that it can be cached, +but that writes are not supported. + +Some read-write regions might only be accessed by a single agent, in +which case they can be cached privately by that agent without requiring +a coherence scheme. The PMA for such regions would indicate they can be +cached. The data can also be cached in a shared cache, as other agents +should not access the region. + +If an agent can cache a read-write region that is accessible by other +agents, whether caching or non-caching, a cache-coherence scheme is +required to avoid use of stale values. In regions lacking hardware cache +coherence (hardware-incoherent regions), cache coherence can be +implemented entirely in software, but software coherence schemes are +notoriously difficult to implement correctly and often have severe +performance impacts due to the need for conservative software-directed +cache-flushing. Hardware cache-coherence schemes require more complex +hardware and can impact performance due to the cache-coherence probes, +but are otherwise invisible to software. + +For each hardware cache-coherent region, the PMA would indicate that the +region is coherent and which hardware coherence controller to use if the +system has multiple coherence controllers. For some systems, the +coherence controller might be an outer-level shared cache, which might +itself access further outer-level cache-coherence controllers +hierarchically. + +Most memory regions within a platform will be coherent to software, +because they will be fixed as either uncached, read-only, hardware +cache-coherent, or only accessed by one agent. +==== + +If a PMA indicates non-cacheability, then accesses to that region must +be satisfied by the memory itself, not by any caches. + +[NOTE] +==== +For implementations with a cacheability-control mechanism, the situation +may arise that a program uncacheably accesses a memory location that is +currently cache-resident. In this situation, the cached copy must be +ignored. This constraint is necessary to prevent more-privileged modes’ +speculative cache refills from affecting the behavior of less-privileged +modes’ uncacheable accesses. +==== + +==== Idempotency PMAs + +Idempotency PMAs describe whether reads and writes to an address region +are idempotent. Main memory regions are assumed to be idempotent. For +I/O regions, idempotency on reads and writes can be specified separately +(e.g., reads are idempotent but writes are not). If accesses are +non-idempotent, i.e., there is potentially a side effect on any read or +write access, then speculative or redundant accesses must be avoided. + +For the purposes of defining the idempotency PMAs, changes in observed +memory ordering created by redundant accesses are not considered a side +effect. + +[NOTE] +==== +While hardware should always be designed to avoid speculative or +redundant accesses to memory regions marked as non-idempotent, it is +also necessary to ensure software or compiler optimizations do not +generate spurious accesses to non-idempotent memory regions. + +Non-idempotent regions might not support misaligned accesses. Misaligned +accesses to such regions should raise access-fault exceptions rather +than address-misaligned exceptions, indicating that software should not +emulate the misaligned access using multiple smaller accesses, which +could cause unexpected side effects. +==== + +For non-idempotent regions, implicit reads and writes must not be +performed early or speculatively, with the following exceptions. When a +non-speculative implicit read is performed, an implementation is +permitted to additionally read any of the bytes within a naturally +aligned power-of-2 region containing the address of the non-speculative +implicit read. Furthermore, when a non-speculative instruction fetch is +performed, an implementation is permitted to additionally read any of +the bytes within the _next_ naturally aligned power-of-2 region of the +same size (with the address of the region taken modulo +2^XLEN^). The results of these additional reads +may be used to satisfy subsequent early or speculative implicit reads. +The size of these naturally aligned power-of-2 regions is +implementation-defined, but, for systems with page-based virtual memory, +must not exceed the smallest supported page size. + +[[pmp]] +=== Physical Memory Protection + +To support secure processing and contain faults, it is desirable to +limit the physical addresses accessible by software running on a hart. +An optional physical memory protection (PMP) unit provides per-hart +machine-mode control registers to allow physical memory access +privileges (read, write, execute) to be specified for each physical +memory region. The PMP values are checked in parallel with the PMA +checks described in <>. + +The granularity of PMP access control settings are platform-specific, +but the standard PMP encoding supports regions as small as four bytes. +Certain regions’ privileges can be hardwired—for example, some regions +might only ever be visible in machine mode but in no lower-privilege +layers. + +[NOTE] +==== +Platforms vary widely in demands for physical memory protection, and +some platforms may provide other PMP structures in addition to or +instead of the scheme described in this section. +==== + +PMP checks are applied to all accesses whose effective privilege mode is +S or U, including instruction fetches and data accesses in S and U mode, +and data accesses in M-mode when the MPRV bit in `mstatus` is set and +the MPP field in `mstatus` contains S or U. PMP checks are also applied +to page-table accesses for virtual-address translation, for which the +effective privilege mode is S. Optionally, PMP checks may additionally +apply to M-mode accesses, in which case the PMP registers themselves are +locked, so that even M-mode software cannot change them until the hart +is reset. In effect, PMP can _grant_ permissions to S and U modes, which +by default have none, and can _revoke_ permissions from M-mode, which by +default has full permissions. + +PMP violations are always trapped precisely at the processor. diff --git a/param_extraction/chunks/chunk_019.txt.license b/param_extraction/chunks/chunk_019.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_019.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_020.txt b/param_extraction/chunks/chunk_020.txt new file mode 100644 index 0000000000..b35767d3cf --- /dev/null +++ b/param_extraction/chunks/chunk_020.txt @@ -0,0 +1,338 @@ +# Chunk: chunk_020 +# Source: machine.adoc +# Lines: 3305-3629 (of 3629) +# Content starts: line 3335 +# Line count: 325 +# Overlap from line: 3305 +# Sections: 5 +# ==== Physical Memory Protection CSRs +# ===== Address Matching +# ===== Locking and Privilege Mode +# ===== Priority and Matching Logic +# ==== Physical Memory Protection and Paging +# +memory region. The PMP values are checked in parallel with the PMA +checks described in <>. + +The granularity of PMP access control settings are platform-specific, +but the standard PMP encoding supports regions as small as four bytes. +Certain regions’ privileges can be hardwired—for example, some regions +might only ever be visible in machine mode but in no lower-privilege +layers. + +[NOTE] +==== +Platforms vary widely in demands for physical memory protection, and +some platforms may provide other PMP structures in addition to or +instead of the scheme described in this section. +==== + +PMP checks are applied to all accesses whose effective privilege mode is +S or U, including instruction fetches and data accesses in S and U mode, +and data accesses in M-mode when the MPRV bit in `mstatus` is set and +the MPP field in `mstatus` contains S or U. PMP checks are also applied +to page-table accesses for virtual-address translation, for which the +effective privilege mode is S. Optionally, PMP checks may additionally +apply to M-mode accesses, in which case the PMP registers themselves are +locked, so that even M-mode software cannot change them until the hart +is reset. In effect, PMP can _grant_ permissions to S and U modes, which +by default have none, and can _revoke_ permissions from M-mode, which by +default has full permissions. + +PMP violations are always trapped precisely at the processor. + +==== Physical Memory Protection CSRs + +PMP entries are described by an 8-bit configuration register and one +MXLEN-bit address register. Some PMP settings additionally use the +address register associated with the preceding PMP entry. Up to 64 PMP +entries are supported. Implementations may implement zero, 16, or 64 PMP +entries; the lowest-numbered PMP entries must be implemented first. All +PMP CSR fields are *WARL* and may be read-only zero. PMP CSRs are only +accessible to M-mode. + +The PMP configuration registers are densely packed into CSRs to minimize +context-switch time. For RV32, sixteen CSRs, `pmpcfg0`–`pmpcfg15`, hold +the configurations `pmp0cfg`–`pmp63cfg` for the 64 PMP entries, as shown +in <>. For RV64, eight +even-numbered CSRs, `pmpcfg0`, `pmpcfg2`, …, `pmpcfg14`, hold the +configurations for the 64 PMP entries, as shown in +<>. For RV64, the odd-numbered +configuration registers, `pmpcfg1`, `pmpcfg3`, …, `pmpcfg15`, are +illegal. + +[NOTE] +==== +RV64 harts use `pmpcfg2`, rather than `pmpcfg1`, to hold +configurations for PMP entries 8-15. This design reduces the cost of +supporting multiple MXLEN values, since the configurations for PMP +entries 8-11 appear in `pmpcfg2`[31:0] for both RV32 and RV64. +==== + +[[pmpcfg-rv32]] +.RV32 PMP configuration CSR layout. +include::images/bytefield/pmp-rv32.edn[] + +[[pmpcfg-rv64]] +.RV64 PMP configuration CSR layout. +include::images/bytefield/pmp-rv64.edn[] + + +The PMP address registers are CSRs named `pmpaddr0`-`pmpaddr63`. Each +PMP address register encodes bits 33-2 of a 34-bit physical address for +RV32, as shown in <>. For RV64, +each PMP address register encodes bits 55-2 of a 56-bit physical +address, as shown in <>. Not all +physical address bits may be implemented, and so the `pmpaddr` registers +are *WARL*. + +[NOTE] +==== +The Sv32 page-based virtual-memory scheme described in +<> supports 34-bit physical addresses for +RV32, so the PMP scheme must support addresses wider than XLEN for RV32. +The Sv39 and Sv48 page-based virtual-memory schemes described in +<> and <> support a +56-bit physical address space, so the RV64 PMP address registers impose +the same limit. +==== + +[[pmpaddr-rv32]] +.PMP address register format, RV32. +include::images/bytefield/pmpaddr-rv32.edn[] + +[[pmpaddr-rv64]] +.PMP address register format, RV64. +include::images/bytefield/pmpaddr-rv64.edn[] + +<> shows the layout of a PMP configuration +register. The R, W, and X bits, when set, indicate that the PMP entry +permits read, write, and instruction execution, respectively. When one +of these bits is clear, the corresponding access type is denied. The R, +W, and X fields form a collective *WARL* field for which the combinations with R=0 and W=1 are reserved. The remaining two fields, A and L, are described in the following sections. + +[[pmpcfg]] +.PMP configuration register format. +include::images/bytefield/pmpcfg.edn[] + + +Attempting to fetch an instruction from a PMP region that does not have +execute permissions raises an instruction access-fault exception. +Attempting to execute a load, load-reserved, or cache-block management instruction which accesses +a physical address within a PMP region without read permissions raises a +load access-fault exception. Attempting to execute a store, +store-conditional, AMO, or cache-block zero instruction which accesses a physical address +within a PMP region without write permissions raises a store +access-fault exception. + +===== Address Matching + +The A field in a PMP entry's configuration register encodes the +address-matching mode of the associated PMP address register. The +encoding of this field is shown in <>. +When A=0, this PMP entry is disabled and matches no addresses. Two other +address-matching modes are supported: naturally aligned power-of-2 +regions (NAPOT), including the special case of naturally aligned +four-byte regions (NA4); and the top boundary of an arbitrary range +(TOR). These modes support four-byte granularity. + +[[pmpcfg-a]] +.Encoding of A field in PMP configuration registers. +[%autowidth,float="center",align="center",cols=">,^,<",options="header"] +|=== +|A |Name |Description +|0 + +1 + +2 + +3 +|OFF + +TOR + +NA4 + +NAPOT +|Null region (disabled) + +Top of range + +Naturally aligned four-byte region + +Naturally aligned power-of-two region, {ge}8 +bytes +|=== + +NAPOT ranges make use of the low-order bits of the associated address +register to encode the size of the range, as shown in +<>. + +[[pmpcfg-napot]] +.`NAPOT` range encoding in PMP address and configuration registers. +[%autowidth,float="center",align="center",cols="^,^,<",options="header"] +|=== +|`pmpaddr` |`pmpcfg`.A |Match type and size +|`yyyy...yyyy` + +`yyyy...yyy0` + +`yyyy...yy01` + +`yyyy...y011` + +... + +`yy01...1111` + +`y011...1111` + +`0111...1111` + +`1111...1111` +|NA4 + +NAPOT + +NAPOT + +NAPOT + +... + +NAPOT + +NAPOT + +NAPOT + +NAPOT +|4-byte NAPOT range + +8-byte NAPOT range + +16-byte NAPOT range + +32-byte NAPOT range + +… + +2^XLEN^-byte NAPOT range + +2^XLEN+1^-byte NAPOT range + +2^XLEN+2^-byte NAPOT range + +2^XLEN+3^-byte NAPOT range +|=== + +If TOR is selected, the associated address register forms the top of the +address range, and the preceding PMP address register forms the bottom +of the address range. If PMP entry __i__'s A field is set to +TOR, the entry matches any address _y_ such that `pmpaddr~i-1~`{le}__y__<``pmpaddr~i~`` (irrespective of the value of `pmpcfg~i-1~`). If PMP entry 0's A field is set to TOR, zero is used for the lower bound, and so it matches +any address `y>. When paging is enabled, +instructions that access virtual memory may result in multiple +physical-memory accesses, including implicit references to the page +tables. The PMP checks apply to all of these accesses. The effective +privilege mode for implicit page-table accesses is S. + +Implementations with virtual memory are permitted to perform address +translations speculatively and earlier than required by an explicit +memory access, and are permitted to cache them in address translation +cache structures—including possibly caching the identity mappings from +effective address to physical address used in Bare translation modes and +M-mode. The PMP settings for the resulting physical address may be +checked (and possibly cached) at any point between the address +translation and the explicit memory access. Hence, when the PMP settings +are modified, M-mode software must synchronize the PMP settings with the +virtual memory system and any PMP or address-translation caches. This is +accomplished by executing an SFENCE.VMA instruction with _rs1_=`x0` and +_rs2_=`x0`, after the PMP CSRs are written. +See <> for additional synchronization requirements when the +hypervisor extension is implemented. + +If page-based virtual memory is not implemented, memory accesses check +the PMP settings synchronously, so no SFENCE.VMA is needed. diff --git a/param_extraction/chunks/chunk_020.txt.license b/param_extraction/chunks/chunk_020.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_020.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_021.txt b/param_extraction/chunks/chunk_021.txt new file mode 100644 index 0000000000..cc273f4459 --- /dev/null +++ b/param_extraction/chunks/chunk_021.txt @@ -0,0 +1,247 @@ +# Chunk: chunk_021 +# Source: mm-alloy.adoc +# Lines: 1-239 (of 239) +# Content starts: line 1 +# Line count: 239 +# Sections: 1 +# == Formal Axiomatic Specification in Alloy +# +[[sec:alloy]] +== Formal Axiomatic Specification in Alloy + +We present a formal specification of the RVWMO memory model in Alloy +(https://alloytools.org/). This model is available online at +https://github.com/daniellustig/riscv-memory-model. + +The online material also contains some litmus tests and some examples of +how Alloy can be used to model check some of the mappings in +Section #sec:memory:porting[[sec:memory:porting]]. + +` ` + +.... +//////////////////////////////////////////////////////////////////////////////// +// =RVWMO PPO= + +// Preserved Program Order +fun ppo : Event->Event { + // same-address ordering + po_loc :> Store + + rdw + + (AMO + StoreConditional) <: rfi + + // explicit synchronization + + ppo_fence + + Acquire <: ^po :> MemoryEvent + + MemoryEvent <: ^po :> Release + + RCsc <: ^po :> RCsc + + pair + + // syntactic dependencies + + addrdep + + datadep + + ctrldep :> Store + + // pipeline dependencies + + (addrdep+datadep).rfi + + addrdep.^po :> Store +} + +// the global memory order respects preserved program order +fact { ppo in ^gmo } +.... + +` ` + +.... +//////////////////////////////////////////////////////////////////////////////// +// =RVWMO axioms= + +// Load Value Axiom +fun candidates[r: MemoryEvent] : set MemoryEvent { + (r.~^gmo & Store & same_addr[r]) // writes preceding r in gmo + + (r.^~po & Store & same_addr[r]) // writes preceding r in po +} + +fun latest_among[s: set Event] : Event { s - s.~^gmo } + +pred LoadValue { + all w: Store | all r: Load | + w->r in rf <=> w = latest_among[candidates[r]] +} + +// Atomicity Axiom +pred Atomicity { + all r: Store.~pair | // starting from the lr, + no x: Store & same_addr[r] | // there is no store x to the same addr + x not in same_hart[r] // such that x is from a different hart, + and x in r.~rf.^gmo // x follows (the store r reads from) in gmo, + and r.pair in x.^gmo // and r follows x in gmo +} + +// Progress Axiom implicit: Alloy only considers finite executions + +pred RISCV_mm { LoadValue and Atomicity /* and Progress */ } +.... + +` ` + +.... +//////////////////////////////////////////////////////////////////////////////// +// Basic model of memory + +sig Hart { // hardware thread + start : one Event +} +sig Address {} +abstract sig Event { + po: lone Event // program order +} + +abstract sig MemoryEvent extends Event { + address: one Address, + acquireRCpc: lone MemoryEvent, + acquireRCsc: lone MemoryEvent, + releaseRCpc: lone MemoryEvent, + releaseRCsc: lone MemoryEvent, + addrdep: set MemoryEvent, + ctrldep: set Event, + datadep: set MemoryEvent, + gmo: set MemoryEvent, // global memory order + rf: set MemoryEvent +} +sig LoadNormal extends MemoryEvent {} // l{b|h|w|d} +sig LoadReserve extends MemoryEvent { // lr + pair: lone StoreConditional +} +sig StoreNormal extends MemoryEvent {} // s{b|h|w|d} +// all StoreConditionals in the model are assumed to be successful +sig StoreConditional extends MemoryEvent {} // sc +sig AMO extends MemoryEvent {} // amo +sig NOP extends Event {} + +fun Load : Event { LoadNormal + LoadReserve + AMO } +fun Store : Event { StoreNormal + StoreConditional + AMO } + +sig Fence extends Event { + pr: lone Fence, // opcode bit + pw: lone Fence, // opcode bit + sr: lone Fence, // opcode bit + sw: lone Fence // opcode bit +} +sig FenceTSO extends Fence {} + +/* Alloy encoding detail: opcode bits are either set (encoded, e.g., + * as f.pr in iden) or unset (f.pr not in iden). The bits cannot be used for + * anything else */ +fact { pr + pw + sr + sw in iden } +// likewise for ordering annotations +fact { acquireRCpc + acquireRCsc + releaseRCpc + releaseRCsc in iden } +// don't try to encode FenceTSO via pr/pw/sr/sw; just use it as-is +fact { no FenceTSO.(pr + pw + sr + sw) } +.... + +` ` + +.... +//////////////////////////////////////////////////////////////////////////////// +// =Basic model rules= + +// Ordering annotation groups +fun Acquire : MemoryEvent { MemoryEvent.acquireRCpc + MemoryEvent.acquireRCsc } +fun Release : MemoryEvent { MemoryEvent.releaseRCpc + MemoryEvent.releaseRCsc } +fun RCpc : MemoryEvent { MemoryEvent.acquireRCpc + MemoryEvent.releaseRCpc } +fun RCsc : MemoryEvent { MemoryEvent.acquireRCsc + MemoryEvent.releaseRCsc } + +// There is no such thing as store-acquire or load-release, unless it's both +fact { Load & Release in Acquire } +fact { Store & Acquire in Release } + +// FENCE PPO +fun FencePRSR : Fence { Fence.(pr & sr) } +fun FencePRSW : Fence { Fence.(pr & sw) } +fun FencePWSR : Fence { Fence.(pw & sr) } +fun FencePWSW : Fence { Fence.(pw & sw) } + +fun ppo_fence : MemoryEvent->MemoryEvent { + (Load <: ^po :> FencePRSR).(^po :> Load) + + (Load <: ^po :> FencePRSW).(^po :> Store) + + (Store <: ^po :> FencePWSR).(^po :> Load) + + (Store <: ^po :> FencePWSW).(^po :> Store) + + (Load <: ^po :> FenceTSO) .(^po :> MemoryEvent) + + (Store <: ^po :> FenceTSO) .(^po :> Store) +} + +// auxiliary definitions +fun po_loc : Event->Event { ^po & address.~address } +fun same_hart[e: Event] : set Event { e + e.^~po + e.^po } +fun same_addr[e: Event] : set Event { e.address.~address } + +// initial stores +fun NonInit : set Event { Hart.start.*po } +fun Init : set Event { Event - NonInit } +fact { Init in StoreNormal } +fact { Init->(MemoryEvent & NonInit) in ^gmo } +fact { all e: NonInit | one e.*~po.~start } // each event is in exactly one hart +fact { all a: Address | one Init & a.~address } // one init store per address +fact { no Init <: po and no po :> Init } +.... + +` ` + +.... +// po +fact { acyclic[po] } + +// gmo +fact { total[^gmo, MemoryEvent] } // gmo is a total order over all MemoryEvents + +//rf +fact { rf.~rf in iden } // each read returns the value of only one write +fact { rf in Store <: address.~address :> Load } +fun rfi : MemoryEvent->MemoryEvent { rf & (*po + *~po) } + +//dep +fact { no StoreNormal <: (addrdep + ctrldep + datadep) } +fact { addrdep + ctrldep + datadep + pair in ^po } +fact { datadep in datadep :> Store } +fact { ctrldep.*po in ctrldep } +fact { no pair & (^po :> (LoadReserve + StoreConditional)).^po } +fact { StoreConditional in LoadReserve.pair } // assume all SCs succeed + +// rdw +fun rdw : Event->Event { + (Load <: po_loc :> Load) // start with all same_address load-load pairs, + - (~rf.rf) // subtract pairs that read from the same store, + - (po_loc.rfi) // and subtract out "fri-rfi" patterns +} + +// filter out redundant instances and/or visualizations +fact { no gmo & gmo.gmo } // keep the visualization uncluttered +fact { all a: Address | some a.~address } + +//////////////////////////////////////////////////////////////////////////////// +// =Optional: opcode encoding restrictions= + +// the list of blessed fences +fact { Fence in + Fence.pr.sr + + Fence.pw.sw + + Fence.pr.pw.sw + + Fence.pr.sr.sw + + FenceTSO + + Fence.pr.pw.sr.sw +} + +pred restrict_to_current_encodings { + no (LoadNormal + StoreNormal) & (Acquire + Release) +} + +//////////////////////////////////////////////////////////////////////////////// +// =Alloy shortcuts= +pred acyclic[rel: Event->Event] { no iden & ^rel } +pred total[rel: Event->Event, bag: Event] { + all disj e, e': bag | e->e' in rel + ~rel + acyclic[rel] +} +.... diff --git a/param_extraction/chunks/chunk_021.txt.license b/param_extraction/chunks/chunk_021.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_021.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_022.txt b/param_extraction/chunks/chunk_022.txt new file mode 100644 index 0000000000..1fb1a2df54 --- /dev/null +++ b/param_extraction/chunks/chunk_022.txt @@ -0,0 +1,1867 @@ +# Chunk: chunk_022 +# Source: mm-eplan.adoc +# Lines: 1-1850 (of 1850) +# Content starts: line 1 +# Line count: 1850 +# Sections: 10 +# == RVWMO Explanatory Material, Version 0.1 +# === Why RVWMO? +# === Litmus Tests +# === Explaining the RVWMO Rules +# ==== Preserved Program Order and Global Memory Order +# ==== Load value axiom +# ==== Atomicity axiom +# ==== Progress axiom +# ==== Overlapping-Address Orderings (<>) +# ==== Fences (<>) +# +[appendix] +== RVWMO Explanatory Material, Version 0.1 +[[mm-explain]] + +This section provides more explanation for RVWMO +<>, using more informal +language and concrete examples. These are intended to clarify the +meaning and intent of the axioms and preserved program order rules. This +appendix should be treated as commentary; all normative material is +provided in <> and in the rest of +the main body of the ISA specification. All currently known +discrepancies are listed in <>. Any +other discrepancies are unintentional. + +[[whyrvwmo]] +=== Why RVWMO? + +Memory consistency models fall along a loose spectrum from weak to +strong. Weak memory models allow more hardware implementation +flexibility and deliver arguably better performance, performance per +watt, power, scalability, and hardware verification overheads than +strong models, at the expense of a more complex programming model. +Strong models provide simpler programming models, but at the cost of +imposing more restrictions on the kinds of (non-speculative) hardware +optimizations that can be performed in the pipeline and in the memory +system, and in turn imposing some cost in terms of power, area overhead, +and verification burden. + +RISC-V has chosen the RVWMO memory model, a variant of release +consistency. This places it in between the two extremes of the memory +model spectrum. The RVWMO memory model enables architects to build +simple implementations, aggressive implementations, implementations +embedded deeply inside a much larger system and subject to complex +memory system interactions, or any number of other possibilities, all +while simultaneously being strong enough to support programming language +memory models at high performance. + +To facilitate the porting of code from other architectures, some +hardware implementations may choose to implement the Ztso extension, +which provides stricter RVTSO ordering semantics by default. Code +written for RVWMO is automatically and inherently compatible with RVTSO, +but code written assuming RVTSO is not guaranteed to run correctly on +RVWMO implementations. In fact, most RVWMO implementations will (and +should) simply refuse to run RVTSO-only binaries. Each implementation +must therefore choose whether to prioritize compatibility with RVTSO +code (e.g., to facilitate porting from x86) or whether to instead +prioritize compatibility with other RISC-V cores implementing RVWMO. + +Some fences and/or memory ordering annotations in code written for RVWMO +may become redundant under RVTSO; the cost that the default of RVWMO +imposes on Ztso implementations is the incremental overhead of fetching +those fences (e.g., FENCE R,RW and FENCE RW,W) which become no-ops on +that implementation. However, these fences must remain present in the +code if compatibility with non-Ztso implementations is desired. + +[[litmustests]] +=== Litmus Tests + +The explanations in this chapter make use of _litmus tests_, or small +programs designed to test or highlight one particular aspect of a memory +model. <> shows an example +of a litmus test with two harts. As a convention for this figure and for +all figures that follow in this chapter, we assume that `s0-s2` are +pre-set to the same value in all harts and that `s0` holds the address +labeled `x`, `s1` holds `y`, and `s2` holds `z`, where `x`, `y`, and `z` +are disjoint memory locations aligned to 8 byte boundaries. All other registers and all referenced memory locations are presumed to be initialized to zero. Each figure +shows the litmus test code on the left, and a visualization of one +particular valid or invalid execution on the right. + +[[litmus-sample, Litmus sample]] +[float="center",align="center",cols="1a,.^1a",frame="none",grid="none",options="noheader"] +.A sample litmus test and one forbidden execution (`a0=1`). +|=== +| +[.left] +[%autowidth,float="center",align="center",cols="^,<,^,<",options="header"] +!=== +2+!Hart 0 2+!Hart 1 +! !{vertical-ellipsis} ! !{vertical-ellipsis} +! !li t1,1 ! !li t4,4 +!(a) !sw t1,0(s0) !(e) !sw t4,0(s0) +! !{vertical-ellipsis} ! !{vertical-ellipsis} +! !li t2,2 ! ! +!(b) !sw t2,0(s0) ! ! +! !{vertical-ellipsis} ! !{vertical-ellipsis} +!(c) !lw a0,0(s0) ! ! +! !{vertical-ellipsis} ! !{vertical-ellipsis} +! !li t3,3 ! !li t5,5 +!(d) !sw t3,0(s0) !(f) !sw t5,0(s0) +! !{vertical-ellipsis} ! !{vertical-ellipsis} +!=== +| +!=== +//a! graphviz::images/graphviz/litmus_sample.txt[] +a! image::graphviz/litmus_sample.png[] +!=== +|=== + +Litmus tests are used to understand the implications of the memory model +in specific concrete situations. For example, in the litmus test of +<>, the final value of `a0` +in the first hart can be either 2, 4, or 5, depending on the dynamic +interleaving of the instruction stream from each hart at runtime. +However, in this example, the final value of `a0` in Hart 0 will never +be 1 or 3; intuitively, the value 1 will no longer be visible at the +time the load executes, and the value 3 will not yet be visible by the +time the load executes. We analyze this test and many others below. + +<<< +[[litmus-key]] +.A key for the litmus test diagrams drawn in this appendix +[%autowidth,cols="<,<",align="center",float="center",options="header",] +|=== +|Edge |Full Name (and explanation) +|rf |Reads From (from each store to the loads that return a value +written by that store) + +|co |Coherence (a total order on the stores to each address) + +|fr |From-Reads (from each load to co-successors of the store from which +the load returned a value) + +|ppo |Preserved Program Order + +|fence |Orderings enforced by a FENCE instruction + +|addr |Address Dependency + +|ctrl |Control Dependency + +|data |Data Dependency +|=== + +The diagram shown to the right of each litmus test shows a visual +representation of the particular execution candidate being considered. +These diagrams use a notation that is common in the memory model +literature for constraining the set of possible global memory orders +that could produce the execution in question. It is also the basis for +the _herd_ models presented in +<>. This notation is explained in +<>. Of the listed relations, rf edges between +harts, co edges, fr edges, and ppo edges directly constrain the global +memory order (as do fence, addr, data, and some ctrl edges, via ppo). +Other edges (such as intra-hart rf edges) are informative but do not +constrain the global memory order. + +For example, in <>, `a0=1` +could occur only if one of the following were true: + +* (b) appears before (a) in global memory order (and in the +coherence order co). However, this violates RVWMO PPO +rule `ppo:->st`. The co edge from (b) to (a) highlights this +contradiction. +* (a) appears before (b) in global memory order (and in the +coherence order co). However, in this case, the Load Value Axiom would +be violated, because (a) is not the latest matching store prior to (c) +in program order. The fr edge from (c) to (b) highlights this +contradiction. + +Since neither of these scenarios satisfies the RVWMO axioms, the outcome +`a0=1` is forbidden. + +Beyond what is described in this appendix, a suite of more than seven +thousand litmus tests is available at +https://github.com/litmus-tests/litmus-tests-riscv. +[NOTE] +==== +The litmus tests repository also provides instructions on how to run the +litmus tests on RISC-V hardware and how to compare the results with the +operational and axiomatic models. + +In the future, we expect to adapt these memory model litmus tests for +use as part of the RISC-V compliance test suite as well. +==== +=== Explaining the RVWMO Rules + +In this section, we provide explanation and examples for all of the +RVWMO rules and axioms. + +==== Preserved Program Order and Global Memory Order + +Preserved program order represents the subset of program order that must +be respected within the global memory order. Conceptually, events from +the same hart that are ordered by preserved program order must appear in +that order from the perspective of other harts and/or observers. Events +from the same hart that are not ordered by preserved program order, on +the other hand, may appear reordered from the perspective of other harts +and/or observers. + +Informally, the global memory order represents the order in which loads +and stores perform. The formal memory model literature has moved away +from specifications built around the concept of performing, but the idea +is still useful for building up informal intuition. A load is said to +have performed when its return value is determined. A store is said to +have performed not when it has executed inside the pipeline, but rather +only when its value has been propagated to globally visible memory. In +this sense, the global memory order also represents the contribution of +the coherence protocol and/or the rest of the memory system to +interleave the (possibly reordered) memory accesses being issued by each +hart into a single total order agreed upon by all harts. + +The order in which loads perform does not always directly correspond to +the relative age of the values those two loads return. In particular, a +load _b_ may perform before another load _a_ to +the same address (i.e., _b_ may execute before +_a_, and _b_ may appear before _a_ +in the global memory order), but _a_ may nevertheless return +an older value than _b_. This discrepancy captures (among +other things) the reordering effects of buffering placed between the +core and memory. For example, _b_ may have returned a value +from a store in the store buffer, while _a_ may have ignored +that younger store and read an older value from memory instead. To +account for this, at the time each load performs, the value it returns +is determined by the load value axiom, not just strictly by determining +the most recent store to the same address in the global memory order, as +described below. + +[[loadvalueaxiom, Load value axiom]] +==== Load value axiom + +[IMPORTANT] +==== +<>: Each byte of each load _i_ returns the value written +to that byte by the store that is the latest in global memory order among +the following stores: + +. Stores that write that byte and that precede i in the global memory +order +. Stores that write that byte and that precede i in program order +==== + +Preserved program order is _not_ required to respect the ordering of a +store followed by a load to an overlapping address. This complexity +arises due to the ubiquity of store buffers in nearly all +implementations. Informally, the load may perform (return a value) by +forwarding from the store while the store is still in the store buffer, +and hence before the store itself performs (writes back to globally +visible memory). Any other hart will therefore observe the load as +performing before the store. + +Consider the <>. When running this program on an implementation with +store buffers, it is possible to arrive at the final outcome `a0=1, a1=0, a2=1, a3=0` as follows: + +[[litms_sb_forward]] +.A store buffer forwarding litmus test (outcome permitted) +[float="center",align="center",cols=".^1a,.^1a",frame="none",grid="none",options="noheader"] +|=== +| +[%autowidth,float="center",align="center",cols="^,<,^,<",options="header",align="center"] +!=== +2+^!Hart 0 2+^!Hart 1 +2+^!li t1, 1 2+^!li t1, 1 +2+> +* (d) precedes (e): by the load value axiom. Otherwise, if (e) +preceded (d), then (d) would be required to return the value 1. (This is +a perfectly legal execution; it's just not the one in question) +* (e) precedes (f): by rule X +* (f) precedes (h): by rule <> +* (h) precedes (a): by the load value axiom, as above. + +The global memory order must be a total order and cannot be cyclic, +because a cycle would imply that every event in the cycle happens before +itself, which is impossible. Therefore, the execution proposed above +would be forbidden, and hence the addition of rule X would forbid +implementations with store buffer forwarding, which would clearly be +undesirable. + +Nevertheless, even if (b) precedes (a) and/or (f) precedes (e) in the +global memory order, the only sensible possibility in this example is +for (b) to return the value written by (a), and likewise for (f) and +(e). This combination of circumstances is what leads to the second +option in the definition of the load value axiom. Even though (b) +precedes (a) in the global memory order, (a) will still be visible to +(b) by virtue of sitting in the store buffer at the time (b) executes. +Therefore, even if (b) precedes (a) in the global memory order, (b) +should return the value written by (a) because (a) precedes (b) in +program order. Likewise for (e) and (f). + +[[litmus_ppoca]] +.Key for test that highlights the behavior of store buffers +[float="center",align="center",cols=".^1a,.^1a",frame="none",grid="none",options="noheader"] +.The "PPOCA" store buffer forwarding litmus test (outcome permitted) +|=== +| +[%autowidth,cols="^,<,^,<",options="header",float="center",align="center"] +!=== +2+^!Hart 0 2+^!Hart 1 +! !li t1, 1 !!li t1, 1 +!(a) !sw t1,0(s0) !!LOOP: +!(b) !fence w,w !(d) !lw a0,0(s1) +!(c) !sw t1,0(s1) !!beqz a0, LOOP +2+! !(e) !sw t1,0(s2) +2+! !(f) !lw a1,0(s2) +2+! ! !xor a2,a1,a1 +2+! ! !add s0,s0,a2 +2+! !(g) !lw a2,0(s0) +4+!Outcome: `a0=1`, `a1=1`, `a2=0` +!=== +| +!=== +//a! graphviz::images/graphviz/litmus_ppoca.txt[] +a! image::graphviz/litmus_ppoca.png[] +!=== +|=== + +Another test that highlights the behavior of store buffers is shown in +<>. In this example, (d) is +ordered before (e) because of the control dependency, and (f) is ordered +before (g) because of the address dependency. However, (e) is _not_ +necessarily ordered before (f), even though (f) returns the value +written by (e). This could correspond to the following sequence of +events: + +* (e) executes speculatively and enters the second hart's private +store buffer (but does not drain to memory) +* (f) executes speculatively and forwards its return value 1 from +(e) in the store buffer +* (g) executes speculatively and reads the value 0 from memory +* (a) executes, enters the first hart's private store buffer, and +drains to memory +* (b) executes and retires +* (c) executes, enters the first hart's private store buffer, and +drains to memory +* (d) executes and reads the value 1 from memory +* (e), (f), and (g) commit, since the speculation turned out to be +correct +* (e) drains from the store buffer to memory + +[[atomicityaxiom]] +==== Atomicity axiom + +[IMPORTANT] +==== +<> (for Aligned Atomics): If r and w are paired load and +store operations generated by aligned LR and SC instructions in a hart +h, s is a store to byte x, and r returns a value written by s, then s must +precede w in the global memory order, and there can be no store from +a hart other than h to byte x following s and preceding w in the global +memory order. +==== + +The RISC-V architecture decouples the notion of atomicity from the +notion of ordering. Unlike architectures such as TSO, RISC-V atomics +under RVWMO do not impose any ordering requirements by default. Ordering +semantics are only guaranteed by the PPO rules that otherwise apply. + +RISC-V contains two types of atomics: AMOs and LR/SC pairs. These +conceptually behave differently, in the following way. LR/SC behave as +if the old value is brought up to the core, modified, and written back +to memory, all while a reservation is held on that memory location. AMOs +on the other hand conceptually behave as if they are performed directly +in memory. AMOs are therefore inherently atomic, while LR/SC pairs are +atomic in the slightly different sense that the memory location in +question will not be modified by another hart during the time the +original hart holds the reservation. + +[[litmus_lrsdsc]] + +[frame=none] +.In all four (independent) instances, the final store-conditional instruction is permitted but not guaranteed to succeed. +|==== +|(a) lr.d a0, 0(s0) |(a) lr.d a0, 0(s0) |(a) lr.w a0, 0(s0) |(a) lr.w a0, 0(s0) + +|(b) sd t1, 0(s0) |(b) sw t1, 4(s0) |(b) sw t1, 4(s0) |(b) sw t1, 4(s0) + +|(c) sc.d t3, t2, 0(s0) |(c) sc.d t3, t2, 0(s0) |(c) sc.w t3, t2, 0(s0) |(c) addi s0, s0, 8 + +||||(d) sc.w t3, t2, 0(s0) +|==== + +The atomicity axiom forbids stores from other harts from being +interleaved in global memory order between an LR and the SC paired with +that LR. The atomicity axiom does not forbid loads from being +interleaved between the paired operations in program order or in the +global memory order, nor does it forbid stores from the same hart or +stores to non-overlapping locations from appearing between the paired +operations in either program order or in the global memory order. For +example, the SC instructions in <> may (but are not +guaranteed to) succeed. None of those successes would violate the +atomicity axiom, because the intervening non-conditional stores are from +the same hart as the paired load-reserved and store-conditional +instructions. This way, a memory system that tracks memory accesses at +cache line granularity (and which therefore will see the four snippets +of <> as identical) will not +be forced to fail a store-conditional instruction that happens to +(falsely) share another portion of the same cache line as the memory +location being held by the reservation. + +The atomicity axiom also technically supports cases in which the LR and +SC touch different addresses and/or use different access sizes; however, +use cases for such behaviors are expected to be rare in practice. +Likewise, scenarios in which stores from the same hart between an LR/SC +pair actually overlap the memory location(s) referenced by the LR or SC +are expected to be rare compared to scenarios where the intervening +store may simply fall onto the same cache line. + +[[mm-progress]] +==== Progress axiom + +[IMPORTANT] +==== +<>: No memory operation may be preceded in the global +memory order by an infinite sequence of other memory operations. +==== + +The progress axiom ensures a minimal forward progress guarantee. It +ensures that stores from one hart will eventually be made visible to +other harts in the system in a finite amount of time, and that loads +from other harts will eventually be able to read those values (or +successors thereof). Without this rule, it would be legal, for example, +for a spinlock to spin infinitely on a value, even with a store from +another hart unlocking the spinlock. + +The progress axiom is intended not to impose any other notion of +fairness, latency, or quality of service onto the harts in a RISC-V +implementation. Any stronger notions of fairness are up to the rest of +the ISA and/or up to the platform and/or device to define and implement. + +The forward progress axiom will in almost all cases be naturally +satisfied by any standard cache coherence protocol. Implementations with +non-coherent caches may have to provide some other mechanism to ensure +the eventual visibility of all stores (or successors thereof) to all +harts. + +[[mm-overlap]] +==== Overlapping-Address Orderings (<>) + +[NOTE] +==== +<>: b is a store, and a and b access overlapping memory addresses + +<>: a and b are loads, x is a byte read by both a and b, there is no +store to x between a and b in program order, and a and b return values +for x written by different memory operations + +<>: a is generated by an AMO or SC instruction, b is a load, and b +returns a value written by a +==== + +Same-address orderings where the latter is a store are straightforward: +a load or store can never be reordered with a later store to an +overlapping memory location. From a microarchitecture perspective, +generally speaking, it is difficult or impossible to undo a +speculatively reordered store if the speculation turns out to be +invalid, so such behavior is simply disallowed by the model. +Same-address orderings from a store to a later load, on the other hand, +do not need to be enforced. As discussed in +<>, this reflects the observable +behavior of implementations that forward values from buffered stores to +later loads. + +Same-address load-load ordering requirements are far more subtle. The +basic requirement is that a younger load must not return a value that is +older than a value returned by an older load in the same hart to the +same address. This is often known as "CoRR" (Coherence for Read-Read +pairs), or as part of a broader "coherence" or "sequential +consistency per location" requirement. Some architectures in the past +have relaxed same-address load-load ordering, but in hindsight this is +generally considered to complicate the programming model too much, and +so RVWMO requires CoRR ordering to be enforced. However, because the +global memory order corresponds to the order in which loads perform +rather than the ordering of the values being returned, capturing CoRR +requirements in terms of the global memory order requires a bit of +indirection. + +[[frirfi]] +.A litmus test MP+fence.w.w+fri-rfi-addr (outcome permitted) + +[float="center",align="center",cols=".^1a,.^1a",frame="none",grid="none",options="noheader"] +.Litmus test MP+fence.w.w+fre-rfi-addr (outcome permitted) +|=== +| +[%autowidth,cols="^,<,^,<",options="header",float="center",align="center"] +!=== +2+!Hart 0 2+^!Hart 1 +!!li t1, 1 !!li t2, 2 +>!(a) !sw t1,0(s0) >!(d) !lw a0,0(s1) +>!(b) !fence w, w >!(e) !sw t2,0(s1) +>!(c) !sw t1,0(s1) >!(f) !lw a1,0(s1) +! ! >!(g) !xor t3,a1,a1 +! ! >!(h) !add s0,s0,t3 +! ! >!(i) !lw a2,0(s0) +4+^!Outcome: `a0=1`, `a1=2`, `a2=0` +!=== +| +!=== +//a! graphviz::images/graphviz/litmus_mp_fenceww_fri_rfi_addr.txt[] +a! image::graphviz/litmus_mp_fenceww_fri_rfi_addr.png[] +!=== +|=== +Consider the litmus test of <>, which is one particular +instance of the more general "fri-rfi" pattern. The term "fri-rfi" +refers to the sequence (d), (e), (f): (d) "from-reads" (i.e., reads +from an earlier write than) (e) which is the same hart, and (f) reads +from (e) which is in the same hart. + +From a microarchitectural perspective, outcome `a0=1`, `a1=2`, `a2=0` is +legal (as are various other less subtle outcomes). Intuitively, the +following would produce the outcome in question: + +* (d) stalls (for whatever reason; perhaps it's stalled waiting +for some other preceding instruction) +* (e) executes and enters the store buffer (but does not yet +drain to memory) +* (f) executes and forwards from (e) in the store buffer +* (g), (h), and (i) execute +* (a) executes and drains to memory, (b) executes, and (c) +executes and drains to memory +* (d) unstalls and executes +* (e) drains from the store buffer to memory + +This corresponds to a global memory order of (f), (i), (a), (c), (d), +(e). Note that even though (f) performs before (d), the value returned +by (f) is newer than the value returned by (d). Therefore, this +execution is legal and does not violate the CoRR requirements. + +Likewise, if two back-to-back loads return the values written by the +same store, then they may also appear out-of-order in the global memory +order without violating CoRR. Note that this is not the same as saying +that the two loads return the same value, since two different stores may +write the same value. + +[[litmus-rsw]] +.Litmus test RSW (outcome permitted) + +[float="center",align="center",cols=".^1a,.^1a",frame="none",grid="none",options="noheader"] +|=== +| +[%autowidth,cols="^,<,^,<",options="header",float="center",align="center"] +!=== +2+!Hart 0 2+^!Hart 1 +2+!li t1, 1 >!(d) !(a) !(e) !xor t2,a0,a0 +>!(b) !(f) !add s4,s2,t2 +>!(c) !(g) !lw a1,0(s4) +! ! >!(h) !lw a2,0(s2) +! ! >!(i) !xor t3,a2,a2 +! ! >!(j) !add s0,s0,t3 +! ! >!(k) !lw a3,0(s0) +4+!Outcome: `a0=1`, `a1=v`, `a2=v`, `a3=0` +!=== +| +!=== +//a! graphviz::images/graphviz/litmus_rsw.txt[] +a! image::graphviz/litmus_rsw.png[] +!=== +|=== + +Consider the litmus test of <>. +The outcome `a0=1`, `a1=v`, `a2=v`, `a3=0` (where _v_ is +some value written by another hart) can be observed by allowing (g) and +(h) to be reordered. This might be done speculatively, and the +speculation can be justified by the microarchitecture (e.g., by snooping +for cache invalidations and finding none) because replaying (h) after +(g) would return the value written by the same store anyway. Hence +assuming `a1` and `a2` would end up with the same value written by the +same store anyway, (g) and (h) can be legally reordered. The global +memory order corresponding to this execution would be +(h),(k),(a),(c),(d),(g). + +Executions of the test in <> in +which `a1` does not equal `a2` do in fact require that (g) appears +before (h) in the global memory order. Allowing (h) to appear before (g) +in the global memory order would in that case result in a violation of +CoRR, because then (h) would return an older value than that returned by +(g). Therefore, <> forbids this CoRR violation +from occurring. As such, <> strikes a careful +balance between enforcing CoRR in all cases while simultaneously being +weak enough to permit "RSW" and "fri-rfi" patterns that commonly +appear in real microarchitectures. + +There is one more overlapping-address rule: <> simply states that a value cannot +be returned from an AMO or SC to a subsequent load until the AMO or SC +has (in the case of the SC, successfully) performed globally. This +follows somewhat naturally from the conceptual view that both AMOs and +SC instructions are meant to be performed atomically in memory. However, +notably, <> states that hardware +may not even non-speculatively forward the value being stored by an +AMOSWAP to a subsequent load, even though for AMOSWAP that store value +is not actually semantically dependent on the previous value in memory, +as is the case for the other AMOs. The same holds true even when +forwarding from SC store values that are not semantically dependent on +the value returned by the paired LR. + +The three PPO rules above also apply when the memory accesses in +question only overlap partially. This can occur, for example, when +accesses of different sizes are used to access the same object. Note +also that the base addresses of two overlapping memory operations need +not necessarily be the same for two memory accesses to overlap. When +misaligned memory accesses are being used, the overlapping-address PPO +rules apply to each of the component memory accesses independently. + +[[mm-fence]] +==== Fences (<>) + +[IMPORTANT] +==== +Rule <>: There is a FENCE instruction that orders a before b +==== + +By default, the FENCE instruction ensures that all memory accesses from +instructions preceding the fence in program order (the "predecessor +set") appear earlier in the global memory order than memory accesses +from instructions appearing after the fence in program order (the +"successor set"). However, fences can optionally further restrict the +predecessor set and/or the successor set to a smaller set of memory +accesses in order to provide some speedup. Specifically, fences have PR, +PW, SR, and SW bits which restrict the predecessor and/or successor +sets. The predecessor set includes loads (resp.stores) if and only if PR +(resp.PW) is set. Similarly, the successor set includes loads +(resp.stores) if and only if SR (resp.SW) is set. + +The FENCE encoding currently has nine non-trivial combinations of the +four bits PR, PW, SR, and SW, plus one extra encoding FENCE.TSO which +facilitates mapping of "acquire+release" or RVTSO semantics. The +remaining seven combinations have empty predecessor and/or successor +sets and hence are no-ops. Of the ten non-trivial options, six are +commonly used in practice: + +* FENCE RW,RW +* FENCE.TSO +* FENCE RW,W +* FENCE R,RW +* FENCE R,R +* FENCE W,W + +FENCE instructions using other combinations of PR, PW, SR, and SW are not +normally used in the Linux or C++ memory models but are otherwise well +defined. + +Finally, we note that since RISC-V uses a multi-copy atomic memory +model, programmers can reason about fences bits in a thread-local +manner. Fences in RISC-V are not cumulative, as they are in some +non-multi-copy-atomic memory models. + +[[sec:memory:acqrel]] +==== Explicit Synchronization (<>) + +[IMPORTANT] +==== +<>: a has an acquire annotation + +<>: b has a release annotation + +<>: a and b both have RCsc annotations + +<>: a is paired with b +==== + +An _acquire_ operation, as would be used at the start of a critical +section, requires all memory operations following the acquire in program +order to also follow the acquire in the global memory order. This +ensures, for example, that all loads and stores inside the critical +section are up to date with respect to the synchronization variable +being used to protect it. Acquire ordering can be enforced in one of two +ways: with an acquire annotation, which enforces ordering with respect +to just the synchronization variable itself, or with a FENCE R,RW, which +enforces ordering with respect to all previous loads. + +[[spinlock_atomics]] +.A spinlock with atomics +[source%linenums,asm] +.... + sd x1, (a1) # Arbitrary unrelated store + ld x2, (a2) # Arbitrary unrelated load + li t0, 1 # Initialize swap value. + again: + amoswap.w.aq t0, t0, (a0) # Attempt to acquire lock. + bnez t0, again # Retry if held. + # ... + # Critical section. + # ... + amoswap.w.rl x0, x0, (a0) # Release lock by storing 0. + sd x3, (a3) # Arbitrary unrelated store + ld x4, (a4) # Arbitrary unrelated load +.... + +Consider <>. +Because this example uses _aq_, the loads and stores in the critical +section are guaranteed to appear in the global memory order after the +AMOSWAP used to acquire the lock. However, assuming `a0`, `a1`, and `a2` +point to different memory locations, the loads and stores in the +critical section may or may not appear after the "Arbitrary unrelated +load" at the beginning of the example in the global memory order. + +[[spinlock_fences]] +.A spinlock with fences +[source%linenums,asm] +.... + sd x1, (a1) # Arbitrary unrelated store + ld x2, (a2) # Arbitrary unrelated load + li t0, 1 # Initialize swap value. + again: + amoswap.w t0, t0, (a0) # Attempt to acquire lock. + fence r, rw # Enforce "acquire" memory ordering + bnez t0, again # Retry if held. + # ... + # Critical section. + # ... + fence rw, w # Enforce "release" memory ordering + amoswap.w x0, x0, (a0) # Release lock by storing 0. + sd x3, (a3) # Arbitrary unrelated store + ld x4, (a4) # Arbitrary unrelated load +.... + +Now, consider the alternative in <>. In +this case, even though the AMOSWAP does not enforce ordering with an +_aq_ bit, the fence nevertheless enforces that the acquire AMOSWAP +appears earlier in the global memory order than all loads and stores in +the critical section. Note, however, that in this case, the fence also +enforces additional orderings: it also requires that the "Arbitrary +unrelated load" at the start of the program appears earlier in the +global memory order than the loads and stores of the critical section. +(This particular fence does not, however, enforce any ordering with +respect to the "Arbitrary unrelated store" at the start of the +snippet.) In this way, fence-enforced orderings are slightly coarser +than orderings enforced by _.aq_. + +Release orderings work exactly the same as acquire orderings, just in +the opposite direction. Release semantics require all loads and stores +preceding the release operation in program order to also precede the +release operation in the global memory order. This ensures, for example, +that memory accesses in a critical section appear before the +lock-releasing store in the global memory order. Just as for acquire +semantics, release semantics can be enforced using release annotations +or with a FENCE RW,W operation. Using the same examples, the ordering +between the loads and stores in the critical section and the "Arbitrary +unrelated store" at the end of the code snippet is enforced only by the +FENCE RW,W in <>, not by +the _rl_ in <>. + +With RCpc annotations alone, store-release-to-load-acquire ordering is +not enforced. This facilitates the porting of code written under the TSO +and/or RCpc memory models. To enforce store-release-to-load-acquire +ordering, the code must use store-release-RCsc and load-acquire-RCsc +operations so that PPO rule 7 applies. RCpc alone is +sufficient for many use cases in C/C\++ but is insufficient for many +other use cases in C/C++, Java, and Linux, to name just a few examples; +see <> for details. + +PPO rule 8 indicates that an SC must appear after +its paired LR in the global memory order. This will follow naturally +from the common use of LR/SC to perform an atomic read-modify-write +operation due to the inherent data dependency. However, PPO +rule 8 also applies even when the value being stored +does not syntactically depend on the value returned by the paired LR. + +Lastly, we note that, as with fences, ordering annotations are +not cumulative. + +[[sec:memory:dependencies]] +==== Syntactic Dependencies (<>) + +[[ppo-addr]] +[IMPORTANT] +==== +<>: b has a syntactic address dependency on a + +<>: b has a syntactic data dependency on a + +<>: b is a store, and b has a syntactic control dependency on a +==== + +Dependencies from a load to a later memory operation in the same hart +are respected by the RVWMO memory model. The Alpha memory model was +notable for choosing _not_ to enforce the ordering of such dependencies, +but most modern hardware and software memory models consider allowing +dependent instructions to be reordered too confusing and +counterintuitive. Furthermore, modern code sometimes intentionally uses +such dependencies as a particularly lightweight ordering enforcement +mechanism. + +The terms in <> work as follows. Instructions +are said to carry dependencies from their +source register(s) to their destination register(s) whenever the value +written into each destination register is a function of the source +register(s). For most instructions, this means that the destination +register(s) carry a dependency from all source register(s). However, +there are a few notable exceptions. In the case of memory instructions, +the value written into the destination register ultimately comes from +the memory system rather than from the source register(s) directly, and +so this breaks the chain of dependencies carried from the source +register(s). In the case of unconditional jumps, the value written into +the destination register comes from the current `pc` (which is never +considered a source register by the memory model), and so likewise, JALR +(the only jump with a source register) does not carry a dependency from +_rs1_ to _rd_. + + +[[fflags]] +.(c) has a syntactic dependency on both (a) and (b) via fflags, a destination register that both (a) and (b) implicitly accumulate into +[.text-center,source%linenums,asm] +---- +(a) fadd f3,f1,f2 +(b) fadd f6,f4,f5 +(c) csrrs a0,fflags,x0 +---- + +The notion of accumulating into a destination register rather than +writing into it reflects the behavior of CSRs such as `fflags`. In +particular, an accumulation into a register does not clobber any +previous writes or accumulations into the same register. For example, in +<>, (c) has a syntactic dependency on both (a) and (b). + +Like other modern memory models, the RVWMO memory model uses syntactic +rather than semantic dependencies. In other words, this definition +depends on the identities of the registers being accessed by different +instructions, not the actual contents of those registers. This means +that an address, control, or data dependency must be enforced even if +the calculation could seemingly be `optimized away`. This choice +ensures that RVWMO remains compatible with code that uses these false +syntactic dependencies as a lightweight ordering mechanism. + +[[address]] +.A syntactic address dependency +[.text-center, source%linenums, asm] +---- +ld a1,0(s0) +xor a2,a1,a1 +add s1,s1,a2 +ld a5,0(s1) +---- + +For example, there is a syntactic address dependency from the memory +operation generated by the first instruction to the memory operation +generated by the last instruction in +<
>, even though `a1` XOR +`a1` is zero and hence has no effect on the address accessed by the +second load. + +The benefit of using dependencies as a lightweight synchronization +mechanism is that the ordering enforcement requirement is limited only +to the specific two instructions in question. Other non-dependent +instructions may be freely reordered by aggressive implementations. One +alternative would be to use a load-acquire, but this would enforce +ordering for the first load with respect to _all_ subsequent +instructions. Another would be to use a FENCE R,R, but this would +include all previous and all subsequent loads, making this option more +expensive. + +[[control1]] +.A syntactic control dependency +[.text-center, source%linenums, asm] +---- +lw x1,0(x2) +bne x1,x0,next +sw x3,0(x4) +next: sw x5,0(x6) +---- + +Control dependencies behave differently from address and data +dependencies in the sense that a control dependency always extends to +all instructions following the original target in program order. +Consider <> the +instruction at `next` will always execute, but the memory operation +generated by that last instruction nevertheless still has a control +dependency from the memory operation generated by the first instruction. + +[[control2]] +.Another syntactic control dependency +[.text-center,source%linenums,asm] +---- +lw x1,0(x2) +bne x1,x0,next +next: sw x3,0(x4) +---- + +Likewise, consider <>. +Even though both branch outcomes have the same target, there is still a +control dependency from the memory operation generated by the first +instruction in this snippet to the memory operation generated by the +last instruction. This definition of control dependency is subtly +stronger than what might be seen in other contexts (e.g., C++), but it +conforms with standard definitions of control dependencies in the +literature. + +Notably, PPO rules <> are also +intentionally designed to respect dependencies that originate from the +output of a successful store-conditional instruction. Typically, an SC +instruction will be followed by a conditional branch checking whether +the outcome was successful; this implies that there will be a control +dependency from the store operation generated by the SC instruction to +any memory operations following the branch. PPO +rule <> in turn implies that any subsequent store +operations will appear later in the global memory order than the store +operation generated by the SC. However, since control, address, and data +dependencies are defined over memory operations, and since an +unsuccessful SC does not generate a memory operation, no order is +enforced between unsuccessful SC and its dependent instructions. +Moreover, since SC is defined to carry dependencies from its source +registers to _rd_ only when the SC is successful, an unsuccessful SC has +no effect on the global memory order. + +[[litmus_lb_lrsc]] +.A variant of the LB litmus test (outcome forbidden) +[float="center",align="center",cols=".^1a,.^1a",frame="none",grid="none",options="noheader"] +|=== +| +[%autowidth,cols="^,<,^,<",float="center",align="center"] +!=== +4+!Initial values: 0(s0)=1; 0(s2)=1 +4+! +2+^!Hart 0 2+^!Hart 1 +!(a) !ld a0,0(s0) !(e) !ld a3,0(s2) +!(b) !lr a1,0(s1) !(f) !sd a3,0(s0) +!(c) !sc a2,a0,0(s1) ! ! +!(d) !sd a2,0(s2) ! ! +4+!Outcome: `a0=0`, `a3=0` +!=== +| +!=== +//a! graphviz::images/graphviz/litmus_lb_lrsc.txt[] +a! image::graphviz/litmus_lb_lrsc.png[] +!=== +|=== + +In addition, the choice to respect dependencies originating at +store-conditional instructions ensures that certain out-of-thin-air-like +behaviors will be prevented. Consider +<>. Suppose a +hypothetical implementation could occasionally make some early guarantee +that a store-conditional operation will succeed. In this case, (c) could +return 0 to `a2` early (before actually executing), allowing the +sequence (d), (e), (f), (a), and then (b) to execute, and then (c) might +execute (successfully) only at that point. This would imply that (c) +writes its own success value to `0(s1)`! Fortunately, this situation and +others like it are prevented by the fact that RVWMO respects +dependencies originating at the stores generated by successful SC +instructions. + +We also note that syntactic dependencies between instructions only have +any force when they take the form of a syntactic address, control, +and/or data dependency. For example: a syntactic dependency between two +`F` instructions via one of the `accumulating CSRs` in +<> does _not_ imply +that the two `F` instructions must be executed in order. Such a +dependency would only serve to ultimately set up later a dependency from +both `F` instructions to a later CSR instruction accessing the CSR +flag in question. + +[[memory-ppopipeline]] +==== Pipeline Dependencies (<>) + +[[addrdatarfi]] +[IMPORTANT] +==== +<>: b is a load, and there exists some store m between a and b in +program order such that m has an address or data dependency on a, +and b returns a value written by m + +<>: b is a store, and there exists some instruction m between a and +b in program order such that m has an address dependency on a +==== + +[[litmus_datarfi]] +.Because of PPO <> and the data dependency from (d) to (e), (d) must also precede (f) in the global memory order (outcome forbidden) +[float="center",align="center",cols=".^1a,.^1a",frame="none",grid="none",options="noheader"] +|=== +| +[%autowidth,float="center",align="center",cols="^,<,^,<",options="header",] +!=== +2+!Hart 0 2+! Hart 1 +! !li t1, 1 !(d) !lw a0, 0(s1) +!(a) !sw t1,0(s0) !(e) !sw a0, 0(s2) +!(b) !fence w, w !(f) !lw a1, 0(s2) +!(c) !sw t1,0(s1) ! !xor a2,a1,a1 +! ! ! !add s0,s0,a2 +! ! !(g) !lw a3,0(s0) +4+!Outcome: `a0=1`, `a3=0` +!=== +| +!=== +//a! graphviz::images/graphviz/litmus_datarfi.txt[] +a! image::graphviz/litmus_datarfi.png[] +!=== +|=== + +PPO rules <> and <> reflect behaviors of almost all real processor +pipeline implementations. Rule <> +states that a load cannot forward from a store until the address and +data for that store are known. Consider <> (f) cannot be +executed until the data for (e) has been resolved, because (f) must +return the value written by (e) (or by something even later in the +global memory order), and the old value must not be clobbered by the +write-back of (e) before (d) has had a chance to perform. Therefore, (f) +will never perform before (d) has performed. + + +.Because of the extra store between (e) and (g), (d) no longer necessarily precedes (g) (outcome permitted) + +[float="center",align="center",cols=".^1a,.^1a",frame="none",grid="none",options="noheader"] +|=== +| +[%autowidth,cols="^,<,^,<",float="center",align="center",options="header",] +!=== +2+!Hart 0 2+!Hart 1 +2+!li t1, 1 2+^!li t1, 1 +!(a) !sw t1,0(s0) !(d) !lw a0, 0(s1) +!(b) !fence w, w !(e) !sw a0, 0(s2) +!(c) !sw t1,0(s1) !(f) !sw t1, 0(s2) +! ! !(g) !lw a1, 0(s2) +! ! ! !xor a2,a1,a1 +! ! ! !add s0,s0,a2 +! ! !(h) !lw a3,0(s0) +4+!Outcome: `a0=1`, `a3=0` +!=== +| +!=== +//a! graphviz::images/graphviz/litmus_datacoirfi.txt[] +a! image::graphviz/litmus_datacoirfi.png[] +!=== +|=== + +If there were another store to the same address in between (e) and (f), +as in <>, +then (f) would no longer be dependent on the data of (e) being resolved, +and hence the dependency of (f) on (d), which produces the data for (e), +would be broken. + +Rule <> makes a similar observation to the +previous rule: a store cannot be performed at memory until all previous +loads that might access the same address have themselves been performed. +Such a load must appear to execute before the store, but it cannot do so +if the store were to overwrite the value in memory before the load had a +chance to read the old value. Likewise, a store generally cannot be +performed until it is known that preceding instructions will not cause +an exception due to failed address resolution, and in this sense, +rule 13 can be seen as somewhat of a special case +of rule <>. + +[[litmus:addrdatarfi_no]] +.Because of the address dependency from (d) to (e), (d) also precedes (f) (outcome forbidden) +[float="center",align="center",cols=".^1a,.^1a",frame="none",grid="none",options="noheader"] +|=== +| +[%autowidth,cols="^,<,^,<"float="center",align="center",options="header"] +!=== +2+!Hart 0 2+^!Hart 1 +2+! 2+^!li t1, 1 +!(a) !lw a0,0(s0) !(d) !lw a1, 0(s1) +!(b) !fence rw,rw !(e) !lw a2, 0(a1) +!(c) !sw s2,0(s1) !(f) !sw t1, 0(s0) +4+!Outcome: `a0=1`, `a1=t` +!=== +| +!=== +//a! graphviz::images/graphviz/litmus_addrpo.txt[] +a! image:graphviz/litmus_addrpo.png[] +!=== +|=== + +Consider <> (f) cannot be +executed until the address for (e) is resolved, because it may turn out +that the addresses match; i.e., that `a1=s0`. Therefore, (f) cannot be +sent to memory before (d) has executed and confirmed whether the +addresses do indeed overlap. + +=== Beyond Main Memory + +RVWMO does not currently attempt to formally describe how FENCE.I, +SFENCE.VMA, I/O fences, and PMAs behave. All of these behaviors will be +described by future formalizations. In the meantime, the behavior of +FENCE.I is described in <>, the +behavior of SFENCE.VMA is described in the RISC-V Instruction Set +Privileged Architecture Manual, and the behavior of I/O fences and the +effects of PMAs are described below. + +==== Coherence and Cacheability + +The RISC-V Privileged ISA defines Physical Memory Attributes (PMAs) +which specify, among other things, whether portions of the address space +are coherent and/or cacheable. See the RISC-V Privileged ISA +Specification for the complete details. Here, we simply discuss how the +various details in each PMA relate to the memory model: + +* Main memory vs.I/O, and I/O memory ordering PMAs: the memory model as +defined applies to main memory regions. I/O ordering is discussed below. +* Supported access types and atomicity PMAs: the memory model is simply +applied on top of whatever primitives each region supports. +* Cacheability PMAs: the cacheability PMAs in general do not affect the +memory model. Non-cacheable regions may have more restrictive behavior +than cacheable regions, but the set of allowed behaviors does not change +regardless. However, some platform-specific and/or device-specific +cacheability settings may differ. +* Coherence PMAs: The memory consistency model for memory regions marked +as non-coherent in PMAs is currently platform-specific and/or +device-specific: the load-value axiom, the atomicity axiom, and the +progress axiom all may be violated with non-coherent memory. Note +however that coherent memory does not require a hardware cache coherence +protocol. The RISC-V Privileged ISA Specification suggests that +hardware-incoherent regions of main memory are discouraged, but the +memory model is compatible with hardware coherence, software coherence, +implicit coherence due to read-only memory, implicit coherence due to +only one agent having access, or otherwise. +* Idempotency PMAs: Idempotency PMAs are used to specify memory regions +for which loads and/or stores may have side effects, and this in turn is +used by the microarchitecture to determine, e.g., whether prefetches are +legal. This distinction does not affect the memory model. + +==== I/O Ordering + +For I/O, the load value axiom and atomicity axiom in general do not +apply, as both reads and writes might have device-specific side effects +and may return values other than the value "written" by the most +recent store to the same address. Nevertheless, the following preserved +program order rules still generally apply for accesses to I/O memory: +memory access _a_ precedes memory access _b_ in +global memory order if _a_ precedes _b_ in +program order and one or more of the following holds: + +. _a_ precedes _b_ in preserved program order as +defined in <>, with the exception +that acquire and release ordering annotations apply only from one memory +operation to another memory operation and from one I/O operation to +another I/O operation, but not from a memory operation to an I/O nor +vice versa +. _a_ and _b_ are accesses to overlapping +addresses in an I/O region +. _a_ and _b_ are accesses to the same strongly +ordered I/O region +. _a_ and _b_ are accesses to I/O regions, and +the channel associated with the I/O region accessed by either +_a_ or _b_ is channel 1 +. _a_ and _b_ are accesses to I/O regions +associated with the same channel (except for channel 0) + +Note that the FENCE instruction distinguishes between main memory +operations and I/O operations in its predecessor and successor sets. To +enforce ordering between I/O operations and main memory operations, code +must use a FENCE with PI, PO, SI, and/or SO, plus PR, PW, SR, and/or SW. +For example, to enforce ordering between a write to main memory and an +I/O write to a device register, a FENCE W,O or stronger is needed. +[[wo]] +.Ordering memory and I/O accesses +[.text-center,source%linenums,asm] +---- +sd t0, 0(a0) +fence w,o +sd a0, 0(a1) +---- + +When a fence is in fact used, implementations must assume that the +device may attempt to access memory immediately after receiving the MMIO +signal, and subsequent memory accesses from that device to memory must +observe the effects of all accesses ordered prior to that MMIO +operation. In other words, in <>, +suppose `0(a0)` is in main memory and `0(a1)` is the address of a device +register in I/O memory. If the device accesses `0(a0)` upon receiving +the MMIO write, then that load must conceptually appear after the first +store to `0(a0)` according to the rules of the RVWMO memory model. In +some implementations, the only way to ensure this will be to require +that the first store does in fact complete before the MMIO write is +issued. Other implementations may find ways to be more aggressive, while +others still may not need to do anything different at all for I/O and +main memory accesses. Nevertheless, the RVWMO memory model does not +distinguish between these options; it simply provides an +implementation-agnostic mechanism to specify the orderings that must be +enforced. + +Many architectures include separate notions of "ordering" and +"completion" fences, especially as it relates to I/O (as opposed to +regular main memory). Ordering fences simply ensure that memory +operations stay in order, while completion fences ensure that +predecessor accesses have all completed before any successors are made +visible. RISC-V does not explicitly distinguish between ordering and +completion fences. Instead, this distinction is simply inferred from +different uses of the FENCE bits. + +For implementations that conform to the RISC-V Unix Platform +Specification, I/O devices and DMA operations are required to access +memory coherently and via strongly ordered I/O channels. Therefore, +accesses to regular main memory regions that are concurrently accessed +by external devices can also use the standard synchronization +mechanisms. Implementations that do not conform to the Unix Platform +Specification and/or in which devices do not access memory coherently +will need to use mechanisms (which are currently platform-specific or +device-specific) to enforce coherency. + +I/O regions in the address space should be considered non-cacheable +regions in the PMAs for those regions. Such regions can be considered +coherent by the PMA if they are not cached by any agent. + +The ordering guarantees in this section may not apply beyond a +platform-specific boundary between the RISC-V cores and the device. In +particular, I/O accesses sent across an external bus (e.g., PCIe) may be +reordered before they reach their ultimate destination. Ordering must be +enforced in such situations according to the platform-specific rules of +those external devices and buses. + +[[memory_porting]] +=== Code Porting and Mapping Guidelines + +[[tsomappings]] +.Mappings from TSO operations to RISC-V operations +[%autowidth,float="center", align="center",cols="<,<",options="header",separator=!] +|=== +!x86/TSO Operation !RVWMO Mapping +!Load ! `l{b|h|w|d}; fence r,rw` +!Store !`fence rw,w; s{b|h|w|d}` +!Atomic RMW !`amo.{w|d}.aqrl OR` + +`loop:lr.{w|d}.aq; ; sc.{w|d}.aqrl; bnez loop` +!Fence !`fence rw,rw` +|=== + +<> provides a mapping from TSO memory +operations onto RISC-V memory instructions. Normal x86 loads and stores +are all inherently acquire-RCpc and release-RCpc operations: TSO +enforces all load-load, load-store, and store-store ordering by default. +Therefore, under RVWMO, all TSO loads must be mapped onto a load +followed by FENCE R,RW, and all TSO stores must be mapped onto +FENCE RW,W followed by a store. TSO atomic read-modify-writes and x86 +instructions using the LOCK prefix are fully ordered and can be +implemented either via an AMO with both _aq_ and _rl_ set, or via an LR +with _aq_ set, the arithmetic operation in question, an SC with both +_aq_ and _rl_ set, and a conditional branch checking the success +condition. In the latter case, the _rl_ annotation on the LR turns out +(for non-obvious reasons) to be redundant and can be omitted. + +Alternatives to <> are also possible. A TSO +store can be mapped onto AMOSWAP with _rl_ set. However, since RVWMO PPO +Rule <> forbids forwarding of values from +AMOs to subsequent loads, the use of AMOSWAP for stores may negatively +affect performance. A TSO load can be mapped using LR with _aq_ set: all +such LR instructions will be unpaired, but that fact in and of itself +does not preclude the use of LR for loads. However, again, this mapping +may also negatively affect performance if it puts more pressure on the +reservation mechanism than was originally intended. + +[[powermappings]] +.Mappings from Power operations to RISC-V operations +[%autowidth,float="center",align="center",cols="<,<",options="header",separator=!] +|=== +!Power Operation !RVWMO Mapping +!Load !`l{b|h|w|d}` +!Load-Reserve !`lr.{w|d}` +!Store !`s{b|h|w|d}` +!Store-Conditional !`sc.{w|d}` +!`lwsync` !`fence.tso` +!`sync` !`fence rw,rw` +!`isync` !`fence.i; fence r,r` +|=== + +<> provides a mapping from Power memory +operations onto RISC-V memory instructions. Power ISYNC maps on RISC-V +to a FENCE.I followed by a FENCE R,R; the latter fence is needed because +ISYNC is used to define a "control+control fence" dependency that is +not present in RVWMO. + +[[armmappings]] +.Mappings from ARM operations to RISC-V operations +[%autowidth,float="center",align="center",cols="<,<",options="header",separator=!] +|=== +!ARM Operation !RVWMO Mapping +!Load !`l{b|h|w|d}` +!Load-Acquire !`fence rw, rw; l{b|h|w|d}; fence r,rw` +!Load-Exclusive !`lr.{w|d}` +!Load-Acquire-Exclusive !`lr.{w|d}.aqrl` +!Store !`s{b|h|w|d}` +!Store-Release !`fence rw,w; s{b|h|w|d}` +!Store-Exclusive !`sc.{w|d}` +!Store-Release-Exclusive !`sc.{w|d}.rl` +!`dmb` !`fence rw,rw` +!`dmb.ld` !`fence r,rw` +!`dmb.st` !`fence w,w` +!`isb` !`fence.i; fence r,r` +|=== + +<> provides a mapping from ARM memory +operations onto RISC-V memory instructions. Since RISC-V does not +currently have plain load and store opcodes with _aq_ or _rl_ +annotations, ARM load-acquire and store-release operations should be +mapped using fences instead. Furthermore, in order to enforce +store-release-to-load-acquire ordering, there must be a FENCE RW,RW +between the store-release and load-acquire; <> +enforces this by always placing the fence in front of each acquire +operation. ARM load-exclusive and store-exclusive instructions can +likewise map onto their RISC-V LR and SC equivalents, but instead of +placing a FENCE RW,RW in front of an LR with _aq_ set, we simply also +set _rl_ instead. ARM ISB maps on RISC-V to FENCE.I followed by +FENCE R,R similarly to how ISYNC maps for Power. + +[[linuxmappings]] +.Mappings from Linux memory primitives to RISC-V primitives. +[%autowidth,float="center",align="center",cols="<,<",options="header",separator=!] +|=== +!Linux Operation !RVWMO Mapping + +!`smp_mb()` !`fence rw,rw` + +!`smp_rmb()` !`fence r,r` + +!`smp_wmb()` !`fence w,w` + +!`dma_rmb()` !`fence r,r` + +!`dma_wmb()` !`fence w,w` + +!`mb()` !`fence iorw,iorw` + +!`rmb()` !`fence ri,ri` + +!`wmb()` !`fence wo,wo` + +!`smp_load_acquire()` !`l{b|h|w|d}; fence r,rw` + +!`smp_store_release()` !`fence.tso; s{b|h|w|d}` + +!Linux Construct !RVWMO AMO Mapping + +!`atomic relaxed` !`amo .{w|d}` + +!`atomic acquire` !`amo .{w|d}.aq` + +!`atomic release` !`amo .{w|d}.rl` + +!`atomic ` !`amo .{w|d}.aqrl` + +!Linux Construct !RVWMO LR/SC Mapping + +!`atomic relaxed` !`loop:lr.{w|d}; ; sc.{w|d}; bnez loop` + +!`atomic acquire` !`loop:lr.{w|d}.aq; ; sc.{w|d}; bnez loop` + +!`atomic release` !`loop:lr.{w|d}; ; sc.{w|d}.aqrl^*^; bnez loop OR` + +! !`fence.tso; loop:lr.{w|d}; ; sc.{w|d}^*^; bnez loop` + +!`atomic ` !`loop:lr.{w|d}.aq;` `; sc.{w|d}.aqrl; bnez loop` + +|=== + +With regards to <>, other +constructs (such as spinlocks) should follow accordingly. Platforms or +devices with non-coherent DMA may need additional synchronization (such +as cache flush or invalidate mechanisms); currently any such extra +synchronization will be device-specific. + +<> provides a mapping of Linux memory +ordering macros onto RISC-V memory instructions. The Linux fences +`dma_rmb()` and `dma_wmb()` map onto FENCE R,R and FENCE W,W, +respectively, since the RISC-V Unix Platform requires coherent DMA, but +would be mapped onto FENCE RI,RI and FENCE WO,WO, respectively, on a +platform with non-coherent DMA. Platforms with non-coherent DMA may also +require a mechanism by which cache lines can be flushed and/or +invalidated. Such mechanisms will be device-specific and/or standardized +in a future extension to the ISA. + +The Linux mappings for release operations may seem stronger than +necessary, but these mappings are needed to cover some cases in which +Linux requires stronger orderings than the more intuitive mappings would +provide. In particular, as of the time this text is being written, Linux +is actively debating whether to require load-load, load-store, and +store-store orderings between accesses in one critical section and +accesses in a subsequent critical section in the same hart and protected +by the same synchronization object. Not all combinations of +FENCE RW,W/FENCE R,RW mappings with _aq_/_rl_ mappings combine to +provide such orderings. There are a few ways around this problem, +including: + +. Always use FENCE RW,W/FENCE R,RW, and never use _aq_/_rl_. This +suffices but is undesirable, as it defeats the purpose of the _aq_/_rl_ +modifiers. +. Always use _aq_/_rl_, and never use FENCE RW,W/FENCE R,RW. This does +not currently work due to the lack of load and store opcodes with _aq_ +and _rl_ modifiers. +. Strengthen the mappings of release operations such that they would +enforce sufficient orderings in the presence of either type of acquire +mapping. This is the currently recommended solution, and the one shown +in <>. + +RVWMO Mapping: (a) lw a0, 0(s0) (b) fence.tso // vs. fence rw,w (c) sd +x0,0(s1) ... loop: (d) amoswap.d.aq a1,t1,0(s1) bnez a1,loop (e) lw +a2,0(s2) + +For example, the critical section ordering rule currently being debated +by the Linux community would require (a) to be ordered before (e) in +<>. If that will indeed be +required, then it would be insufficient for (b) to map as FENCE RW,W. +That said, these mappings are subject to change as the Linux Kernel +Memory Model evolves. + +[[lkmm_ll]] +.Orderings between critical sections in Linux +[source%linenums,asm] +---- +Linux Code: +(a) int r0 = *x; + (bc) spin_unlock(y, 0); +.... +.... +(d) spin_lock(y); +(e) int r1 = *z; + +RVWMO Mapping: +(a) lw a0, 0(s0) +(b) fence.tso // vs. fence rw,w +(c) sd x0,0(s1) +.... +loop: +(d) lr.d.aq a1,(s1) +bnez a1,loop +sc.d a1,t1,(s1) +bnez a1,loop +(e) lw a2,0(s2) +---- + +<> provides a mapping of C11/C++11 atomic +operations onto RISC-V memory instructions. If load and store opcodes +with _aq_ and _rl_ modifiers are introduced, then the mappings in +<> will suffice. Note however that +the two mappings only interoperate correctly if +`atomic_(memory_order_seq_cst)` is mapped using an LR that has both +_aq_ and _rl_ set. +Even more importantly, a <> sequentially consistent store, +followed by a <> sequentially consistent load +can be reordered unless the <> mapping of stores is +strengthened by either adding a second fence or mapping the store +to `amoswap.rl` instead. + +[[c11mappings]] +.Mappings from C/C++ primitives to RISC-V primitives. +[%autowidth,float="center",align="center",cols="<,<",options="header",separator=!] +|=== + +!C/C++ Construct ! RVWMO Mapping + +!Non-atomic load ! `l{b|h|w|d}` + +!`atomic_load(memory_order_relaxed)` !`l{b|h|w|d}` + +!`atomic_load(memory_order_acquire)` !`l{b|h|w|d}; fence r,rw` + +!`atomic_load(memory_order_seq_cst)` !`fence rw,rw; l{b|h|w|d}; fence r,rw` + +!Non-atomic store !`s{b|h|w|d}` + +!`atomic_store(memory_order_relaxed)` !`s{b|h|w|d}` + +!`atomic_store(memory_order_release)` !`fence rw,w; s{b|h|w|d}` + +!`atomic_store(memory_order_seq_cst)` !`fence rw,w; s{b|h|w|d}` + +!`atomic_thread_fence(memory_order_acquire)` !`fence r,rw` + +!`atomic_thread_fence(memory_order_release)` !`fence rw,w` + +!`atomic_thread_fence(memory_order_acq_rel)` !`fence.tso` + +!`atomic_thread_fence(memory_order_seq_cst)` !`fence rw,rw` + +!C/C++ Construct !RVWMO AMO Mapping + +!`atomic_(memory_order_relaxed)` !`amo.{w|d}` + +!`atomic_(memory_order_acquire)` !`amo.{w|d}.aq` + +!`atomic_(memory_order_release)` !`amo.{w|d}.rl` + +!`atomic_(memory_order_acq_rel)` !`amo.{w|d}.aqrl` + +!`atomic_(memory_order_seq_cst)` !`amo.{w|d}.aqrl` + +!C/C++ Construct !RVWMO LR/SC Mapping + +!`atomic_(memory_order_relaxed)` !`loop:lr.{w|d}; ; sc.{w|d};` + +! !`bnez loop` + +!`atomic_(memory_order_acquire)` !`loop:lr.{w|d}.aq; ; sc.{w|d};` + +! !`bnez loop` + +!`atomic_(memory_order_release)` !`loop:lr.{w|d}; ; sc.{w|d}.rl;` + +! !`bnez loop` + +!`atomic_(memory_order_acq_rel)` !`loop:lr.{w|d}.aq; ; sc.{w|d}.rl;` + +! !`bnez loop` + +!`atomic_(memory_order_seq_cst)` !`loop:lr.{w|d}.aqrl; ;` + +! !`sc.{w|d}.rl; bnez loop` + +|=== + +[[c11mappings_hypothetical]] +.Hypothetical mappings from C/C++ primitives to RISC-V primitives, if native load-acquire and store-release opcodes are introduced. +[%autowidth,float="center",align="center",cols="<,<",options="header",separator=!] +|=== +!C/C++ Construct !RVWMO Mapping + +!Non-atomic load !`l{b|h|w|d}` + +!`atomic_load(memory_order_relaxed)` !`l{b|h|w|d}` + +!`atomic_load(memory_order_acquire)` !`l{b|h|w|d}.aq` + +!`atomic_load(memory_order_seq_cst)` !`l{b|h|w|d}.aq` + +!Non-atomic store !`s{b|h|w|d}` + +!`atomic_store(memory_order_relaxed)` !`s{b|h|w|d}` + +!`atomic_store(memory_order_release)` !`s{b|h|w|d}.rl` + +!`atomic_store(memory_order_seq_cst)` !`s{b|h|w|d}.rl` + +!`atomic_thread_fence(memory_order_acquire)` !`fence r,rw` + +!`atomic_thread_fence(memory_order_release)` !`fence rw,w` + +!`atomic_thread_fence(memory_order_acq_rel)` !`fence.tso` + +!`atomic_thread_fence(memory_order_seq_cst)` !`fence rw,rw` + +!C/C++ Construct !RVWMO AMO Mapping + +!`atomic_(memory_order_relaxed)` !`amo.{w|d}` + +!`atomic_(memory_order_acquire)` !`amo.{w|d}.aq` + +!`atomic_(memory_order_release)` !`amo.{w|d}.rl` + +!`atomic_(memory_order_acq_rel)` !`amo.{w|d}.aqrl` + +!`atomic_(memory_order_seq_cst)` !`amo.{w|d}.aqrl` + +!C/C++ Construct !RVWMO LR/SC Mapping + +!`atomic_(memory_order_relaxed)` !`lr.{w|d}; ; sc.{w|d}` + +!`atomic_(memory_order_acquire)` !`lr.{w|d}.aq; ; sc.{w|d}` + +!`atomic_(memory_order_release)` !`lr.{w|d}; ; sc.{w|d}.rl` + +!`atomic_(memory_order_acq_rel)` !`lr.{w|d}.aq; ; sc.{w|d}.rl` + +!`atomic_(memory_order_seq_cst)` !`lr.{w|d}.aq^*^ ; sc.{w|d}.rl` + +2+!^*^ must be `lr.{w|d}.aqrl` in order to interoperate with code mapped per <> +|=== + +Any AMO can be emulated by an LR/SC pair, but care must be taken to +ensure that any PPO orderings that originate from the LR are also made +to originate from the SC, and that any PPO orderings that terminate at +the SC are also made to terminate at the LR. For example, the LR must +also be made to respect any data dependencies that the AMO has, given +that load operations do not otherwise have any notion of a data +dependency. Likewise, the effect a FENCE R,R elsewhere in the same hart +must also be made to apply to the SC, which would not otherwise respect +that fence. The emulator may achieve this effect by simply mapping AMOs +onto `lr.aq; ; sc.aqrl`, matching the mapping used elsewhere for +fully ordered atomics. + +These C11/C++11 mappings require the platform to provide the following +Physical Memory Attributes (as defined in the RISC-V Privileged ISA) for +all memory: + +* main memory +* coherent +* AMOArithmetic +* RsrvEventual + +Platforms with different attributes may require different mappings, or +require platform-specific SW (e.g., memory-mapped I/O). + +=== Implementation Guidelines + +The RVWMO and RVTSO memory models by no means preclude +microarchitectures from employing sophisticated speculation techniques +or other forms of optimization in order to deliver higher performance. +The models also do not impose any requirement to use any one particular +cache hierarchy, nor even to use a cache coherence protocol at all. +Instead, these models only specify the behaviors that can be exposed to +software. Microarchitectures are free to use any pipeline design, any +coherent or non-coherent cache hierarchy, any on-chip interconnect, +etc., as long as the design only admits executions that satisfy the +memory model rules. That said, to help people understand the actual +implementations of the memory model, in this section we provide some +guidelines on how architects and programmers should interpret the +models' rules. + +Both RVWMO and RVTSO are multi-copy atomic (or +_other-multi-copy-atomic_): any store value that is visible to a hart +other than the one that originally issued it must also be conceptually +visible to all other harts in the system. In other words, harts may +forward from their own previous stores before those stores have become +globally visible to all harts, but no early inter-hart forwarding is +permitted. Multi-copy atomicity may be enforced in a number of ways. It +might hold inherently due to the physical design of the caches and store +buffers, it may be enforced via a single-writer/multiple-reader cache +coherence protocol, or it might hold due to some other mechanism. + +Although multi-copy atomicity does impose some restrictions on the +microarchitecture, it is one of the key properties keeping the memory +model from becoming extremely complicated. For example, a hart may not +legally forward a value from a neighbor hart's private store buffer +(unless of course it is done in such a way that no new illegal behaviors +become architecturally visible). Nor may a cache coherence protocol +forward a value from one hart to another until the coherence protocol +has invalidated all older copies from other caches. Of course, +microarchitectures may (and high-performance implementations likely +will) violate these rules under the covers through speculation or other +optimizations, as long as any non-compliant behaviors are not exposed to +the programmer. + +As a rough guideline for interpreting the PPO rules in RVWMO, we expect +the following from the software perspective: + +* programmers will use PPO rules <> and <> regularly and actively. +* expert programmers will use PPO rules <> to speed up critical paths +of important data structures. +* even expert programmers will rarely if ever use PPO rules <> and +<> directly. +These are included to facilitate common microarchitectural optimizations +(rule <>) and the operational formal modeling approach (rules <> and +<>) described +in <>. They also facilitate the +process of porting code from other architectures that have similar +rules. + +We also expect the following from the hardware perspective: + +* PPO rules <> and <> reflect +well-understood rules that should pose few surprises to architects. +* PPO rule <> reflects a natural and common hardware +optimization, but one that is very subtle and hence is worth double +checking carefully. +* PPO rule <> may not be immediately obvious to +architects, but it is a standard memory model requirement +* The load value axiom, the atomicity axiom, and PPO rules +<> reflect rules that most +hardware implementations will enforce naturally, unless they contain +extreme optimizations. Of course, implementations should make sure to +double check these rules nevertheless. Hardware must also ensure that +syntactic dependencies are not `optimized away`. + +Architectures are free to implement any of the memory model rules as +conservatively as they choose. For example, a hardware implementation +may choose to do any or all of the following: + +* interpret all fences as if they were FENCE RW,RW (or FENCE IORW,IORW, +if I/O is involved), regardless of the bits actually set +* implement all fences with PW and SR as if they were FENCE RW,RW (or +FENCE IORW,IORW, if I/O is involved), as PW with SR is the most +expensive of the four possible main memory ordering components anyway +* emulate _aq_ and _rl_ as described in <> +* enforcing all same-address load-load ordering, even in the presence of +patterns such as `fri-rfi` and `RSW` +* forbid any forwarding of a value from a store in the store buffer to a +subsequent AMO or LR to the same address +* forbid any forwarding of a value from an AMO or SC in the store buffer +to a subsequent load to the same address +* implement TSO on all memory accesses, and ignore any main memory +fences that do not include PW and SR ordering (e.g., as Ztso +implementations will do) +* implement all atomics to be RCsc or even fully ordered, regardless of +annotation + +Architectures that implement RVTSO can safely do the following: + +* Ignore all fences that do not have both PW and SR (unless the fence +also orders I/O) +* Ignore all PPO rules except for rules <> through <>, since the rest +are redundant with other PPO rules under RVTSO assumptions + +Other general notes: + +* Silent stores (i.e., stores that write the same value that already +exists at a memory location) behave like any other store from a memory +model point of view. Likewise, AMOs which do not actually change the +value in memory (e.g., an AMOMAX for which the value in _rs2_ is smaller +than the value currently in memory) are still semantically considered +store operations. Microarchitectures that attempt to implement silent +stores must take care to ensure that the memory model is still obeyed, +particularly in cases such as RSW <> +which tend to be incompatible with silent stores. +* Writes may be merged (i.e., two consecutive writes to the same address +may be merged) or subsumed (i.e., the earlier of two back-to-back writes +to the same address may be elided) as long as the resulting behavior +does not otherwise violate the memory model semantics. + +The question of write subsumption can be understood from the following +example: + +.Write subsumption litmus test, allowed execution +[float="center",align="center",cols=".^1a,.^1a",frame="none",grid="none",options="noheader"] +|=== +| +[%autowidth,float="center",align="center",cols="^,<,^,<",options="header",] +!=== +2+!Hart 0 2+^!Hart 1 +2+!li t1, 3 2+^!li t3, 2 +! !li t2, 1 ! ! +!(a) !sw t1,0(s0) !(d) !lw a0,0(s1) +!(b) !fence w, w !(e) !sw a0,0(s0) +!(c) !sw t2,0(s1) !(f) !sw t3,0(s0) +!=== +| +!=== +//a! graphviz::images/graphviz/litmus_subsumption.txt[] +a! image::graphviz/litmus_subsumption.png[] +!=== +|=== + +As written, if the load (d) reads value _1_, then (a) must +precede (f) in the global memory order: + +* (a) precedes (c) in the global memory order because of rule 4 +* (c) precedes (d) in the global memory order because of the Load +Value axiom +* (d) precedes (e) in the global memory order because of rule 10 +* (e) precedes (f) in the global memory order because of rule 1 + +In other words the final value of the memory location whose address is +in `s0` must be _2_ (the value written by the store (f)) and +cannot be _3_ (the value written by the store (a)). + +A very aggressive microarchitecture might erroneously decide to discard +(e), as (f) supersedes it, and this may in turn lead the +microarchitecture to break the now-eliminated dependency between (d) and +(f) (and hence also between (a) and (f)). This would violate the memory +model rules, and hence it is forbidden. Write subsumption may in other +cases be legal, if for example there were no data dependency between (d) +and (e). + +==== Possible Future Extensions + +We expect that any or all of the following possible future extensions +would be compatible with the RVWMO memory model: + +* "V" vector ISA extensions +* "J" JIT extension +* Native encodings for load and store opcodes with _aq_ and _rl_ set +* Fences limited to certain addresses +* Cache write-back/flush/invalidate/etc.instructions + +[[discrepancies]] +=== Known Issues + +[[mixedrsw]] +==== Mixed-size RSW + +[[rsw1]] +.Mixed-size discrepancy (permitted by axiomatic models, forbidden by operational model) +[%autowidth,float="center",align="center",cols="^,<,^,<",options="header",] +|=== +2+|Hart 0 2+^|Hart 1 +2+|li t1, 1 2+^|li t1, 1 +|(a) |lw a0,0(s0) |(d) |lw a1,0(s1) +|(b) |fence rw,rw |(e) |amoswap.w.rl a2,t1,0(s2) +|(c) |sw t1,0(s1) |(f) |ld a3,0(s2) +| | |(g) |lw a4,4(s2) +| | | |xor a5,a4,a4 +| | | |add s0,s0,a5 +| | |(h) |sw t1,0(s0) +4+|Outcome: `a0=1`, `a1=1`, `a2=0`, `a3=1`, `a4=0` +|=== + +[[rsw2]] +.Mixed-size discrepancy (permitted by axiomatic models, forbidden by operational model) +[%autowidth,float="center",align="center",cols="^,<,^,<",options="header"] +|=== +2+|Hart 0 2+^|Hart 1 +2+|li t1, 1 2+^|li t1, 1 +|(a) |lw a0,0(s0) |(d) |ld a1,0(s1) +|(b) |fence rw,rw |(e) |lw a2,4(s1) +|(c) |sw t1,0(s1) | |xor a3,a2,a2 +| | | |add s0,s0,a3 +| | |(f) |sw t1,0(s0) +4+|Outcome: `a0=1`, `a1=1`, `a2=0` +|=== + +[[rsw3]] +.Mixed-size discrepancy (permitted by axiomatic models, forbidden by operational model) +[%autowidth,float="center",align="center",cols="^,<,^,<",options="header",] +|=== +2+|Hart 0 2+^|Hart 1 +2+|li t1, 1 2+^|li t1, 1 +|(a) |lw a0,0(s0) |(d) |sw t1,4(s1) +|(b) |fence rw,rw |(e) |ld a1,0(s1) +|(c) |sw t1,0(s1) |(f) |lw a2,4(s1) +| | | |xor a3,a2,a2 +| | | |add s0,s0,a3 +| | |(g) |sw t1,0(s0) +4+|Outcome: `a0=1`, `a1=0x100000001`, `a2=1` +|=== + +There is a known discrepancy between the operational and axiomatic +specifications within the family of mixed-size RSW variants shown in +<>-<>. +To address this, we may choose to add something like the following new +PPO rule: Memory operation _a_ precedes memory operation +_b_ in preserved program order (and hence also in the global +memory order) if _a_ precedes _b_ in program +order, _a_ and _b_ both access regular main +memory (rather than I/O regions), _a_ is a load, +_b_ is a store, there is a load _m_ between +_a_ and _b_, there is a byte _x_ +that both _a_ and _m_ read, there is no store +between _a_ and _m_ that writes to +_x_, and _m_ precedes _b_ in PPO. In +other words, in herd syntax, we may choose to add +`(po-loc & rsw);ppo;[W]` to PPO. Many implementations will already +enforce this ordering naturally. As such, even though this rule is not +official, we recommend that implementers enforce it nevertheless in +order to ensure forwards compatibility with the possible future addition +of this rule to RVWMO. diff --git a/param_extraction/chunks/chunk_022.txt.license b/param_extraction/chunks/chunk_022.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_022.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_023.txt b/param_extraction/chunks/chunk_023.txt new file mode 100644 index 0000000000..364ac0d57b --- /dev/null +++ b/param_extraction/chunks/chunk_023.txt @@ -0,0 +1,1442 @@ +# Chunk: chunk_023 +# Source: mm-formal.adoc +# Lines: 1-1425 (of 1425) +# Content starts: line 1 +# Line count: 1425 +# Sections: 10 +# == Formal Memory Model Specifications, Version 0.1 +# === Formal Axiomatic Specification in Alloy +# === Formal Axiomatic Specification in Herd +# === An Operational Memory Model +# ==== Intra-instruction Pseudocode Execution +# ==== Instruction Instance State +# ==== Hart State +# ==== Shared Memory State +# ==== Transitions +# ===== Fetch instruction +# +[appendix] +== Formal Memory Model Specifications, Version 0.1 +[[mm-formal]] + +To facilitate formal analysis of RVWMO, this chapter presents a set of +formalizations using different tools and modeling approaches. Any +discrepancies are unintended; the expectation is that the models +describe exactly the same sets of legal behaviors. + +This appendix should be treated as commentary; all normative material is +provided in <> and in the rest of +the main body of the ISA specification. +All currently known discrepancies are listed in <>. +Any other discrepancies are unintentional. + +[[alloy]] +=== Formal Axiomatic Specification in Alloy + +We present a formal specification of the RVWMO memory model in Alloy +(http://alloy.mit.edu). This model is available online at +https://github.com/daniellustig/riscv-memory-model. + +The online material also contains some litmus tests and some examples of +how Alloy can be used to model check some of the mappings in <>. + +.The RVWMO memory model formalized in Alloy (1/5: PPO) +[source,c] +---- +// =RVWMO PPO= + +// Preserved Program Order +fun ppo : Event->Event { + // same-address ordering + po_loc :> Store + + rdw + + (AMO + StoreConditional) <: rfi + + // explicit synchronization + + ppo_fence + + Acquire <: ^po :> MemoryEvent + + MemoryEvent <: ^po :> Release + + RCsc <: ^po :> RCsc + + pair + + // syntactic dependencies + + addrdep + + datadep + + ctrldep :> Store + + // pipeline dependencies + + (addrdep+datadep).rfi + + addrdep.^po :> Store +} + +// the global memory order respects preserved program order +fact { ppo in ^gmo } +---- + +.The RVWMO memory model formalized in Alloy (2/5: Axioms) +[,io] +.... +// =RVWMO axioms= + +// Load Value Axiom +fun candidates[r: MemoryEvent] : set MemoryEvent { + (r.~^gmo & Store & same_addr[r]) // writes preceding r in gmo + + (r.^~po & Store & same_addr[r]) // writes preceding r in po +} + +fun latest_among[s: set Event] : Event { s - s.~^gmo } + +pred LoadValue { + all w: Store | all r: Load | + w->r in rf <=> w = latest_among[candidates[r]] +} + +// Atomicity Axiom +pred Atomicity { + all r: Store.~pair | // starting from the lr, + no x: Store & same_addr[r] | // there is no store x to the same addr + x not in same_hart[r] // such that x is from a different hart, + and x in r.~rf.^gmo // x follows (the store r reads from) in gmo, + and r.pair in x.^gmo // and r follows x in gmo +} + +// Progress Axiom implicit: Alloy only considers finite executions + +pred RISCV_mm { LoadValue and Atomicity /* and Progress */ } +.... + + +.The RVWMO memory model formalized in Alloy (3/5: model of memory) +[source,sml] +.... +//Basic model of memory + +sig Hart { // hardware thread + start : one Event +} +sig Address {} +abstract sig Event { + po: lone Event // program order +} + +abstract sig MemoryEvent extends Event { + address: one Address, + acquireRCpc: lone MemoryEvent, + acquireRCsc: lone MemoryEvent, + releaseRCpc: lone MemoryEvent, + releaseRCsc: lone MemoryEvent, + addrdep: set MemoryEvent, + ctrldep: set Event, + datadep: set MemoryEvent, + gmo: set MemoryEvent, // global memory order + rf: set MemoryEvent +} +sig LoadNormal extends MemoryEvent {} // l{b|h|w|d} +sig LoadReserve extends MemoryEvent { // lr + pair: lone StoreConditional +} +sig StoreNormal extends MemoryEvent {} // s{b|h|w|d} +// all StoreConditionals in the model are assumed to be successful +sig StoreConditional extends MemoryEvent {} // sc +sig AMO extends MemoryEvent {} // amo +sig NOP extends Event {} + +fun Load : Event { LoadNormal + LoadReserve + AMO } +fun Store : Event { StoreNormal + StoreConditional + AMO } + +sig Fence extends Event { + pr: lone Fence, // opcode bit + pw: lone Fence, // opcode bit + sr: lone Fence, // opcode bit + sw: lone Fence // opcode bit +} +sig FenceTSO extends Fence {} + +/* Alloy encoding detail: opcode bits are either set (encoded, e.g., + * as f.pr in iden) or unset (f.pr not in iden). The bits cannot be used for + * anything else */ +fact { pr + pw + sr + sw in iden } +// likewise for ordering annotations +fact { acquireRCpc + acquireRCsc + releaseRCpc + releaseRCsc in iden } +// don't try to encode FenceTSO via pr/pw/sr/sw; just use it as-is +fact { no FenceTSO.(pr + pw + sr + sw) } +.... + +.The RVWMO memory model formalized in Alloy (4/5: Basic model rules) +[source,scala] +.... +// =Basic model rules= + +// Ordering annotation groups +fun Acquire : MemoryEvent { MemoryEvent.acquireRCpc + MemoryEvent.acquireRCsc } +fun Release : MemoryEvent { MemoryEvent.releaseRCpc + MemoryEvent.releaseRCsc } +fun RCpc : MemoryEvent { MemoryEvent.acquireRCpc + MemoryEvent.releaseRCpc } +fun RCsc : MemoryEvent { MemoryEvent.acquireRCsc + MemoryEvent.releaseRCsc } + +// There is no such thing as store-acquire or load-release, unless it's both +fact { Load & Release in Acquire } +fact { Store & Acquire in Release } + +// FENCE PPO +fun FencePRSR : Fence { Fence.(pr & sr) } +fun FencePRSW : Fence { Fence.(pr & sw) } +fun FencePWSR : Fence { Fence.(pw & sr) } +fun FencePWSW : Fence { Fence.(pw & sw) } + +fun ppo_fence : MemoryEvent->MemoryEvent { + (Load <: ^po :> FencePRSR).(^po :> Load) + + (Load <: ^po :> FencePRSW).(^po :> Store) + + (Store <: ^po :> FencePWSR).(^po :> Load) + + (Store <: ^po :> FencePWSW).(^po :> Store) + + (Load <: ^po :> FenceTSO) .(^po :> MemoryEvent) + + (Store <: ^po :> FenceTSO) .(^po :> Store) +} + +// auxiliary definitions +fun po_loc : Event->Event { ^po & address.~address } +fun same_hart[e: Event] : set Event { e + e.^~po + e.^po } +fun same_addr[e: Event] : set Event { e.address.~address } + +// initial stores +fun NonInit : set Event { Hart.start.*po } +fun Init : set Event { Event - NonInit } +fact { Init in StoreNormal } +fact { Init->(MemoryEvent & NonInit) in ^gmo } +fact { all e: NonInit | one e.*~po.~start } // each event is in exactly one hart +fact { all a: Address | one Init & a.~address } // one init store per address +fact { no Init <: po and no po :> Init } +.... + +.The RVWMO memory model formalized in Alloy (5/5: Auxiliaries) +[source,asm] +.... +// po +fact { acyclic[po] } + +// gmo +fact { total[^gmo, MemoryEvent] } // gmo is a total order over all MemoryEvents + +//rf +fact { rf.~rf in iden } // each read returns the value of only one write +fact { rf in Store <: address.~address :> Load } +fun rfi : MemoryEvent->MemoryEvent { rf & (*po + *~po) } + +//dep +fact { no StoreNormal <: (addrdep + ctrldep + datadep) } +fact { addrdep + ctrldep + datadep + pair in ^po } +fact { datadep in datadep :> Store } +fact { ctrldep.*po in ctrldep } +fact { no pair & (^po :> (LoadReserve + StoreConditional)).^po } +fact { StoreConditional in LoadReserve.pair } // assume all SCs succeed + +// rdw +fun rdw : Event->Event { + (Load <: po_loc :> Load) // start with all same_address load-load pairs, + - (~rf.rf) // subtract pairs that read from the same store, + - (po_loc.rfi) // and subtract out "fri-rfi" patterns +} + +// filter out redundant instances and/or visualizations +fact { no gmo & gmo.gmo } // keep the visualization uncluttered +fact { all a: Address | some a.~address } + +// =Optional: opcode encoding restrictions= + +// the list of blessed fences +fact { Fence in + Fence.pr.sr + + Fence.pw.sw + + Fence.pr.pw.sw + + Fence.pr.sr.sw + + FenceTSO + + Fence.pr.pw.sr.sw +} + +pred restrict_to_current_encodings { + no (LoadNormal + StoreNormal) & (Acquire + Release) +} + +// =Alloy shortcuts= +pred acyclic[rel: Event->Event] { no iden & ^rel } +pred total[rel: Event->Event, bag: Event] { + all disj e, f: bag | e->f in rel + ~rel + acyclic[rel] +} +.... + +[[sec:herd]] +=== Formal Axiomatic Specification in Herd + +The tool [.sans-serif]#herd# takes a memory model and a litmus test as +input and simulates the execution of the test on top of the memory +model. Memory models are written in the domain specific language Cat. +This section provides two Cat memory model of RVWMO. The first model, +<>, follows the _global memory order_, +<>, definition of RVWMO, as much +as is possible for a Cat model. The second model, +<>, is an equivalent, more efficient, +partial order based RVWMO model. + +The simulator `herd` is part of the `diy` tool +suite — see http://diy.inria.fr for software and documentation. The +models and more are available online at http://diy.inria.fr/cats7/riscv/. +[[herd1]] +.riscv-defs.cat, a herd definition of preserved program order (1/3) +[source,asm] +.... +(*************) +(* Utilities *) +(*************) + +(* All fence relations *) +let fence.r.r = [R];fencerel(Fence.r.r);[R] +let fence.r.w = [R];fencerel(Fence.r.w);[W] +let fence.r.rw = [R];fencerel(Fence.r.rw);[M] +let fence.w.r = [W];fencerel(Fence.w.r);[R] +let fence.w.w = [W];fencerel(Fence.w.w);[W] +let fence.w.rw = [W];fencerel(Fence.w.rw);[M] +let fence.rw.r = [M];fencerel(Fence.rw.r);[R] +let fence.rw.w = [M];fencerel(Fence.rw.w);[W] +let fence.rw.rw = [M];fencerel(Fence.rw.rw);[M] +let fence.tso = + let f = fencerel(Fence.tso) in + ([W];f;[W]) | ([R];f;[M]) + +let fence = + fence.r.r | fence.r.w | fence.r.rw | + fence.w.r | fence.w.w | fence.w.rw | + fence.rw.r | fence.rw.w | fence.rw.rw | + fence.tso + +(* Same address, no W to the same address in-between *) +let po-loc-no-w = po-loc \ (po-loc?;[W];po-loc) +(* Read same write *) +let rsw = rf^-1;rf +(* Acquire, or stronger *) +let AQ = Acq|AcqRel +(* Release or stronger *) +and RL = RelAcqRel +(* All RCsc *) +let RCsc = Acq|Rel|AcqRel +(* Amo events are both R and W, relation rmw relates paired lr/sc *) +let AMO = R & W +let StCond = range(rmw) + +(*************) +(* ppo rules *) +(*************) + +(* Overlapping-Address Orderings *) +let r1 = [M];po-loc;[W] +and r2 = ([R];po-loc-no-w;[R]) \ rsw +and r3 = [AMO|StCond];rfi;[R] +(* Explicit Synchronization *) +and r4 = fence +and r5 = [AQ];po;[M] +and r6 = [M];po;[RL] +and r7 = [RCsc];po;[RCsc] +and r8 = rmw +(* Syntactic Dependencies *) +and r9 = [M];addr;[M] +and r10 = [M];data;[W] +and r11 = [M];ctrl;[W] +(* Pipeline Dependencies *) +and r12 = [R];(addr|data);[W];rfi;[R] +and r13 = [R];addr;[M];po;[W] + +let ppo = r1 | r2 | r3 | r4 | r5 | r6 | r7 | r8 | r9 | r10 | r11 | r12 | r13 +.... +[[herd2]] +.riscv.cat, a herd version of the RVWMO memory model (2/3) +[source,asm] +.... +Total + +(* Notice that herd has defined its own rf relation *) + +(* Define ppo *) +include "riscv-defs.cat" + +(********************************) +(* Generate global memory order *) +(********************************) + +let gmo0 = (* precursor: ie build gmo as an total order that include gmo0 *) + loc & (W\FW) * FW | # Final write after any write to the same location + ppo | # ppo compatible + rfe # includes herd external rf (optimization) + +(* Walk over all linear extensions of gmo0 *) +with gmo from linearizations(M\IW,gmo0) + +(* Add initial writes upfront -- convenient for computing rfGMO *) +let gmo = gmo | loc & IW * (M\IW) + +(**********) +(* Axioms *) +(**********) + +(* Compute rf according to the load value axiom, aka rfGMO *) +let WR = loc & ([W];(gmo|po);[R]) +let rfGMO = WR \ (loc&([W];gmo);WR) + +(* Check equality of herd rf and of rfGMO *) +empty (rf\rfGMO)|(rfGMO\rf) as RfCons + +(* Atomicity axiom *) +let infloc = (gmo & loc)^-1 +let inflocext = infloc & ext +let winside = (infloc;rmw;inflocext) & (infloc;rf;rmw;inflocext) & [W] +empty winside as Atomic +.... +[[herd3]] +.`riscv.cat`, an alternative herd presentation of the RVWMO memory model (3/3) +[source,asm] +.... +Partial + +(***************) +(* Definitions *) +(***************) + +(* Define ppo *) +include "riscv-defs.cat" + +(* Compute coherence relation *) +include "cos-opt.cat" + +(**********) +(* Axioms *) +(**********) + +(* Sc per location *) +acyclic co|rf|fr|po-loc as Coherence + +(* Main model axiom *) +acyclic co|rfe|fr|ppo as Model + +(* Atomicity axiom *) +empty rmw & (fre;coe) as Atomic +.... + +[[operational]] +=== An Operational Memory Model + +This is an alternative presentation of the RVWMO memory model in +operational style. It aims to admit exactly the same extensional +behavior as the axiomatic presentation: for any given program, admitting +an execution if and only if the axiomatic presentation allows it. + +The axiomatic presentation is defined as a predicate on complete +candidate executions. In contrast, this operational presentation has an +abstract microarchitectural flavor: it is expressed as a state machine, +with states that are an abstract representation of hardware machine +states, and with explicit out-of-order and speculative execution (but +abstracting from more implementation-specific microarchitectural details +such as register renaming, store buffers, cache hierarchies, cache +protocols, etc.). As such, it can provide useful intuition. It can also +construct executions incrementally, making it possible to interactively +and randomly explore the behavior of larger examples, while the +axiomatic model requires complete candidate executions over which the +axioms can be checked. + +The operational presentation covers mixed-size execution, with +potentially overlapping memory accesses of different power-of-two byte +sizes. Misaligned accesses are broken up into single-byte accesses. + +The operational model, together with a fragment of the RISC-V ISA +semantics (RV64I and A), are integrated into the `rmem` exploration tool +(https://github.com/rems-project/rmem). `rmem` can explore litmus tests +(see <>) and small ELF binaries +exhaustively, pseudorandomly and interactively. In `rmem`, the ISA +semantics is expressed explicitly in Sail (see +https://github.com/rems-project/sail for the Sail language, and +https://github.com/rems-project/sail-riscv for the RISC-V ISA model), +and the concurrency semantics is expressed in Lem (see +https://github.com/rems-project/lem for the Lem language). + +`rmem` has a command-line interface and a web-interface. The +web-interface runs entirely on the client side, and is provided online +together with a library of litmus tests: +http://www.cl.cam.ac.uk/. The command-line interface is +faster than the web-interface, specially in exhaustive mode. + +Below is an informal introduction of the model states and transitions. +The description of the formal model starts in the next subsection. + +Terminology: In contrast to the axiomatic presentation, here every +memory operation is either a load or a store. Hence, AMOs give rise to +two distinct memory operations, a load and a store. When used in +conjunction with `instruction`, the terms `load` and `store` refer +to instructions that give rise to such memory operations. As such, both +include AMO instructions. The term `acquire` refers to an instruction +(or its memory operation) with the acquire-RCpc or acquire-RCsc +annotation. The term `release` refers to an instruction (or its memory +operation) with the release-RCpc or release-RCsc annotation. + +*Model states* + +Model states: A model state consists of a shared memory and a tuple of hart states. + + +["ditaa",shadows=false, separation=false, fontsize: 14,float="center"] +.... ++----------+ +---------+ +| Hart 0 | ... | Trace | ++----------+ +---------+ + ↑ ↓ ↑ ↓ ++--------------------------+ +| Shared memory | ++--------------------------+ +.... + +The shared memory state records all the memory store operations that +have propagated so far, in the order they propagated (this can be made +more efficient, but for simplicity of the presentation we keep it this +way). + +Each hart state consists principally of a tree of instruction instances, +some of which have been _finished_, and some of which have not. +Non-finished instruction instances can be subject to _restart_, e.g. if +they depend on an out-of-order or speculative load that turns out to be +unsound. + +Conditional branch and indirect jump instructions may have multiple +successors in the instruction tree. When such instruction is finished, +any un-taken alternative paths are discarded. + +Each instruction instance in the instruction tree has a state that +includes an execution state of the intra-instruction semantics (the ISA +pseudocode for this instruction). The model uses a formalization of the +intra-instruction semantics in Sail. One can think of the execution +state of an instruction as a representation of the pseudocode control +state, pseudocode call stack, and local variable values. An instruction +instance state also includes information about the instance's memory and +register footprints, its register reads and writes, its memory +operations, whether it is finished, etc. + +*Model transitions* + +The model defines, for any model state, the set of allowed transitions, +each of which is a single atomic step to a new abstract machine state. +Execution of a single instruction will typically involve many +transitions, and they may be interleaved in operational-model execution +with transitions arising from other instructions. Each transition arises +from a single instruction instance; it will change the state of that +instance, and it may depend on or change the rest of its hart state and +the shared memory state, but it does not depend on other hart states, +and it will not change them. The transitions are introduced below and +defined in <>, with a precondition and +a construction of the post-transition model state for each. + +Transitions for all instructions: + +* <>: This transition represents a fetch and decode of a new instruction instance, as a program order successor of a previously fetched +instruction instance (or the initial fetch address). + +The model assumes the instruction memory is fixed; it does not describe +the behavior of self-modifying code. In particular, the <> transition does +not generate memory load operations, and the shared memory is not +involved in the transition. Instead, the model depends on an external +oracle that provides an opcode when given a memory location. + +[circle] +* <>: This is a write of a register value. + +* <>: This is a read of a register value from the most recent +program-order-predecessor instruction instance that writes to that +register. + +* <>: This covers pseudocode internal computation: arithmetic, function +calls, etc. + +* <>: At this point the instruction pseudocode is done, the instruction cannot be restarted, memory accesses cannot be discarded, and all memory +effects have taken place. For conditional branch and indirect jump +instructions, any program order successors that were fetched from an +address that is not the one that was written to the _pc_ register are +discarded, together with the sub-tree of instruction instances below +them. + +Transitions specific to load instructions: + +[circle] +* <>: At this point the memory footprint of the load instruction is +provisionally known (it could change if earlier instructions are +restarted) and its individual memory load operations can start being +satisfied. + +[disc] +* <>: This partially or entirely satisfies a single memory load operation by forwarding, from program-order-previous memory store operations. + +* <>: This entirely satisfies the outstanding slices of a single memory +load operation, from memory. + +[circle] +* <>: At this point all the memory load operations of the instruction have +been entirely satisfied and the instruction pseudocode can continue +executing. A load instruction can be subject to being restarted until +the transition. But, under some conditions, the model might treat a load +instruction as non-restartable even before it is finished (e.g. see ). + +Transitions specific to store instructions: + +[circle] +* <>: At this point the memory footprint of the store is provisionally +known. + +* <>: At this point the memory store operations have their values and +program-order-successor memory load operations can be satisfied by +forwarding from them. + +* <>: At this point the store operations are guaranteed to happen (the +instruction can no longer be restarted or discarded), and they can start +being propagated to memory. + +[disc] +* <>: This propagates a single memory store operation to memory. + +[circle] +* <>: At this point all the memory store operations of the instruction +have been propagated to memory, and the instruction pseudocode can +continue executing. + +Transitions specific to `sc` instructions: + +[disc] +* <>: This causes the `sc` to fail, either a spontaneous fail or because it is not paired with a program-order-previous `lr`. + +* <>: This transition indicates the `sc` is paired with an `lr` and might +succeed. + +* <>: This is an atomic execution of the transitions <> and <>, it is enabled +only if the stores from which the `lr` read from have not been +overwritten. + +* <>: This causes the `sc` to fail, either a spontaneous fail or because +the stores from which the `lr` read from have been overwritten. + +Transitions specific to AMO instructions: + +[disc] +* <>: This is an atomic execution of all the transitions needed to satisfy +the load operation, do the required arithmetic, and propagate the store +operation. + +Transitions specific to fence instructions: + +[circle] +* <> + +The transitions labeled {circ} can always be taken eagerly, +as soon as their precondition is satisfied, without excluding other +behavior; the {bullet} cannot. Although <> is marked with a +{bullet}, it can be taken eagerly as long as it is not +taken infinitely many times. + +An instance of a non-AMO load instruction, after being fetched, will +typically experience the following transitions in this order: + +. <> +. <> +. <> and/or <> (as many as needed to satisfy all the load operations of the +instance) +. <> +. <> +. <> + +Before, between, and after the transitions above, any number of +<> transitions may appear. In addition, a <> transition for fetching the +instruction in the next program location will be available until it is +taken. + +This concludes the informal description of the operational model. The +following sections describe the formal operational model. + +[[pseudocode_exec]] +==== Intra-instruction Pseudocode Execution + +The intra-instruction semantics for each instruction instance is +expressed as a state machine, essentially running the instruction +pseudocode. Given a pseudocode execution state, it computes the next +state. Most states identify a pending memory or register operation, +requested by the pseudocode, which the memory model has to do. The +states are (this is a tagged union; tags in small-caps): + +[cols="<,<",grid="none"] +|=== +|Load_mem(_kind_, _address_, _size_, _load_continuation_) |- memory load +operation + +|Early_sc_fail(_res_continuation_) |- allow `sc` to fail early + +|Store_ea(_kind_, _address_, _size_, _next_state_) |- memory store +effective address + +|Store_memv(_mem_value_, _store_continuation_) |- memory store value + +|Fence(_kind_, _next_state_) |- fence + +|Read_reg(_reg_name_, _read_continuation_) |- register read + +|Write_reg(_reg_name_, _reg_value_, _next_state_) |- register write + +|Internal(_next_state_) |- pseudocode internal step + +|Done |- end of pseudocode +|=== + +Here: + +* _mem_value_ and _reg_value_ are lists of bytes; +* _address_ is an integer of XLEN bits; + +for load/store, _kind_ identifies whether it is `lr/sc`, +acquire-RCpc/release-RCpc, acquire-RCsc/release-RCsc, +acquire-release-RCsc; +* for fence, _kind_ identifies whether it is a normal or TSO, and (for +normal fences) the predecessor and successor ordering bits; +* _reg_name_ identifies a register and a slice thereof (start and end bit +indices); and the continuations describe how the instruction instance will continue +for each value that might be provided by the surrounding memory model +(the _load_continuation_ and _read_continuation_ take the value loaded +from memory and read from the previous register write, the +_store_continuation_ takes _false_ for an `sc` that failed and _true_ in +all other cases, and _res_continuation_ takes _false_ if the `sc` fails +and _true_ otherwise). +[NOTE] +==== +For example, given the load instruction `lw x1,0(x2)`, an execution will +typically go as follows. The initial execution state will be computed +from the pseudocode for the given opcode. This can be expected to be +Read_reg(`x2`, _read_continuation_). Feeding the most recently written +value of register `x2` (the instruction semantics will be blocked if +necessary until the register value is available), say `0x4000`, to +_read_continuation_ returns Load_mem(`plain_load`, `0x4000`, `4`, +_load_continuation_). Feeding the 4-byte value loaded from memory +location `0x4000`, say `0x42`, to _load_continuation_ returns +Write_reg(`x1`, `0x42`, Done). Many Internal(_next_state_) states may +appear before and between the states above. +==== +Notice that writing to memory is split into two steps, Store_ea and +Store_memv: the first one makes the memory footprint of the store +provisionally known, and the second one adds the value to be stored. We +ensure these are paired in the pseudocode (Store_ea followed by +Store_memv), but there may be other steps between them. +[NOTE] +==== +It is observable that the Store_ea can occur before the value to be +stored is determined. For example, for the litmus test +LB+fence.r.rw+data-po to be allowed by the operational model (as it is +by RVWMO), the first store in Hart 1 has to take the Store_ea step +before its value is determined, so that the second store can see it is +to a non-overlapping memory footprint, allowing the second store to be +committed out of order without violating coherence. +==== +The pseudocode of each instruction performs at most one store or one +load, except for AMOs that perform exactly one load and one store. Those +memory accesses are then split apart into the architecturally atomic +units by the hart semantics (see <> and <> below). + +Informally, each bit of a register read should be satisfied from a +register write by the most recent (in program order) instruction +instance that can write that bit (or from the hart’s initial register +state if there is no such write). Hence, it is essential to know the +register write footprint of each instruction instance, which we +calculate when the instruction instance is created (see the <> action of +below). We ensure in the pseudocode that each instruction does at most +one register write to each register bit, and also that it does not try +to read a register value it just wrote. + +Data-flow dependencies (address and data) in the model emerge from the +fact that each register read has to wait for the appropriate register +write to be executed (as described above). + +[[inst_state]] +==== Instruction Instance State + +Each instruction instance __i_ has a state comprising: + +* _program_loc_, the memory address from which the instruction was +fetched; +* _instruction_kind_, identifying whether this is a load, store, AMO, +fence, branch/jump or a `simple` instruction (this also includes a +_kind_ similar to the one described for the pseudocode execution +states); +* _src_regs_, the set of source _reg_name_s (including system +registers), as statically determined from the pseudocode of the +instruction; +* _dst_regs_, the destination _reg_name_s (including system registers), +as statically determined from the pseudocode of the instruction; +* _pseudocode_state_ (or sometimes just `state` for short), one of (this +is a tagged union; tags in small-caps): + + + +[cols="<,<",grid="none"] +|=== +|Plain(_isa_state_) |- ready to make a pseudocode transition + +|Pending_mem_loads(_load_continuation_) |- requesting memory load +operation(s) + +|Pending_mem_stores(_store_continuation_) |- requesting memory store +operation(s) +|=== +* _reg_reads_, the register reads the instance has performed, including, +for each one, the register write slices it read from; +* _reg_writes_, the register writes the instance has performed; +* _mem_loads_, a set of memory load operations, and for each one the +as-yet-unsatisfied slices (the byte indices that have not been satisfied +yet), and, for the satisfied slices, the store slices (each consisting +of a memory store operation and subset of its byte indices) that +satisfied it. +* _mem_stores_, a set of memory store operations, and for each one a +flag that indicates whether it has been propagated (passed to the shared +memory) or not. +* information recording whether the instance is committed, finished, +etc. + +Each memory load operation includes a memory footprint (address and +size). Each memory store operations includes a memory footprint, and, +when available, a value. + +A load instruction instance with a non-empty _mem_loads_, for which all +the load operations are satisfied (i.e. there are no unsatisfied load +slices) is said to be _entirely satisfied_. + +Informally, an instruction instance is said to have _fully determined +data_ if the load (and `sc`) instructions feeding its source registers +are finished. Similarly, it is said to have a _fully determined memory +footprint_ if the load (and `sc`) instructions feeding its memory +operation address register are finished. Formally, we first define the +notion of _fully determined register write_: a register write +_w_ from _reg_writes_ of instruction instance +_i_ is said to be _fully determined_ if one of the following +conditions hold: + +. _i_ is finished; or +. the value written by _w_ is not affected by a memory +operation that _i_ has made (i.e. a value loaded from memory +or the result of `sc`), and, for every register read that +_i_ has made, that affects _w_, the register +write from which _i_ read is fully determined (or +_i_ read from the initial register state). + +Now, an instruction instance _i_ is said to have _fully +determined data_ if for every register read _r_ from +_reg_reads_, the register writes that _r_ reads from are +fully determined. An instruction instance _i_ is said to +have a _fully determined memory footprint_ if for every register read +_r_ from _reg_reads_ that feeds into _i_’s +memory operation address, the register writes that _r_ reads +from are fully determined. +[NOTE] +==== +The `rmem` tool records, for every register write, the set of register +writes from other instructions that have been read by this instruction +at the point of performing the write. By carefully arranging the +pseudocode of the instructions covered by the tool we were able to make +it so that this is exactly the set of register writes on which the write +depends on. +==== + +==== Hart State + +The model state of a single hart comprises: + +* _hart_id_, a unique identifier of the hart; +* _initial_register_state_, the initial register value for each +register; +* _initial_fetch_address_, the initial instruction fetch address; +* _instruction_tree_, a tree of the instruction instances that have been +fetched (and not discarded), in program order. + +==== Shared Memory State + +The model state of the shared memory comprises a list of memory store +operations, in the order they propagated to the shared memory. + +When a store operation is propagated to the shared memory it is simply +added to the end of the list. When a load operation is satisfied from +memory, for each byte of the load operation, the most recent +corresponding store slice is returned. +[NOTE] +==== +For most purposes, it is simpler to think of the shared memory as an +array, i.e., a map from memory locations to memory store operation +slices, where each memory location is mapped to a one-byte slice of the +most recent memory store operation to that location. However, this +abstraction is not detailed enough to properly handle the `sc` +instruction. The RVWMO allows store operations from the same hart as the +`sc` to intervene between the store operation of the `sc` and the store +operations the paired `lr` read from. To allow such store operations to +intervene, and forbid others, the array abstraction must be extended to +record more information. Here, we use a list as it is very simple, but a +more efficient and scalable implementations should probably use +something better. +==== + +[[transitions]] +==== Transitions + +Each of the paragraphs below describes a single kind of system +transition. The description starts with a condition over the current +system state. The transition can be taken in the current state only if +the condition is satisfied. The condition is followed by an action that +is applied to that state when the transition is taken, in order to +generate the new system state. + +[[fetch]] +===== Fetch instruction + +A possible program-order-successor of instruction instance +_i_ can be fetched from address _loc_ if: + +. it has not already been fetched, i.e., none of the immediate +successors of _i_ in the hart’s _instruction_tree_ are from +_loc_; and +. if _i_’s pseudocode has already written an address to +_pc_, then _loc_ must be that address, otherwise _loc_ is: +* for a conditional branch, the successor address or the branch target +address; +* for a (direct) jump and link instruction (`jal`), the target address; +* for an indirect jump instruction (`jalr`), any address; and +* for any other instruction, _i.program_loc_+4. + +Action: construct a freshly initialized instruction instance +_i'_ for the instruction in the program memory at _loc_, +with state Plain(_isa_state_), computed from the instruction pseudocode, +including the static information available from the pseudocode such as +its _instruction_kind_, _src_regs_, and _dst_regs_, and add +_i'_ to the hart’s _instruction_tree_ as a successor of +_i_. + +The possible next fetch addresses (_loc_) are available immediately +after fetching _i_ and the model does not need to wait for +the pseudocode to write to _pc_; this allows out-of-order execution, and +speculation past conditional branches and jumps. For most instructions +these addresses are easily obtained from the instruction pseudocode. The +only exception to that is the indirect jump instruction (`jalr`), where +the address depends on the value held in a register. In principle the +mathematical model should allow speculation to arbitrary addresses here. +The exhaustive search in the `rmem` tool handles this by running the +exhaustive search multiple times with a growing set of possible next +fetch addresses for each indirect jump. The initial search uses empty +sets, hence there is no fetch after indirect jump instruction until the +pseudocode of the instruction writes to _pc_, and then we use that value +for fetching the next instruction. Before starting the next iteration of +exhaustive search, we collect for each indirect jump (grouped by code +location) the set of values it wrote to _pc_ in all the executions in +the previous search iteration, and use that as possible next fetch +addresses of the instruction. This process terminates when no new fetch +addresses are detected. + +[[initiate_load]] +===== Initiate memory load operations + +An instruction instance _i_ in state Plain(Load_mem(_kind_, +_address_, _size_, _load_continuation_)) can always initiate the +corresponding memory load operations. Action: + +. Construct the appropriate memory load operations _mlos_: +* if _address_ is aligned to _size_ then _mlos_ is a single +memory load operation of _size_ bytes from _address_; +* otherwise, _mlos_ is a set of _size_ memory load +operations, each of one byte, from the addresses +_address_..._address_+_size_−1. +. set _mem_loads_ of _i_ to _mlos_; and +. update the state of _i_ to +Pending_mem_loads(_load_continuation_). +[NOTE] +==== +In <> it is said that +misaligned memory accesses may be decomposed at any granularity. Here we +decompose them to one-byte accesses as this granularity subsumes all +others. +==== +[[sat_by_forwarding]] +===== Satisfy memory load operation by forwarding from unpropagated stores + +For a non-AMO load instruction instance _i_ in state +Pending_mem_loads(_load_continuation_), and a memory load operation +_mlo_ in _i.mem_loads_ that has +unsatisfied slices, the memory load operation can be partially or +entirely satisfied by forwarding from unpropagated memory store +operations by store instruction instances that are program-order-before +_i_ if: + +. all program-order-previous `fence` instructions with `.sr` and `.pw` +set are finished; +. for every program-order-previous `fence` instruction, _f_, +with `.sr` and `.pr` set, and `.pw` not set, if _f_ is not +finished then all load instructions that are program-order-before +_f_ are entirely satisfied; +. for every program-order-previous `fence.tso` instruction, +_f_, that is not finished, all load instructions that are +program-order-before _f_ are entirely satisfied; +. if _i_ is a load-acquire-RCsc, all program-order-previous +store-releases-RCsc are finished; +. if _i_ is a load-acquire-release, all +program-order-previous instructions are finished; +. all non-finished program-order-previous load-acquire instructions are +entirely satisfied; and +. all program-order-previous store-acquire-release instructions are +finished; + +Let _msoss_ be the set of all unpropagated memory store +operation slices from non-`sc` store instruction instances that are +program-order-before _i_ and have already calculated the +value to be stored, that overlap with the unsatisfied slices of +_mlo_, and which are not superseded by intervening store +operations or store operations that are read from by an intervening +load. The last condition requires, for each memory store operation slice +_msos_ in _msoss_ from instruction +_i'_: + +* that there is no store instruction program-order-between _i_ +and _i'_ with a memory store operation overlapping +_msos_; and +* that there is no load instruction program-order-between _i_ +and _i'_ that was satisfied from an overlapping memory store +operation slice from a different hart. + +Action: + +. update _i.mem_loads_ to indicate that +_mlo_ was satisfied by _msoss_; and +. restart any speculative instructions which have violated coherence as +a result of this, i.e., for every non-finished instruction +_i'_ that is a program-order-successor of _i_, +and every memory load operation _mlo'_ of _i'_ +that was satisfied from _msoss'_, if there exists a memory +store operation slice _msos'_ in _msoss'_, and +an overlapping memory store operation slice from a different memory +store operation in _msoss_, and _msos'_ is not +from an instruction that is a program-order-successor of +_i_, restart _i'_ and its _restart-dependents_. + +Where, the _restart-dependents_ of instruction _j_ are: + +* program-order-successors of _j_ that have data-flow +dependency on a register write of _j_; +* program-order-successors of _j_ that have a memory load +operation that reads from a memory store operation of _j_ +(by forwarding); +* if _j_ is a load-acquire, all the program-order-successors +of _j_; +* if _j_ is a load, for every `fence`, _f_, with +`.sr` and `.pr` set, and `.pw` not set, that is a +program-order-successor of _j_, all the load instructions +that are program-order-successors of _f_; +* if _j_ is a load, for every `fence.tso`, _f_, +that is a program-order-successor of _j_, all the load +instructions that are program-order-successors of _f_; and +* (recursively) all the restart-dependents of all the instruction +instances above. +[NOTE] +==== +Forwarding memory store operations to a memory load might satisfy only +some slices of the load, leaving other slices unsatisfied. + +A program-order-previous store operation that was not available when +taking the transition above might make _msoss_ provisionally +unsound (violating coherence) when it becomes available. That store will +prevent the load from being finished (see <>), and will cause it to +restart when that store operation is propagated (see <>). + +A consequence of the transition condition above is that +store-release-RCsc memory store operations cannot be forwarded to +load-acquire-RCsc instructions: _msoss_ does not include +memory store operations from finished stores (as those must be +propagated memory store operations), and the condition above requires +all program-order-previous store-releases-RCsc to be finished when the +load is acquire-RCsc. +==== +[[sat_from_mem]] +===== Satisfy memory load operation from memory + +For an instruction instance _i_ of a non-AMO load +instruction or an AMO instruction in the context of the <> transition, +any memory load operation _mlo_ in +_i.mem_loads_ that has unsatisfied slices, can be +satisfied from memory if all the conditions of > are satisfied. Action: +let _msoss_ be the memory store operation slices from memory +covering the unsatisfied slices of _mlo_, and apply the +action of <>. +[NOTE] +==== +Note that <> might leave some slices of the memory load operation +unsatisfied, those will have to be satisfied by taking the transition +again, or taking <>. <>, on the other hand, will always satisfy all the +unsatisfied slices of the memory load operation. +==== +[[complete_loads]] +===== Complete load operations + +A load instruction instance _i_ in state +Pending_mem_loads(_load_continuation_) can be completed (not to be +confused with finished) if all the memory load operations +_i.mem_loads_ are entirely satisfied (i.e. there +are no unsatisfied slices). Action: update the state of _i_ +to Plain(_load_continuation(mem_value)_), where _mem_value_ is assembled +from all the memory store operation slices that satisfied +_i.mem_loads_. + +[[early_sc_fail]] +===== Early `sc` fail + +An `sc` instruction instance _i_ in state +Plain(Early_sc_fail(_res_continuation_)) can always be made to fail. +Action: update the state of _i_ to +Plain(_res_continuation(false)_). + +[[paired_sc]] +===== Paired `sc` + +An `sc` instruction instance _i_ in state +Plain(Early_sc_fail(_res_continuation_)) can continue its (potentially +successful) execution if _i_ is paired with an `lr`. Action: +update the state of _i_ to Plain(_res_continuation(true)_). + +[[initiate_store_footprint]] +===== Initiate memory store operation footprints + +An instruction instance _i_ in state Plain(Store_ea(_kind_, +_address_, _size_, _next_state_)) can always announce its pending memory +store operation footprint. Action: + +. construct the appropriate memory store operations _msos_ +(without the store value): +* if _address_ is aligned to _size_ then _msos_ is a single +memory store operation of _size_ bytes to _address_; +* otherwise, _msos_ is a set of _size_ memory store +operations, each of one-byte size, to the addresses +_address_..._address_+_size_−1. +. set _i.mem_stores_ to _msos_; and +. update the state of _i_ to Plain(_next_state_). +[NOTE] +==== +Note that after taking the transition above the memory store operations +do not yet have their values. The importance of splitting this +transition from the transition below is that it allows other +program-order-successor store instructions to observe the memory +footprint of this instruction, and if they don’t overlap, propagate out +of order as early as possible (i.e. before the data register value +becomes available). +==== +[[instantiate_store_value]] +===== Instantiate memory store operation values + +An instruction instance _i_ in state +Plain(Store_memv(_mem_value_, _store_continuation_)) can always +instantiate the values of the memory store operations +_i.mem_stores_. Action: + +. split _mem_value_ between the memory store operations +_i.mem_stores_; and +. update the state of _i_ to +Pending_mem_stores(_store_continuation_). + +[[commit_stores]] +===== Commit store instruction + +An uncommitted instruction instance _i_ of a non-`sc` store +instruction or an `sc` instruction in the context of the <> +transition, in state Pending_mem_stores(_store_continuation_), can be +committed (not to be confused with propagated) if: + +. _i_ has fully determined data; +. all program-order-previous conditional branch and indirect jump +instructions are finished; +. all program-order-previous `fence` instructions with `.sw` set are +finished; +. all program-order-previous `fence.tso` instructions are finished; +. all program-order-previous load-acquire instructions are finished; +. all program-order-previous store-acquire-release instructions are +finished; +. if _i_ is a store-release, all program-order-previous +instructions are finished; +. all program-order-previous memory access instructions have a fully +determined memory footprint; +. all program-order-previous store instructions, except for `sc` that failed, +have initiated and so have non-empty _mem_stores_; and +. all program-order-previous load instructions have initiated and so have +non-empty _mem_loads_. + +Action: record that _i_ is committed. +[NOTE] +==== +Notice that if condition +<> is satisfied +the conditions +<> and +<> are also +satisfied, or will be satisfied after taking some eager transitions. +Hence, requiring them does not strengthen the model. By requiring them, +we guarantee that previous memory access instructions have taken enough +transitions to make their memory operations visible for the condition +check of , which is the next transition the instruction will take, +making that condition simpler. +==== +[[prop_store]] +===== Propagate store operation + +For a committed instruction instance _i_ in state +Pending_mem_stores(_store_continuation_), and an unpropagated memory +store operation _mso_ in +_i.mem_stores_, _mso_ can be +propagated if: + +. all memory store operations of program-order-previous store +instructions that overlap with _mso_ have already +propagated; +. all memory load operations of program-order-previous load instructions +that overlap with _mso_ have already been satisfied, and +(the load instructions) are _non-restartable_ (see definition below); +and +. all memory load operations that were satisfied by forwarding +_mso_ are entirely satisfied. + +Where a non-finished instruction instance _j_ is +_non-restartable_ if: + +. there does not exist a store instruction _s_ and an +unpropagated memory store operation _mso_ of _s_ +such that applying the action of the <> transition to +_mso_ will result in the restart of _j_; and +. there does not exist a non-finished load instruction _l_ +and a memory load operation _mlo_ of _l_ such +that applying the action of the <>/<> transition (even if +_mlo_ is already satisfied) to _mlo_ will result +in the restart of _j_. + +Action: + +. update the shared memory state with _mso_; +. update _i.mem_stores_ to indicate that +_mso_ was propagated; and +. restart any speculative instructions which have violated coherence as +a result of this, i.e., for every non-finished instruction +_i'_ program-order-after _i_ and every memory +load operation _mlo'_ of _i'_ that was satisfied +from _msoss'_, if there exists a memory store operation +slice _msos'_ in _msoss'_ that overlaps with +_mso_ and is not from _mso_, and +_msos'_ is not from a program-order-successor of +_i_, restart _i'_ and its _restart-dependents_ +(see <>). + +[[commit_sc]] +===== Commit and propagate store operation of an `sc` + +An uncommitted `sc` instruction instance _i_, from hart +_h_, in state Pending_mem_stores(_store_continuation_), with +a paired `lr` _i'_ that has been satisfied by some store +slices _msoss_, can be committed and propagated at the same +time if: + +. _i'_ is finished; +. every memory store operation that has been forwarded to +_i'_ is propagated; +. the conditions of <> is satisfied; +. the conditions of <> is satisfied (notice that an `sc` instruction can +only have one memory store operation); and +. for every store slice _msos_ from _msoss_, +_msos_ has not been overwritten, in the shared memory, by a +store that is from a hart that is not _h_, at any point +since _msos_ was propagated to memory. + +Action: + +. apply the actions of <>; and +. apply the action of <>. + +[[late_sc_fail]] +===== Late `sc` fail + +An `sc` instruction instance _i_ in state +Pending_mem_stores(_store_continuation_), that has not propagated its +memory store operation, can always be made to fail. Action: + +. clear _i.mem_stores_; and +. update the state of _i_ to +Plain(_store_continuation(false)_). +[NOTE] +==== +For efficiency, the `rmem` tool allows this transition only when it is +not possible to take the <> transition. This does not affect the set of +allowed final states, but when explored interactively, if the `sc` +should fail one should use the <> transition instead of waiting for this transition. +==== +[[complete_stores]] +===== Complete store operations + +A store instruction instance _i_ in state +Pending_mem_stores(_store_continuation_), for which all the memory store +operations in _i.mem_stores_ have been propagated, +can always be completed (not to be confused with finished). Action: +update the state of _i_ to +Plain(_store_continuation(true)_). + +[[do_amo]] +===== Satisfy, commit and propagate operations of an AMO + +An AMO instruction instance _i_ in state +Pending_mem_loads(_load_continuation_) can perform its memory access if +it is possible to perform the following sequence of transitions with no +intervening transitions: + +. <> +. <> +. <> (zero or more times) +. <> +. <> +. <> +. <> + +and in addition, the condition of <>, with the exception of not requiring +_i_ to be in state Plain(Done), holds after those +transitions. Action: perform the above sequence of transitions (this +does not include <>), one after the other, with no intervening +transitions. +[NOTE] +==== +Notice that program-order-previous stores cannot be forwarded to the +load of an AMO. This is simply because the sequence of transitions above +does not include the forwarding transition. But even if it did include +it, the sequence will fail when trying to do the <> transition, as this +transition requires all program-order-previous store operations to +overlapping memory footprints to be propagated, and forwarding requires +the store operation to be unpropagated. + +In addition, the store of an AMO cannot be forwarded to a +program-order-successor load. Before taking the transition above, the +store operation of the AMO does not have its value and therefore cannot +be forwarded; after taking the transition above the store operation is +propagated and therefore cannot be forwarded. +==== +[[commit_fence]] +===== Commit fence + +A fence instruction instance _i_ in state +Plain(Fence(_kind_, _next_state_)) can be committed if: + +. if _i_ is a normal fence and it has `.pr` set, all +program-order-previous load instructions are finished; +. if _i_ is a normal fence and it has `.pw` set, all +program-order-previous store instructions are finished; and +. if _i_ is a `fence.tso`, all program-order-previous load +and store instructions are finished. + +Action: + +. record that _i_ is committed; and +. update the state of _i_ to Plain(_next_state_). + +[[reg_read]] +===== Register read + +An instruction instance _i_ in state +Plain(Read_reg(_reg_name_, _read_cont_)) can do a register read of +_reg_name_ if every instruction instance that it needs to read from has +already performed the expected _reg_name_ register write. + +Let _read_sources_ include, for each bit of _reg_name_, the write to +that bit by the most recent (in program order) instruction instance that +can write to that bit, if any. If there is no such instruction, the +source is the initial register value from _initial_register_state_. Let +_reg_value_ be the value assembled from _read_sources_. Action: + +. add _reg_name_ to _i.reg_reads_ with +_read_sources_ and _reg_value_; and +. update the state of _i_ to Plain(_read_cont(reg_value)_). + +[[reg_write]] +===== Register write + +An instruction instance _i_ in state +Plain(Write_reg(_reg_name_, _reg_value_, _next_state_)) can always do a +_reg_name_ register write. Action: + +. add _reg_name_ to _i.reg_writes_ with +_deps_ and _reg_value_; and +. update the state of _i_ to Plain(_next_state_). + +where _deps_ is a pair of the set of all _read_sources_ from +_i.reg_reads_, and a flag that is true iff +_i_ is a load instruction instance that has already been +entirely satisfied. + +[[sail_interp]] +===== Pseudocode internal step + +An instruction instance _i_ in state +Plain(Internal(_next_state_)) can always do that pseudocode-internal +step. Action: update the state of _i_ to +Plain(_next_state_). + +[[finish]] +===== Finish instruction + +A non-finished instruction instance _i_ in state Plain(Done) +can be finished if: + +. if _i_ is a load instruction: +.. all program-order-previous load-acquire instructions are finished; +.. all program-order-previous `fence` instructions with `.sr` set are +finished; +.. for every program-order-previous `fence.tso` instruction, +_f_, that is not finished, all load instructions that are +program-order-before _f_ are finished; and +.. it is guaranteed that the values read by the memory load operations +of _i_ will not cause coherence violations, i.e., for any +program-order-previous instruction instance _i'_, let +_cfp_ be the combined footprint of propagated +memory store operations from store instructions program-order-between +_i_ and _i'_, and _fixed memory store +operations_ that were forwarded to _i_ from store +instructions program-order-between _i_ and _i'_ +including _i'_, and let +_/cfp_ be the complement of +_cfp_ in the memory footprint of _i_. +If _/cfp_ is not empty: +... _i'_ has a fully determined memory footprint; +... _i'_ has no unpropagated memory store operations that +overlap with _/cfp_; and +... if _i'_ is a load with a memory footprint that overlaps +with _/cfp_, then all the memory load +operations of _i'_ that overlap with +_/cfp_ are satisfied and _i'_ +is _non-restartable_ (see the <> transition for how to determined if an +instruction is non-restartable). ++ +Here, a memory store operation is called fixed if the store instruction +has fully determined data. +. _i_ has a fully determined data; and +. if _i_ is not a fence, all program-order-previous +conditional branch and indirect jump instructions are finished. + +Action: + +. if _i_ is a conditional branch or indirect jump +instruction, discard any untaken paths of execution, i.e., remove all +instruction instances that are not reachable by the branch/jump taken in +_instruction_tree_; and +. record the instruction as finished, i.e., set _finished_ to _true_. + +[[limitations]] +==== Limitations + +* The model covers user-level RV64I and RV64A. In particular, it does +not support the misaligned atomicity granule PMA or the total store +ordering extension "Ztso". It should be trivial to adapt the model to +RV32I/A and to the G, Q and C extensions, but we have never tried it. +This will involve, mostly, writing Sail code for the instructions, with +minimal, if any, changes to the concurrency model. +* The model covers only normal memory accesses (it does not handle I/O +accesses). +* The model does not cover TLB-related effects. +* The model assumes the instruction memory is fixed. In particular, the +<> transition does not generate memory load operations, and the shared +memory is not involved in the transition. Instead, the model depends on +an external oracle that provides an opcode when given a memory location. +* The model does not cover exceptions, traps and interrupts. diff --git a/param_extraction/chunks/chunk_023.txt.license b/param_extraction/chunks/chunk_023.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_023.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_024.txt b/param_extraction/chunks/chunk_024.txt new file mode 100644 index 0000000000..b0210bbd62 --- /dev/null +++ b/param_extraction/chunks/chunk_024.txt @@ -0,0 +1,163 @@ +# Chunk: chunk_024 +# Source: mm-herd.adoc +# Lines: 1-155 (of 155) +# Content starts: line 1 +# Line count: 155 +# Sections: 1 +# == Formal Axiomatic Specification in Herd +# +[[sec:herd]] +== Formal Axiomatic Specification in Herd + +The tool [.sans-serif]#herd# takes a memory model and a litmus test as +input and simulates the execution of the test on top of the memory +model. Memory models are written in the domain specific language Cat. +This section provides two Cat memory model of RVWMO. The first model, +Figure #fig:herd2[[fig:herd2]], follows the _global memory order_, +Chapter #ch:memorymodel[[ch:memorymodel]], definition of RVWMO, as much +as is possible for a Cat model. The second model, +Figure #fig:herd3[[fig:herd3]], is an equivalent, more efficient, +partial order based RVWMO model. + +The simulator [.sans-serif]#herd# is part of the [.sans-serif]#diy# tool +suite — see http://diy.inria.fr for software and documentation. The +models and more are available online +at http://diy.inria.fr/cats7/riscv/. + +` ` + +.... +(*************) +(* Utilities *) +(*************) + +(* All fence relations *) +let fence.r.r = [R];fencerel(Fence.r.r);[R] +let fence.r.w = [R];fencerel(Fence.r.w);[W] +let fence.r.rw = [R];fencerel(Fence.r.rw);[M] +let fence.w.r = [W];fencerel(Fence.w.r);[R] +let fence.w.w = [W];fencerel(Fence.w.w);[W] +let fence.w.rw = [W];fencerel(Fence.w.rw);[M] +let fence.rw.r = [M];fencerel(Fence.rw.r);[R] +let fence.rw.w = [M];fencerel(Fence.rw.w);[W] +let fence.rw.rw = [M];fencerel(Fence.rw.rw);[M] +let fence.tso = + let f = fencerel(Fence.tso) in + ([W];f;[W]) | ([R];f;[M]) + +let fence = + fence.r.r | fence.r.w | fence.r.rw | + fence.w.r | fence.w.w | fence.w.rw | + fence.rw.r | fence.rw.w | fence.rw.rw | + fence.tso + +(* Same address, no W to the same address in-between *) +let po-loc-no-w = po-loc \ (po-loc?;[W];po-loc) +(* Read same write *) +let rsw = rf^-1;rf +(* Acquire, or stronger *) +let AQ = Acq|AcqRel +(* Release or stronger *) +let RL = Rel|AcqRel +(* All RCsc *) +let RCsc = Acq|Rel|AcqRel +(* Amo events are both R and W, relation rmw relates paired lr/sc *) +let AMO = R & W +let StCond = range(rmw) + +(*************) +(* ppo rules *) +(*************) + +(* Overlapping-Address Orderings *) +let r1 = [M];po-loc;[W] +and r2 = ([R];po-loc-no-w;[R]) \ rsw +and r3 = [AMO|StCond];rfi;[R] +(* Explicit Synchronization *) +and r4 = fence +and r5 = [AQ];po;[M] +and r6 = [M];po;[RL] +and r7 = [RCsc];po;[RCsc] +and r8 = rmw +(* Syntactic Dependencies *) +and r9 = [M];addr;[M] +and r10 = [M];data;[W] +and r11 = [M];ctrl;[W] +(* Pipeline Dependencies *) +and r12 = [R];(addr|data);[W];rfi;[R] +and r13 = [R];addr;[M];po;[W] + +let ppo = r1 | r2 | r3 | r4 | r5 | r6 | r7 | r8 | r9 | r10 | r11 | r12 | r13 +.... + +` ` + +.... +Total + +(* Notice that herd has defined its own rf relation *) + +(* Define ppo *) +include "riscv-defs.cat" + +(********************************) +(* Generate global memory order *) +(********************************) + +let gmo0 = (* precursor: ie build gmo as an total order that include gmo0 *) + loc & (W\FW) * FW | # Final write after any write to the same location + ppo | # ppo compatible + rfe # includes herd external rf (optimization) + +(* Walk over all linear extensions of gmo0 *) +with gmo from linearizations(M\IW,gmo0) + +(* Add initial writes upfront -- convenient for computing rfGMO *) +let gmo = gmo | loc & IW * (M\IW) + +(**********) +(* Axioms *) +(**********) + +(* Compute rf according to the load value axiom, aka rfGMO *) +let WR = loc & ([W];(gmo|po);[R]) +let rfGMO = WR \ (loc&([W];gmo);WR) + +(* Check equality of herd rf and of rfGMO *) +empty (rf\rfGMO)|(rfGMO\rf) as RfCons + +(* Atomicity axiom *) +let infloc = (gmo & loc)^-1 +let inflocext = infloc & ext +let winside = (infloc;rmw;inflocext) & (infloc;rf;rmw;inflocext) & [W] +empty winside as Atomic +.... + +` ` + +.... +Partial + +(***************) +(* Definitions *) +(***************) + +(* Define ppo *) +include "riscv-defs.cat" + +(* Compute coherence relation *) +include "cos-opt.cat" + +(**********) +(* Axioms *) +(**********) + +(* Sc per location *) +acyclic co|rf|fr|po-loc as Coherence + +(* Main model axiom *) +acyclic co|rfe|fr|ppo as Model + +(* Atomicity axiom *) +empty rmw & (fre;coe) as Atomic +.... diff --git a/param_extraction/chunks/chunk_024.txt.license b/param_extraction/chunks/chunk_024.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_024.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_025.txt b/param_extraction/chunks/chunk_025.txt new file mode 100644 index 0000000000..7aa9e6247e --- /dev/null +++ b/param_extraction/chunks/chunk_025.txt @@ -0,0 +1,239 @@ +# Chunk: chunk_025 +# Source: naming.adoc +# Lines: 1-222 (of 222) +# Content starts: line 1 +# Line count: 222 +# Sections: 10 +# == ISA Extension Naming Conventions +# === Case Sensitivity +# === Base Integer ISA +# === Instruction-Set Extension Names +# === Underscores +# === Additional Standard Unprivileged Extension Names +# === Supervisor-level Instruction-Set Extension Names +# === Hypervisor-level Instruction-Set Extension Names +# === Machine-level Instruction-Set Extension Names +# === Non-Standard Extension Names +# +[[naming]] +== ISA Extension Naming Conventions + +This chapter describes the RISC-V ISA extension naming scheme that is +used to concisely describe the set of instructions present in a hardware +implementation, or the set of instructions used by an application binary +interface (ABI). +[NOTE] +==== +The RISC-V ISA is designed to support a wide variety of implementations +with various experimental instruction-set extensions. We have found that +an organized naming scheme simplifies software tools and documentation. +==== +=== Case Sensitivity + +The ISA naming strings are case insensitive. + +=== Base Integer ISA + +RISC-V ISA strings begin with either RV32I, RV32E, RV64I, or RV64E, +indicating the supported address space size in bits for the base integer +ISA. + +=== Instruction-Set Extension Names + +Standard ISA extensions are given a name consisting of a single letter. +For example, the first four standard extensions to the integer bases +are: "M" for integer multiplication and division, "A" for atomic +memory instructions, "F" for single-precision floating-point +instructions, and "D" for double-precision floating-point +instructions. Any RISC-V instruction-set variant can be succinctly +described by concatenating the base integer prefix with the names of the +included extensions, e.g., "RV64IMAFD". + +We have also defined an abbreviation "G" to represent the +"IMAFDZicsr_Zifencei" base and extensions, as this is intended to +represent our standard general-purpose ISA. + +Standard extensions to the RISC-V ISA are given other reserved letters, +e.g., "Q" for quad-precision floating-point, or "C" for the 16-bit +compressed instruction format. + +Some ISA extensions depend on the presence of other extensions, e.g., +"D" depends on "F" and "F" depends on "Zicsr". These dependencies +may be implicit in the ISA name: for example, RV32IF is equivalent to +RV32IFZicsr, and RV32ID is equivalent to RV32IFD and RV32IFDZicsr. + +=== Underscores + +Underscores "_" may be used to separate ISA extensions to improve +readability and to provide disambiguation, e.g., "RV32I2_M2_A2". + +=== Additional Standard Unprivileged Extension Names + +Standard unprivileged extensions can also be named by using a single "Z" followed by an +alphanumeric name. The name must end with an alphabetical character. +The second letter from the end cannot be numeric if the +last letter is "p". For example, "Zifencei" names the instruction-fetch fence extension +described in <>. + +The first letter following the "Z" conventionally indicates the most +closely related alphabetical extension category, IMAFDQLCBKJTPVH. For the +"Zfa" extension for additional floating-point instructions, for example, the letter "f" +indicates the extension is related to the "F" standard extension. If +multiple "Z" extensions are named, they should be ordered first by +category, then alphabetically within a category—for example, +"Zicsr_Zifencei_Ztso". + +All multi-letter extensions, including those with the "Z" prefix, must be +separated from other multi-letter extensions by an underscore, e.g., +"RV32IMACZicsr_Zifencei". + +=== Supervisor-level Instruction-Set Extension Names + +Standard extensions that extend the supervisor-level virtual-memory +architecture are prefixed with the letters "Sv", followed by an alphanumeric +name. Other standard extensions that extend the supervisor-level architecture are +prefixed with the letters "Ss", followed by an alphanumeric name. The name +must end with an alphabetical character. The second letter from the end cannot +be numeric if the last letter is "p". These extensions are further defined in +Volume II. + +The extensions "sv32", "sv39", "sv48", and "sv59" were defined before the rule +against extension names ending in numbers was established. + +Standard supervisor-level extensions should be listed after standard +unprivileged extensions, and like other multi-letter extensions, must be +separated from other multi-letter extensions by an underscore. If multiple +supervisor-level extensions are listed, they should be ordered alphabetically. + +=== Hypervisor-level Instruction-Set Extension Names + +Standard extensions that extend the hypervisor-level architecture are prefixed +with the letters "Sh". +If multiple hypervisor-level extensions are listed, they should be ordered +alphabetically. + +NOTE: Many augmentations to the hypervisor-level architecture are more +naturally defined as supervisor-level extensions, following the scheme +described in the previous section. +The "Sh" prefix is used by the few hypervisor-level extensions that have no +supervisor-visible effects. + +=== Machine-level Instruction-Set Extension Names + +Standard machine-level instruction-set extensions are prefixed with the +letters "Sm". + +Standard machine-level extensions should be listed after standard +lesser-privileged extensions, and like other multi-letter extensions, must be +separated from other multi-letter extensions by an underscore. If multiple +machine-level extensions are listed, they should be ordered alphabetically. + +=== Non-Standard Extension Names + +Non-standard extensions are named by using a single "X" followed by the alphanumeric +name. The name must end with an alphabetic character. The +second letter from the end cannot be numeric if the last letter is +"p". For example, "Xhwacha" names the Hwacha vector-fetch ISA +extension. + +Non-standard extensions must be listed after all standard extensions, and, +like other multi-letter extensions, must be separated from other multi-letter +extensions by an underscore. +For example, an ISA with non-standard extensions Argle and +Bargle may be named "RV64IZifencei_Xargle_Xbargle". + +If multiple non-standard extensions are listed, they should be ordered +alphabetically. Like other multi-letter extensions, they should be +separated from other multi-letter extensions by an underscore. + +=== Version Numbers + +Recognizing that instruction sets may expand or alter over time, we +encode extension version numbers following the extension name. Version +numbers are divided into major and minor version numbers, separated by a +"p". If the minor version is "0", then "p0" can be omitted from +the version string. To avoid ambiguity, no extension name may end with a number +or a "p" preceded by a number. + +Because the "P" extension for Packed SIMD can be confused for the +decimal point in a version number, it must be preceded by an underscore +if it follows another extension with a version number. For example, "rv32i2p2" +means version 2.2 of RV32I, whereas "rv32i2_p2" means version 2.0 of RV32I with +version 2.0 of the P extension. + +Changes in major version numbers imply a loss of +backwards compatibility, whereas changes in only the minor version +number must be backwards-compatible. For example, the original 64-bit +standard ISA defined in release 1.0 of this manual can be written in +full as "RV64I1p0M1p0A1p0F1p0D1p0", more concisely as +"RV64I1M1A1F1D1". + +We introduced the version numbering scheme with the second release. +Hence, we define the default version of a standard extension to be the +version present at that time, e.g., "RV32I" is equivalent to +"RV32I2". + +=== Subset Naming Convention + +<> summarizes the standardized extension +names. The table also defines the canonical +order in which extension names must appear in the name string, with +top-to-bottom in table indicating first-to-last in the name string, +e.g., RV32IMACV is legal, whereas RV32IMAVC is not. + +[[isanametable]] +.Standard ISA extension names. +[%autowidth,float="center",align="center",cols="<,^,^",options="header",] +|=== +|Subset |Name |Implies + +|Base ISA | | + +|Integer |I | + +|Reduced Integer |E | + +3+|*Standard Unprivileged Extensions* + +|Integer Multiplication and Division |M |Zmmul + +|Atomics |A | + +|Single-Precision Floating-Point |F |Zicsr + +|Double-Precision Floating-Point |D |F + +|General |G |IMAFDZicsr_Zifencei + +|Quad-Precision Floating-Point |Q |D + +|16-bit Compressed Instructions |C | + +|B Extension |B | + +|Packed-SIMD Extensions |P | + +|Vector Extension |V |D + +|Hypervisor Extension |H | + +3+|*Additional Standard Unprivileged Extensions* + +|Additional Standard unprivileged extensions "abc" |Zabc | + +3+|*Standard Supervisor-Level Extensions* + +|Supervisor-level extension "def" |Ssdef | + +3+|*Standard Hypervisor-Level Extensions* + +|Hypervisor-level extension "ghi" |Shghi | + +3+|*Standard Machine-Level Extensions* + +|Machine-level extension "jkl" |Smjkl | + +3+|*Non-Standard Extensions* + +|Non-standard extension "mno" |Xmno | +|=== diff --git a/param_extraction/chunks/chunk_025.txt.license b/param_extraction/chunks/chunk_025.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_025.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_026.txt b/param_extraction/chunks/chunk_026.txt new file mode 100644 index 0000000000..38f16ed1b5 --- /dev/null +++ b/param_extraction/chunks/chunk_026.txt @@ -0,0 +1,388 @@ +# Chunk: chunk_026 +# Source: priv-cfi.adoc +# Lines: 1-373 (of 373) +# Content starts: line 1 +# Line count: 373 +# Sections: 8 +# == Control-flow Integrity (CFI) +# === Landing Pad (Zicfilp) +# ==== Landing-Pad-Enabled (LPE) State +# ==== Preserving Expected Landing Pad State on Traps +# === Shadow Stack (Zicfiss) +# ==== Shadow Stack Pointer (`ssp`) CSR access control +# ==== Shadow-Stack-Enabled (SSE) State +# ==== Shadow Stack Memory Protection +# +[[priv-cfi]] +== Control-flow Integrity (CFI) + +Control-flow Integrity (CFI) capabilities help defend against Return-Oriented +Programming (ROP) and Call/Jump-Oriented Programming (COP/JOP) style +control-flow subversion attacks. The Zicfiss and Zicfilp extensions provide +backward-edge and forward-edge control flow integrity respectively. Please see +the Control-flow Integrity chapter of the Unprivileged ISA specification for further +details on these CFI capabilities and the associated Unprivileged ISA. + +[[priv-forward]] +=== Landing Pad (Zicfilp) + +This section specifies the Privileged ISA for the Zicfilp extension. + +[[FCFIACT]] +==== Landing-Pad-Enabled (LPE) State + +The term `xLPE` is used to determine if forward-edge CFI using landing pads +provided by the Zicfilp extension is enabled at a privilege mode. + +When S-mode is implemented, it is determined as follows: + +.`xLPE` determination when S-mode is implemented +[width=100%] +[%header, cols="^4,^12"] +|=== +|Privilege Mode| xLPE +| M | `mseccfg.MLPE` +| S or HS | `menvcfg.LPE` +| VS | `henvcfg.LPE` +| U or VU | `senvcfg.LPE` +|=== + +When S-mode is not implemented, it is determined as follows: + +.`xLPE` determination when S-mode is not implemented +[width=100%] +[%header, cols="^4,^12"] +|=== +|Privilege Mode| xLPE +| M | `mseccfg.MLPE` +| U | `menvcfg.LPE` +|=== + +[NOTE] +==== +The Zicfilp must be explicitly enabled for use at each privilege mode. + +Programs compiled with the `LPAD` instruction continue to function correctly, +but without forward-edge CFI protection, when the Zicfilp extension is not +implemented or is not enabled. +==== + +<<< + +[[ZICFILP_FORWARD_TRAPS]] +==== Preserving Expected Landing Pad State on Traps + +[#norm:zicflip_forward_traps]#A trap may need to be delivered to the same or to a higher privilege mode upon +completion of `JALR`/`C.JALR`/`C.JR`, but before the instruction at the target +of indirect call/jump was decoded#, due to: + +* [#norm:zicflip_forward_trap_async_interrupt]#Asynchronous interrupts.# +* [#norm:zicflip_forward_trap_async_exception]#Synchronous exceptions with priority higher than that of a software-check + exception with `__x__tval` set to "landing pad fault (code=2)" (See + <> of Privileged Specification).# + +[[norm:zicflip_exception_priority]] +The software-check exception caused by Zicfilp has higher priority than an +illegal-instruction exception but lower priority than instruction access-fault. + +[[norm:lpad_sw_exception]] +The software-check exception due to the instruction not being an `LPAD` +instruction when `ELP` is `LP_EXPECTED` or a software-check exception caused by +the `LPAD` instruction itself leads to a trap being delivered +to the same or to a higher privilege mode. + +In such cases, the `ELP` prior to the trap, the previous `ELP`, must be +preserved by the trap delivery such that it can be restored on a return from the +trap. [#norm:mstatus-mpelp_op]#To store the previous `ELP` state on trap delivery to M-mode, an `MPELP` +bit is provided in the `mstatus` CSR.# [#norm:mstatus-spelp_op]#To store the previous `ELP` state on trap +delivery to S/HS-mode, an `SPELP` bit is provided in the `mstatus` CSR.# [#norm:sstatus-spelp_op]#The +`SPELP` bit in `mstatus` can be accessed through the `sstatus` CSR.# [#norm:vsstatus-spelp_op2]#To store +the previous `ELP` state on traps to VS-mode, a `SPELP` bit is defined in the +`vsstatus` (VS-modes version of `sstatus`).# [#norm:dcsr-pelp_op]#To store the previous `ELP` state on +transition to Debug Mode, a `pelp` bit is defined in the `dcsr` register.# + +[[norm:zicflip_pelp_trap]] +When a trap is taken into privilege mode `x`, the `__x__PELP` is set to `ELP` +and `ELP` is set to `NO_LP_EXPECTED`. + +[[norm:zicflip_pelp_trap_return]] +An `MRET` or `SRET` instruction is used to return from a trap in M-mode or +S-mode, respectively. When executing an `__x__RET` instruction, if the new +privilege mode is `y`, then `ELP` is set to the value of `__x__PELP` if +`__y__LPE` (see <>) is 1; otherwise, it is set to `NO_LP_EXPECTED`; +`__x__PELP` is set to `NO_LP_EXPECTED`. + +[[norm:zicflip_pelp_debug_mode]] +Upon entry into Debug Mode, the `pelp` bit in `dcsr` is updated with the `ELP` +at the privilege level the hart was previously in, and the `ELP` is set to +`NO_LP_EXPECTED`. When a hart resumes from Debug Mode, if the new privilege mode +is `y`, then `ELP` is set to the value of `pelp` if `__y__LPE` (see <>) +is 1; otherwise, it is set to `NO_LP_EXPECTED`. + +See also <> for semantics added to the RNMI trap and the MNRET instruction +when this extension is implemented. + +[NOTE] +==== +The trap handler in privilege mode `x` must save the `__x__PELP` bit and the +`x7` register before performing an indirect call/jump if `xLPE=1`. If the +privilege mode `x` can respond to interrupts and `xLPE=1`, then the trap handler +should also save these values before enabling interrupts. + +The trap handler in privilege mode `x` must restore the saved `__x__PELP` bit +and the `x7` register before executing the `__x__RET` instruction to return from +a trap. +==== + +<<< + +[[priv-backward]] +=== Shadow Stack (Zicfiss) + +This section specifies the Privileged ISA for the Zicfiss extension. + +==== Shadow Stack Pointer (`ssp`) CSR access control + +[[norm:zicfiss_ssp_csr]] +Attempts to access the `ssp` CSR may result in either an illegal-instruction +exception or a virtual-instruction exception, contingent upon the state of the +*__x__*`envcfg.SSE` fields. The conditions are specified as follows: + +* [#norm:zicfiss_m_menvcfg-sse]#If the privilege mode is less than M and `menvcfg.SSE` is 0, an + illegal-instruction exception is raised.# +* [#norm:zicfiss_u_senvcfg-sse]#Otherwise, if in U-mode and `senvcfg.SSE` is 0, an illegal-instruction + exception is raised.# +* [#norm:zicfiss_vs_henvcfg-sse]#Otherwise, if in VS-mode and `henvcfg.SSE` is 0, a virtual-instruction + exception is raised.# +* [#norm:zicfiss_vu_henvcfg_senvcfg-sse]#Otherwise, if in VU-mode and either `henvcfg.SSE` or `senvcfg.SSE` is 0, + a virtual-instruction exception is raised.# +* [#norm:zicfiss_sse_access]#Otherwise, the access is allowed.# + +==== Shadow-Stack-Enabled (SSE) State + +The term `xSSE` is used to determine if backward-edge CFI using shadow stacks +provided by the Zicfiss extension is enabled at a privilege mode. + +When S-mode is implemented, it is determined as follows: + +.`xSSE` determination when S-mode is implemented +[width=100%] +[%header, cols="^4,^12"] +|=== +|Privilege Mode| `xSSE` +| M | `0` +| S or HS | `menvcfg.SSE` +| VS | `henvcfg.SSE` +| U or VU | `senvcfg.SSE` +|=== + +[[norm:zicfiss_smode-xsse]] +When S-mode is not implemented, then `xSSE` is 0 at both M and U privilege modes. + +[NOTE] +==== +Activating Zicfiss in U-mode must be done explicitly per process. Not activating +Zicfiss at U-mode for a process when that application is not compiled with +Zicfiss allows it to invoke shared libraries that may contain Zicfiss +instructions. The Zicfiss instructions in the shared library revert to their +Zimop/Zcmop-defined behavior in this case. + +When Zicfiss is enabled in S-mode it is benign to use an operating system that is +not compiled with Zicfiss instructions. Such an operating system that does +not use backward-edge CFI for S-mode execution may still activate Zicfiss for +U-mode applications. + +When programs that use Zicfiss instructions are installed on a processor that +supports the Zicfiss extension but the extension is not enabled at the privilege +mode where the program executes, the program continues to function correctly but +without backward-edge CFI protection as the Zicfiss instructions will revert to +their Zimop/Zcmop-defined behavior. + +When programs that use Zicfiss instructions are installed on a processor that +does not support the Zicfiss extension but supports the Zimop and Zcmop +extensions, the programs continues to function correctly but without +backward-edge CFI protection as the Zicfiss instructions will revert to their +Zimop/Zcmop-defined behavior. + +On processors that do not support Zimop/Zcmop extensions, all Zimop/Zcmop code +points including those used for Zicfiss instructions may cause an +illegal-instruction exception. Execution of programs that use these instructions +on such machines is not supported. + +Activating Zicfiss in M-mode is currently not supported. Additionally, when +S-mode is not implemented, activation in U-mode is also not supported. These +functionalities may be introduced in a future standard extension. +==== + +NOTE: Changes to `xSSE` take effect immediately; address-translation caches +need not be synchronized with SFENCE.VMA, HFENCE.GVMA, or HFENCE.VVMA +instructions. + + +[[SSMP]] +==== Shadow Stack Memory Protection + +To protect shadow stack memory, the memory is associated with a new page type – +the Shadow Stack (SS) page – in the single-stage and VS-stage page tables. [#norm:ss_page_enc]#The +encoding `R=0`, `W=1`, and `X=0`, is defined to represent an SS page.# [#norm:ssmp_menvcfg-sse]#When +`menvcfg.SSE=0`, this encoding remains reserved.# [#norm:ssmp_henvcfg-sse]#Similarly, when `V=1` and +`henvcfg.SSE=0`, this encoding remains reserved at `VS` and `VU` levels.# + +[#norm:satp-mode_bare]#If `satp.MODE` (or `vsatp.MODE` when `V=1`) is set to `Bare` and the effective +privilege mode is less than M, shadow stack instructions raise a store/AMO access-fault exception.# +[#norm:ssmp_ssamoswap]#When the effective privilege mode is M, memory access +by an `SSAMOSWAP.W/D` instruction results in a store/AMO access-fault exception.# + +[#norm:ssmp_ss_page_access_fault]#Memory mapped as an SS page cannot be written to by instructions other than +`SSAMOSWAP.W/D`, `SSPUSH`, and `C.SSPUSH`. Attempts will raise a store/AMO +access-fault exception.# [#norm:ssmp_ss_cache_block_access_fault]#Access to a SS page using _cache-block operation_ +(`CBO.*`) instructions is not permitted. Such accesses will raise a store/AMO +access-fault exception.# [#norm:ssmp_ss_implicit_access_fault]#Implicit accesses, including instruction fetches to an +SS page, are not permitted. Such accesses will raise an access-fault exception +appropriate to the access type.# [#norm:ssmp_ss_load]#However, the shadow stack is readable by all +instructions that only load from memory.# + +[NOTE] +==== +Stores to shadow stack pages by instructions other than `SSAMOSWAP`, `SSPUSH`, +and `C.SSPUSH` will trigger a store/AMO access-fault exception, not a store/AMO +page-fault exception, signaling a fatal error. A store/AMO page-fault suggests +that the operating system could address and rectify the fault, which is not +feasible in this scenario. Hence, the page-fault handler must decode the opcode +of the faulting instruction to discern whether the fault was caused by a +non-shadow-stack instruction writing to an SS page (a fatal condition) or by a +shadow stack instruction to a non-resident page (a recoverable condition). The +performance-critical nature of operating system page fault handlers necessitates +triggering an access fault instead of a page fault, allowing for a +straightforward distinction between fatal conditions and recoverable faults. + +Operating systems must ensure that no writable, non-shadow-stack alias virtual +address mappings exist for the physical memory backing the shadow stack. +Furthermore, in systems where an address-misaligned exception supersedes the +access-fault exception, handlers emulating misaligned stores must be designed to +cause an access-fault exception when the store is directed to a shadow stack +page. + +All instructions that perform load operations are allowed to read from the +shadow stack. This feature facilitates debugging and performance profiling by +allowing examination of the link register values backed up in the shadow stack. +==== + +[NOTE] +==== +As of the drafting of this specification, instruction fetches are the sole type +of implicit access subjected to single- or VS-stage address translation. +==== + +[#norm:ss_fault_exception_code]#If a shadow stack (SS) instruction raises an access-fault, page-fault, or +guest-page-fault exception that is supposed to indicate the original instruction +type (load or store/AMO), then the reported exception cause is respectively a +store/AMO access fault (code 7), a store/AMO page fault (code 15), or a +store/AMO guest-page fault (code 23).# For shadow stack instructions, the +reported instruction type is always as though it were a store or AMO, even for +instructions `SSPOPCHK` and `C.SSPOPCHK` that only read from memory and do not +write to it. + +[NOTE] +==== +When Zicfiss is implemented, the existing "store/AMO" exceptions can be thought +of as "store/AMO/SS" exceptions, indicating that the trapping instruction is +either a store, an AMO, or a shadow stack instruction. +==== + +Shadow stack instructions are restricted to accessing shadow stack +(`pte.xwr=010b`) pages. [#norm:ssmp_ss_page_illegeal_access]#Should a shadow stack instruction access a page that is +not designated as a shadow stack page and is not marked as read-only +(`pte.xwr=001`), a store/AMO access-fault exception will be invoked.# [#norm:ssmp_ss_read_only_page]#Conversely, +if the page being accessed by a shadow stack instruction is a read-only page, a +store/AMO page-fault exception will be triggered.# + + +[NOTE] +==== +Shadow stack loads and stores will trigger a store/AMO page-fault if the +accessed page is read-only, to support copy-on-write (COW) of a shadow stack +page. If the page has been marked read-only for COW tracking, the page-fault +handler responds by creating a copy of the page and updates the `pte.xwr` to +`010b`, thereby designating each copy as a shadow stack page. Conversely, if +the access targets a genuinely read-only page, the fault being reported as a +store/AMO page-fault signals to the operating system that the fault is fatal +and non-recoverable. Reporting the fault as a store/AMO page-fault, even for +`SSPOPCHK` initiated memory access, aids in the determination of fatality; if +these were reported as load page-faults, access to a truly read-only page +might be mistakenly treated as a recoverable fault, leading to the faulting +instruction being retried indefinitely. The PTE does not provide a read-only +shadow stack encoding. + +Attempts by shadow stack instructions to access pages marked as read-write, +read-write-execute, read-execute, or execute-only result in a store/AMO +access-fault exception, similarly indicating a fatal condition. + +Shadow stacks should be bounded at each end by guard pages to prevent accidental +underflows or overflows from one shadow stack into another. Conventionally, a +guard page for a stack is a page that is not accessible by the process that owns +the stack. +==== + +<<< + +[[norm:ssp_xlen_aligned]] +If the virtual address in `ssp` is not `XLEN` aligned, then the `SSPUSH`/ +`C.SSPUSH`/`SSPOPCHK`/`C.SSPOPCHK` instructions cause a store/AMO access-fault +exception. + +[NOTE] +==== +Misaligned accesses to shadow stack are not required and enforcing alignment is +more secure to detect errors in the program. An access-fault exception is raised +instead of address-misaligned exception in such cases to indicate fatality and +that the instruction must not be emulated by a trap handler. +==== + +Correct execution of shadow stack instructions that access memory requires the +the accessed memory to be idempotent. [#norm:ssmp_ss_idempotent_memory]#If the memory referenced by +`SSPUSH`/`C.SSPUSH`/`SSPOPCHK`/`C.SSPOPCHK`/`SSAMOSWAP.W/D` instructions is not +idempotent, then the instructions cause a store/AMO access-fault exception.# + +[NOTE] +==== +The `SSPOPCHK` instruction performs a load followed by a check of the loaded +data value with the link register as source. If the check against the link +register faults, and the instruction is restarted by the trap handler, then the +instruction will perform a load again. If the memory from which the load is +performed is non-idempotent, then the second load may cause unexpected side +effects. Shadow stack instructions that access the shadow stack require the +memory referenced by `ssp` to be idempotent to avoid such concerns. Locating +shadow stacks in non-idempotent memory, such as non-idempotent device memory, +is not an expected usage, and requiring memory referenced to be idempotent +does not pose a significant restriction. +==== + +The `U` and `SUM` bit enforcement is performed normally for shadow stack +instruction initiated memory accesses. The state of the `MXR` bit does not +affect read access to a shadow stack page as the shadow stack page is always +readable by all instructions that load from memory. + +The G-stage address translation and protections remain unaffected by the Zicfiss +extension. The `xwr == 010b` encoding in the G-stage PTE remains reserved. +[#norm:active_g_stage_pte]#When G-stage page tables are active, the shadow stack instructions that access memory +require the G-stage page table to have read-write permission for the accessed +memory; else a store/AMO guest-page-fault exception is raised.# + +[NOTE] +==== +A future extension may define a shadow stack encoding in the G-stage page table +to support use cases such as a hypervisor enforcing shadow stack protections for +its guests. +==== + +Svpbmt and Svnapot extensions are supported for shadow stack pages. + +The PMA checks are extended to require memory referenced by shadow stack +instructions to be idempotent. The PMP checks are extended to require read-write +permission for memory accessed by shadow stack instructions. If the PMP does not +provide read-write permissions or if the accessed memory is not idempotent then +a store/AMO access-fault exception is raised. + +The `SSAMOSWAP.W/D` instructions require the PMA of the accessed memory range to +provide AMOSwap level support. diff --git a/param_extraction/chunks/chunk_026.txt.license b/param_extraction/chunks/chunk_026.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_026.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_027.txt b/param_extraction/chunks/chunk_027.txt new file mode 100644 index 0000000000..e00948d5aa --- /dev/null +++ b/param_extraction/chunks/chunk_027.txt @@ -0,0 +1,1289 @@ +# Chunk: chunk_027 +# Source: priv-csrs.adoc +# Lines: 1-1272 (of 1272) +# Content starts: line 1 +# Line count: 1272 +# Sections: 10 +# == Control and Status Registers (CSRs) +# === CSR Address Mapping Conventions +# === CSR Listing +# === CSR Field Specifications +# ==== Reserved Writes Preserve Values, Reads Ignore Values (WPRI) +# ==== Write/Read Only Legal Values (WLRL) +# ==== Write Any Values, Reads Legal Values (WARL) +# === CSR Field Modulation +# === Implicit Reads of CSRs +# === CSR Width Modulation +# +[[priv-csrs]] +== Control and Status Registers (CSRs) + +The SYSTEM major opcode is used to encode all privileged instructions in +the RISC-V ISA. These can be divided into two main classes: those that +atomically read-modify-write control and status registers (CSRs), which +are defined in the Zicsr extension, and all other privileged +instructions. The privileged architecture requires the Zicsr extension; +which other privileged instructions are required depends on the +privileged-architecture feature set. + +In addition to the unprivileged state described in Volume I of this +manual, an implementation may contain additional CSRs, accessible by +some subset of the privilege levels using the CSR instructions described +in Volume I. In this chapter, we map out the CSR address space. The +following chapters describe the function of each of the CSRs according +to privilege level, as well as the other privileged instructions which +are generally closely associated with a particular privilege level. Note +that [#norm:Zicsr_higher_priv]#although CSRs and instructions are associated with one privilege +level, they are also accessible at all higher privilege levels.# + +Standard CSRs do not have side effects on reads but may have side +effects on writes. + +=== CSR Address Mapping Conventions + +The standard RISC-V ISA sets aside a 12-bit encoding space (csr[11:0]) +for up to 4,096 CSRs. By convention, the upper 4 bits of the CSR address +(csr[11:8]) are used to encode the read and write accessibility of the +CSRs according to privilege level as shown in <>. [#norm:Zicsr_rw]#The top two bits (csr[11:10]) indicate whether the register is read/write (`00`,`01`, or `10`) or read-only (`11`).# +[#norm:Zicsr_access]#The next two bits (csr[9:8]) encode the lowest privilege level that can access the CSR.# + +[NOTE] +==== +The CSR address convention uses the upper bits of the CSR address to +encode default access privileges. This simplifies error checking in the +hardware and provides a larger CSR space, but does constrain the mapping +of CSRs into the address space. + +Implementations might allow a more-privileged level to trap otherwise +permitted CSR accesses by a less-privileged level to allow these +accesses to be intercepted. This change should be transparent to the +less-privileged software. +==== + +Instructions that access a non-existent CSR are reserved. +[#norm:Zicsr_illegal_mode]#Attempts to access a CSR without appropriate privilege level +raise illegal-instruction exceptions or, as described in +<>, virtual-instruction exceptions.# +[#norm:Zicsr_illegal_acc]#Attempts to write a read-only register raise illegal-instruction exceptions.# +[#norm:Zicwr_write_ro]#A read/write register might also contain some bits that are +read-only, in which case writes to the read-only bits are ignored.# + +<> also indicates the convention to +allocate CSR addresses between standard and custom uses. The CSR +addresses designated for custom uses will not be redefined by future +standard extensions. + +Machine-mode standard read-write CSRs `0x7A0`-`0x7BF` are reserved for +use by the debug system. Of these CSRs, `0x7A0`-`0x7AF` are accessible +to machine mode, whereas +[#norm:Zicsr_debug-illegal]#`0x7B0`-`0x7BF` are only visible to debug mode. +Implementations should raise illegal-instruction exceptions on +machine-mode access to the latter set of registers.# + +[NOTE] +==== +Effective virtualization requires that as many instructions run natively +as possible inside a virtualized environment, while any privileged +accesses trap to the virtual machine monitor. cite:[goldbergvm] CSRs that are read-only +at some lower privilege level are shadowed into separate CSR addresses +if they are made read-write at a higher privilege level. This avoids +trapping permitted lower-privilege accesses while still causing traps on +illegal accesses. Currently, the counters are the only shadowed CSRs. +==== + +=== CSR Listing + +<>-<> list the CSRs that +have currently been allocated CSR addresses. The timers, counters, and +floating-point CSRs are standard unprivileged CSRs. The other registers +are used by privileged code, as described in the following chapters. +Note that not all registers are required on all implementations. + +[[csrrwpriv]] +.Allocation of RISC-V CSR address ranges. +[%autowidth,float="center",align="center",cols="^,^,^,^,<,<,<,<"] +[.monofont] +|=== +3+^|CSR Address 2.2+|Hex 3.2+|Use and Accessibility +|[11:10] |[9:8] |[7:4] +8+|Unprivileged and User-Level CSRs +m|00 m|00 m|XXXX 2+m| 0x000-0x0FF 3+|Standard read/write +|`01` |`00` |`XXXX` 2+| `0x400-0x4FF` 3+|Standard read/write +|`10` |`00` |`XXXX` 2+| `0x800-0x8FF` 3+|Custom read/write +|`11` |`00` |`0XXX` 2+| `0xC00-0xC7F` 3+|Standard read-only +|`11` |`00` |`10XX` 2+| `0xC80-0xCBF` 3+|Standard read-only +|`11` |`00` |`11XX` 2+| `0xCC0-0xCFF` 3+|Custom read-only +8+|Supervisor-Level CSRs +|`00` |`01` |`XXXX` 2+| `0x100-0x1FF` 3+|Standard read/write +|`01` |`01` |`0XXX` 2+| `0x500-0x57F` 3+|Standard read/write +|`01` |`01` |`10XX` 2+| `0x580-0x5BF` 3+|Standard read/write +|`01` |`01` |`11XX` 2+| `0x5C0-0x5FF` 3+|Custom read/write +|`10` |`01` |`0XXX` 2+| `0x900-0x97F` 3+|Standard read/write +|`10` |`01` |`10XX` 2+| `0x980-0x9BF` 3+|Standard read/write +|`10` |`01` |`11XX` 2+| `0x9C0-0x9FF` 3+|Custom read/write +|`11` |`01` |`0XXX` 2+| `0xD00-0xD7F` 3+|Standard read-only +|`11` |`01` |`10XX` 2+| `0xD80-0xDBF` 3+|Standard read-only +|`11` |`01` |`11XX` 2+| `0xDC0-0xDFF` 3+|Custom read-only +8+|Hypervisor and VS CSRs +|`00` |`10` |`XXXX` 2+| `0x200-0x2FF` 3+|Standard read/write +|`01` |`10` |`0XXX` 2+| `0x600-0x67F` 3+|Standard read/write +|`01` |`10` |`10XX` 2+| `0x680-0x6BF` 3+|Standard read/write +|`01` |`10` |`11XX` 2+| `0x6C0-0x6FF` 3+|Custom read/write +|`10` |`10` |`0XXX` 2+| `0xA00-0xA7F` 3+|Standard read/write +|`10` |`10` |`10XX` 2+| `0xA80-0xABF` 3+|Standard read/write +|`10` |`10` |`11XX` 2+| `0xAC0-0xAFF` 3+|Custom read/write +|`11` |`10` |`0XXX` 2+| `0xE00-0xE7F` 3+|Standard read-only +|`11` |`10` |`10XX` 2+| `0xE80-0xEBF` 3+|Standard read-only +|`11` |`10` |`11XX` 2+| `0xEC0-0xEFF` 3+|Custom read-only +8+|Machine-Level CSRs +|`00` |`11` |`XXXX` 2+|`0x300-0x3FF` 3+|Standard read/write +|`01` |`11` |`0XXX` 2+|`0x700-0x77F` 3+|Standard read/write +|`01` |`11` |`100X` 2+|`0x780-0x79F` 3+|Standard read/write +|`01` |`11` |`1010` 2+|`0x7A0-0x7AF` 3+|Standard read/write debug CSRs +|`01` |`11` |`1011` 2+|`0x7B0-0x7BF` 3+|Debug-mode-only CSRs +|`01` |`11` |`11XX` 2+|`0x7C0-0x7FF` 3+|Custom read/write +|`10` |`11` |`0XXX` 2+|`0xB00-0xB7F` 3+|Standard read/write +|`10` |`11` |`10XX` 2+|`0xB80-0xBBF` 3+|Standard read/write +|`10` |`11` |`11XX` 2+|`0xBC0-0xBFF` 3+|Custom read/write +|`11` |`11` |`0XXX` 2+|`0xF00-0xF7F` 3+|Standard read-only +|`11` |`11` |`10XX` 2+|`0xF80-0xFBF` 3+|Standard read-only +|`11` |`11` |`11XX` 2+|`0xFC0-0xFFF` 3+|Custom read-only +|=== + +<<< + +[[ucsrnames]] +.Currently allocated RISC-V unprivileged CSR addresses. +[float="center",align="center",cols="<10%,<10%,<20%,<60%",options="header"] +|=== +|Number |Privilege |Name |Description +4+^|Unprivileged Floating-Point CSRs + +|`0x001` + +`0x002` + +`0x003` +|URW + +URW + +URW +|`fflags` + +`frm` + +`fcsr` +|Floating-Point Accrued Exceptions. + +Floating-Point Dynamic Rounding Mode. + +Floating-Point Control and Status Register (`frm` +`fflags`). + +4+^|Unprivileged Vector CSRs + +|`0x008` + +`0x009` + +`0x00A` + +`0x00F` + +`0xC20` + +`0xC21` + +`0xC22` +|URW + +URW + +URW + +URW + +URO + +URO + +URO +|`vstart` + +`vxsat` + +`vxrm` + +`vcsr` + +`vl` + +`vtype` + +`vlenb` +|Vector start position. + +Fixed-point accrued saturation flag. + +Fixed-point rounding mode. + +Vector control and status register. + +Vector length. + +Vector data type register. + +Vector register length in bytes. + +4+^|Unprivileged Zicfiss extension CSR +|`0x011` + +|URW + +|`ssp` + +|Shadow Stack Pointer. + + +4+^|Unprivileged Entropy Source Extension CSR +|`0x015` + +|URW + +|`seed` + +|Seed for cryptographic random bit generators. + + +4+^|Unprivileged Zcmt Extension CSR +|`0x017` + +|URW + +|`jvt` + +|Table jump base vector and control register. + + +4+^|Unprivileged Counter/Timers + +|`0xC00` + +`0xC01` + +`0xC02` + +`0xC03` + +`0xC04` + + {nbsp} + +`0xC1F` + +`0xC80` + +`0xC81` + +`0xC82` + +`0xC83` + +`0xC84` + +{nbsp} + +`0xC9F` +|URO + +URO + +URO + +URO + +URO + +{nbsp} + +URO + +URO + +URO + +URO + +URO + +URO + +{nbsp} + +URO +|`cycle` + +`time` + +`instret` + +`hpmcounter3` + +`hpmcounter4` + +{vertical-ellipsis} + +`hpmcounter31` + +`cycleh` + +`timeh` + +`instreth` + +`hpmcounter3h` + +`hpmcounter4h` + +{vertical-ellipsis} + +`hpmcounter31h` +|Cycle counter for RDCYCLE instruction. + +Timer for RDTIME instruction. + +Instructions-retired counter for RDINSTRET instruction. + +Performance-monitoring counter. + +Performance-monitoring counter. + +{nbsp} + +Performance-monitoring counter. + +Upper 32 bits of `cycle`, RV32 only. + +Upper 32 bits of `time`, RV32 only. + +Upper 32 bits of `instret`, RV32 only. + +Upper 32 bits of `hpmcounter3`, RV32 only. + +Upper 32 bits of `hpmcounter4`, RV32 only. + +{nbsp} + +Upper 32 bits of `hpmcounter31`, RV32 only. +|=== + +<<< + +[[scsrnames]] +.Currently allocated RISC-V supervisor-level CSR addresses. +[%autowidth,float="center",align="center",cols="<,<,<,<",options="header"] +|=== +|Number |Privilege |Name |Description +4+^|Supervisor Trap Setup + +|`0x100` + +`0x104` + +`0x105` + +`0x106` +|SRW + +SRW + +SRW + +SRW +|`sstatus` + +`sie` + +`stvec` + +`scounteren` +|Supervisor status register. + +Supervisor interrupt-enable register. + +Supervisor trap handler base address. + +Supervisor counter enable. + +4+^|Supervisor Configuration + +|`0x10A` |SRW |`senvcfg` |Supervisor environment configuration register. + +4+^|Supervisor Counter Setup + +|`0x120` |SRW |`scountinhibit` |Supervisor counter-inhibit register. + +4+^|Supervisor Trap Handling + +|`0x140` + +`0x141` + +`0x142` + +`0x143` + +`0x144` + +`0xDA0` +|SRW + +SRW + +SRW + +SRW + +SRW + +SRO +|`sscratch` + +`sepc` + +`scause` + +`stval` + +`sip` + +`scountovf` +|Supervisor scratch register. + +Supervisor exception program counter. + +Supervisor trap cause. + +Supervisor trap value. + +Supervisor interrupt pending. + +Supervisor count overflow. + +4+^|Supervisor Indirect + +|`0x150` + +`0x151` + +`0x152` + +`0x153` + +`0x155` + +`0x156` + +`0x157` +|SRW + +SRW + +SRW + +SRW + +SRW + +SRW + +SRW +|`siselect` + +`sireg` + +`sireg2` + +`sireg3` + +`sireg4` + +`sireg5` + +`sireg6` +|Supervisor indirect register select. + +Supervisor indirect register alias. + +Supervisor indirect register alias 2. + +Supervisor indirect register alias 3. + +Supervisor indirect register alias 4. + +Supervisor indirect register alias 5. + +Supervisor indirect register alias 6. + +4+^|Supervisor Protection and Translation + +|`0x180` |SRW |`satp` |Supervisor address translation and protection. + +4+^|Supervisor Timer Compare + +|`0x14D` + +`0x15D` +|SRW + +SRW +|`stimecmp` + +`stimecmph` +|Supervisor timer compare. + +Upper 32 bits of `stimecmp`, RV32 only. + +4+^|Debug/Trace Registers + +|`0x5A8` |SRW |`scontext` |Supervisor-mode context register. + +4+^|Supervisor Resource Management Configuration +|`0x181` |SRW |`srmcfg` |Supervisor Resource Management Configuration. + +4+^|Supervisor State Enable Registers +|`0x10C` + + `0x10D` + + `0x10E` + + `0x10F` +|SRW + + SRW + + SRW + + SRW +|`sstateen0` + + `sstateen1` + + `sstateen2` + + `sstateen3` +|Supervisor State Enable 0 Register. + + Supervisor State Enable 1 Register. + + Supervisor State Enable 2 Register. + + Supervisor State Enable 3 Register. + +4+^|Supervisor Control Transfer Records Configuration +|`0x14E` + + `0x14F` + + `0x15F` +|SRW + + SRW + + SRW +|`sctrctl` + + `sctrstatus` + + `sctrdepth` +|Supervisor Control Transfer Records Control Register. + + Supervisor Control Transfer Records Status Register. + + Supervisor Control Transfer Records Depth Register. + +|=== + +<<< + +[[hcsrnames]] +.Currently allocated RISC-V hypervisor and VS CSR addresses. +[%autowidth,float="center",align="center",cols="<,<,<,<",options="header"] +|=== +|Number |Privilege |Name |Description +4+^|Hypervisor Trap Setup + +|`0x600` + +`0x602` + +`0x603` + +`0x604` + +`0x606` + +`0x607` + +`0x612` +|HRW + +HRW + +HRW + +HRW + +HRW + +HRW + +HRW +|`hstatus` + +`hedeleg` + +`hideleg` + +`hie` + +`hcounteren` + +`hgeie` + +`hedelegh` +|Hypervisor status register. + +Hypervisor exception delegation register. + +Hypervisor interrupt delegation register. + +Hypervisor interrupt-enable register. + +Hypervisor counter enable. + +Hypervisor guest external interrupt-enable register. + +Upper 32 bits of `hedeleg`, RV32 only. + +4+^|Hypervisor Trap Handling + +|`0x643` + +`0x644` + +`0x645` + +`0x64A` + +`0xE12` +|HRW + +HRW + +HRW + +HRW + +HRO +|`htval` + +`hip` + +`hvip` + +`htinst` + +`hgeip` +|Hypervisor trap value. + +Hypervisor interrupt pending. + +Hypervisor virtual interrupt pending. + +Hypervisor trap instruction (transformed). + +Hypervisor guest external interrupt pending. + +4+^|Hypervisor Configuration + +|`0x60A` + +`0x61A` +|HRW + +HRW +|`henvcfg` + +`henvcfgh` +|Hypervisor environment configuration register. + +Upper 32 bits of `henvcfg`, RV32 only. + +4+^|Hypervisor Protection and Translation + +|`0x680` |HRW |`hgatp` |Hypervisor guest address translation and protection. + +4+^|Debug/Trace Registers + +|`0x6A8` |HRW |`hcontext` |Hypervisor-mode context register. + +4+^|Hypervisor Counter/Timer Virtualization Registers + +|`0x605` + +`0x615` +|HRW + +HRW +|`htimedelta` + +`htimedeltah` +|Delta for VS/VU-mode timer. + +Upper 32 bits of `htimedelta`, RV32 only. + +4+^|Hypervisor State Enable Registers +|`0x60C` + + `0x60D` + + `0x60E` + + `0x60F` + + `0x61C` + + `0x61D` + + `0x61E` + + `0x61F` +|HRW + + HRW + + HRW + + HRW + + HRW + + HRW + + HRW + + HRW +|`hstateen0` + + `hstateen1` + + `hstateen2` + + `hstateen3` + + `hstateen0h` + + `hstateen1h` + + `hstateen2h` + + `hstateen3h` +|Hypervisor State Enable 0 Register. + + Hypervisor State Enable 1 Register. + + Hypervisor State Enable 2 Register. + + Hypervisor State Enable 3 Register. + + Upper 32 bits of Hypervisor State Enable 0 Register, RV32 only. + + Upper 32 bits of Hypervisor State Enable 1 Register, RV32 only. + + Upper 32 bits of Hypervisor State Enable 2 Register, RV32 only. + + Upper 32 bits of Hypervisor State Enable 3 Register, RV32 only. + +4+^|Virtual Supervisor Registers + +|`0x200` + +`0x204` + +`0x205` + +`0x240` + +`0x241` + +`0x242` + +`0x243` + +`0x244` + +`0x280` +|HRW + +HRW + +HRW + +HRW + +HRW + +HRW + +HRW + +HRW + +HRW +|`vsstatus` + +`vsie` + +`vstvec` + +`vsscratch` + +`vsepc` + +`vscause` + +`vstval` + +`vsip` + +`vsatp` +|Virtual supervisor status register. + +Virtual supervisor interrupt-enable register. + +Virtual supervisor trap handler base address. + +Virtual supervisor scratch register. + +Virtual supervisor exception program counter. + +Virtual supervisor trap cause. + +Virtual supervisor trap value. + +Virtual supervisor interrupt pending. + +Virtual supervisor address translation and protection. + +4+^|Virtual Supervisor Indirect + +|`0x250` + +`0x251` + +`0x252` + +`0x253` + +`0x255` + +`0x256` + +`0x257` +|HRW + +HRW + +HRW + +HRW + +HRW + +HRW + +HRW +|`vsiselect` + +`vsireg` + +`vsireg2` + +`vsireg3` + +`vsireg4` + +`vsireg5` + +`vsireg6` +|Virtual supervisor indirect register select. + +Virtual supervisor indirect register alias. + +Virtual supervisor indirect register alias 2. + +Virtual supervisor indirect register alias 3. + +Virtual supervisor indirect register alias 4. + +Virtual supervisor indirect register alias 5. + +Virtual supervisor indirect register alias 6. + +4+^|Virtual Supervisor Timer Compare + +|`0x24D` + +`0x25D` +|HRW + +HRW +|`vstimecmp` + +`vstimecmph` +|Virtual supervisor timer compare. + +Upper 32 bits of `vstimecmp`, RV32 only. + +4+^|Virtual Supervisor Control Transfer Records Configuration +|`0x24E` +|HRW +|`vsctrctl` +|Virtual Supervisor Control Transfer Records Control Register. + +|=== + +<<< + +[[mcsrnames0]] +[.monocell] +.Currently allocated RISC-V machine-level CSR addresses. +[%autowidth,float="center",align="center",cols="<,<,<,<",options="header"] +|=== +|Number |Privilege |Name |Description +4+^|Machine Information Registers + +|`0xF11` + +`0xF12` + +`0xF13` + +`0xF14` + +`0xF15` +|MRO + +MRO + +MRO + +MRO + +MRO +|`mvendorid` + +`marchid` + +`mimpid` + +`mhartid` + +`mconfigptr` +|Vendor ID. + +Architecture ID. + +Implementation ID. + +Hardware thread ID. + +Pointer to configuration data structure. + +4+^|Machine Trap Setup + +|`0x300` + +`0x301` + +`0x302` + +`0x303` + +`0x304` + +`0x305` + +`0x306` + +`0x310` + +`0x312` +|MRW + +MRW + +MRW + +MRW + +MRW + +MRW + +MRW + +MRW + +MRW +|`mstatus` + +`misa` + +`medeleg` + +`mideleg` + +`mie` + +`mtvec` + +`mcounteren` + +`mstatush` + +`medelegh` +|Machine status register. + +ISA and extensions + +Machine exception delegation register. + +Machine interrupt delegation register. + +Machine interrupt-enable register. + +Machine trap-handler base address. + +Machine counter enable. + +Additional machine status register, RV32 only. + +Upper 32 bits of `medeleg`, RV32 only. + +4+^|Machine Counter Configuration + +|`0x321` + +`0x322` + +`0x721` + +`0x722` +|MRW + +MRW + +MRW + +MRW +|`mcyclecfg` + +`minstretcfg` + +`mcyclecfgh` + +`minstretcfgh` +|Machine cycle counter configuration register. + +Machine instret counter configuration register. + +Upper 32 bits of `mcyclecfg`, RV32 only. + +Upper 32 bits of `minstretcfg`, RV32 only. + +4+^|Machine Trap Handling + +|`0x340` + +`0x341` + +`0x342` + +`0x343` + +`0x344` + +`0x34A` + +`0x34B` +|MRW + +MRW + +MRW + +MRW + +MRW + +MRW + +MRW +|`mscratch` + +`mepc` + +`mcause` + +`mtval` + +`mip` + +`mtinst` + +`mtval2` +|Machine scratch register. + +Machine exception program counter. + +Machine trap cause. + +Machine trap value. + +Machine interrupt pending. + +Machine trap instruction (transformed). + +Machine second trap value. + +4+^|Machine Indirect + +|`0x350` + +`0x351` + +`0x352` + +`0x353` + +`0x355` + +`0x356` + +`0x357` +|MRW + +MRW + +MRW + +MRW + +MRW + +MRW + +MRW +|`miselect` + +`mireg` + +`mireg2` + +`mireg3` + +`mireg4` + +`mireg5` + +`mireg6` +|Machine indirect register select. + +Machine indirect register alias. + +Machine indirect register alias 2. + +Machine indirect register alias 3. + +Machine indirect register alias 4. + +Machine indirect register alias 5. + +Machine indirect register alias 6. + +4+^|Machine Configuration + +|`0x30A` + +`0x31A` + +`0x747` + +`0x757` +|MRW + +MRW + +MRW + +MRW +|`menvcfg` + +`menvcfgh` + +`mseccfg` + +`mseccfgh` +|Machine environment configuration register. + +Upper 32 bits of `menvcfg`, RV32 only. + +Machine security configuration register. + +Upper 32 bits of `mseccfg`, RV32 only. + +4+^|Machine Memory Protection + +|`0x3A0` + +`0x3A1` + +`0x3A2` + +`0x3A3` + +{nbsp} + +`0x3AE` + +`0x3AF` + +`0x3B0` + +`0x3B1` + +{nbsp} + +`0x3EF` +|MRW + +MRW + +MRW + +MRW + +{nbsp} + +MRW + +MRW + +MRW + +MRW + +{nbsp} + +MRW +|`pmpcfg0` + +`pmpcfg1` + +`pmpcfg2` + +`pmpcfg3` + +{ellipsis} + +`pmpcfg14` + +`pmpcfg15` + +`pmpaddr0` + +`pmpaddr1` + +{ellipsis} + +`pmpaddr63` +|Physical memory protection configuration. + +Physical memory protection configuration, RV32 only. + +Physical memory protection configuration. + +Physical memory protection configuration, RV32 only. + +{nbsp} + +Physical memory protection configuration. + +Physical memory protection configuration, RV32 only. + +Physical memory protection address register. + +Physical memory protection address register. + +{nbsp} + +Physical memory protection address register. + +4+^|Machine State Enable Registers +|`0x30C` + + `0x30D` + + `0x30E` + + `0x30F` + + `0x31C` + + `0x31D` + + `0x31E` + + `0x31F` +|MRW + + MRW + + MRW + + MRW + + MRW + + MRW + + MRW + + MRW +|`mstateen0` + + `mstateen1` + + `mstateen2` + + `mstateen3` + + `mstateen0h` + + `mstateen1h` + + `mstateen2h` + + `mstateen3h` +|Machine State Enable 0 Register. + + Machine State Enable 1 Register. + + Machine State Enable 2 Register. + + Machine State Enable 3 Register. + + Upper 32 bits of Machine State Enable 0 Register, RV32 only. + + Upper 32 bits of Machine State Enable 1 Register, RV32 only. + + Upper 32 bits of Machine State Enable 2 Register, RV32 only. + + Upper 32 bits of Machine State Enable 3 Register, RV32 only. +|=== + +<<< + +[[mcsrnames1]] +.Currently allocated RISC-V machine-level CSR addresses. +[%autowidth,float="center",align="center",cols="<,<,<,<",options="header"] +|=== +|Number |Privilege |Name |Description +4+^|Machine Non-Maskable Interrupt Handling + +|`0x740` + +`0x741` + +`0x742` + +`0x744` +|MRW + +MRW + +MRW + +MRW +|`mnscratch` + +`mnepc` + +`mncause` + +`mnstatus` +|Resumable NMI scratch register. + +Resumable NMI program counter. + +Resumable NMI cause. + +Resumable NMI status. + +4+^|Machine Counter/Timers + +|`0xB00` + +`0xB02` + +`0xB03` + +`0xB04` + +{nbsp} + +`0xB1F` + +`0xB80` + +`0xB82` + +`0xB83` + +`0xB84` + +{nbsp} + +`0xB9F` +|MRW + +MRW + +MRW + +MRW + +{nbsp} + +MRW + +MRW + +MRW + +MRW + +MRW + +{nbsp} + +MRW + +|`mcycle` + +`minstret` + +`mhpmcounter3` + +`mhpmcounter4` + +{vertical-ellipsis} + +`mhpmcounter31` + +`mcycleh` + +`minstreth` + +`mhpmcounter3h` + +`mhpmcounter4h` + +{vertical-ellipsis} + +`mhpmcounter31h` +|Machine cycle counter. + +Machine instructions-retired counter. + +Machine performance-monitoring counter. + +Machine performance-monitoring counter. + +{nbsp} + +Machine performance-monitoring counter. + +Upper 32 bits of `mcycle`, RV32 only. + +Upper 32 bits of `minstret`, RV32 only. + +Upper 32 bits of `mhpmcounter3`, RV32 only. + +Upper 32 bits of `mhpmcounter4`, RV32 only. + +{nbsp} + +Upper 32 bits of `mhpmcounter31`, RV32 only. + +4+^|Machine Counter Setup + +|`0x320` + +`0x323` + +`0x324` + +{nbsp} + +`0x33F` + +`0x723` + +`0x724` + +{nbsp} + +`0x73F` +|MRW + +MRW + +MRW + +{nbsp} + +MRW + +MRW + +MRW + +{nbsp} + +MRW +|`mcountinhibit` + +`mhpmevent3` + +`mhpmevent4` + +{vertical-ellipsis} + +`mhpmevent31` + +`mhpmevent3h` + +`mhpmevent4h` + +{vertical-ellipsis} + +`mhpmevent31h` +|Machine counter-inhibit register. + +Machine performance-monitoring event selector. + +Machine performance-monitoring event selector. + +{nbsp} + +Machine performance-monitoring event selector. + +Upper 32 bits of `mhpmevent3`, RV32 only. + +Upper 32 bits of `mhpmevent4`, RV32 only. + +{nbsp} + +Upper 32 bits of `mhpmevent31`, RV32 only. + +4+^|Machine Control Transfer Records Configuration +|`0x34E` +|MRW +|`mctrctl` +|Machine Control Transfer Records Control Register. + +4+^|Debug/Trace Registers (shared with Debug Mode) + +|`0x7A0` + +`0x7A1` + +`0x7A2` + +`0x7A3` + +`0x7A8` +|MRW + +MRW + +MRW + +MRW + +MRW +|`tselect` + +`tdata1` + +`tdata2` + +`tdata3` + +`mcontext` + +|Debug/Trace trigger register select. + +First Debug/Trace trigger data register. + +Second Debug/Trace trigger data register. + +Third Debug/Trace trigger data register. + +Machine-mode context register. + +4+^|Debug Mode Registers + +|`0x7B0` + +`0x7B1` + +`0x7B2` + +`0x7B3` +|DRW + +DRW + +DRW + +DRW + +|`dcsr` + +`dpc` + +`dscratch0` + +`dscratch1` +|Debug control and status register. + +Debug program counter. + +Debug scratch register 0. + +Debug scratch register 1. +|=== + +[[indcsrs-m]] +.Currently allocated RISC-V indirect CSR (Smcsrind) mappings - M-mode +[float="center",align="center",options="header"] +|=== +| `miselect` | `mireg` | `mireg2` | `mireg3` | `mireg4` | `mireg5` | `mireg6` +| 0x30 | `iprio0` | none | none | none | none | none +| ... | ... | ... | ... | ... | ... | ... +| 0x3F | `iprio15` | none | none | none | none | none +| 0x70 | `eidelivery` | none | none | none | none | none +| 0x71 | 0 | none | none | none | none | none +| 0x72 | `eithreshold` | none | none | none | none | none +| 0x73 | 0 | none | none | none | none | none +| ... | ... | ... | ... | ... | ... | ... +| 0x7F | 0 | none | none | none | none | none +| 0x80 | `eip0` | none | none | none | none | none +| ... | ... | ... | ... | ... | ... | ... +| 0xBF | `eip63` | none | none | none | none | none +| 0xC0 | `eie0` | none | none | none | none | none +| ... | ... | ... | ... | ... | ... | ... +| 0xFF | `eie63` | none | none | none | none | none +|=== + +[[indcsrs-s]] +.Currently allocated RISC-V indirect CSR (Smcsrind/Sscsrind) mappings - S-mode +[float="center",align="center",options="header"] +|=== +| `siselect` | `sireg` | `sireg2` | `sireg3` | `sireg4` | `sireg5` | `sireg6` +| 0x30 | `iprio0` | none | none | none | none | none +| ... | ... | ... | ... | ... | ... | ... +| 0x3F | `iprio15` | none | none | none | none | none +| 0x40 | `cycle` | `cyclecfg` | none | `cycleh` | `cyclecfgh` | none +| 0x41 | none | none | none | none | none | none +| 0x42 | `instret` | `instretcfg` | none | `instreth` | `instretcfgh` | none +| 0x43 | `hpmcounter3` | `hpmevent3` | none | `hpmcounter3h` | `hpmevent3h` | none +| ... | ... | ... | ... | ... | ... | ... +| 0x5F | `hpmcounter31` | `hpmevent31` | none | `hpmcounter31h` | `hpmevent31h` | none +| 0x70 | `eidelivery` | none | none | none | none | none +| 0x71 | 0 | none | none | none | none | none +| 0x72 | `eithreshold` | none | none | none | none | none +| 0x73 | 0 | none | none | none | none | none +| ... | ... | ... | ... | ... | ... | ... +| 0x7F | 0 | none | none | none | none | none +| 0x80 | `eip0` | none | none | none | none | none +| ... | ... | ... | ... | ... | ... | ... +| 0xBF | `eip63` | none | none | none | none | none +| 0xC0 | `eie0` | none | none | none | none | none +| ... | ... | ... | ... | ... | ... | ... +| 0xFF | `eie63` | none | none | none | none | none +| 0x200 | `ctrsource0` | `ctrtarget0` | `ctrdata0` | 0 | 0 | 0 +| ... | ... | ... | ... | ... | ... | ... +| 0x2FF | `ctrsource255` | `ctrtarget255` | `ctrdata255` | 0 | 0 | 0 +|=== + +[[indcsrs-vs]] +.Currently allocated RISC-V indirect CSR (Smcsrind/Sscsrind) mappings - VS-mode +[float="center",align="center",options="header"] +|=== +| `vsiselect` | `vsireg` | `vsireg2` | `vsireg3` | `vsireg4` | `vsireg5` | `vsireg6` +| 0x30 | `iprio0` | none | none | none | none | none +| ... | ... | ... | ... | ... | ... | ... +| 0x3F | `iprio15` | none | none | none | none | none +| 0x70 | `eidelivery` | none | none | none | none | none +| 0x71 | 0 | none | none | none | none | none +| 0x72 | `eithreshold` | none | none | none | none | none +| 0x73 | 0 | none | none | none | none | none +| ... | ... | ... | ... | ... | ... | ... +| 0x7F | 0 | none | none | none | none | none +| 0x80 | `eip0` | none | none | none | none | none +| ... | ... | ... | ... | ... | ... | ... +| 0xBF | `eip63` | none | none | none | none | none +| 0xC0 | `eie0` | none | none | none | none | none +| ... | ... | ... | ... | ... | ... | ... +| 0xFF | `eie63` | none | none | none | none | none +| 0x200 | `ctrsource0` | `ctrtarget0` | `ctrdata0` | 0 | 0 | 0 +| ... | ... | ... | ... | ... | ... | ... +| 0x2FF | `ctrsource255` | `ctrtarget255` | `ctrdata255` | 0 | 0 | 0 +|=== + +=== CSR Field Specifications + +The following definitions and abbreviations are used in specifying the +behavior of fields within the CSRs. + +==== Reserved Writes Preserve Values, Reads Ignore Values (WPRI) + +Some whole read/write fields are reserved for future use. Software +should ignore the values read from these fields, and should preserve the +values held in these fields when writing values to other fields of the +same register. [#norm:Zicsr_wpri_roz]#For forward compatibility, implementations that do not +furnish these fields must make them read-only zero. These fields are +labeled *WPRI* in the register descriptions.# + +[NOTE] +==== +To simplify the software model, any backward-compatible future +definition of previously reserved fields within a CSR must cope with the +possibility that a non-atomic read/modify/write sequence is used to +update other fields in the CSR. Alternatively, the original CSR +definition must specify that subfields can only be updated atomically, +which may require a two-instruction clear bit/set bit sequence in +general that can be problematic if intermediate values are not legal. +==== + +==== Write/Read Only Legal Values (WLRL) + +Some read/write CSR fields specify behavior for only a subset of +possible bit encodings, with other bit encodings reserved. +[#norm:Zicsr_wlrl]#Software +should not write anything other than legal values to such a field, and +should not assume a read will return a legal value unless the last write +was of a legal value, or the register has not been written since another +operation (e.g., reset) set the register to a legal value. These fields +are labeled *WLRL* in the register descriptions.# + +[NOTE] +==== +Hardware implementations need only implement enough state bits to +differentiate between the supported values, but must always return the +complete specified bit-encoding of any supported value when read. +==== + +[#norm:Zicsr_wlrl_exception_param]#Implementations are permitted but not required to raise an +illegal-instruction exception if an instruction attempts to write a +non-supported value to a *WLRL* field.# +Implementations can return arbitrary +bit patterns on the read of a *WLRL* field when the last write was of an +illegal value, but the value returned should deterministically depend on +the illegal written value and the value of the field prior to the write. + +==== Write Any Values, Reads Legal Values (WARL) + +Some read/write CSR fields are only defined for a subset of bit +encodings, but allow any value to be written while guaranteeing to +return a legal value whenever read. Assuming that writing the CSR has no +other side effects, the range of supported values can be determined by +attempting to write a desired setting then reading to see if the value +was retained. These fields are labeled *WARL* in the register descriptions. + + +[#norm:Zicsr_warl]#Implementations will not raise an exception on writes of unsupported +values to a *WARL* field.# Implementations can return any legal value on the +read of a *WARL* field when the last write was of an illegal value, but the +legal value returned should deterministically depend on the illegal +written value and the architectural state of the hart. + +=== CSR Field Modulation + +If a write to one CSR changes the set of legal values allowed for a +field of a second CSR, then unless specified otherwise, the second CSR's +field immediately gets an `UNSPECIFIED` value from among its new legal values. This +is true even if the field's value before the write remains legal after +the write; the value of the field may be changed in consequence of the +write to the controlling CSR. + +[NOTE] +==== +As a special case of this rule, the value written to one CSR may control +whether a field of a second CSR is writable (with multiple legal values) +or is read-only. When a write to the controlling CSR causes the second +CSR's field to change from previously read-only to now writable, that +field immediately gets an `UNSPECIFIED` but legal value, unless specified otherwise. + +*** +Some CSR fields are, when writable, defined as aliases of other CSR +fields. Let _x_ be such a CSR field, and let _y_ be the CSR field it aliases when writable. If a write to a controlling CSR causes field _x_ to change from previously read-only to now writable, the new value of _x_ is not `UNSPECIFIED` but instead immediately reflects the existing value of its alias _y_, as required. +==== + +A change to the value of a CSR for this reason is not a write to the +affected CSR and thus does not trigger any side effects specified for +that CSR. + +=== Implicit Reads of CSRs + +Implementations sometimes perform _implicit_ reads of CSRs. (For +example, all S-mode instruction fetches implicitly read the `satp` CSR.) +Unless otherwise specified, the value returned by an implicit read of a +CSR is the same value that would have been returned by an explicit read +of the CSR, using a CSR-access instruction in a sufficient privilege +mode. + +[[csrwidthmodulation]] +=== CSR Width Modulation + +If the width of a CSR is changed (for example, by changing SXLEN or +UXLEN, as described in <>), the +values of the _writable_ fields and bits of the new-width CSR are, +unless specified otherwise, determined from the previous-width CSR as +though by this algorithm: + +. The value of the previous-width CSR is copied to a temporary register +of the same width. +. For the read-only bits of the previous-width CSR, the bits at the same +positions in the temporary register are set to zeros. +. The width of the temporary register is changed to the new width. If +the new width _W_ is narrower than the previous width, the +least-significant _W_ bits of the temporary register are +retained and the more-significant bits are discarded. If the new width +is wider than the previous width, the temporary register is +zero-extended to the wider width. +. Each writable field of the new-width CSR takes the value of the bits +at the same positions in the temporary register. + +Changing the width of a CSR is not a read or write of the CSR and thus +does not trigger any side effects. + +=== Explicit Accesses to CSRs Wider than XLEN + +If a standard CSR is wider than XLEN bits, then an explicit read +of the CSR returns the register's least-significant XLEN bits, +and an explicit write to the CSR modifies only the register's +least-significant XLEN bits, leaving the upper bits unchanged. + +Some standard CSRs, such as the counter CSRs of extension +Zicntr, are always 64 bits, even when XLEN=32 (RV32). +For each such 64-bit CSR (for example, counter `time`), +a corresponding 32-bit _high-half CSR_ is usually defined with +the same name but with the letter '`h`' appended at the end (`timeh`). +The high-half CSR aliases bits 63:32 of its namesake +64-bit CSR, thus providing a way for RV32 software +to read and modify the otherwise-unreachable 32 bits. + +Standard high-half CSRs are accessible only when +the base RISC-V instruction set is RV32 (XLEN=32). +For RV64 (when XLEN=64), the addresses of all standard high-half CSRs +are reserved, so an attempt to access a high-half CSR +typically raises an illegal-instruction exception. diff --git a/param_extraction/chunks/chunk_027.txt.license b/param_extraction/chunks/chunk_027.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_027.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_028.txt b/param_extraction/chunks/chunk_028.txt new file mode 100644 index 0000000000..674246a967 --- /dev/null +++ b/param_extraction/chunks/chunk_028.txt @@ -0,0 +1,31 @@ +# Chunk: chunk_028 +# Source: priv-history.adoc +# Lines: 1-22 (of 22) +# Content starts: line 1 +# Line count: 22 +# Sections: 2 +# == History +# === Research Funding at UC Berkeley +# +== History + +=== Research Funding at UC Berkeley + +Development of the RISC-V architecture and implementations has been +partially funded by the following sponsors. + +* *Par Lab:* Research supported by Microsoft (Award #024263) and Intel +(Award #024894) funding and by matching funding by U.C. Discovery (Award +#DIG07-10227). Additional support came from Par Lab affiliates Nokia, +NVIDIA, Oracle, and Samsung. +* *Project Isis:* DoE Award DE-SC0003624. +* *ASPIRE Lab*: DARPA PERFECT program, Award HR0011-12-2-0016. DARPA +POEM program Award HR0011-11-C-0100. The Center for Future Architectures +Research (C-FAR), a STARnet center funded by the Semiconductor Research +Corporation. Additional support from ASPIRE industrial sponsor, Intel, +and ASPIRE affiliates, Google, Huawei, Nokia, NVIDIA, Oracle, and +Samsung. + +The content of this paper does not necessarily reflect the position or +the policy of the US government and no official endorsement should be +inferred. diff --git a/param_extraction/chunks/chunk_028.txt.license b/param_extraction/chunks/chunk_028.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_028.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_029.txt b/param_extraction/chunks/chunk_029.txt new file mode 100644 index 0000000000..38636f9c27 --- /dev/null +++ b/param_extraction/chunks/chunk_029.txt @@ -0,0 +1,20 @@ +# Chunk: chunk_029 +# Source: priv-insns.adoc +# Lines: 1-12 (of 12) +# Content starts: line 1 +# Line count: 12 +# Sections: 1 +# == RISC-V Privileged Instruction Set Listings +# + +== RISC-V Privileged Instruction Set Listings + +This chapter presents instruction-set listings for all instructions +defined in the RISC-V Privileged Architecture. + +The instruction-set listings for unprivileged instructions, including +the ECALL and EBREAK instructions, are provided in Volume I of this +manual. + +.RISC-V Privileged Instructions +include::images/bytefield/priv-instr-set.edn[] diff --git a/param_extraction/chunks/chunk_029.txt.license b/param_extraction/chunks/chunk_029.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_029.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_030.txt b/param_extraction/chunks/chunk_030.txt new file mode 100644 index 0000000000..598903fd60 --- /dev/null +++ b/param_extraction/chunks/chunk_030.txt @@ -0,0 +1,228 @@ +# Chunk: chunk_030 +# Source: priv-intro.adoc +# Lines: 1-217 (of 217) +# Content starts: line 1 +# Line count: 217 +# Sections: 4 +# == Introduction +# === RISC-V Privileged Software Stack Terminology +# === Privilege Levels +# === Debug Mode +# +[[priv-intro]] + +== Introduction + +This document describes the RISC-V privileged architecture, which covers +all aspects of RISC-V systems beyond the unprivileged ISA, including +privileged instructions as well as additional functionality required for +running operating systems and attaching external devices. + +[NOTE] +==== +Commentary on our design decisions is formatted as in this paragraph, +and can be skipped if the reader is only interested in the specification +itself. + +*** +We briefly note that the entire privileged-level design described in +this document could be replaced with an entirely different +privileged-level design without changing the unprivileged ISA, and +possibly without even changing the ABI. In particular, this privileged +specification was designed to run existing popular operating systems, +and so embodies the conventional level-based protection model. Alternate +privileged specifications could embody other more flexible +protection-domain models. For simplicity of expression, the text is +written as if this was the only possible privileged architecture. +==== + +=== RISC-V Privileged Software Stack Terminology + +This section describes the terminology we use to describe components of +the wide range of possible privileged software stacks for RISC-V. + +<> shows some of the possible software stacks +that can be supported by the RISC-V architecture. The left-hand side +shows a simple system that supports only a single application running on +an application execution environment (AEE). The application is coded to +run with a particular application binary interface (ABI). The ABI +includes the supported user-level ISA plus a set of ABI calls to +interact with the AEE. The ABI hides details of the AEE from the +application to allow greater flexibility in implementing the AEE. The +same ABI could be implemented natively on multiple different host OSs, +or could be supported by a user-mode emulation environment running on a +machine with a different native ISA. + +[NOTE] +==== +Our graphical convention represents abstract interfaces using black +boxes with white text, to separate them from concrete instances of +components implementing the interfaces. +==== +[[privimps]] +.Different implementation stacks supporting various forms of privileged execution. +image::png/privimps.png[] + +The middle configuration shows a conventional operating system (OS) that +can support multiprogrammed execution of multiple applications. Each +application communicates over an ABI with the OS, which provides the +AEE. Just as applications interface with an AEE via an ABI, RISC-V +operating systems interface with a supervisor execution environment +(SEE) via a supervisor binary interface (SBI). An SBI comprises the +user-level and supervisor-level ISA together with a set of SBI function +calls. Using a single SBI across all SEE implementations allows a single +OS binary image to run on any SEE. The SEE can be a simple boot loader +and BIOS-style IO system in a low-end hardware platform, or a +hypervisor-provided virtual machine in a high-end server, or a thin +translation layer over a host operating system in an architecture +simulation environment. + +[NOTE] +==== +Most supervisor-level ISA definitions do not separate the SBI from the +execution environment and/or the hardware platform, complicating +virtualization and bring-up of new hardware platforms. +==== +The rightmost configuration shows a virtual machine monitor +configuration where multiple multiprogrammed OSs are supported by a +single hypervisor. Each OS communicates via an SBI with the hypervisor, +which provides the SEE. The hypervisor communicates with the hypervisor +execution environment (HEE) using a hypervisor binary interface (HBI), +to isolate the hypervisor from details of the hardware platform. + +[NOTE] +==== +The ABI, SBI, and HBI are still a work-in-progress, but we are now +prioritizing support for Type-2 hypervisors where the SBI is provided +recursively by an S-mode OS. +==== + +Hardware implementations of the RISC-V ISA will generally require +additional features beyond the privileged ISA to support the various +execution environments (AEE, SEE, or HEE). + +=== Privilege Levels + +[#norm:always-priv-level]#At any time, a RISC-V hardware thread (_hart_) is running at some +privilege level encoded as a mode in one or more CSRs (control and +status registers).# +[#norm:priv-levels-txt]#Three RISC-V privilege levels are currently defined# +as shown in <>. + +[[norm:priv-levels-tbl]] +.RISC-V privilege levels. +[%autowidth,float="center",align="center",cols="^,^,^,^",options="header"] +|=== +|Level |Encoding |Name |Abbreviation +|0 + +1 + +2 + +3 +|`00` + +`01` + +`10` + +`11` +|User/Application + +Supervisor + +_Reserved_ + +Machine +|U + +S + +{nbsp} + +M +|=== + +Privilege levels are used to provide protection between different +components of the software stack, and [#norm:non-priv-exc]#attempts to perform operations not +permitted by the current privilege mode will cause an exception to be +raised.# These exceptions will normally cause traps into an underlying +execution environment. + +[NOTE] +==== +In the description, we try to separate the privilege level for which +code is written, from the privilege mode in which it runs, although the +two are often tied. For example, a supervisor-level operating system can +run in supervisor-mode on a system with three privilege modes, but can +also run in user-mode under a classic virtual machine monitor on systems +with two or more privilege modes. In both cases, the same +supervisor-level operating system binary code can be used, coded to a +supervisor-level SBI and hence expecting to be able to use +supervisor-level privileged instructions and CSRs. When running a guest +OS in user mode, all supervisor-level actions will be trapped and +emulated by the SEE running in the higher-privilege level. +==== +[#norm:m-level-high-priv-only-mandatory]#The machine level has the highest privileges and +is the only mandatory privilege level for a RISC-V hardware platform.# Code run in machine-mode +(M-mode) is usually inherently trusted, as it has low-level access to +the machine implementation. M-mode can be used to manage secure +execution environments on RISC-V. User-mode (U-mode) and supervisor-mode +(S-mode) are intended for conventional application and operating system +usage respectively. + +Each privilege level has a core set of privileged ISA extensions with +optional extensions and variants. For example, machine-mode supports an +optional standard extension for memory protection. Also, supervisor mode +can be extended to support Type-2 hypervisor execution as described in +<>. + +[#norm:priv-combs-txt]#Implementations might provide anywhere from 1 to 3 privilege modes# +trading off reduced isolation for lower implementation cost, as shown in +<>. + +[[norm:priv-combs-tbl]] +.Supported combination of privilege modes. +[%autowidth,float="center",align="center",cols="^,<,<",options="header"] +|=== +|Number of levels |Supported Modes |Intended Usage +|1 + +2 + +3 +|M + +M, U + +M, S, U +|Simple embedded systems + +Secure embedded systems + +Systems running Unix-like operating systems +|=== + +[#norm:m-mode-mandatory]#All hardware implementations must provide M-mode#, as this is the only +mode that has unfettered access to the whole machine. The simplest +RISC-V implementations may provide only M-mode, though this will provide +no protection against incorrect or malicious application code. + +[NOTE] +==== +The lock feature of the optional PMP facility can provide some limited +protection even with only M-mode implemented. +==== +Many RISC-V implementations will also support at least user mode +(U-mode) to protect the rest of the system from application code. +Supervisor mode (S-mode) can be added to provide isolation between a +supervisor-level operating system and the SEE. + +A hart normally runs application code in U-mode until some trap (e.g., a +supervisor call or a timer interrupt) forces a switch to a trap handler, +which usually runs in a more privileged mode. The hart will then execute +the trap handler, which will eventually resume execution at or after the +original trapped instruction in U-mode. Traps that increase privilege +level are termed _vertical_ traps, while traps that remain at the same +privilege level are termed _horizontal_ traps. The RISC-V privileged +architecture provides flexible routing of traps to different privilege +layers. + +[NOTE] +==== +Horizontal traps can be implemented as vertical traps that return +control to a horizontal trap handler in the less-privileged mode. +==== + +=== Debug Mode + +Implementations may also include a debug mode to support off-chip +debugging and/or manufacturing test. Debug mode (D-mode) can be +considered an additional privilege mode, with even more access than +M-mode. The separate debug specification describes operation of +a RISC-V hart in debug mode. Debug mode reserves a few CSR addresses +that are only accessible in D-mode, and may also reserve some portions +of the physical address space on a platform. diff --git a/param_extraction/chunks/chunk_030.txt.license b/param_extraction/chunks/chunk_030.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_030.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_031.txt b/param_extraction/chunks/chunk_031.txt new file mode 100644 index 0000000000..ea34b4126f --- /dev/null +++ b/param_extraction/chunks/chunk_031.txt @@ -0,0 +1,606 @@ +# Chunk: chunk_031 +# Source: priv-preface.adoc +# Lines: 1-598 (of 598) +# Content starts: line 1 +# Line count: 598 +# Sections: 1 +# == Preface +# +[colophon] +== Preface + +This document describes the RISC-V privileged architecture. +It contains the following versions of the RISC-V ISA modules, +all of which have been ratified: + +[%autowidth,float="center",align="center",cols="^,<",options="header",] +|=== +|Module |Version +|*Machine ISA* + +*Smstateen Extension* + +*Smcsrind/Sscsrind Extension* + +*Smepmp Extension* + +*Smcntrpmf Extension* + +*Smrnmi Extension* + +*Smcdeleg Extension* + +*Smdbltrp Extension* + +*Smctr Extension* + +*Supervisor ISA* + +*Svade Extension* + +*Svnapot Extension* + +*Svpbmt Extension* + +*Svinval Extension* + +*Svadu Extension* + +*Svvptc Extension* + +*Ssqosid Extension* + +*Sstc Extension* + +*Sscofpmf Extension* + +*Ssdbltrp Extension* + +*Ssqosid Extension* + +*Hypervisor ISA* + +*Shlcofideleg Extension* + +*Svvptc Extension* + +*Pointer-Masking Extensions* + +*Svrsw60t59b Extension* + +|*1.13* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.13* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* +|=== + +The following changes have been made since version 20250508: + +* Addition of the Svrsw60t59b extension for additional PTE reserved-for-software bits. + +// Had to make the above a level 1 heading (two equals signs) to avoid error when building +// the ISA manual as a book with other "parts". This is opposite to what the adoc says to do +// but otherwise asciidoctor creates the error message: +// +// asciidoctor: ERROR: ext/riscv-isa-manual/src/priv-preface.adoc: line 2: invalid part, must have at least one section (e.g., chapter, appendix, etc.) +// +// See asciidoctor doc which seems wrong: https://docs.asciidoctor.org/asciidoc/latest/sections/colophon/ +[.big]*_Preface to Version 20250508_* + +This document describes the RISC-V privileged architecture. + +The ISA modules marked *Ratified* have been ratified at this time. The +modules marked _Frozen_ are not expected to change significantly before +being put up for ratification. The modules marked _Draft_ are expected +to change before ratification. + +The document contains the following versions of the RISC-V ISA modules: + +[%autowidth,float="center",align="center",cols="^,<,^",options="header",] +|=== +|Module |Version |Status +|*Machine ISA* + +*Smstateen Extension* + +*Smcsrind/Sscsrind Extension* + +*Smepmp Extension* + +*Smcntrpmf Extension* + +*Smrnmi Extension* + +*Smcdeleg Extension* + +*Smdbltrp Extension* + +*Smctr Extension* + +*Supervisor ISA* + +*Svade Extension* + +*Svnapot Extension* + +*Svpbmt Extension* + +*Svinval Extension* + +*Svadu Extension* + +*Svvptc Extension* + +*Ssqosid Extension* + +*Sstc Extension* + +*Sscofpmf Extension* + +*Ssdbltrp Extension* + +*Ssqosid Extension* + +*Hypervisor ISA* + +*Shlcofideleg Extension* + +*Svvptc Extension* + +*Pointer-Masking Extensions* + +|*1.13* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.13* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +|*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* +|=== + +The following changes have been made since version 20241101: + +* Addition of the Smctr Control Transfer Records extension. +* Addition of the Svvptc Extension for Obviating Memory-Management Instructions after Marking PTEs Valid. +* Addition of the Ssqosid Extension for Quality-of-Service Identifiers. +* Addition of the Pointer-Masking Extensions. + +[.big]*_Preface to Version 20241101_* + +This document describes the RISC-V privileged architecture. + +The ISA modules marked *Ratified* have been ratified at this time. The +modules marked _Frozen_ are not expected to change significantly before +being put up for ratification. The modules marked _Draft_ are expected +to change before ratification. + +The document contains the following versions of the RISC-V ISA modules: + +[%autowidth,float="center",align="center",cols="^,<,^",options="header",] +|=== +|Module |Version |Status +|*Machine ISA* + +*Smstateen Extension* + +*Smcsrind/Sscsrind Extension* + +*Smepmp Extension* + +*Smcntrpmf Extension* + +*Smrnmi Extension* + +*Smcdeleg Extension* + +*Smdbltrp Extension* + +*Supervisor ISA* + +*Svade Extension* + +*Svnapot Extension* + +*Svpbmt Extension* + +*Svinval Extension* + +*Svadu Extension* + +*Sstc Extension* + +*Sscofpmf Extension* + +*Ssdbltrp Extension* + +*Ssqosid Extension* + +*Hypervisor ISA* + +*Shlcofideleg Extension* + +*Svvptc Extension* + +|*1.13* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.13* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +|*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* +|=== + +[.big]*_Preface to Version 20241017_* + +This document describes the RISC-V privileged architecture. This +release, version 20241017, contains the following versions of the RISC-V ISA +modules: + +[%autowidth,float="center",align="center",cols="^,<,^",options="header",] +|=== +|Module |Version |Status +|*Machine ISA* + +*Smstateen Extension* + +*Smcsrind/Sscsrind Extension* + +*Smepmp* + +*Smcntrpmf* + +*Smrnmi Extension* + +*Smcdeleg* + +*Smdbltrp* + +*Supervisor ISA* + +*Svade Extension* + +*Svnapot Extension* + +*Svpbmt Extension* + +*Svinval Extension* + +*Svadu Extension* + +*Sstc* + +*Sscofpmf* + +*Ssdbltrp* + +*Hypervisor ISA* + +*Shlcofideleg* + +*Svvptc* + +|*1.13* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.13* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +|*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* +|=== + +The following changes have been made since version 1.12 of the Machine and +Supervisor ISAs, which, while not strictly backwards compatible, are not +anticipated to cause software portability problems in practice: + +* Redefined `misa`.MXL to be read-only, making MXLEN a constant. +* Added the constraint that SXLEN{ge}UXLEN. + +Additionally, the following compatible changes have been +made to the Machine and Supervisor ISAs since version 1.12: + +* Defined the `misa`.B field to reflect that the B extension has been +implemented. +* Defined the `misa`.V field to reflect that the V extension has been +implemented. +* Defined the RV32-only `medelegh` and `hedelegh` CSRs. +* Defined the misaligned atomicity granule PMA, superseding the proposed Zam + extension. +* Allocated interrupt 13 for Sscofpmf LCOFI interrupt. +* Defined hardware-error and software-check exception codes. +* Specified synchronization requirements when changing the PBMTE and ADUE fields +in `menvcfg` and `henvcfg`. +* Exposed count-overflow interrupts to VS-mode via the Shlcofideleg extension. +* Relaxed behavior of some HINTs when MXLEN > XLEN. +* Defined the format of the memory-mapped `msip` registers. + +Finally, the following clarifications and document improvements have been made +since the last document release: + +* Transliterated the document from LaTeX into AsciiDoc. +* Included all ratified extensions through March 2024. +* Clarified that "platform- or custom-use" interrupts are actually +"platform-use interrupts", where the platform can choose to make some custom. +* Clarified semantics of explicit accesses to CSRs wider than XLEN bits. +* Clarified that MXLEN{ge}SXLEN. +* Clarified that WFI is not a HINT instruction. +* Clarified that VS-stage page-table accesses set G-stage A/D bits. +* Clarified ordering rules when PBMT=IO is used on main-memory regions. +* Clarified ordering rules for hardware A/D bit updates. +* Clarified that, for a given exception cause, `__x__tval` might sometimes +be set to a nonzero value but sometimes not. +* Clarified exception behavior of unimplemented or inaccessible CSRs. +* Clarified that Svpbmt allows implementations to override additional PMAs. +* Replaced the concept of vacant memory regions with inaccessible memory or I/O regions. +* Clarified that timer and count-overflow interrupts' arrival in + interrupt-pending registers is not immediate. +* Clarified that MXR affects only explicit memory accesses. + +[.big]*_Preface to Version 20211203_* + +This document describes the RISC-V privileged architecture. This +release, version 20211203, contains the following versions of the RISC-V +ISA modules: + +[%autowidth,float="center",align="center",cols="^,<,^",options="header",] +|=== +|Module |Version |Status +|*Machine ISA* + +*Supervisor ISA* + +*Svnapot Extension* + +*Svpbmt Extension* + +*Svinval Extension* + +*Hypervisor ISA* + +|*1.12* + +*1.12* + +*1.0* + +*1.0* + +*1.0* + +*1.0* + +|*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* + +*Ratified* +|=== + +The following changes have been made since version 1.11, which, while +not strictly backwards compatible, are not anticipated to cause software +portability problems in practice: + +* Changed MRET and SRET to clear `mstatus`.MPRV when leaving M-mode. +* Reserved additional `satp` patterns for future use. +* Stated that the `scause` Exception Code field must implement bits 4–0 +at minimum. +* Relaxed I/O regions have been specified to follow RVWMO. The previous +specification implied that PPO rules other than fences and +acquire/release annotations did not apply. +* Constrained the LR/SC reservation set size and shape when using +page-based virtual memory. +* PMP changes require an SFENCE.VMA on any hart that implements +page-based virtual memory, even if VM is not currently enabled. +* Allowed for speculative updates of page table entry A bits. +* Clarify that if the address-translation algorithm non-speculatively +reaches a PTE in which a bit reserved for future standard use is set, a +page-fault exception must be raised. + +Additionally, the following compatible changes have been made since +version 1.11: + +* Removed the N extension. +* Defined the mandatory RV32-only CSR `mstatush`, which contains most of +the same fields as the upper 32 bits of RV64’s `mstatus`. +* Defined the mandatory CSR `mconfigptr`, which if nonzero contains the +address of a configuration data structure. +* Defined `mseccfg` and `mseccfgh` CSRs, which control the +machine’s security configuration. +* Defined `menvcfg`, `henvcfg`, and `senvcfg` CSRs (and RV32-only +`menvcfgh` and `henvcfgh` CSRs), which control various characteristics +of the execution environment. +* Designated part of SYSTEM major opcode for custom use. +* Permitted the unconditional delegation of less-privileged interrupts. +* Added optional big-endian and bi-endian support. +* Made priority of load/store/AMO address-misaligned exceptions +implementation-defined relative to load/store/AMO page-fault and +access-fault exceptions. +* PMP reset values are now platform-defined. +* An additional 48 optional PMP registers have been defined. +* Slightly relaxed the atomicity requirement for A and D bit updates +performed by the implementation. +* Clarify the architectural behavior of address-translation caches +* Added Sv57 and Sv57x4 address translation modes. +* Software breakpoint exceptions are permitted to write either 0 or the +`pc` to `__x__tval`. +* Clarified that bare S-mode need not support the SFENCE.VMA +instruction. +* Specified relaxed constraints for implicit reads of non-idempotent +regions. +* Added the Svnapot Standard Extension, along with the N bit in Sv39, +Sv48, and Sv57 PTEs. +* Added the Svpbmt Standard Extension, along with the PBMT bits in Sv39, +Sv48, and Sv57 PTEs. +* Added the Svinval Standard Extension and associated instructions. + +Finally, the hypervisor architecture proposal has been extensively +revised. + +[.big]*_Preface to Version 1.11_* + +This is version 1.11 of the RISC-V privileged architecture. The document +contains the following versions of the RISC-V ISA modules: + +[%autowidth,float="center",align="center",cols="^,<,^",options="header",] +|=== +|Module |Version |Status +|*Machine ISA* + +*Supervisor ISA* + +_Hypervisor ISA_ +|*1.11* + +*1.11* + +_0.3_ +|*Ratified* + +*Ratified* + +_Draft_ +|=== + +Changes from version 1.10 include: + +* Moved Machine and Supervisor spec to *Ratified* status. +* Improvements to the description and commentary. +* Added a draft proposal for a hypervisor extension. +* Specified which interrupt sources are reserved for standard use. +* Allocated some synchronous exception causes for custom use. +* Specified the priority ordering of synchronous exceptions. +* Added specification that xRET instructions may, but are not required +to, clear LR reservations if A extension present. +* The virtual-memory system no longer permits supervisor mode to execute +instructions from user pages, regardless of the SUM setting. +* Clarified that ASIDs are private to a hart, and added commentary about +the possibility of a future global-ASID extension. +* SFENCE.VMA semantics have been clarified. +* Made the `mstatus`.MPP field *WARL*, rather than *WLRL*. +* Made the unused `__x__ip` fields *WPRI*, rather than *WIRI*. +* Made the unused `misa` fields *WARL*, rather than *WIRI*. +* Made the unused `pmpaddr` and `pmpcfg` fields *WARL*, rather than *WIRI*. +* Required all harts in a system to employ the same PTE-update scheme as +each other. +* Rectified an editing error that misdescribed the mechanism by which +`mstatus.__x__IE` is written upon an exception. +* Described scheme for emulating misaligned AMOs. +* Specified the behavior of the `misa` and `__x__epc` registers in systems +with variable IALIGN. +* Specified the behavior of writing self-contradictory values to the +`misa` register. +* Defined the `mcountinhibit` CSR, which stops performance counters from +incrementing to reduce energy consumption. +* Specified semantics for PMP regions coarser than four bytes. +* Specified contents of CSRs across XLEN modification. +* Moved PLIC chapter into its own document. + +[.big]*_Preface to Version 1.10_* + +This is version 1.10 of the RISC-V privileged architecture proposal. +Changes from version 1.9.1 include: + +* The previous version of this document was released under a Creative +Commons Attribution 4.0 International License by the original authors, +and this and future versions of this document will be released under the +same license. +* The explicit convention on shadow CSR addresses has been removed to +reclaim CSR space. Shadow CSRs can still be added as needed. +* The `mvendorid` register now contains the JEDEC code of the core +provider as opposed to a code supplied by the Foundation. This avoids +redundancy and offloads work from the Foundation. +* The interrupt-enable stack discipline has been simplified. +* An optional mechanism to change the base ISA used by supervisor and +user modes has been added to the `mstatus` CSR, and the field previously +called Base in `misa` has been renamed to `MXL` for consistency. +* Clarified expected use of XS to summarize additional extension state +status fields in `mstatus`. +* Optional vectored interrupt support has been added to the `mtvec` and +`stvec` CSRs. +* The SEIP and UEIP bits in the `mip` CSR have been redefined to support +software injection of external interrupts. +* The `mbadaddr` register has been subsumed by a more general `mtval` +register that can now capture bad instruction bits on an illegal-instruction +fault to speed instruction emulation. +* The machine-mode base-and-bounds translation and protection schemes +have been removed from the specification as part of moving the virtual +memory configuration to `sptbr` (now `satp`). Some of the motivation for +the base and bound schemes are now covered by the PMP registers, but +space remains available in `mstatus` to add these back at a later date +if deemed useful. +* In systems with only M-mode, or with both M-mode and U-mode but +without U-mode trap support, the `medeleg` and `mideleg` registers now +do not exist, whereas previously they returned zero. +* Virtual-memory page faults now have `mcause` values distinct from +physical-memory access faults. Page-fault exceptions can now be +delegated to S-mode without delegating exceptions generated by PMA and +PMP checks. +* An optional physical-memory protection (PMP) scheme has been proposed. +* The supervisor virtual memory configuration has been moved from the +`mstatus` register to the `sptbr` register. Accordingly, the `sptbr` +register has been renamed to `satp` (Supervisor Address Translation and +Protection) to reflect its broadened role. +* The SFENCE.VM instruction has been removed in favor of the improved +SFENCE.VMA instruction. +* The `mstatus` bit MXR has been exposed to S-mode via `sstatus`. +* The polarity of the PUM bit in `sstatus` has been inverted to shorten +code sequences involving MXR. The bit has been renamed to SUM. +* Hardware management of page-table entry Accessed and Dirty bits has +been made optional; simpler implementations may trap to software to set +them. +* The counter-enable scheme has changed, so that S-mode can control +availability of counters to U-mode. +* H-mode has been removed, as we are focusing on recursive +virtualization support in S-mode. The encoding space has been reserved +and may be repurposed at a later date. +* A mechanism to improve virtualization performance by trapping S-mode +virtual-memory management operations has been added. +* The Supervisor Binary Interface (SBI) chapter has been removed, so +that it can be maintained as a separate specification. + +[.big]*_Preface to Version 1.9.1_* + +This is version 1.9.1 of the RISC-V privileged architecture proposal. +Changes from version 1.9 include: + +* Numerous additions and improvements to the commentary sections. +* Change configuration string proposal to be use a search process that +supports various formats including Device Tree String and flattened +Device Tree. +* Made `misa` optionally writable to support modifying base and +supported ISA extensions. CSR address of `misa` changed. +* Added description of debug mode and debug CSRs. +* Added a hardware performance monitoring scheme. Simplified the +handling of existing hardware counters, removing privileged versions of +the counters and the corresponding delta registers. +* Fixed description of SPIE in presence of user-level interrupts. diff --git a/param_extraction/chunks/chunk_031.txt.license b/param_extraction/chunks/chunk_031.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_031.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_032.txt b/param_extraction/chunks/chunk_032.txt new file mode 100644 index 0000000000..ac11d6346b --- /dev/null +++ b/param_extraction/chunks/chunk_032.txt @@ -0,0 +1,89 @@ +# Chunk: chunk_032 +# Source: priv-rationale.adoc +# Lines: 1-80 (of 80) +# Content starts: line 1 +# Line count: 80 +# Sections: 2 +# == Historical Rationale for Extensions +# === "Smepmp" Extension for PMP Enhancements for memory access and execution prevention in Machine mode +# +[appendix] +== Historical Rationale for Extensions +[[chap:rationale]] + +This appendix contains the rationale for RISC-V ISA extensions at the time they +were ratified. +Unlike the ISA specification, this appendix is ordered chronologically, so as +to convey the motivation and architectural reasoning underpinning each +extension at the time of ratification. +For extensions ratified prior to the conception of this appendix (ca. 2025), +the rationale will be added over time. +In cases where the rationale was not recorded, the authors and editors will +synthesize it from the historical record. + +[[smepmp_rationale]] +=== "Smepmp" Extension for PMP Enhancements for memory access and execution prevention in Machine mode + +. Since a CSR for security and / or global PMP behavior settings is not available with the current spec, we needed to define a new `mseccfg` CSR. This new CSR will allow us to add further security configuration options in the future and also allow developers to verify the existence of the new mechanisms defined on this extension. + +. There are use cases where developers want to enforce PMP rules in M-mode during the boot process, that are also able to modify, merge, and / or remove later on. Since a rule that is enforced in M-mode also needs to be locked (or else badly written or malicious M-mode software can remove it at any time), the only way for developers to approach this is to keep adding PMP rules to the chain and rely on rule priority. This is a waste of PMP rules and since it’s only needed during boot, ``mseccfg.RLB`` is a simple workaround that can be used temporarily and then disabled and locked down. ++ +Also when ``mseccfg.MML`` is set, according to 4b it’s not possible to add a _Shared-Region_ rule with executable privileges. So RLB can be set temporarily during the boot process to register such regions. Note that it’s still possible to register executable _Shared-Region_ rules using initial register settings (that may include ``mseccfg.MML`` being set and the rule being set on PMP registers) on *PMP reset*, without using RLB. ++ +[WARNING] +==== +*Be aware that RLB introduces a security vulnerability if left set after the boot process is over and in general it should be used with caution, even when used temporarily.* Having editable PMP rules in M-mode gives a false sense of security since it only takes a few malicious instructions to lift any PMP restrictions this way. It doesn’t make sense to have a security control in place and leave it unprotected. Rule Locking Bypass is only meant as a way to optimize the allocation of PMP rules, catch errors during debugging, and allow the bootrom/firmware to register executable _Shared-Region_ rules. If developers / vendors have no use for such functionality, they should never set ``mseccfg.RLB`` and if possible hard-wire it to 0. In any case *RLB should be disabled and locked as soon as possible*. +==== ++ +[NOTE] +==== +If ``mseccfg.RLB`` is not used and left unset, it will be locked as soon as a PMP rule/entry with the ``pmpcfg.L`` bit set is configured. +==== ++ +[IMPORTANT] +==== +Since PMP rules with a higher priority override rules with a lower priority, locked rules must precede non-locked rules. +==== + +. With the current spec M-mode can access any memory region unless restricted by a PMP rule with the ``pmpcfg.L`` bit set. There are cases where this approach is overly permissive, and although it’s possible to restrict M-mode by adding PMP rules during the boot process, this can also be seen as a waste of PMP rules. Having the option to block anything by default, and use PMP as an allowlist for M-mode is considered a safer approach. This functionality may be used during the boot process or upon *PMP reset*, using initial register settings. + + +. The current dual meaning of the ``pmpcfg.L`` bit that marks a rule as Locked and *enforced* on all modes is neither flexible nor clean. With the introduction of _Machine Mode Lock-down_ the ``pmpcfg.L`` bit distinguishes between rules that are *enforced* *only* in M-mode (_M-mode-only_) or *only* in S/U-modes (_S/U-mode-only_). The rule locking becomes part of the definition of an _M-mode-only_ rule, since when a rule is added in M mode, if not locked, can be modified or removed in a few instructions. On the other hand, S/U modes can’t modify PMP rules anyway so locking them doesn’t make sense. + +.. This separation between _M-mode-only_ and _S/U-mode-only_ rules also allows us to distinguish which regions are to be used by processes in Machine mode (``pmpcfg.L == 1``) and which by Supervisor or User mode processes (``pmpcfg.L == 0``), in the same way the U bit on the Virtual Memory’s PTEs marks which Virtual Memory pages are to be used by User mode applications (U=1) and which by the Supervisor / OS (U=0). With this distinction in place we are able to implement memory access and execution prevention in M-mode for any physical memory region that is not _M-mode-only_. ++ +An attacker that manages to tamper with a memory region used by S/U mode, even after successfully tricking a process running in M-mode to use or execute that region, will fail to perform a successful attack since that region will be _S/U-mode-only_ hence any access when in M-mode will trigger an access exception. ++ +[NOTE] +==== +In order to support zero-copy transfers between M-mode and S/U-mode we need to either allow shared memory regions, or introduce a mechanism similar to the ``sstatus.SUM`` bit to temporary allow the high-privileged mode (in this case M-mode) to be able to perform loads and stores on the region of a less-privileged process (in this case S/U-mode). In our case after discussion within the group it seemed a better idea to follow the first approach and have this functionality encoded on a per-rule basis to avoid the risk of leaving a temporary, global bypass active when exiting M-mode, hence rendering memory access prevention useless. +==== ++ + +[NOTE] +==== +Although it’s possible to use ``mstatus.MPRV`` in M-mode to read/write data on an _S/U-mode-only_ region using general purpose registers for copying, this will happen with S/U-mode permissions, honoring any MMU restrictions put in place by S-mode. Of course it’s still possible for M-mode to tamper with the page tables and / or add _S/U-mode-only_ rules and bypass the protections put in place by S-mode but if an attacker has managed to compromise M-mode to such extent, no security guarantees are possible in any way. *Also note that the threat model we present here assumes buggy software in M-mode, not compromised software*. We considered disabling ``mstatus.MPRV`` but it seemed too much and out of scope. +==== ++ +_Shared-region_ rules can be used both for zero-copy data transfers and for sharing code segments. The latter may be used for example to allow S/U-mode to execute code by the vendor, that makes use of some vendor-specific ISA extension, without having to go through the firmware with an ecall. This is similar to the vDSO approach followed on Linux, that allows user space code to execute kernel code without having to perform a system call. ++ +To make sure that shared data regions can’t be executed and shared code regions can’t be modified, the encoding changes the meaning of the ``pmpcfg.X bit``. In case of shared data regions, with the exception of the ``pmpcfg.LRWX=1111`` encoding, the ``pmpcfg.X`` bit marks the capability of S/U-mode to write to that region, so it’s not possible to encode an executable shared data region. In case of shared code regions, the ``pmpcfg.X`` bit marks the capability of M-mode to read from that region, and since ``pmpcfg.RW=01`` is used for encoding the shared region, it’s not possible to encode a shared writable code region. ++ +[NOTE] +==== +For adding _Shared-region_ rules with executable privileges to share code segments between M-mode and S/U-mode, ``mseccfg.RLB`` needs to be implemented, or else such rules can only be added together with ``mseccfg.MML`` being set on *PMP Reset*. That's because the reserved encoding ``pmpcfg.RW=01`` being used for _Shared-region_ rules is only defined when ``mseccfg.MML`` is set, and 4b prevents the addition of rules with executable privileges on M-mode after ``mseccfg.MML`` is set unless ``mseccfg.RLB`` is also set. +==== ++ +[NOTE] +==== +Using the ``pmpcfg.LRWX=1111`` encoding for a locked shared read-only data region was decided later on, its initial meaning was an M-mode-only read/write/execute region. The reason for that change was that the already defined shared data regions were not locked, so r/w access to M-mode couldn’t be restricted. In the same way we have execute-only shared code regions for both modes, it was decided to also be able to allow a least-privileged shared data region for both modes. This approach allows for example to share the .text section of an ELF with a shared code region and the .rodata section with a locked shared data region, without allowing M-mode to modify .rodata. We also decided that having a locked read/write/execute region in M-mode doesn’t make much sense and could be dangerous, since M-mode won’t be able to add further restrictions there (as in the case of S/U-mode where S-mode can further limit access to an ``pmpcfg.LWRX=0111`` region through the MMU), leaving the possibility of modifying an executable region in M-mode open. +==== ++ +[NOTE] +==== +For encoding Shared-region rules initially we used one of the two reserved bits on pmpcfg (bit 5) but in order to avoid allocating an extra bit, since those bits are a very limited resource, it was decided to use the reserved R=0,W=1 combination. +==== +.. The idea with this restriction is that after the Firmware or the OS running in M-mode is initialized and ``mseccfg.MML`` is set, no new code regions are expected to be added since nothing else is expected to run in M-mode (everything else will run in S/U mode). Since we want to limit the attack surface of the system as much as possible, it makes sense to disallow any new code regions which may include malicious code, to be added/executed in M-mode. + +.. In case ``mseccfg.MMWP`` is not set, M-mode can still access and execute any region not covered by a PMP rule. Since we try to prevent M-mode from executing malicious code and since an attacker may manage to place code on some region not covered by PMP (e.g. a directly-addressable flash memory), we need to ensure that M-mode can only execute the code segments initialized during firmware / OS initialization. + +.. We are only using the encoding ``pmpcfg.RW=01`` together with ``mseccfg.MML``, if ``mseccfg.MML`` is not set the encoding remains usable for future use. diff --git a/param_extraction/chunks/chunk_032.txt.license b/param_extraction/chunks/chunk_032.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_032.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_033.txt b/param_extraction/chunks/chunk_033.txt new file mode 100644 index 0000000000..e22faaf34e --- /dev/null +++ b/param_extraction/chunks/chunk_033.txt @@ -0,0 +1,133 @@ +# Chunk: chunk_033 +# Source: q-st-ext.adoc +# Lines: 1-120 (of 120) +# Content starts: line 1 +# Line count: 120 +# Sections: 6 +# == "Q" Extension for Quad-Precision Floating-Point, Version 2.2 +# === Quad-Precision Load and Store Instructions +# === Quad-Precision Computational Instructions +# === Quad-Precision Convert and Move Instructions +# === Quad-Precision Floating-Point Compare Instructions +# === Quad-Precision Floating-Point Classify Instruction +# +== "Q" Extension for Quad-Precision Floating-Point, Version 2.2 + +This chapter describes the Q standard extension for 128-bit +quad-precision binary floating-point instructions compliant with the +IEEE 754-2008 arithmetic standard. The quad-precision binary +floating-point instruction-set extension is named "Q"; it depends on +the double-precision floating-point extension D. [#norm:Q_flen_128]#The floating-point +registers are now extended to hold either a single, double, or +quad-precision floating-point value (FLEN=128).# The NaN-boxing scheme +described in <> is now extended +recursively to allow a single-precision value to be NaN-boxed inside a +double-precision value which is itself NaN-boxed inside a quad-precision +value. + +=== Quad-Precision Load and Store Instructions + +[[norm:fsq_flq_op]] +New 128-bit variants of LOAD-FP and STORE-FP instructions are added, +encoded with a new value for the funct3 width field. + +include::images/wavedrom/quad-ls.edn[] +[[quad-ls]] +//.Quad-precision load and store + +[[norm:fsq_flq_atomic_align]] +FLQ and FSQ are only guaranteed to execute atomically if the effective +address is naturally aligned and XLEN=128. + +[[norm:fsq_flq_bits_maintained]] +FLQ and FSQ do not modify the bits being transferred; in particular, the +payloads of non-canonical NaNs are preserved. + +=== Quad-Precision Computational Instructions + +A new supported format is added to the format field of most +instructions, as shown in <> + +[[fpextfmt]] +.Format field encoding. +[%autowidth,float="center",align="center",cols="^,^,<",options="header",] +|=== +|_fmt_ field |Mnemonic |Meaning +|00 |S |32-bit single-precision +|01 |D |64-bit double-precision +|10 |H |16-bit half-precision +|11 |Q |128-bit quad-precision +|=== + +[[norm:Q_computational_instrs]] +The quad-precision floating-point computational instructions are defined +analogously to their double-precision counterparts, but operate on +quad-precision operands and produce quad-precision results. + +include::images/wavedrom/quad-compute.edn[] +[[quad-compute]] +//.Quad-precision computational + +=== Quad-Precision Convert and Move Instructions + +New floating-point-to-integer and integer-to-floating-point conversion +instructions are added. These instructions are defined analogously to +the double-precision-to-integer and integer-to-double-precision +conversion instructions. [#norm:fcvt-w-q_fcvt-l-q_op]#FCVT.W.Q or FCVT.L.Q converts a quad-precision +floating-point number to a signed 32-bit or 64-bit integer, +respectively#. [#norm:fcvt-q-w_fcvt-q-l_op]#FCVT.Q.W or FCVT.Q.L converts a 32-bit or 64-bit signed +integer, respectively, into a quad-precision floating-point number#. +[#norm:fcvt-wu-q_fcvt-lu-q_fcvt-q-wu_fcvt-q-lu_op]#FCVT.WU.Q, FCVT.LU.Q, FCVT.Q.WU, and FCVT.Q.LU variants convert to or +from unsigned integer values#. [#norm:fcvt_long_quad_rv64_only]#FCVT.L[U].Q and FCVT.Q.L[U] are RV64-only +instructions#. Note FCVT.Q.L[U] always produces an exact result and is unaffected by rounding mode. + +include::images/wavedrom/quad-cnvrt-mv.edn[] +[[quad-cnvrt-mv]] +//.Quad-precision convert and move + +New floating-point-to-floating-point conversion instructions are added. +These instructions are defined analogously to the double-precision +floating-point-to-floating-point conversion instructions. [#norm:fcvt-s-q_fcvt-q-s_op]#FCVT.S.Q or +FCVT.Q.S converts a quad-precision floating-point number to a +single-precision floating-point number, or vice-versa, respectively#. +[#norm:fcvt-d-q_fcvt-q-d_op]#FCVT.D.Q or FCVT.Q.D converts a quad-precision floating-point number to +a double-precision floating-point number, or vice-versa, respectively#. + +include::images/wavedrom/quad-cnvt-interchange.edn[] +[[quad-convert-interchange]] +//.Quad-precision convert and move interchangeably + +[[norm:fsgnj-q_fsgnjn-q_fsgnjx-q_op]] +Floating-point to floating-point sign-injection instructions, FSGNJ.Q, +FSGNJN.Q, and FSGNJX.Q are defined analogously to the double-precision +sign-injection instruction. + +include::images/wavedrom/quad-cnvrt-intch-xqqx.edn[] +[[quad-cnvrt-intch-xqqx]] +//.Quad-precision convert and move interchangeably XQ-QX + +FMV.X.Q and FMV.Q.X instructions are not provided in RV32 or RV64, so +quad-precision bit patterns must be moved to the integer registers via +memory. + +=== Quad-Precision Floating-Point Compare Instructions + +[[norm:Q_compare_instrs]] +The quad-precision floating-point compare instructions are defined +analogously to their double-precision counterparts, but operate on +quad-precision operands. + +include::images/wavedrom/quad-float-compare.edn[] +[[quad-float-compare]] +//.Quad-precision floatinf-point compare + +=== Quad-Precision Floating-Point Classify Instruction + +[[norm:fclass-q_op]] +The quad-precision floating-point classify instruction, FCLASS.Q, is +defined analogously to its double-precision counterpart, but operates on +quad-precision operands. + +include::images/wavedrom/quad-float-clssfy.edn[] +[[quad-float-clssfy]] +//.Quad-precision floating point classify diff --git a/param_extraction/chunks/chunk_033.txt.license b/param_extraction/chunks/chunk_033.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_033.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_034.txt b/param_extraction/chunks/chunk_034.txt new file mode 100644 index 0000000000..f802b7f30b --- /dev/null +++ b/param_extraction/chunks/chunk_034.txt @@ -0,0 +1,119 @@ +# Chunk: chunk_034 +# Source: rationale.adoc +# Lines: 1-107 (of 107) +# Content starts: line 1 +# Line count: 107 +# Sections: 5 +# == Historical Rationale for Extensions +# === "Zihintpause" Extension for Pause Hint +# === "Zicond" Extension for Integer Conditional Operations +# === "Zacas" Extension for Atomic Compare-and-Swap (CAS) Instructions +# === "Zabha" Extension for Byte and Halfword Atomic Memory Operations, Version 1.0 +# +[appendix] +== Historical Rationale for Extensions +[[chap:rationale]] + +This appendix contains the rationale for RISC-V ISA extensions at the time they +were ratified. +Unlike the ISA specification, this appendix is ordered chronologically, so as +to convey the motivation and architectural reasoning underpinning each +extension at the time of ratification. +For extensions ratified prior to the conception of this appendix (ca. 2025), +the rationale will be added over time. +In cases where the rationale was not recorded, the authors and editors will +synthesize it from the historical record. + +=== "Zihintpause" Extension for Pause Hint + +The PAUSE instruction hints to a hart that it should temporarily reduce its +rate of execution. +It is normally used to save energy and execution resources while polling, e.g. +while waiting for a spinlock to become free. + +Much of the debate surrounding this extension centered on whether a facility +similar to x86's MONITOR/MWAIT should instead be provided. +We concluded that, even if such a facility were to be defined for RISC-V, +it would not supplant PAUSE. +PAUSE is more appropriate when polling for non-memory events, when polling for +multiple events, or when software does not know precisely what events it is +polling for. +(Perhaps surprisingly, the latter case is ubiquitous, in part because it is +the mechanism expected by the Linux kernel's `cpu_relax` API.) + +=== "Zicond" Extension for Integer Conditional Operations + +Replacing unpredictable branches with conditional-select or conditional-move +instructions can mitigate a class of costly branch mispredictions. +Unfortunately, conditional-select instructions require three source operands. +These instructions are a logical addition to ISAs that include three-source +integer instructions for other reasons, but are too costly otherwise. + +Some ISAs have instead furnished conditional-move instructions, which consume +less encoding space and avoid the extra register read in simple +microarchitectures. +Unfortunately, in register-renamed microarchitectures, these instructions incur +costs simlar to conditional select, or require additional microarchitectural +structures and micro-op-issue constraints. + +The Zicond extension was defined to solve the same problem as conditional +select and conditional move, but with very little incremental cost for complex +microarchitectures. +It provides conditional-zero instructions, which read two source operands and, +based upon the zeroness of the second operand, produce either the first operand +or zero. +These instructions can be used as part of a three-instruction sequence to +synthesize conditional select. +Several common conditional-execution idioms require only two instructions, +as would be the case with conditional select or move, including +conditional addition, subtraction, and bitwise AND, OR, and XOR. + +Two conditional-zero instructions are included: one that writes zero if the +comparand is zero, and one that does so if the comparand is nonzero. +Variants that perform magnitude comparisons with zero were considered but +ultimately excluded for insufficient quantitative justification. + +=== "Zacas" Extension for Atomic Compare-and-Swap (CAS) Instructions + +While compare-and-swap for XLEN wide data may be accomplished using LR/SC, the +CAS atomic instructions scale better to highly parallel systems than LR/SC. +Many lock-free algorithms, such as a lock-free queue, require manipulation of +pointer variables. A simple CAS operation may not be sufficient to guard against +what is commonly referred to as the ABA problem in such algorithms that +manipulate pointer variables. To avoid the ABA problem, the algorithms associate +a reference counter with the pointer variable and perform updates using a +quadword compare and swap (of both the pointer and the counter). The double and +quadword CAS instructions support implementation of algorithms for ABA problem +avoidance. + +The CAS instruction supports the C++11 atomic compare and exchange +operation. + +=== "Zabha" Extension for Byte and Halfword Atomic Memory Operations, Version 1.0 + +The A-extension offers atomic memory operation (AMO) instructions for _words_, +_doublewords_, and _quadwords_ (only for `AMOCAS`). The absence of atomic +operations for subword data types necessitates emulation strategies. For bitwise +operations, this emulation can be performed via word-sized bitwise AMO* +instructions. For non-bitwise operations, emulation is achievable using +word-sized `LR`/`SC` instructions. + +Several limitations arise from this emulation approach: + +. In systems with large-scale or Non-Uniform Memory Access (NUMA) + configurations, emulation based on `LR`/`SC` introduces issues related to + scalability and fairness, particularly under conditions of high contention. + +. Emulation of narrower AMOs through wider AMO* instructions on non-idempotent + IO memory regions may result in unintended side effects. + +. Utilizing wider AMO* instructions for emulating narrower AMOs risks activating + extraneous breakpoints or watchpoints. + +. In the absence of native support for subword atomics, compilers often resort + to inlining code sequences to provide the required emulation. This practice + contributes to an increase in code size, with consequent impacts on system + performance and memory utilization. + +The Zabha extension addresses these limitations by adding support for _byte_ and +_halfword_ atomic memory operations to the RISC-V Unprivileged ISA. diff --git a/param_extraction/chunks/chunk_034.txt.license b/param_extraction/chunks/chunk_034.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_034.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_035.txt b/param_extraction/chunks/chunk_035.txt new file mode 100644 index 0000000000..5d25bc35a2 --- /dev/null +++ b/param_extraction/chunks/chunk_035.txt @@ -0,0 +1,143 @@ +# Chunk: chunk_035 +# Source: riscv-privileged.adoc +# Lines: 1-136 (of 136) +# Content starts: line 1 +# Line count: 136 +# Sections: 0 +# +[[manual:priv,RISC-V ISA Manual, Volume II: Privileged Architecture]] += The RISC-V Instruction Set Manual, Volume II: Privileged Architecture +include::../docs-resources/global-config.adoc[] +:description: Privileged Architecture +//development: assume everything can change +//stable: assume everything could change +//frozen: of you implement this version you assume the risk that something might change because of the public review cycle but we expect little to no change. +//ratified: you can implement this and be assured nothing will change. if something needs to change due to an errata or enhancement, it will come out in a new extension. we do not revise extensions. +:colophon: +:preface-title: Preamble +:appendix-caption: Appendix +:imagesdir: ../docs-resources/images +:title-logo-image: image:risc-v_logo.png["RISC-V International Logo",pdfwidth=3.25in,align=center] +ifdef::draft-watermark[] +:page-background-image: image:draft.png[opacity=20%] +endif::[] +//:title-page-background-image: none +//:back-cover-image: image:backpage.png[opacity=25%] +// Settings: +:experimental: +:reproducible: +:imagesoutdir: {docdir}/../build/images-out +:bibtex-file: src/resources/riscv-spec.bib +:bibtex-order: alphabetical +:bibtex-style: apa +:bibtex-format: asciidoc +:bibtex-throw: false +:icons: font +:lang: en +:example-caption: Example +:listing-caption: Listing +:sectnums: +:sectnumlevels: 5 +:sectlinks: +:toc: left +:toclevels: 4 +:source-highlighter: rouge +:table-caption: Table +:figure-caption: Figure +:xrefstyle: short +:chapter-refsig: Chapter +:section-refsig: Section +:appendix-refsig: Appendix +// Uncomment :data-uri: if your eBook reader is not capable of rendering +// embedded images. One known affected device is PocketBook InkPad 3. +:data-uri: +:hide-uri-scheme: +:stem: latexmath +:footnote: +:imagesdir: images + +include::symbols.adoc[] + +_Contributors to all versions of the spec in alphabetical order (please contact editors to suggest corrections): +Krste Asanović, +Peter Ashenden, +Rimas Avižienis, +Jacob Bachmeyer, +Allen J. Baum, +Jonathan Behrens, +Paolo Bonzini, +Ruslan Bukin, +Christopher Celio, +Chuanhua Chang, +David Chisnall, +Anthony Coulter, +Palmer Dabbelt, +Monte Dalrymple, +Paul Donahue, +Greg Favor, +Dennis Ferguson, +Marc Gauthier, +Andy Glew, +Gary Guo, +Mike Frysinger, +John Hauser, +David Horner, +Olof Johansson, +David Kruckemyer, +Yunsup Lee, +Daniel Lustig, +Andrew Lutomirski, +Martin Maas, +Prashanth Mundkur, +Jonathan Neuschäfer, +Rishiyur Nikhil, +Stefan O'Rear, +Albert Ou, +John Ousterhout, +David Patterson, +Dmitri Pavlov, +Kade Phillips, +Josh Scheid, +Colin Schmidt, +Michael Taylor, +Wesley Terpstra, +Matt Thomas, +Tommy Thorn, +Ray VanDeWalker, +Megan Wachs, +Steve Wallach, +Andrew Waterman, +Claire Wolf, +Adam Zabrocki, +and Reinoud Zandijk._ + +_This document is released under a Creative Commons Attribution 4.0 International License._ + +_This document is a derivative of the RISC-V +privileged specification version 1.9.1 released under following license: ©2010-2017 Andrew Waterman, Yunsup Lee, Rimas +Avižienis, +David Patterson, Krste Asanović. Creative Commons Attribution 4.0 International License._ + +include::priv-preface.adoc[] +include::priv-intro.adoc[] +include::priv-csrs.adoc[] +include::machine.adoc[] +include::smstateen.adoc[] +include::indirect-csr.adoc[] +include::smepmp.adoc[] +include::smcntrpmf.adoc[] +include::rnmi.adoc[] +include::smcdeleg.adoc[] +include::smdbltrp.adoc[] +include::smctr.adoc[] +include::supervisor.adoc[] +include::sstc.adoc[] +include::sscofpmf.adoc[] +include::hypervisor.adoc[] +include::priv-cfi.adoc[] +include::ssdbltrp.adoc[] +include::zpm.adoc[] +include::priv-insns.adoc[] +include::priv-history.adoc[] +include::priv-rationale.adoc[] +include::bibliography.adoc[] diff --git a/param_extraction/chunks/chunk_035.txt.license b/param_extraction/chunks/chunk_035.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_035.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_036.txt b/param_extraction/chunks/chunk_036.txt new file mode 100644 index 0000000000..43609d1f00 --- /dev/null +++ b/param_extraction/chunks/chunk_036.txt @@ -0,0 +1,213 @@ +# Chunk: chunk_036 +# Source: riscv-unprivileged.adoc +# Lines: 1-206 (of 206) +# Content starts: line 1 +# Line count: 206 +# Sections: 0 +# +[[manual:unpriv,RISC-V ISA Manual, Volume I: Unprivileged Architecture]] += The RISC-V Instruction Set Manual, Volume I: Unprivileged Architecture +include::../docs-resources/global-config.adoc[] +:description: Unprivileged Architecture +:colophon: +:preface-title: Preamble +:appendix-caption: Appendix +:imagesdir: ../docs-resources/images +:title-logo-image: image:risc-v_logo.png["RISC-V International Logo",pdfwidth=3.25in,align=center] +ifdef::draft-watermark[] +:page-background-image: image:draft.png[opacity=20%] +endif::[] +//:title-page-background-image: none +//:back-cover-image: image:backpage.png[opacity=25%] +:back-cover-image: image:riscv-horizontal-color.svg[opacity=25%] +// Settings: +:experimental: +:reproducible: +:imagesoutdir: {docdir}/../build/images-out +:bibtex-file: src/resources/riscv-spec.bib +:bibtex-order: alphabetical +:bibtex-style: apa +:bibtex-format: asciidoc +:bibtex-throw: false +:icons: font +:lang: en +:example-caption: Example +:listing-caption: Listing +:sectnums: +:sectnumlevels: 5 +:sectlinks: +:toc: left +:toclevels: 5 +:source-highlighter: rouge +:table-caption: Table +:figure-caption: Figure +:xrefstyle: short +:chapter-refsig: Chapter +:section-refsig: Section +:appendix-refsig: Appendix +// Uncomment :data-uri: if your eBook reader is not capable of rendering +// embedded images. One known affected device is PocketBook InkPad 3. +:data-uri: +:hide-uri-scheme: +:stem: latexmath +:footnote: +:csrname: envcfg +:imagesdir: images + +include::symbols.adoc[] + +_Contributors to all versions of the spec in alphabetical order (please contact editors to suggest corrections): +Arvind, +Krste Asanović, +Derek Atkins, +Rimas Avižienis, +Jacob Bachmeyer, +Christopher F. Batten, +Allen J. Baum, +Scott Beamer, +Abel Bernabeu, +Hans Boehm, +Alex Bradbury, +Preston Briggs, +Christopher Celio, +Chuanhua Chang, +David Chisnall, +Paul Clayton, +Palmer Dabbelt, +L Peter Deutsch, +Ken Dockser, +Paul Donahue, +Aaron Durbin, +Roger Espasa, +Greg Favor, +Shaked Flur, +Stefan Freudenberger, +Marc Gauthier, +Andy Glew, +Jan Gray, +Gianluca Guida, +Michael Hamburg, +John Hauser, +Christian Herber, +David Horner, +Bruce Hoult, +Bill Huffman, +John Ingalls, +Alexandre Joannou, +Olof Johansson, +Ben Keller, +David Kruckemyer, +Tariq Kurd, +Yunsup Lee, +Paul Loewenstein, +Daniel Lustig, +Yatin Manerkar, +Luc Maranget, +Ben Marshall, +Margaret Martonosi, +Phil McCoy, +Nathan Menhorn, +Christoph Müllner, +Joseph Myers, +Vijayanand Nagarajan, +Torbjørn Viem Ness, +Rishiyur Nikhil, +Jonas Oberhauser, +Stefan O'Rear, +Markku-Juhani O. Saarinen, +Albert Ou, +John Ousterhout, +Daniel Page, +David Patterson, +Christopher Pulte, +Jose Renau, +Susmit Sarkar, +Josh Scheid, +Colin Schmidt, +Peter Sewell, +Ved Shanbhogue, +Brent Spinney, +Brendan Sweeney, +Michael Taylor, +Wesley Terpstra, +Matt Thomas, +Tommy Thorn, +Philipp Tomsich, +Caroline Trippel, +Ray VanDeWalker, +Muralidaran Vijayaraghavan, +Megan Wachs, +Paul Wamsley, +Andrew Waterman, +Robert Watson, +David Weaver, +Derek Williams, +Claire Wolf, +Andrew Wright, +Reinoud Zandijk, +and Sizhuo Zhang._ + +_This document is released under a Creative Commons Attribution 4.0 International License._ + +_This document is a derivative of “The RISC-V Instruction Set Manual, Volume I: User-Level ISA +Version 2.1” released under the following license: ©2010-2017 Andrew Waterman, Yunsup Lee, +David Patterson, Krste Asanović. Creative Commons Attribution 4.0 International License. +Please cite as: “The RISC-V Instruction Set Manual, Volume I: User-Level ISA, Document +Version 20191214-draft”, Editors Andrew Waterman and Krste Asanović, RISC-V Foundation, +December 2019._ + +//the colophon allows for a section after the preamble that is part of the frontmatter and therefore not assigned a page number. +include::colophon.adoc[] + +include::intro.adoc[] +include::rv32.adoc[] +include::rv32e.adoc[] +include::rv64.adoc[] +include::zifencei.adoc[] +include::zicsr.adoc[] +include::counters.adoc[] +include::zihintntl.adoc[] +include::zihintpause.adoc[] +include::zimop.adoc[] +include::zicond.adoc[] +include::m-st-ext.adoc[] +include::a-st-ext.adoc[] +include::zawrs.adoc[] +include::zacas.adoc[] +include::zabha.adoc[] +include::zalasr.adoc[] +include::rvwmo.adoc[] +include::ztso-st-ext.adoc[] +include::cmo.adoc[] +include::f-st-ext.adoc[] +include::d-st-ext.adoc[] +include::q-st-ext.adoc[] +include::zfh.adoc[] +include::bfloat16.adoc[] +include::zfa.adoc[] +include::zfinx.adoc[] +include::c-st-ext.adoc[] +include::zc.adoc[] +include::b-st-ext.adoc[] +include::v-st-ext.adoc[] +include::scalar-crypto.adoc[] +include::vector-crypto.adoc[] +include::unpriv-cfi.adoc[] +include::zilsd.adoc[] +include::rv-32-64g.adoc[] +include::naming.adoc[] +include::mm-eplan.adoc[] +include::mm-formal.adoc[] + +//Appendices for Vector +include::vector-examples.adoc[] +include::calling-convention.adoc[] +//End of Vector appendices +include::bitmanip-examples.adoc[] +include::rationale.adoc[] +//include::fraclmul.adoc[] + +include::index.adoc[] +// this is generated generated from index markers. +include::bibliography.adoc[] +// this references the riscv-spec.bi file that has been copied into the resources directory diff --git a/param_extraction/chunks/chunk_036.txt.license b/param_extraction/chunks/chunk_036.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_036.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_037.txt b/param_extraction/chunks/chunk_037.txt new file mode 100644 index 0000000000..bbd9af24ec --- /dev/null +++ b/param_extraction/chunks/chunk_037.txt @@ -0,0 +1,179 @@ +# Chunk: chunk_037 +# Source: rnmi.adoc +# Lines: 1-166 (of 166) +# Content starts: line 1 +# Line count: 166 +# Sections: 6 +# == "Smrnmi" Extension for Resumable Non-Maskable Interrupts, Version 1.0 +# === RNMI Interrupt Signals +# === RNMI Handler Addresses +# === RNMI CSRs +# === MNRET Instruction +# === RNMI Operation +# +[[rnmi]] +== "Smrnmi" Extension for Resumable Non-Maskable Interrupts, Version 1.0 + +The base machine-level architecture supports only unresumable +non-maskable interrupts (UNMIs), where the NMI jumps to a handler in +machine mode, overwriting the current `mepc` and `mcause` register +values. If the hart had been executing machine-mode code in a trap +handler, the previous values in `mepc` and `mcause` would not be +recoverable and so execution is not generally resumable. + +The Smrnmi extension adds support for resumable non-maskable interrupts +(RNMIs) to RISC-V. The extension adds four new CSRs (`mnepc`, `mncause`, +`mnstatus`, and `mnscratch`) to hold the interrupted state, and one new +instruction, MNRET, to resume from the RNMI handler. + +=== RNMI Interrupt Signals + +The `rnmi` interrupt signals are inputs to the hart. These interrupts +have higher priority than any other interrupt or exception on the hart +and cannot be disabled by software. Specifically, they are not disabled +by clearing the `mstatus`.MIE register. + +=== RNMI Handler Addresses + +The RNMI interrupt trap handler address is implementation-defined. + +RNMI also has an associated exception trap handler address, which is +implementation defined. + +NOTE: For example, some implementations might use the address specified +in `mtvec` as the RNMI exception trap handler. + +=== RNMI CSRs + +This extension adds additional M-mode CSRs to enable a resumable +non-maskable interrupt (RNMI). + +.Resumable NMI scratch register `mnscratch` +include::images/bytefield/mnscratch.edn[] + +The `mnscratch` CSR holds an MXLEN-bit read-write register which enables +the RNMI trap handler to save and restore the context that was +interrupted. + +.Resumable NMI program counter `mnepc`. +include::images/bytefield/mnepc.edn[] + +The `mnepc` CSR is an MXLEN-bit read-write register which on entry to +the RNMI trap handler holds the PC of the instruction that took the +interrupt. + +The low bit of `mnepc` (`mnepc[0]`) is always zero. On implementations +that support only IALIGN=32, the two low bits (`mnepc[1:0]`) are always +zero. + +If an implementation allows IALIGN to be either 16 or 32 (by changing +CSR `misa`, for example), then, whenever IALIGN=32, bit `mnepc[1]` is +masked on reads so that it appears to be 0. This masking occurs also for +the implicit read by the MNRET instruction. Though masked, `mnepc[1]` +remains writable when IALIGN=32. + +`mnepc` is a *WARL* register that must be able to hold all valid virtual +addresses. It need not be capable of holding all possible invalid +addresses. Prior to writing `mnepc`, implementations may convert an +invalid address into some other invalid address that `mnepc` is capable +of holding. + +.Resumable NMI cause `mncause`. +include::images/bytefield/mncause.edn[] + +The `mncause` CSR holds the reason for the RNMI. +If the reason is an interrupt, bit MXLEN-1 is set to 1, and the RNMI +cause is encoded in the least-significant bits. +If the reason is an interrupt and RNMI causes are not supported, bit MXLEN-1 is +set to 1, and zero is written to the least-significant bits. +If the reason is an exception within M-mode that results in a double trap as +specified in the Smdbltrp extension, bit MXLEN-1 is set to 0 and the +least-significant bits are set to the cause code corresponding to the +exception that precipitated the double trap. + +.Resumable NMI status register `mnstatus`. +include::images/bytefield/mnstatus.edn[] + +The `mnstatus` CSR holds a two-bit field, MNPP, which on entry to the +RNMI trap handler holds the privilege mode of the interrupted context, +encoded in the same manner as `mstatus`.MPP. It also holds a one-bit +field, MNPV, which on entry to the RNMI trap handler holds the virtualization +mode of the interrupted context, encoded in the same manner as +`mstatus`.MPV. + +If the Zicfilp extension is implemented, `mnstatus` also holds the MNPELP +field, which on entry to the RNMI trap handler holds the previous `ELP` state. +When an RNMI trap is taken, MNPELP is set to `ELP` and `ELP` is set to 0. + +`mnstatus` also holds the NMIE bit. When NMIE=1, non-maskable interrupts +are enabled. When NMIE=0, _all_ interrupts are disabled. + +When NMIE=0, the hart behaves as though `mstatus`.MPRV were clear, +regardless of the current setting of `mstatus`.MPRV. + +Upon reset, NMIE contains the value 0. + +[NOTE] +==== +RNMIs are masked out of reset to give software the opportunity to +initialize data structures and devices for subsequent RNMI handling. +==== + +Software can set NMIE to 1, but attempts to clear NMIE have no effect. + +[NOTE] +==== +Normally, only reset sequences will explicitly set the NMIE bit. + +*** + +That the NMIE bit is settable does not suffice to support the nesting of +RNMIs. To support this feature in a direct manner would have required +allowing software to clear the NMIE bit—a design choice that would have +contravened the concept of non-maskability. + +Software that wishes to minimize the latency until the next RNMI is +taken can follow the top-half/bottom-half model, where the RNMI handler +itself only enqueues a task to a task queue then returns. The bulk of +the interrupt servicing is performed later, with RNMIs enabled. +==== + +For the purposes of the WFI instruction, NMIE is a global interrupt +enable, meaning that the setting of NMIE does not affect the operation +of the WFI instruction. + +The other bits in `mnstatus` are _reserved_; software should write zeros +and hardware implementations should return zeros. + +=== MNRET Instruction + +MNRET is an M-mode-only instruction that uses the values in `mnepc` and +`mnstatus` to return to the program counter, privilege mode, and +virtualization mode of the interrupted context. This instruction also +sets `mnstatus`.NMIE. If MNRET changes the privilege mode to a mode less privileged than M, it also sets `mstatus`.MPRV to 0. +If the Zicfilp extension is implemented, then if the new privileged mode +is __y__, MNRET sets `ELP` to the logical AND of __y__LPE (see <>) and `mnstatus`.MNPELP. + +=== RNMI Operation + +When an RNMI interrupt is detected, the interrupted PC is written to the +`mnepc` CSR, the type of RNMI to the `mncause` CSR, and the privilege +mode of the interrupted context to the `mnstatus` CSR. The +`mnstatus`.NMIE bit is cleared, masking all interrupts. + +The hart then enters machine-mode and jumps to the RNMI trap handler +address. + +The RNMI handler can resume original execution using the new MNRET +instruction, which restores the PC from `mnepc`, the privilege mode from +`mnstatus`, and also sets `mnstatus`.NMIE, which re-enables interrupts. + +If the hart encounters an exception while executing in M-mode with the `mnstatus`.NMIE bit clear, the actions taken are the same as if the exception had occurred while `mnstatus`.NMIE were set, except that the program counter is set to the RNMI exception trap handler address. + +[NOTE] +==== +The Smrnmi extension does not change the behavior of the MRET and SRET +instructions. In particular, MRET and SRET are unaffected by the +`mnstatus`.NMIE bit, and their execution does not alter the +`mnstatus`.NMIE bit. +==== diff --git a/param_extraction/chunks/chunk_037.txt.license b/param_extraction/chunks/chunk_037.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_037.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_038.txt b/param_extraction/chunks/chunk_038.txt new file mode 100644 index 0000000000..7e40f8e528 --- /dev/null +++ b/param_extraction/chunks/chunk_038.txt @@ -0,0 +1,469 @@ +# Chunk: chunk_038 +# Source: rv-32-64g.adoc +# Lines: 1-461 (of 461) +# Content starts: line 1 +# Line count: 461 +# Sections: 1 +# == RV32/64G Instruction Set Listings +# +[[rv32-64g]] +== RV32/64G Instruction Set Listings + +One goal of the RISC-V project is that it be used as a stable software +development target. For this purpose, we define a combination of a base +ISA (RV32I or RV64I) plus selected standard extensions (IMAFD, Zicsr, +Zifencei) as a "general-purpose" ISA, and we use the abbreviation G +for the IMAFDZicsr_Zifencei combination of instruction-set extensions. +This chapter presents opcode maps and instruction-set listings for RV32G +and RV64G. + +[[opcodemap]] +.RISC-V base opcode map, inst[1:0]=11 +[%autowidth.stretch,float="center",align="center",cols= ">.^4m, ^.^4m, ^.^4m, ^.^4m, ^.^4m, ^.^4m, ^.^4m, ^.^6m, ^.^4h"] +|=== +|inst[4:2] .2+|000 .2+|001 .2+|010 .2+|011 .2+|100 .2+|101 .2+|110 .2+|111 (>32b) +|inst[6:5] +|00 |LOAD |LOAD-FP |_custom-0_ |MISC-MEM |OP-IMM |AUIPC |OP-IMM-32 |_reserved_ +|01 |STORE |STORE-FP |_custom-1_ |AMO |OP |LUI |OP-32 |_reserved_ +|10 |MADD |MSUB |NMSUB |NMADD |OP-FP |OP-V |_custom-2_ |_reserved_ +|11 |BRANCH |JALR |_reserved_ |JAL |SYSTEM |OP-VE |_custom-3_ |_reserved_ +|=== + +<> shows a map of the major opcodes for +RVG. Opcodes marked as _reserved_ +should be avoided for custom instruction-set extensions as they might be +used by future standard extensions. Major opcodes marked as _custom-0_ +through _custom-3_ will be avoided by future standard extensions and are +recommended for use by custom instruction-set extensions within the base +32-bit instruction format. + +We believe RV32G and RV64G provide simple but complete instruction sets +for a broad range of general-purpose computing. The optional compressed +instruction set described in <> can +be added (forming RV32GC and RV64GC) to improve performance, code size, +and energy efficiency, though with some additional hardware complexity. + +As we move beyond IMAFDC into further instruction-set extensions, the +added instructions tend to be more domain-specific and only provide +benefits to a restricted class of applications, e.g., for multimedia or +security. Unlike most commercial ISAs, the RISC-V ISA design clearly +separates the base ISA and broadly applicable standard extensions from +these more specialized additions. + +<<< + +[%autowidth.stretch,float="center",align="center",cols="^2m,^2m,^2m,^2m,<2m,>3m, <4m, >4m, <4m, >4m, <4m, >4m, <4m, >4m, <6m"] +|=== + |31 |27 |26 |25 |24 | 20|19 | 15| 14 | 12|11 | 7|6 | 0| + 4+^|funct7 2+^|rs2 2+^|rs1 2+^|funct3 2+^|rd 2+^|opcode <|R-type + 6+^|imm[11:0] 2+^|rs1 2+^|funct3 2+^|rd 2+^|opcode <|I-type + 4+^|imm[11:5] 2+^|rs2 2+^|rs1 2+^|funct3 2+^|imm[4:0] 2+^|opcode <|S-type + 4+^|imm[12\|10:5] 2+^|rs2 2+^|rs1 2+^|funct3 2+^|imm[4:1\|11] 2+^|opcode <|B-type +10+^|imm[31:12] 2+^|rd 2+^|opcode <|U-type +10+^|imm[20\|10:1\|11\|19:12] 2+^|rd 2+^|opcode <|J-type +|=== + +[%autowidth.stretch,float="center",align="center",cols="^2m,^2m,^2m,^2m,<2m,>3m, <4m, >4m, <4m, >4m, <4m, >4m, <4m, >4m, <6m"] +|=== +15+^|*RV32I Base Instruction Set* +10+^|imm[31:12] 2+^|rd 2+^|0110111 <|[#norm:lui_enc]#LUI# +10+^|imm[31:12] 2+^|rd 2+^|0010111 <|[#norm:auipc_enc]#AUIPC# +10+^|imm[20\|10:1\|11\|19:12] 2+^|rd 2+^|1101111 <|[#norm:jal_enc]#JAL# + 6+^|imm[11:0] 2+^|rs1 2+^|000 2+^|rd 2+^|1100111 <|[#norm:jalr_enc]#JALR# + 4+^|imm[12\|10:5] 2+^|rs2 2+^|rs1 2+^|000 2+^|imm[4:1\|11] 2+^|1100011 <|[#norm:beq_enc]#BEQ# + 4+^|imm[12\|10:5] 2+^|rs2 2+^|rs1 2+^|001 2+^|imm[4:1\|11] 2+^|1100011 <|[#norm:bne_enc]#BNE# + 4+^|imm[12\|10:5] 2+^|rs2 2+^|rs1 2+^|100 2+^|imm[4:1\|11] 2+^|1100011 <|[#norm:blt_enc]#BLT# + 4+^|imm[12\|10:5] 2+^|rs2 2+^|rs1 2+^|101 2+^|imm[4:1\|11] 2+^|1100011 <|[#norm:bge_enc]#BGE# + 4+^|imm[12\|10:5] 2+^|rs2 2+^|rs1 2+^|110 2+^|imm[4:1\|11] 2+^|1100011 <|[#norm:bltu_enc]#BLTU# + 4+^|imm[12\|10:5] 2+^|rs2 2+^|rs1 2+^|111 2+^|imm[4:1\|11] 2+^|1100011 <|[#norm:bgeu_enc]#BGEU# + 6+^|imm[11:0] 2+^|rs1 2+^|000 2+^|rd 2+^|0000011 <|[#norm:lb_enc]#LB# + 6+^|imm[11:0] 2+^|rs1 2+^|001 2+^|rd 2+^|0000011 <|[#norm:lh_enc]#LH# + 6+^|imm[11:0] 2+^|rs1 2+^|010 2+^|rd 2+^|0000011 <|[#norm:lw_enc]#LW# + 6+^|imm[11:0] 2+^|rs1 2+^|100 2+^|rd 2+^|0000011 <|[#norm:lbu_enc]#LBU# + 6+^|imm[11:0] 2+^|rs1 2+^|101 2+^|rd 2+^|0000011 <|[#norm:lhu_enc]#LHU# + 4+^|imm[11:5] 2+^|rs2 2+^|rs1 2+^|000 2+^|imm[4:0] 2+^|0100011 <|[#norm:sb_enc]#SB# + 4+^|imm[11:5] 2+^|rs2 2+^|rs1 2+^|001 2+^|imm[4:0] 2+^|0100011 <|[#norm:sh_enc]#SH# + 4+^|imm[11:5] 2+^|rs2 2+^|rs1 2+^|010 2+^|imm[4:0] 2+^|0100011 <|[#norm:sw_enc]#SW# + 6+^|imm[11:0] 2+^|rs1 2+^|000 2+^|rd 2+^|0010011 <|[#norm:addi_enc]#ADDI# + 6+^|imm[11:0] 2+^|rs1 2+^|010 2+^|rd 2+^|0010011 <|[#norm:slti_enc]#SLTI# + 6+^|imm[11:0] 2+^|rs1 2+^|011 2+^|rd 2+^|0010011 <|[#norm:sltiu_enc]#SLTIU# + 6+^|imm[11:0] 2+^|rs1 2+^|100 2+^|rd 2+^|0010011 <|[#norm:xori_enc]#XORI# + 6+^|imm[11:0] 2+^|rs1 2+^|110 2+^|rd 2+^|0010011 <|[#norm:ori_enc]#ORI# + 6+^|imm[11:0] 2+^|rs1 2+^|111 2+^|rd 2+^|0010011 <|[#norm:andi_enc]#ANDI# + 4+^|0000000 2+^|shamt 2+^|rs1 2+^|001 2+^|rd 2+^|0010011 <|[#norm:slli_enc]#SLLI# + 4+^|0000000 2+^|shamt 2+^|rs1 2+^|101 2+^|rd 2+^|0010011 <|[#norm:srli_enc]#SRLI# + 4+^|0100000 2+^|shamt 2+^|rs1 2+^|101 2+^|rd 2+^|0010011 <|[#norm:srai_enc]#SRAI# + 4+^|0000000 2+^|rs2 2+^|rs1 2+^|000 2+^|rd 2+^|0110011 <|[#norm:add_enc]#ADD# + 4+^|0100000 2+^|rs2 2+^|rs1 2+^|000 2+^|rd 2+^|0110011 <|[#norm:sub_enc]#SUB# + 4+^|0000000 2+^|rs2 2+^|rs1 2+^|001 2+^|rd 2+^|0110011 <|[#norm:sll_enc]#SLL# + 4+^|0000000 2+^|rs2 2+^|rs1 2+^|010 2+^|rd 2+^|0110011 <|[#norm:slt_enc]#SLT# + 4+^|0000000 2+^|rs2 2+^|rs1 2+^|011 2+^|rd 2+^|0110011 <|[#norm:sltu_enc]#SLTU# + 4+^|0000000 2+^|rs2 2+^|rs1 2+^|100 2+^|rd 2+^|0110011 <|[#norm:xor_enc]#XOR# + 4+^|0000000 2+^|rs2 2+^|rs1 2+^|101 2+^|rd 2+^|0110011 <|[#norm:srl_enc]#SRL# + 4+^|0100000 2+^|rs2 2+^|rs1 2+^|101 2+^|rd 2+^|0110011 <|[#norm:sra_enc]#SRA# + 4+^|0000000 2+^|rs2 2+^|rs1 2+^|110 2+^|rd 2+^|0110011 <|[#norm:or_enc]#OR# + 4+^|0000000 2+^|rs2 2+^|rs1 2+^|111 2+^|rd 2+^|0110011 <|[#norm:and_enc]#AND# + 3+^|fm 2+^|pred 1+^|succ 2+^|rs1 2+^|000 2+^|rd 2+^|0001111 <|[#norm:fence_enc]#FENCE# + 3+^|1000 2+^|0011 1+^|0011 2+^|00000 2+^|000 2+^|00000 2+^|0001111 <|[#norm:fence-tso_enc]#FENCE.TSO# + 3+^|0000 2+^|0001 1+^|0000 2+^|00000 2+^|000 2+^|00000 2+^|0001111 <|[#norm:pause_enc]#PAUSE# + 6+^|000000000000 2+^|00000 2+^|000 2+^|00000 2+^|1110011 <|[#norm:ecall_enc]#ECALL# + 6+^|000000000001 2+^|00000 2+^|000 2+^|00000 2+^|1110011 <|[#norm:ebreak_enc]#EBREAK# +|=== + +<<< + +[%autowidth.stretch,float="center",align="center",cols="^2m,^2m,^2m,^2m,<2m,>3m, <4m, >4m, <4m, >4m, <4m, >4m, <4m, >4m, <6m"] +|=== +15+^| + |31 |27 |26 |25 |24 | 20|19 | 15| 14 | 12|11 | 7|6 | 0| + 4+^|funct7 2+^|rs2 2+^|rs1 2+^|funct3 2+^|rd 2+^|opcode <|R-type + 6+^|imm[11:0] 2+^|rs1 2+^|funct3 2+^|rd 2+^|opcode <|I-type + 4+^|imm[11:5] 2+^|rs2 2+^|rs1 2+^|funct3 2+^|imm[4:0] 2+^|opcode <|S-type +|=== + +[%autowidth.stretch,float="center",align="center",cols="^2m,^2m,^2m,^2m,<2m,>3m, <4m, >4m, <4m, >4m, <4m, >4m, <4m, >4m, <6m"] +|=== +15+^|*RV64I Base Instruction Set (in addition to RV32I)* + 6+^|imm[11:0] 2+^|rs1 2+^|110 2+^|rd 2+^|0000011 <|[#norm:lwu_enc]#LWU# + 6+^|imm[11:0] 2+^|rs1 2+^|011 2+^|rd 2+^|0000011 <|[#norm:ld_enc]#LD# + 4+^|imm[11:5] 2+^|rs2 2+^|rs1 2+^|011 2+^|imm[4:0] 2+^|0100011 <|[#norm:sd_enc]#SD# + 3+^|000000 3+^|shamt 2+^|rs1 2+^|001 2+^|rd 2+^|0010011 <|SLLI + 3+^|000000 3+^|shamt 2+^|rs1 2+^|101 2+^|rd 2+^|0010011 <|SRLI + 3+^|010000 3+^|shamt 2+^|rs1 2+^|101 2+^|rd 2+^|0010011 <|SRAI + 6+^|imm[11:0] 2+^|rs1 2+^|000 2+^|rd 2+^|0011011 <|[#norm:addiw_enc]#ADDIW# + 4+^|0000000 2+^|shamt 2+^|rs1 2+^|001 2+^|rd 2+^|0011011 <|[#norm:slliw_enc]#SLLIW# + 4+^|0000000 2+^|shamt 2+^|rs1 2+^|101 2+^|rd 2+^|0011011 <|[#norm:srliw_enc]#SRLIW# + 4+^|0100000 2+^|shamt 2+^|rs1 2+^|101 2+^|rd 2+^|0011011 <|[#norm:sraiw_enc]#SRAIW# + 4+^|0000000 2+^|rs2 2+^|rs1 2+^|000 2+^|rd 2+^|0111011 <|[#norm:addw_enc]#ADDW# + 4+^|0100000 2+^|rs2 2+^|rs1 2+^|000 2+^|rd 2+^|0111011 <|[#norm:subw_enc]#SUBW# + 4+^|0000000 2+^|rs2 2+^|rs1 2+^|001 2+^|rd 2+^|0111011 <|[#norm:sllw_enc]#SLLW# + 4+^|0000000 2+^|rs2 2+^|rs1 2+^|101 2+^|rd 2+^|0111011 <|[#norm:srlw_enc]#SRLW# + 4+^|0100000 2+^|rs2 2+^|rs1 2+^|101 2+^|rd 2+^|0111011 <|[#norm:sraw_enc]#SRAW# +|=== +[%autowidth.stretch,float="center",align="center",cols="^2m,^2m,^2m,^2m,<2m,>3m, <4m, >4m, <4m, >4m, <4m, >4m, <4m, >4m, <6m"] +|=== +15+^|*RV32/RV64 _Zifencei_ Standard Extension* + 6+^|imm[11:0] 2+^|rs1 2+^|001 2+^|rd 2+^|0001111 <|FENCE.I +|=== + +[%autowidth.stretch,float="center",align="center",cols="^2m,^2m,^2m,^2m,<2m,>3m, <4m, >4m, <4m, >4m, <4m, >4m, <4m, >4m, <6m"] +|=== +15+^|*RV32/RV64 _Zicsr_ Standard Extension* + 6+^|csr 2+^|rs1 2+^|001 2+^|rd 2+^|1110011 <|CSRRW + 6+^|csr 2+^|rs1 2+^|010 2+^|rd 2+^|1110011 <|CSRRS + 6+^|csr 2+^|rs1 2+^|011 2+^|rd 2+^|1110011 <|CSRRC + 6+^|csr 2+^|uimm 2+^|101 2+^|rd 2+^|1110011 <|CSRRWI + 6+^|csr 2+^|uimm 2+^|110 2+^|rd 2+^|1110011 <|CSRRSI + 6+^|csr 2+^|uimm 2+^|111 2+^|rd 2+^|1110011 <|CSRRCI +|=== + +[%autowidth.stretch,float="center",align="center",cols="^2m,^2m,^2m,^2m,<2m,>3m, <4m, >4m, <4m, >4m, <4m, >4m, <4m, >4m, <6m"] +|=== +15+^|*RV32M Standard Extension* + 4+^|0000001 2+^|rs2 2+^|rs1 2+^|000 2+^|rd 2+^|0110011 <|[#norm:mul_enc]#MUL# + 4+^|0000001 2+^|rs2 2+^|rs1 2+^|001 2+^|rd 2+^|0110011 <|[#norm:mulh_enc]#MULH# + 4+^|0000001 2+^|rs2 2+^|rs1 2+^|010 2+^|rd 2+^|0110011 <|[#norm:mulhsu_enc]#MULHSU# + 4+^|0000001 2+^|rs2 2+^|rs1 2+^|011 2+^|rd 2+^|0110011 <|[#norm:mulhu_enc]#MULHU# + 4+^|0000001 2+^|rs2 2+^|rs1 2+^|100 2+^|rd 2+^|0110011 <|[#norm:div_enc]#DIV# + 4+^|0000001 2+^|rs2 2+^|rs1 2+^|101 2+^|rd 2+^|0110011 <|[#norm:divu_enc]#DIVU# + 4+^|0000001 2+^|rs2 2+^|rs1 2+^|110 2+^|rd 2+^|0110011 <|[#norm:rem_enc]#REM# + 4+^|0000001 2+^|rs2 2+^|rs1 2+^|111 2+^|rd 2+^|0110011 <|[#norm:remu_enc]#REMU# +|=== + +[%autowidth.stretch,float="center",align="center",cols="^2m,^2m,^2m,^2m,<2m,>3m, <4m, >4m, <4m, >4m, <4m, >4m, <4m, >4m, <6m"] +|=== +15+^|*RV64M Standard Extension (in addition to RV32M)* + 4+^|0000001 2+^|rs2 2+^|rs1 2+^|000 2+^|rd 2+^|0111011 <|[#norm:mulw_enc]#MULW# + 4+^|0000001 2+^|rs2 2+^|rs1 2+^|100 2+^|rd 2+^|0111011 <|[#norm:divw_enc]#DIVW# + 4+^|0000001 2+^|rs2 2+^|rs1 2+^|101 2+^|rd 2+^|0111011 <|[#norm:divuw_enc]#DIVUW# + 4+^|0000001 2+^|rs2 2+^|rs1 2+^|110 2+^|rd 2+^|0111011 <|[#norm:remw_enc]#REMW# + 4+^|0000001 2+^|rs2 2+^|rs1 2+^|111 2+^|rd 2+^|0111011 <|[#norm:remuw_enc]#REMUW# +|=== + +<<< + +[%autowidth.stretch,float="center",align="center",cols="^2m,^2m,^2m,^2m,<2m,>3m, <4m, >4m, <4m, >4m, <4m, >4m, <4m, >4m, <6m"] +|=== +15+^| + |31 |27 |26 |25 |24 | 20|19 | 15| 14 | 12|11 | 7|6 | 0| + 4+^|funct7 2+^|rs2 2+^|rs1 2+^|funct3 2+^|rd 2+^|opcode <|R-type +|=== + +[%autowidth.stretch,float="center",align="center",cols="^2m,^2m,^2m,^2m,<2m,>3m, <4m, >4m, <4m, >4m, <4m, >4m, <4m, >4m, <6m"] +|=== +15+^|*RV32A Standard Extension* + 2+^|00010 ^|aq ^|rl 2+^|00000 2+^|rs1 2+^|010 2+^|rd 2+^|0101111 <|LR.W + 2+^|00011 ^|aq ^|rl 2+^|rs2 2+^|rs1 2+^|010 2+^|rd 2+^|0101111 <|SC.W + 2+^|00001 ^|aq ^|rl 2+^|rs2 2+^|rs1 2+^|010 2+^|rd 2+^|0101111 <|AMOSWAP.W + 2+^|00000 ^|aq ^|rl 2+^|rs2 2+^|rs1 2+^|010 2+^|rd 2+^|0101111 <|AMOADD.W + 2+^|00100 ^|aq ^|rl 2+^|rs2 2+^|rs1 2+^|010 2+^|rd 2+^|0101111 <|AMOXOR.W + 2+^|01100 ^|aq ^|rl 2+^|rs2 2+^|rs1 2+^|010 2+^|rd 2+^|0101111 <|AMOAND.W + 2+^|01000 ^|aq ^|rl 2+^|rs2 2+^|rs1 2+^|010 2+^|rd 2+^|0101111 <|AMOOR.W + 2+^|10000 ^|aq ^|rl 2+^|rs2 2+^|rs1 2+^|010 2+^|rd 2+^|0101111 <|AMOMIN.W + 2+^|10100 ^|aq ^|rl 2+^|rs2 2+^|rs1 2+^|010 2+^|rd 2+^|0101111 <|AMOMAX.W + 2+^|11000 ^|aq ^|rl 2+^|rs2 2+^|rs1 2+^|010 2+^|rd 2+^|0101111 <|AMOMINU.W + 2+^|11100 ^|aq ^|rl 2+^|rs2 2+^|rs1 2+^|010 2+^|rd 2+^|0101111 <|AMOMAXU.W +|=== + +[%autowidth.stretch,float="center",align="center",cols="^2m,^2m,^2m,^2m,<2m,>3m, <4m, >4m, <4m, >4m, <4m, >4m, <4m, >4m, <6m"] +|=== +15+^|*RV64A Standard Extension (in addition to RV32A)* + 2+^|00010 ^|aq ^|rl 2+^|00000 2+^|rs1 2+^|011 2+^|rd 2+^|0101111 <|LR.D + 2+^|00011 ^|aq ^|rl 2+^|rs2 2+^|rs1 2+^|011 2+^|rd 2+^|0101111 <|SC.D + 2+^|00001 ^|aq ^|rl 2+^|rs2 2+^|rs1 2+^|011 2+^|rd 2+^|0101111 <|AMOSWAP.D + 2+^|00000 ^|aq ^|rl 2+^|rs2 2+^|rs1 2+^|011 2+^|rd 2+^|0101111 <|AMOADD.D + 2+^|00100 ^|aq ^|rl 2+^|rs2 2+^|rs1 2+^|011 2+^|rd 2+^|0101111 <|AMOXOR.D + 2+^|01100 ^|aq ^|rl 2+^|rs2 2+^|rs1 2+^|011 2+^|rd 2+^|0101111 <|AMOAND.D + 2+^|01000 ^|aq ^|rl 2+^|rs2 2+^|rs1 2+^|011 2+^|rd 2+^|0101111 <|AMOOR.D + 2+^|10000 ^|aq ^|rl 2+^|rs2 2+^|rs1 2+^|011 2+^|rd 2+^|0101111 <|AMOMIN.D + 2+^|10100 ^|aq ^|rl 2+^|rs2 2+^|rs1 2+^|011 2+^|rd 2+^|0101111 <|AMOMAX.D + 2+^|11000 ^|aq ^|rl 2+^|rs2 2+^|rs1 2+^|011 2+^|rd 2+^|0101111 <|AMOMINU.D + 2+^|11100 ^|aq ^|rl 2+^|rs2 2+^|rs1 2+^|011 2+^|rd 2+^|0101111 <|AMOMAXU.D +|=== + +<<< + +[%autowidth.stretch,float="center",align="center",cols="^2m,^2m,^2m,^2m,<2m,>3m, <4m, >4m, <4m, >4m, <4m, >4m, <4m, >4m, <6m"] +|=== + |31 |27 |26 |25 |24 | 20|19 | 15| 14 | 12|11 | 7|6 | 0| + 4+^|funct7 2+^|rs2 2+^|rs1 2+^|funct3 2+^|rd 2+^|opcode <|R-type + 2+^|rs3 2+^|funct2 2+^|rs2 2+^|rs1 2+^|funct3 2+^|rd 2+^|opcode <|R4-type + 6+^|imm[11:0] 2+^|rs1 2+^|funct3 2+^|rd 2+^|opcode <|I-type + 4+^|imm[11:5] 2+^|rs2 2+^|rs1 2+^|funct3 2+^|imm[4:0] 2+^|opcode <|S-type +|=== + +[%autowidth.stretch,float="center",align="center",cols="^2m,^2m,^2m,^2m,<2m,>3m, <4m, >4m, <4m, >4m, <4m, >4m, <4m, >4m, <6m"] +|=== +15+^|*RV32F Standard Extension* + 6+^|imm[11:0] 2+^|rs1 2+^|010 2+^|rd 2+^|0000111 <|FLW + 4+^|imm[11:5] 2+^|rs2 2+^|rs1 2+^|010 2+^|imm[4:0] 2+^|0100111 <|FSW + 2+^|rs3 2+^|00 2+^|rs2 2+^|rs1 2+^|rm 2+^|rd 2+^|1000011 <|FMADD.S + 2+^|rs3 2+^|00 2+^|rs2 2+^|rs1 2+^|rm 2+^|rd 2+^|1000111 <|FMSUB.S + 2+^|rs3 2+^|00 2+^|rs2 2+^|rs1 2+^|rm 2+^|rd 2+^|1001011 <|FNMSUB.S + 2+^|rs3 2+^|00 2+^|rs2 2+^|rs1 2+^|rm 2+^|rd 2+^|1001111 <|FNMADD.S + 4+^|0000000 2+^|rs2 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FADD.S + 4+^|0000100 2+^|rs2 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FSUB.S + 4+^|0001000 2+^|rs2 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FMUL.S + 4+^|0001100 2+^|rs2 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FDIV.S + 4+^|0101100 2+^|00000 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FSQRT.S + 4+^|0010000 2+^|rs2 2+^|rs1 2+^|000 2+^|rd 2+^|1010011 <|FSGNJ.S + 4+^|0010000 2+^|rs2 2+^|rs1 2+^|001 2+^|rd 2+^|1010011 <|FSGNJN.S + 4+^|0010000 2+^|rs2 2+^|rs1 2+^|010 2+^|rd 2+^|1010011 <|FSGNJX.S + 4+^|0010100 2+^|rs2 2+^|rs1 2+^|000 2+^|rd 2+^|1010011 <|FMIN.S + 4+^|0010100 2+^|rs2 2+^|rs1 2+^|001 2+^|rd 2+^|1010011 <|FMAX.S + 4+^|1100000 2+^|00000 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FCVT.W.S + 4+^|1100000 2+^|00001 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FCVT.WU.S + 4+^|1110000 2+^|00000 2+^|rs1 2+^|000 2+^|rd 2+^|1010011 <|FMV.X.W + 4+^|1010000 2+^|rs2 2+^|rs1 2+^|010 2+^|rd 2+^|1010011 <|FEQ.S + 4+^|1010000 2+^|rs2 2+^|rs1 2+^|001 2+^|rd 2+^|1010011 <|FLT.S + 4+^|1010000 2+^|rs2 2+^|rs1 2+^|000 2+^|rd 2+^|1010011 <|FLE.S + 4+^|1110000 2+^|00000 2+^|rs1 2+^|001 2+^|rd 2+^|1010011 <|FCLASS.S + 4+^|1101000 2+^|00000 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FCVT.S.W + 4+^|1101000 2+^|00001 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FCVT.S.WU + 4+^|1111000 2+^|00000 2+^|rs1 2+^|000 2+^|rd 2+^|1010011 <|FMV.W.X +|=== + +[%autowidth.stretch,float="center",align="center",cols="^2m,^2m,^2m,^2m,<2m,>3m, <4m, >4m, <4m, >4m, <4m, >4m, <4m, >4m, <6m"] +|=== +15+^|*RV64F Standard Extension (in addition to RV32F)* + 4+^|1100000 2+^|00010 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FCVT.L.S + 4+^|1100000 2+^|00011 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FCVT.LU.S + 4+^|1101000 2+^|00010 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FCVT.S.L + 4+^|1101000 2+^|00011 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FCVT.S.LU +|=== + +<<< + +[%autowidth.stretch,float="center",align="center",cols="^2m,^2m,^2m,^2m,<2m,>3m, <4m, >4m, <4m, >4m, <4m, >4m, <4m, >4m, <6m"] +|=== + |31 |27 |26 |25 |24 | 20|19 | 15| 14 | 12|11 | 7|6 | 0| + 4+^|funct7 2+^|rs2 2+^|rs1 2+^|funct3 2+^|rd 2+^|opcode <|R-type + 2+^|rs3 2+^|funct2 2+^|rs2 2+^|rs1 2+^|funct3 2+^|rd 2+^|opcode <|R4-type + 6+^|imm[11:0] 2+^|rs1 2+^|funct3 2+^|rd 2+^|opcode <|I-type + 4+^|imm[11:5] 2+^|rs2 2+^|rs1 2+^|funct3 2+^|imm[4:0] 2+^|opcode <|S-type +|=== + +[%autowidth.stretch,float="center",align="center",cols="^2m,^2m,^2m,^2m,<2m,>3m, <4m, >4m, <4m, >4m, <4m, >4m, <4m, >4m, <6m"] +|=== +15+|*RV32D Standard Extension* + 6+^|imm[11:0] 2+^|rs1 2+^|011 2+^|rd 2+^|0000111 <|FLD + 4+^|imm[11:5] 2+^|rs2 2+^|rs1 2+^|011 2+^|imm[4:0] 2+^|0100111 <|FSD + 2+^|rs3 2+^|01 2+^|rs2 2+^|rs1 2+^|rm 2+^|rd 2+^|1000011 <|FMADD.D + 2+^|rs3 2+^|01 2+^|rs2 2+^|rs1 2+^|rm 2+^|rd 2+^|1000111 <|FMSUB.D + 2+^|rs3 2+^|01 2+^|rs2 2+^|rs1 2+^|rm 2+^|rd 2+^|1001011 <|FNMSUB.D + 2+^|rs3 2+^|01 2+^|rs2 2+^|rs1 2+^|rm 2+^|rd 2+^|1001111 <|FNMADD.D + 4+^|0000001 2+^|rs2 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FADD.D + 4+^|0000101 2+^|rs2 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FSUB.D + 4+^|0001001 2+^|rs2 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FMUL.D + 4+^|0001101 2+^|rs2 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FDIV.D + 4+^|0101101 2+^|00000 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FSQRT.D + 4+^|0010001 2+^|rs2 2+^|rs1 2+^|000 2+^|rd 2+^|1010011 <|FSGNJ.D + 4+^|0010001 2+^|rs2 2+^|rs1 2+^|001 2+^|rd 2+^|1010011 <|FSGNJN.D + 4+^|0010001 2+^|rs2 2+^|rs1 2+^|010 2+^|rd 2+^|1010011 <|FSGNJX.D + 4+^|0010101 2+^|rs2 2+^|rs1 2+^|000 2+^|rd 2+^|1010011 <|FMIN.D + 4+^|0010101 2+^|rs2 2+^|rs1 2+^|001 2+^|rd 2+^|1010011 <|FMAX.D + 4+^|0100000 2+^|00001 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FCVT.S.D + 4+^|0100001 2+^|00000 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FCVT.D.S + 4+^|1010001 2+^|rs2 2+^|rs1 2+^|010 2+^|rd 2+^|1010011 <|FEQ.D + 4+^|1010001 2+^|rs2 2+^|rs1 2+^|001 2+^|rd 2+^|1010011 <|FLT.D + 4+^|1010001 2+^|rs2 2+^|rs1 2+^|000 2+^|rd 2+^|1010011 <|FLE.D + 4+^|1110001 2+^|00000 2+^|rs1 2+^|001 2+^|rd 2+^|1010011 <|FCLASS.D + 4+^|1100001 2+^|00000 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FCVT.W.D + 4+^|1100001 2+^|00001 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FCVT.WU.D + 4+^|1101001 2+^|00000 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FCVT.D.W + 4+^|1101001 2+^|00001 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FCVT.D.WU +|=== + +[%autowidth.stretch,float="center",align="center",cols="^2m,^2m,^2m,^2m,<2m,>3m, <4m, >4m, <4m, >4m, <4m, >4m, <4m, >4m, <6m"] +|=== +15+^|*RV64D Standard Extension (in addition to RV32D)* + 4+^|1100001 2+^|00010 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FCVT.L.D + 4+^|1100001 2+^|00011 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FCVT.LU.D + 4+^|1110001 2+^|00000 2+^|rs1 2+^|000 2+^|rd 2+^|1010011 <|FMV.X.D + 4+^|1101001 2+^|00010 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FCVT.D.L + 4+^|1101001 2+^|00011 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FCVT.D.LU + 4+^|1111001 2+^|00000 2+^|rs1 2+^|000 2+^|rd 2+^|1010011 <|FMV.D.X +|=== + +<<< + +[%autowidth.stretch,float="center",align="center",cols="^2m,^2m,^2m,^2m,<2m,>3m, <4m, >4m, <4m, >4m, <4m, >4m, <4m, >4m, <6m"] +|=== +15+^| + |31 |27 |26 |25 |24 | 20|19 | 15| 14 | 12|11 | 7|6 | 0| + 4+^|funct7 2+^|rs2 2+^|rs1 2+^|funct3 2+^|rd 2+^|opcode <|R-type + 2+^|rs3 2+^|funct2 2+^|rs2 2+^|rs1 2+^|funct3 2+^|rd 2+^|opcode <|R4-type + 6+^|imm[11:0] 2+^|rs1 2+^|funct3 2+^|rd 2+^|opcode <|I-type + 4+^|imm[11:5] 2+^|rs2 2+^|rs1 2+^|funct3 2+^|imm[4:0] 2+^|opcode <|S-type +|=== + +[%autowidth.stretch,float="center",align="center",cols="^2m,^2m,^2m,^2m,<2m,>3m, <4m, >4m, <4m, >4m, <4m, >4m, <4m, >4m, <6m"] +|=== +15+^|*RV32Q Standard Extension* + 4+^|imm[11:0] 2+^| 2+^|rs1 2+^|100 2+^|rd 2+^|0000111 <|FLQ + 4+^|imm[11:5] 2+^|rs2 2+^|rs1 2+^|100 2+^|imm[4:0] 2+^|0100111 <|FSQ + 2+^|rs3 2+^|11 2+^|rs2 2+^|rs1 2+^|rm 2+^|rd 2+^|1000011 <|FMADD.Q + 2+^|rs3 2+^|11 2+^|rs2 2+^|rs1 2+^|rm 2+^|rd 2+^|1000111 <|FMSUB.Q + 2+^|rs3 2+^|11 2+^|rs2 2+^|rs1 2+^|rm 2+^|rd 2+^|1001011 <|FNMSUB.Q + 2+^|rs3 2+^|11 2+^|rs2 2+^|rs1 2+^|rm 2+^|rd 2+^|1001111 <|FNMADD.Q + 4+^|0000011 2+^|rs2 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FADD.Q + 4+^|0000111 2+^|rs2 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FSUB.Q + 4+^|0001011 2+^|rs2 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FMUL.Q + 4+^|0001111 2+^|rs2 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FDIV.Q + 4+^|0101111 2+^|00000 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FSQRT.Q + 4+^|0010011 2+^|rs2 2+^|rs1 2+^|000 2+^|rd 2+^|1010011 <|FSGNJ.Q + 4+^|0010011 2+^|rs2 2+^|rs1 2+^|001 2+^|rd 2+^|1010011 <|FSGNJN.Q + 4+^|0010011 2+^|rs2 2+^|rs1 2+^|010 2+^|rd 2+^|1010011 <|FSGNJX.Q + 4+^|0010111 2+^|rs2 2+^|rs1 2+^|000 2+^|rd 2+^|1010011 <|FMIN.Q + 4+^|0010111 2+^|rs2 2+^|rs1 2+^|001 2+^|rd 2+^|1010011 <|FMAX.Q + 4+^|0100000 2+^|00011 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FCVT.S.Q + 4+^|0100011 2+^|00000 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FCVT.Q.S + 4+^|0100001 2+^|00011 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FCVT.D.Q + 4+^|0100011 2+^|00001 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FCVT.Q.D + 4+^|1010011 2+^|rs2 2+^|rs1 2+^|010 2+^|rd 2+^|1010011 <|FEQ.Q + 4+^|1010011 2+^|rs2 2+^|rs1 2+^|001 2+^|rd 2+^|1010011 <|FLT.Q + 4+^|1010011 2+^|rs2 2+^|rs1 2+^|000 2+^|rd 2+^|1010011 <|FLE.Q + 4+^|1110011 2+^|00000 2+^|rs1 2+^|001 2+^|rd 2+^|1010011 <|FCLASS.Q + 4+^|1100011 2+^|00000 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FCVT.W.Q + 4+^|1100011 2+^|00001 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FCVT.WU.Q + 4+^|1101011 2+^|00000 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FCVT.Q.W + 4+^|1101011 2+^|00001 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FCVT.Q.WU +|=== + +[%autowidth.stretch,float="center",align="center",cols="^2m,^2m,^2m,^2m,<2m,>3m, <4m, >4m, <4m, >4m, <4m, >4m, <4m, >4m, <6m"] +|=== +15+^|*RV64Q Standard Extension (in addition to RV32Q)* + 4+^|1100011 2+^|00010 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FCVT.L.Q + 4+^|1100011 2+^|00011 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FCVT.LU.Q + 4+^|1101011 2+^|00010 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FCVT.Q.L + 4+^|1101011 2+^|00011 2+^|rs1 2+^|rm 2+^|rd 2+^|1010011 <|FCVT.Q.LU +|=== + +<<< + +[%autowidth.stretch,float="center",align="center",cols="^2m,^2m,^2m,^2m,<2m,>3m, <4m, >4m, <4m, >4m, <4m, >4m, <4m, >4m, <6m"] +|=== +15+^| + |31 |27 |26 |25 |24 | 20|19 | 15| 14 | 12|11 | 7|6 | 0| + 4+^|funct7 2+^|rs2 2+^|rs1 2+^|funct3 2+^|rd 2+^|opcode <|R-type + 2+^|rs3 2+^|funct2 2+^|rs2 2+^|rs1 2+^|funct3 2+^|rd 2+^|opcode <|R4-type + 6+^|imm[11:0] 2+^|rs1 2+^|funct3 2+^|rd 2+^|opcode <|I-type + 4+^|imm[11:5] 2+^|rs2 2+^|rs1 2+^|funct3 2+^|imm[4:0] 2+^|opcode <|S-type +|=== + +[%autowidth.stretch,float="center",align="center",cols="^m,^m,^m,^m,^m,^m,^m,> lists the CSRs that have currently been +allocated CSR addresses. The timers, counters, and floating-point CSRs +are the only CSRs defined in this specification. + +[[rvgcsrnames]] +.RISC-V control and status register (CSR) address map. +[%autowidth,float="center",align="center",cols=" +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_039.txt b/param_extraction/chunks/chunk_039.txt new file mode 100644 index 0000000000..af8b34444e --- /dev/null +++ b/param_extraction/chunks/chunk_039.txt @@ -0,0 +1,1122 @@ +# Chunk: chunk_039 +# Source: rv32.adoc +# Lines: 1-1105 (of 1105) +# Content starts: line 1 +# Line count: 1105 +# Sections: 10 +# == RV32I Base Integer Instruction Set, Version 2.1 +# === Programmers' Model for Base Integer ISA +# === Base Instruction Formats +# === Immediate Encoding Variants +# === Integer Computational Instructions +# ==== Integer Register-Immediate Instructions +# ==== Integer Register-Register Instructions +# ==== NOP Instruction +# === Control Transfer Instructions +# ==== Unconditional Jumps +# +[[rv32]] +== RV32I Base Integer Instruction Set, Version 2.1 + +This chapter describes the RV32I base integer instruction set. + +[NOTE] +==== +RV32I was designed to be sufficient to form a compiler target and to +support modern operating system environments. The ISA was also designed +to reduce the hardware required in a minimal implementation. RV32I +contains 40 unique instructions, though a simple implementation might +cover the ECALL/EBREAK instructions with a single SYSTEM hardware +instruction that always traps and might be able to implement the FENCE +instruction as a NOP, reducing base instruction count to 38 total. RV32I +can emulate almost any other ISA extension (except the A extension, +which requires additional hardware support for atomicity). + +In practice, a hardware implementation including the machine-mode +privileged architecture will also require the 6 CSR instructions. + +Subsets of the base integer ISA might be useful for pedagogical +purposes, but the base has been defined such that there should be little +incentive to subset a real hardware implementation beyond omitting +support for misaligned memory accesses and treating all SYSTEM +instructions as a single trap. +==== + +[NOTE] +==== +The standard RISC-V assembly language syntax is documented in the +Assembly Programmer's Manual cite:[riscv-asm-manual]. +==== + +[NOTE] +==== +Most of the commentary for RV32I also applies to the RV64I base. +==== + +=== Programmers' Model for Base Integer ISA + +<> shows the unprivileged state for the base integer ISA. +[#norm:rv32i_xreg_sz]#For RV32I, the 32 `x` registers are each 32 bits wide, +i.e., `XLEN=32`.# [#norm:x0eq0]#Register `x0` is hardwired with all bits equal to 0.# +[#norm:rv32i_rv64i_other_xregs]#General purpose registers `x1-x31` hold values that various +instructions interpret as a collection of Boolean values, or as two's +complement signed binary integers or unsigned binary integers.# + +[[norm:pcreg_op]] +There is one additional unprivileged register: the program counter `pc` +holds the address of the current instruction. + +[[gprs]] +.RISC-V base unprivileged integer register state. +[cols="<,^,>",options="header",width="50%",align="center",grid="rows"] +|=== +<| [.small]#XLEN-1#| >| [.small]#0# +3+^| [.small]#x0/zero# +3+^| [.small]#x1# +3+^| [.small]#x2# +3+^| [.small]#x3# +3+^| [.small]#x4# +3+^| [.small]#x5# +3+^| [.small]#x6# +3+^| [.small]#x7# +3+^| [.small]#x8# +3+^| [.small]#x9# +3+^| [.small]#x10# +3+^| [.small]#x11# +3+^| [.small]#x12# +3+^| [.small]#x13# +3+^| [.small]#x14# +3+^| [.small]#x15# +3+^| [.small]#x16# +3+^| [.small]#x17# +3+^| [.small]#x18# +3+^| [.small]#x19# +3+^| [.small]#x20# +3+^| [.small]#x21# +3+^| [.small]#x22# +3+^| [.small]#x23# +3+^| [.small]#x24# +3+^| [.small]#x25# +3+^| [.small]#x26# +3+^| [.small]#x27# +3+^| [.small]#x28# +3+^| [.small]#x29# +3+^| [.small]#x30# +3+^| [.small]#x31# +3+^| [.small]#pc# +|=== +[NOTE] +==== +There is no dedicated stack pointer or subroutine return address link +register in the Base Integer ISA; the instruction encoding allows any +`x` register to be used for these purposes. However, the standard +software calling convention uses register `x1` to hold the return +address for a call, with register `x5` available as an alternate link +register. The standard calling convention uses register `x2` as the +stack pointer. + +Hardware might choose to accelerate function calls and returns that use +`x1` or `x5`. See the descriptions of the JAL and JALR instructions. + +The optional compressed 16-bit instruction format is designed around the +assumption that `x1` is the return address register and `x2` is the +stack pointer. Software using other conventions will operate correctly +but may have greater code size. + +The number of available architectural registers can have large impacts +on code size, performance, and energy consumption. Although 16 registers +would arguably be sufficient for an integer ISA running compiled code, +it is impossible to encode a complete ISA with 16 registers in 16-bit +instructions using a 3-address format. Although a 2-address format would +be possible, it would increase instruction count and lower efficiency. +We wanted to avoid intermediate instruction sizes (such as Xtensa's +24-bit instructions) to simplify base hardware implementations, and once +a 32-bit instruction size was adopted, it was straightforward to support +32 integer registers. A larger number of integer registers also helps +performance on high-performance code, where there can be extensive use +of loop unrolling, software pipelining, and cache tiling. + +For these reasons, we chose a conventional size of 32 integer registers +for RV32I. Dynamic register usage tends to be dominated by a few +frequently accessed registers, and register file implementations can be +optimized to reduce access energy for the frequently accessed +registers cite:[jtseng:sbbci]. The optional compressed 16-bit instruction format mostly +only accesses 8 registers and hence can provide a dense instruction +encoding, while additional instruction-set extensions could support a +much larger register space (either flat or hierarchical) if desired. + +For resource-constrained embedded applications, we have defined the +RV32E subset, which only has 16 registers +(<>). +==== +=== Base Instruction Formats +In the base RV32I ISA, there are four core instruction formats +(R/I/S/U), as shown in <>. All are a fixed 32 bits in length. +The base ISA has `IALIGN=32`, meaning that instructions must be aligned on a four-byte boundary in memory. +[#norm:taken_cti_misaligned_exc]#An instruction-address-misaligned exception is generated on a taken branch +or unconditional jump if the target address is not `IALIGN-bit` aligned. +This exception is reported on the branch or jump instruction, not on the target instruction.# +[#norm:cond_br_no_ia_misaligned_exc_not_taken]#No instruction-address-misaligned exception is generated +for a conditional branch that is not taken.# + +[NOTE] +==== +The alignment constraint for base ISA instructions is relaxed to a +two-byte boundary when instruction extensions with 16-bit lengths or +other odd multiples of 16-bit lengths are added (i.e., IALIGN=16). + +Instruction-address-misaligned exceptions are reported on the branch or +jump that would cause instruction misalignment to help debugging, and to +simplify hardware design for systems with IALIGN=32, where these are the +only places where misalignment can occur. +==== + +The behavior upon decoding a reserved instruction is UNSPECIFIED. + +[NOTE] +==== +Some platforms may require that opcodes reserved for standard use raise +an illegal-instruction exception. Other platforms may permit reserved +opcode space be used for non-conforming extensions. +==== + +The RISC-V ISA keeps the source (_rs1_ and _rs2_) and destination (_rd_) +registers at the same position in all formats to simplify decoding. +[#norm:imm_always_sex]#Except for the 5-bit immediates used in CSR instructions (<>), +immediates are always sign-extended#, +and are generally packed towards the leftmost available +bits in the instruction and have been allocated to reduce hardware +complexity. In particular, the sign bit for all immediates is always in +bit 31 of the instruction to speed sign-extension circuitry. + +include::images/wavedrom/instruction-formats.edn[] +[[base_instr,Base instruction formats]] +RISC-V base instruction formats. Each immediate subfield is labeled with the bit position (imm[x]) in the immediate value being produced, rather than the bit position within the instruction's immediate field as is usually done. + +[NOTE] +==== +Decoding register specifiers is usually on the critical paths in +implementations, and so the instruction format was chosen to keep all +register specifiers at the same position in all formats at the expense +of having to move immediate bits across formats (a property shared with +RISC-IV aka. SPUR cite:[spur-jsscc1989]). + +In practice, most immediates are either small or require all XLEN bits. +We chose an asymmetric immediate split (12 bits in regular instructions +plus a special load-upper-immediate instruction with 20 bits) to +increase the opcode space available for regular instructions. + +Immediates are sign-extended because we did not observe a benefit to +using zero extension for some immediates as in the MIPS ISA and wanted +to keep the ISA as simple as possible. +==== + +=== Immediate Encoding Variants + +There are a further two variants of the instruction formats (B/J) based +on the handling of immediates, as shown in <>. + +include::images/wavedrom/immediate-variants.edn[] +[[baseinstformatsimm,Base instruction formats immediate variants.]] +//.RISC-V base instruction formats showing immediate variants. + + +The only difference between the S and B formats is that the 12-bit +immediate field is used to encode branch offsets in multiples of 2 in +the B format. Instead of shifting all bits in the instruction-encoded +immediate left by one in hardware as is conventionally done, the middle +bits (imm[10:1]) and sign bit stay in fixed positions, while the lowest +bit in S format (inst[7]) encodes a high-order bit in B format. + +Similarly, the only difference between the U and J formats is that the +20-bit immediate is shifted left by 12 bits to form U immediates and by +1 bit to form J immediates. The location of instruction bits in the U +and J format immediates is chosen to maximize overlap with the other +formats and with each other. + +<> shows the immediates produced by +each of the base instruction formats, and is labeled to show which +instruction bit (inst[_y_]) produces each bit of the immediate value. + +[[immtypes, Immediate types]] +include::images/wavedrom/i-immediate.edn[] + +include::images/wavedrom/s-immediate.edn[] + +include::images/wavedrom/b-immediate.edn[] + +include::images/wavedrom/u-immediate.edn[] + +.Types of immediate produced by RISC-V instructions. +include::images/wavedrom/j-immediate.edn[] + + +The fields are labeled with the instruction bits used to construct their value. Sign extensions always uses inst[31]. + +[NOTE] +==== +Sign extension is one of the most critical operations on immediates +(particularly for XLEN>32), and in RISC-V the sign bit for +all immediates is always held in bit 31 of the instruction to allow +sign extension to proceed in parallel with instruction decoding. + +Although more complex implementations might have separate adders for +branch and jump calculations and so would not benefit from keeping the +location of immediate bits constant across types of instruction, we +wanted to reduce the hardware cost of the simplest implementations. By +rotating bits in the instruction encoding of B and J immediates instead +of using dynamic hardware multiplexers to multiply the immediate by 2, we +reduce instruction signal fanout and immediate multiplexer costs by around a +factor of 2. The scrambled immediate encoding will add negligible time +to static or ahead-of-time compilation. For dynamic generation of +instructions, there is some small additional overhead, but the most +common short forward branches have straightforward immediate encodings. +==== + +=== Integer Computational Instructions + +Most integer computational instructions operate on `XLEN` bits of values +held in the integer register file. Integer computational instructions +are either encoded as register-immediate operations using the I-type +format or as register-register operations using the R-type format. The +destination is register _rd_ for both register-immediate and +register-register instructions. No integer computational instructions +cause arithmetic exceptions. + +[NOTE] +==== +We did not include special instruction-set support for overflow checks +on integer arithmetic operations in the base instruction set, as many +overflow checks can be cheaply implemented using RISC-V branches. +Overflow checking for unsigned addition requires only a single +additional branch instruction after the addition: +`add t0, t1, t2; bltu t0, t1, overflow`. + +For signed addition, if one operand's sign is known, overflow checking +requires only a single branch after the addition: +`addi t0, t1, +imm; blt t0, t1, overflow`. This covers the common case +of addition with an immediate operand. + +For general signed addition, three additional instructions after the +addition are required, leveraging the observation that the sum should be +less than one of the operands if and only if the other operand is +negative. + +[source,asm] +.... + add t0, t1, t2 + slti t3, t2, 0 + slt t4, t0, t1 + bne t3, t4, overflow +.... + +In RV64I, checks of 32-bit signed additions can be optimized further by +comparing the results of ADD and ADDW on the operands. +==== + +==== Integer Register-Immediate Instructions + +include::images/wavedrom/integer-computational.edn[] +//.Integer Computational Instructions + +[#norm:addi_op]#ADDI adds the sign-extended 12-bit immediate to register _rs1_.# +[#norm:addi_overflow]#Arithmetic overflow is ignored and the result is simply the low XLEN bits of the result.# +ADDI _rd, rs1, 0_ is used to implement the MV _rd, rs1_ assembler pseudoinstruction. + +[#norm:slti_sltiu_op]#SLTI (set less than immediate) places the value 1 in register _rd_ if +register _rs1_ is less than the sign-extended immediate when both are +treated as signed numbers, else 0 is written to _rd_. SLTIU is similar +but compares the values as unsigned numbers (i.e., the immediate is +first sign-extended to XLEN bits then treated as an unsigned number).# +Note, SLTIU _rd, rs1, 1_ sets _rd_ to 1 if _rs1_ equals zero, otherwise +sets _rd_ to 0 (assembler pseudoinstruction SEQZ _rd, rs_). + +[#norm:andi_ori_xori_op]#ANDI, ORI, XORI are logical operations that perform bitwise AND, OR, and +XOR on register _rs1_ and the sign-extended 12-bit immediate and place +the result in _rd_.# +Note, XORI _rd, rs1, -1_ performs a bitwise logical inversion of register _rs1_ (assembler pseudoinstruction NOT _rd, rs_). + +include::images/wavedrom/int-comp-slli-srli-srai.edn[] +[[int-comp-slli-srli-srai]] +//.Integer register-immediate, SLLI, SRLI, SRAI + +Shifts by a constant are encoded as a specialization of the I-type +format. The operand to be shifted is in _rs1_, and the shift amount is +encoded in the lower 5 bits of the I-immediate field. The right-shift +type is encoded in bit 30. +[#norm:slli_op]#SLLI is a logical left shift (zeros are shifted into the lower bits);# +[#norm:srli_op]#SRLI is a logical right shift (zeros are shifted into the upper bits);# and +[#norm:srai_op]#SRAI is an arithmetic right shift (the original sign bit is copied into the vacated upper bits).# + +include::images/wavedrom/int-comp-lui-aiupc.edn[] +[[int-comp-lui-aiupc]] +//.Integer register-immediate, U-immediate + +LUI (load upper immediate) is used to build 32-bit constants and uses the U-type format. +[#norm:lui_op]#LUI places the 32-bit U-immediate value into the +destination register _rd_, filling in the lowest 12 bits with zeros.# + +AUIPC (add upper immediate to `pc`) is used to build `pc`-relative +addresses and uses the U-type format. +[#norm:auipc_op]#AUIPC forms a 32-bit offset from +the U-immediate, filling in the lowest 12 bits with zeros, adds this +offset to the address of the AUIPC instruction, then places the result +in register _rd_.# + +[NOTE] +==== +The assembly syntax for `lui` and `auipc` does not represent the lower +12 bits of the U-immediate, which are always zero. + +The AUIPC instruction supports two-instruction sequences to access +arbitrary offsets from the PC for both control-flow transfers and data +accesses. The combination of an AUIPC and the 12-bit immediate in a JALR +can transfer control to any 32-bit PC-relative address, while an AUIPC +plus the 12-bit immediate offset in regular load or store instructions +can access any 32-bit PC-relative data address. + +The current PC can be obtained by setting the U-immediate to 0. Although +a JAL +4 instruction could also be used to obtain the local PC (of the +instruction following the JAL), it might cause pipeline breaks in +simpler microarchitectures or pollute BTB structures in more complex +microarchitectures. +==== + +==== Integer Register-Register Instructions + +RV32I defines several arithmetic R-type operations. [#norm:R-type_operands]#All operations read +the _rs1_ and _rs2_ registers as source operands and write the result into register _rd_.# +The _funct7_ and _funct3_ fields select the type of operation. + +include::images/wavedrom/int-reg-reg.edn[] +[[int-reg-reg]] +//.Integer register-register + +[#norm:add_op]#ADD performs the addition of _rs1_ and _rs2_.# +[#norm:sub_op]#SUB performs the subtraction of _rs2_ from _rs1_.# +[#norm:add_sub_overflow]#Overflows are ignored and the low XLEN bits of results are written to the destination _rd_.# +[#norm:slt_sltu_op]#SLT and SLTU perform signed and unsigned compares respectively, writing 1 to _rd_ if +_rs1_ < _rs2_, 0 otherwise.# +Note, SLTU _rd_, _x0_, _rs2_ sets _rd_ to 1 if _rs2_ is not equal to zero, +otherwise sets _rd_ to zero (assembler pseudoinstruction SNEZ _rd, rs_). +[#norm:and_or_xor_op]#AND, OR, and XOR perform bitwise logical operations.# + +[#norm:sll_srl_sra_op]#SLL, SRL, and SRA perform logical left, logical right, and arithmetic +right shifts on the value in register _rs1_ by the shift amount held in +the lower 5 bits of register _rs2_.# + +==== NOP Instruction + +include::images/wavedrom/nop.edn[] +[[nop]] +//.NOP instructions + +[#norm:nop_op]#The NOP instruction does not change any architecturally visible state, +except for advancing the `pc` and incrementing any applicable +performance counters.# [#norm:nop_enc]#NOP is encoded as ADDI _x0, x0, 0_.# + +[NOTE] +==== +NOPs can be used to align code segments to microarchitecturally +significant address boundaries, or to leave space for inline code +modifications. Although there are many possible ways to encode a NOP, we +define a canonical NOP encoding to allow microarchitectural +optimizations as well as for more readable disassembly output. The other +NOP encodings are made available for <>. + +ADDI was chosen for the NOP encoding as this is most likely to take +fewest resources to execute across a range of systems (if not optimized +away in decode). In particular, the instruction only reads one register. +Also, an ADDI functional unit is more likely to be available in a +superscalar design as adds are the most common operation. In particular, +address-generation functional units can execute ADDI using the same +hardware needed for base+offset address calculations, while +register-register ADD or logical/shift operations require additional +hardware. +==== + +=== Control Transfer Instructions +RV32I provides two types of control transfer instructions: unconditional +jumps and conditional branches. +[#norm:no_cti_delay_slots]#Control transfer instructions in RV32I +do _not_ have architecturally visible delay slots.# + +[#norm:ia_fault_exc_on_target]#If an instruction access-fault or instruction page-fault exception +occurs on the target of a jump or taken branch, the exception is +reported on the target instruction, not on the jump or branch instruction.# + +==== Unconditional Jumps +The jump and link (JAL) instruction uses the J-type format, where the +J-immediate encodes a signed offset in multiples of 2 bytes. +[#norm:jal_target]#The offset is sign-extended and added to the address of the jump instruction to +form the jump target address.# Jumps can therefore target a {pm}1 MiB range. +[#norm:jal_op]#JAL stores the address of the instruction +following the jump ('pc'+4) into register _rd_.# +The standard software calling convention uses 'x1' as the return address register and 'x5' as +an alternate link register. + +[NOTE] +==== +The alternate link register supports calling millicode routines (e.g., +those to save and restore registers in compressed code) while preserving +the regular return address register. The register `x5` was chosen as the +alternate link register as it maps to a temporary in the standard +calling convention, and has an encoding that is only one bit different +than the regular link register. +==== + +Plain unconditional jumps (assembler pseudoinstruction J) are encoded as +a JAL with _rd_=`x0`. + +include::images/wavedrom/ct-unconditional.edn[] +[[ct-unconditional]] +//.The unconditional-jump instruction, JAL + +The indirect jump instruction JALR (jump and link register) uses the I-type encoding. +[#norm:jalr_target]#The target address is obtained by adding the +sign-extended 12-bit I-immediate to the register _rs1_, then setting the +least-significant bit of the result to zero.# +[#norm:jalr_op]#The address of the +instruction following the jump (`pc`+4) is written to register _rd_.# +Register `x0` can be used as the destination if the result is not +required. + +Plain unconditional indirect jumps (assembler pseudoinstruction JR) are +encoded as a JALR with _rd_=`x0`. +Procedure returns in the standard calling convention (assembler +pseudoinstruction RET) are encoded as a JALR with _rd_=`x0`, _rs1_=`x1`, and +_imm_=0. + +include::images/wavedrom/ct-unconditional-2.edn[] +[[ct-unconditional-2]] +//.The indirect unconditional-jump instruction, JALR + +[NOTE] +==== +The unconditional jump instructions all use PC-relative addressing to +help support position-independent code. The JALR instruction was defined +to enable a two-instruction sequence to jump anywhere in a 32-bit +absolute address range. A LUI instruction can first load _rs1_ with the +upper 20 bits of a target address, then JALR can add in the lower bits. +Similarly, AUIPC then JALR can jump anywhere in a 32-bit `pc`-relative +address range. + +Note that the JALR instruction does not treat the 12-bit immediate as +multiples of 2 bytes, unlike the conditional branch instructions. This +avoids one more immediate format in hardware. In practice, most uses of +JALR will have either a zero immediate or be paired with a LUI or AUIPC, +so the slight reduction in range is not significant. + +Clearing the least-significant bit when calculating the JALR target +address both simplifies the hardware slightly and allows the low bit of +function pointers to be used to store auxiliary information. Although +there is potentially a slight loss of error checking in this case, in +practice jumps to an incorrect instruction address will usually quickly +raise an exception. + +When used with a base _rs1_=`x0`, JALR can be used to +implement a single instruction subroutine call to the lowest or highest +address region from anywhere in the address space, which could be used +to implement fast calls to a small runtime library. Alternatively, an +ABI could dedicate a general-purpose register to point to a library +elsewhere in the address space. +==== + +[[norm:jump_misaligned_exception]] +The JAL and JALR instructions will generate an +instruction-address-misaligned exception if the target address is not +aligned to a four-byte boundary. + +[NOTE] +==== +[[norm:jump_misaligned_c_no_exception]] +Instruction-address-misaligned exceptions are not possible on machines +with IALIGN=16, e.g., those with the +compressed instruction-set extension, C. +==== + +Return-address prediction stacks are a common feature of +high-performance instruction-fetch units, but require accurate detection +of instructions used for procedure calls and returns to be effective. +For RISC-V, hints as to the instructions' usage are encoded implicitly +via the register numbers used. A JAL instruction should push the return +address onto a return-address stack (RAS) only when _rd_ is 'x1' or +`x5`. JALR instructions should push/pop a RAS as shown in <>. + +[[rashints]] +.Return-address stack prediction hints encoded in the register operands of a JALR instruction. +[%autowidth,float="center",align="center",cols="^,^,^,<",options="header"] +|=== +|_rd_ is _x1/x5_ |_rs1_ is _x1/x5_ |_rd_=_rs1_ |RAS action + +|No |No |-- |None + +|No |Yes |-- |Pop + +|Yes |No |-- |Push + +|Yes |Yes |No |Pop, then push + +|Yes |Yes |Yes |Push +|=== + + +[NOTE] +==== +Some other ISAs added explicit hint bits to their indirect-jump +instructions to guide return-address stack manipulation. We use implicit +hinting tied to register numbers and the calling convention to reduce +the encoding space used for these hints. + +When two different link registers (`x1` and `x5`) are given as _rs1_ and +_rd_, then the RAS is both popped and pushed to support coroutines. If +_rs1_ and _rd_ are the same link register (either `x1` or `x5`), the RAS +is only pushed to enable macro-op fusion of the sequences: +`lui ra, imm20; jalr ra, imm12(ra)_ and _auipc ra, imm20; jalr ra, imm12(ra)` +==== + +==== Conditional Branches + +All branch instructions use the B-type instruction format. +[#norm:br_target]#The 12-bit B-immediate encodes signed offsets in multiples of 2 bytes. The offset +is sign-extended and added to the address of the branch instruction to give the target address.# +The conditional branch range is {pm}4 KiB. + +include::images/wavedrom/ct-conditional.edn[] +[[ct-conditional]] +//.Conditional branches + +Branch instructions compare two registers. +[#norm:beq_bne_op]#BEQ and BNE take the branch if registers _rs1_ and _rs2_ are equal or unequal respectively.# +[#norm:blt_bltu_op]#BLT and BLTU take the branch if _rs1_ is less than _rs2_, using signed and +unsigned comparison respectively.# +[#norm:bge_bgeu_op]#BGE and BGEU take the branch if _rs1_ is greater than or equal to _rs2_, +using signed and unsigned comparison respectively.# +Note, BGT, BGTU, BLE, and BLEU can be synthesized by +reversing the operands to BLT, BLTU, BGE, and BGEU, respectively. + +[NOTE] +==== +Signed array bounds may be checked with a single BLTU instruction, since +any negative index will compare greater than any nonnegative bound. +==== + +Software should be optimized such that the sequential code path is the +most common path, with less-frequently taken code paths placed out of +line. Software should also assume that backward branches will be +predicted taken and forward branches as not taken, at least the first +time they are encountered. Dynamic predictors should quickly learn any +predictable branch behavior. + +Unlike some other architectures, the RISC-V jump (JAL with _rd_=`x0`) +instruction should always be used for unconditional branches instead of +a conditional branch instruction with an always-true condition. RISC-V +jumps are also PC-relative and support a much wider offset range than +branches, and will not pollute conditional-branch prediction tables. + +[NOTE] +==== +The conditional branches were designed to include arithmetic comparison +operations between two registers (as also done in PA-RISC, Xtensa, and +MIPS R6), rather than use condition codes (x86, ARM, SPARC, PowerPC), or +to only compare one register against zero (Alpha, MIPS), or two +registers only for equality (MIPS). This design was motivated by the +observation that a combined compare-and-branch instruction fits into a +regular pipeline, avoids additional condition code state or use of a +temporary register, and reduces static code size and dynamic instruction +fetch traffic. Another point is that comparisons against zero require +non-trivial circuit delay (especially after the move to static logic in +advanced processes) and so are almost as expensive as arithmetic +magnitude compares. Another advantage of a fused compare-and-branch +instruction is that branches are observed earlier in the front-end +instruction stream, and so can be predicted earlier. There is perhaps an +advantage to a design with condition codes in the case where multiple +branches can be taken based on the same condition codes, but we believe +this case to be relatively rare. + +We considered but did not include static branch hints in the instruction +encoding. These can reduce the pressure on dynamic predictors, but +require more instruction encoding space and software profiling for best +results, and can result in poor performance if production runs do not +match profiling runs. + +We considered but did not include conditional moves or predicated +instructions, which can effectively replace unpredictable short forward +branches. Conditional moves are the simpler of the two, but are +difficult to use with conditional code that might cause exceptions +(memory accesses and floating-point operations). Predication adds +additional flag state to a system, additional instructions to set and +clear flags, and additional encoding overhead on every instruction. Both +conditional move and predicated instructions add complexity to +out-of-order microarchitectures, adding an implicit third source operand +due to the need to copy the original value of the destination +architectural register into the renamed destination physical register if +the predicate is false. Also, static compile-time decisions to use +predication instead of branches can result in lower performance on +inputs not included in the compiler training set, especially given that +unpredictable branches are rare, and becoming rarer as branch prediction +techniques improve. + +We note that various microarchitectural techniques exist to dynamically +convert unpredictable short forward branches into internally predicated +code to avoid the cost of flushing pipelines on a branch mispredict cite:[heil-tr1996], cite:[Klauser-1998], cite:[Kim-micro2005] and +have been implemented in commercial processors cite:[ibmpower7]. The simplest techniques +just reduce the penalty of recovering from a mispredicted short forward +branch by only flushing instructions in the branch shadow instead of the +entire fetch pipeline, or by fetching instructions from both sides using +wide instruction fetch or idle instruction fetch slots. More complex +techniques for out-of-order cores add internal predicates on +instructions in the branch shadow, with the internal predicate value +written by the branch instruction, allowing the branch and following +instructions to be executed speculatively and out-of-order with respect +to other code. +==== + +[#norm:branch_misaligned_taken_exception]#The conditional branch instructions will generate an +instruction-address-misaligned exception if the target address is not +aligned to a four-byte boundary and the branch condition evaluates to +true.# [#norm:branch_misaligned_untaken_exception]#If the branch condition evaluates to false, the +instruction-address-misaligned exception will not be raised.# + +[NOTE] +==== +[[norm:branch_misaligned_c_no_exception]] +Instruction-address-misaligned exceptions are not possible on machines +with IALIGN=16, e.g., those with the +compressed instruction-set extension, C. +==== + +[[ldst]] +=== Load and Store Instructions +RV32I is a load-store architecture, where only load and store +instructions access memory and arithmetic instructions only operate on +CPU registers. RV32I provides a 32-bit address space that is +byte-addressed. The EEI will define what portions of the address space +are legal to access with which instructions (e.g., some addresses might +be read only, or support word access only). +[#norm:load_exc_x0]#Loads with a destination of +`x0` must still raise any exceptions and cause any other side effects +even though the load value is discarded.# + +[#norm:ENDIANNESS_LITTLE_OR_BIG]#The EEI will define whether the memory system is little-endian or big-endian.# +[#norm:ldst_endian_byte_invariant]#In RISC-V, endianness is byte-address invariant.# + +[NOTE] +==== +[[norm:ldst_endian_byte_op]] +In a system for which endianness is byte-address invariant, the +following property holds: if a byte is stored to memory at some address +in some endianness, then a byte-sized load from that address in any +endianness returns the stored value. + +[[norm:ldst_little_endian_op]] +In a little-endian configuration, multibyte stores write the +least-significant register byte at the lowest memory byte address, +followed by the other register bytes in ascending order of their +significance. Loads similarly transfer the contents of the lesser memory +byte addresses to the less-significant register bytes. + +[[norm:ldst_big_endian_op]] +In a big-endian configuration, multibyte stores write the +most-significant register byte at the lowest memory byte address, +followed by the other register bytes in descending order of their +significance. Loads similarly transfer the contents of the greater +memory byte addresses to the less-significant register bytes. +==== + +include::images/wavedrom/load-store.edn[] +[[load-store,load and store]] +//.Load and store instructions + +Load and store instructions transfer a value between the registers and +memory. Loads are encoded in the I-type format and stores are S-type. +[#norm:ldst_ea]#The effective address is obtained by adding register _rs1_ to the +sign-extended 12-bit offset.# +[#norm:load_op]#Loads copy a value from memory to register _rd_.# +[#norm:store_op]#Stores copy the value in register _rs2_ to memory.# + +[#norm:lw_op]#The LW instruction loads a 32-bit value from memory into _rd_.# +[#norm:lh_op]#LH loads a 16-bit value from memory, then sign-extends to 32-bits before storing +in _rd_.# +[#norm:lhu_op]#LHU loads a 16-bit value from memory but then zero extends to +32-bits before storing in _rd_.# +[#norm:lb_lbu_op]#LB and LBU are defined analogously for 8-bit values.# +[#norm:sw_sh_sb_op]#The SW, SH, and SB instructions store 32-bit, 16-bit, and +8-bit values from the low bits of register _rs2_ to memory.# + +Regardless of EEI, [#norm:ldst_no_exc_aligned]#loads and stores whose effective addresses are +naturally aligned shall not raise an address-misaligned exception.# +[#norm:MISALIGNED_LDST_EEI_DEPENDENT_BEHAVIOR]#Loads and stores whose effective address is not naturally aligned to the +referenced datatype (i.e., the effective address is not divisible by the +size of the access in bytes) have behavior dependent on the EEI.# + +An EEI may guarantee that misaligned loads and stores are fully +supported, and so the software running inside the execution environment +will never experience a contained or fatal address-misaligned trap. In this case, the +[#norm:MISALIGNED_LDST_FULLY_HW_SUPPORTED]#misaligned loads and stores can be handled in hardware#, or +[#norm:MISALIGNED_LDST_INVISIBLE_TRAP]#via an invisible trap into the execution environment implementation#, or possibly a +[#norm:MISALIGNED_LDST_HW_OR_INVISIBLE_TRAP_FUNC_OF_ADDR]#combination of hardware and invisible trap depending on address.# + +An EEI may not guarantee misaligned loads and stores are handled invisibly. In this case, +[#norm:MISALIGNED_LDST_FULLY_HW_SUPPORTED_OR_VISIBLE_TRAP]#loads and stores that are not naturally aligned +may either complete execution successfully or raise an exception.# +[#norm:ldst_addr_misaligned_or_access_fault_exc]#The exception raised can be either an +address-misaligned exception or an access-fault exception. +For a memory access that would otherwise be able +to complete except for the misalignment, an access-fault exception can +be raised instead of an address-misaligned exception if the misaligned +access should not be emulated, e.g., if accesses to the memory region +have side effects.# +[#norm:MISALIGNED_LDST_CONTAINED_OR_FATAL_TRAP]#When an EEI does not guarantee misaligned loads and +stores are handled invisibly, the EEI must define if exceptions caused +by address misalignment result in a contained trap (allowing software +running inside the execution environment to handle the trap) or a fatal +trap (terminating execution).# + +[NOTE] +==== +Misaligned accesses are occasionally required when porting legacy code, +and help performance on applications when using any form of packed-SIMD +extension or handling externally packed data structures. Our rationale +for allowing EEIs to choose to support misaligned accesses via the +regular load and store instructions is to simplify the addition of +misaligned hardware support. One option would have been to disallow +misaligned accesses in the base ISAs and then provide some separate ISA +support for misaligned accesses, either special instructions to help +software handle misaligned accesses or a new hardware addressing mode +for misaligned accesses. Special instructions are difficult to use, +complicate the ISA, and often add new processor state (e.g., SPARC VIS +align address offset register) or complicate access to existing +processor state (e.g., MIPS LWL/LWR partial register writes). In +addition, for loop-oriented packed-SIMD code, the extra overhead when +operands are misaligned motivates software to provide multiple forms of +loop depending on operand alignment, which complicates code generation +and adds to loop startup overhead. New misaligned hardware addressing +modes take considerable space in the instruction encoding or require +very simplified addressing modes (e.g., register indirect only). +==== + +Even when misaligned loads and stores complete successfully, these +accesses might run extremely slowly depending on the implementation +(e.g., when implemented via an invisible trap). Furthermore, whereas +[#norm:ldst_atomicity_for_aligned]#naturally aligned +loads and stores are guaranteed to execute atomically#, +misaligned loads and stores might not, and hence require additional +synchronization to ensure atomicity. + +[NOTE] +==== +We do not mandate atomicity for misaligned accesses so execution +environment implementations can use an invisible machine trap and a +software handler to handle some or all misaligned accesses. If hardware +misaligned support is provided, software can exploit this by simply +using regular load and store instructions. Hardware can then +automatically optimize accesses depending on whether runtime addresses +are aligned. +==== + +[[fence]] +=== Memory Ordering Instructions + +include::images/wavedrom/mem-order.edn[] +[[mem-order]] +//.Memory ordering instructions + +FENCE instructions are used to order device I/O and memory accesses as +viewed by other RISC-V harts and external devices or coprocessors. Any +combination of device input (I), device output (O), memory reads \(R), +and memory writes (W) may be ordered with respect to any combination of +the same. Informally, no other RISC-V hart or external device can +observe any operation in the _successor_ set following a FENCE before +any operation in the _predecessor_ set preceding the FENCE. +<> provides a precise description +of the RISC-V memory consistency model. + +FENCE instructions also order memory reads and writes made by the +hart as observed by memory reads and writes made by an external device. +However, FENCE instructions do not order observations of events made by an external +device using any other signaling mechanism. + +[NOTE] +==== +A device might observe an access to a memory location via some external +communication mechanism, e.g., a memory-mapped control register that +drives an interrupt signal to an interrupt controller. This +communication is outside the scope of the FENCE ordering mechanism and +hence FENCE instructions can provide no guarantee on when a change in +the interrupt signal is visible to the interrupt controller. Specific +devices might provide additional ordering guarantees to reduce software +overhead but those are outside the scope of the RISC-V memory model. +==== + +The EEI will define what I/O operations are possible, and in particular, +which memory addresses when accessed by load and store instructions will +be treated and ordered as device input and device output operations +respectively rather than memory reads and writes. For example, +memory-mapped I/O devices will typically be accessed with uncached loads +and stores that are ordered using the I and O bits rather than the R and +W bits. Instruction-set extensions might also describe new I/O +instructions that will also be ordered using the I and O bits in a +FENCE instruction. + +[[fm]] +[float="center",align="center",cols="^1,^1,<3",options="header"] +.Fence mode encoding +|=== +|_fm_ field |Mnemonic suffix|Meaning +|0000 |_none_ |Normal Fence +|1000 |.TSO |With `FENCE RW,RW`: exclude write-to-read ordering; otherwise: _Reserved for future use._ +|_other_|_other_ |_Reserved for future use._ +|=== + +The FENCE mode field _fm_ defines the semantics of the FENCE instruction. +[#norm:fence_op]#A `FENCE` +(with _fm_=`0000`) orders all memory operations in its predecessor set +before all memory operations in its successor set.# + +A `FENCE.TSO` instruction is encoded as a FENCE instruction +with _fm_=`1000`, _predecessor_=`RW`, and _successor_=`RW`. +[#norm:fence-tso_op]#`FENCE.TSO` orders +all load operations in its predecessor set before all memory operations +in its successor set, and all store operations in its predecessor set +before all store operations in its successor set. This leaves `non-AMO` +store operations in the `FENCE.TSO's` predecessor set unordered with +`non-AMO` loads in its successor set.# + +[NOTE] +==== +[[norm:fence-tso_ordering_rw_rw_ok]] +Because `FENCE RW,RW` imposes a superset of the orderings that `FENCE.TSO` +imposes, it is correct to ignore the _fm_ field and implement `FENCE.TSO` as `FENCE RW,RW`. +==== + +[#norm:fence_unused_flds_rsv]#The unused fields in the FENCE +instructions--_rs1_ and _rd_--are reserved +for finer-grain fences in future extensions. For forward compatibility, +base implementations shall ignore these fields#, and standard software +shall zero these fields. Likewise, many _fm_ and predecessor/successor +set settings are also reserved for future use. +Base implementations shall treat all such reserved configurations as +`FENCE` instructions (with _fm_=`0000`), and standard software shall use only +non-reserved configurations. + +[NOTE] +==== +[[norm:fence_cons_ok]] +We chose a relaxed memory model to allow high performance from simple +machine implementations and from likely future coprocessor or +accelerator extensions. We separate out I/O ordering from memory R/W +ordering to avoid unnecessary serialization within a device-driver hart +and also to support alternative non-memory paths to control added +coprocessors or I/O devices. Simple implementations may additionally +ignore the _predecessor_ and _successor_ fields and always execute a +conservative FENCE on all operations. +==== + +[[ecall-ebreak]] +=== Environment Call and Breakpoints +`SYSTEM` instructions are used to access system functionality that might +require privileged access and are encoded using the I-type instruction +format. These can be divided into two main classes: those that +atomically read-modify-write control and status registers (CSRs), and +all other potentially privileged instructions. CSR instructions are +described in <>, and the base +unprivileged instructions are described in the following section. + + +[NOTE] +==== +The SYSTEM instructions are defined to allow simpler implementations to +always trap to a single software trap handler. More sophisticated +implementations might execute more of each system instruction in +hardware. +==== + +include::images/wavedrom/env-call-breakpoint.edn[] +[[env-call]] +//.Environment call and breakpoint instructions + +These two instructions cause a precise requested trap to the supporting +execution environment. + +[#norm:ecall_op]#The `ECALL` instruction is used to make a service request to the execution environment.# +The `EEI` will define how parameters for the service request +are passed, but usually these will be in defined locations in the +integer register file. + +[#norm:ebreak_op]#The `EBREAK` instruction is used to return control to a debugging environment.# + +[NOTE] +==== +ECALL and EBREAK were previously named SCALL and SBREAK. The +instructions have the same functionality and encoding, but were renamed +to reflect that they can be used more generally than to call a +supervisor-level operating system or debugger. +==== + +[NOTE] +==== +EBREAK was primarily designed to be used by a debugger to cause +execution to stop and fall back into the debugger. EBREAK is also used +by the standard GCC compiler to mark code paths that should not be +executed. + +Another use of EBREAK is to support "semihosting", where the execution +environment includes a debugger that can provide services over an +alternate system call interface built around the EBREAK instruction. +Because the RISC-V base ISAs do not provide more than one EBREAK +instruction, RISC-V semihosting uses a special sequence of instructions +to distinguish a semihosting EBREAK from a debugger inserted EBREAK. + +[source,asm] +.... + slli x0, x0, 0x1f # Entry NOP + ebreak # Break to debugger + srai x0, x0, 7 # Exit NOP +.... + +Note that these three instructions must be 32-bit-wide instructions, +i.e., they mustn't be among the compressed 16-bit instructions described +in <>. + +The shift NOP instructions are still considered available for use as +HINTs. + +Semihosting is a form of service call and would be more naturally +encoded as an ECALL using an existing ABI, but this would require the +debugger to be able to intercept ECALLs, which is a newer addition to +the debug standard. We intend to move over to using ECALLs with a +standard ABI, in which case, semihosting can share a service ABI with an +existing standard. + +We note that ARM processors have also moved to using SVC instead of BKPT +for semihosting calls in newer designs. +==== + +=== HINT Instructions +//[#rv32i-hints,HINT Instructions] + +[[rv32i-hints,HINT Instructions]] + +RV32I reserves a large encoding space for HINT instructions, which are +usually used to communicate performance hints to the microarchitecture. +Like the NOP instruction, [#norm:hints_op]#HINTs do not change any architecturally +visible state, except for advancing the `pc` and any applicable +performance counters. Implementations are always allowed to ignore the +encoded hints.# + +[#norm:hints_enc]#Most RV32I HINTs are encoded as integer computational instructions with +_rd_=`x0`. The other RV32I HINTs are encoded as FENCE instructions with +a null predecessor or successor set and with _fm_=0.# + +[NOTE] +==== +These HINT encodings have been chosen so that simple implementations can +ignore HINTs altogether, and instead execute a HINT as a regular +instruction that happens not to mutate the architectural state. For +example, ADD is a HINT if the destination register is `x0`; the five-bit +_rs1_ and _rs2_ fields encode arguments to the HINT. However, a simple +implementation can simply execute the HINT as an ADD of _rs1_ and _rs2_ +that writes `x0`, which has no architecturally visible effect. + +As another example, a FENCE instruction with a zero _pred_ field and a +zero _fm_ field is a HINT; the _succ_, _rs1_, and _rd_ fields encode the +arguments to the HINT. A simple implementation can simply execute the +HINT as a FENCE that orders the null set of prior memory accesses before +whichever subsequent memory accesses are encoded in the _succ_ field. +Since the intersection of the predecessor and successor sets is null, +the instruction imposes no memory orderings, and so it has no +architecturally visible effect. +==== + +<> lists all RV32I HINT code points. 91% of the +HINT space is reserved for standard HINTs. The remainder of the HINT +space is designated for custom HINTs: no standard HINTs will ever be +defined in this subspace. + +[NOTE] +==== +We anticipate standard hints to eventually include memory-system spatial +and temporal locality hints, branch prediction hints, thread-scheduling +hints, security tags, and instrumentation flags for simulation/emulation. +==== + +// this table might still have some problems--some rows might not have landed properly. It needs to be checked cell-by cell. + +[[t-rv32i-hints]] +.RV32I HINT instructions. +[float="center",align="center",cols="<,<,^,<",options="header"] +|=== +|Instruction |Constraints |Code Points |Purpose + +|LUI |_rd_=`x0` |2^20^ .8+<.^m|_Designated for future standard use_ + +|AUIPC |_rd_=`x0` |2^20^ + +|ADDI |_rd_=`x0`, and either _rs1_{ne}``x0`` or _imm_{ne}0 |2^17^−1 + +|ANDI |_rd_=`x0` |2^17^ + +|ORI |_rd_=`x0` |2^17^ + +|XORI |_rd_=`x0` |2^17^ + +|ADD |_rd_=`x0`, _rs1_{ne}``x0`` |2^10^−32 + +|ADD |_rd_=`x0`, _rs1_=`x0`, _rs2_{ne}``x2-x5`` | 28 + +|ADD |_rd_=`x0`, _rs1_=`x0`, _rs2_=`x2-x5` |4|(_rs2_=`x2`) NTL.P1 + +(_rs2_=`x3`) NTL.PALL + +(_rs2_=`x4`) NTL.S1 + +(_rs2_=`x5`) NTL.ALL + +|SLLI |_rd_=`x0`, _rs1_=`x0`, _shamt_=31 |1|Semihosting entry marker + +|SRAI |_rd_=`x0`, _rs1_=`x0`, _shamt_=7 |1|Semihosting exit marker + +|SUB |_rd_=`x0` |2^10^ .11+<.^m|_Designated for future standard use_ + +|AND |_rd_=`x0` |2^10^ + +|OR |_rd_=`x0` |2^10^ + +|XOR |_rd_=`x0` |2^10^ + +|SLL |_rd_=`x0` |2^10^ + +|SRL |_rd_=`x0` |2^10^ + +|SRA |_rd_=`x0` |2^10^ + +|FENCE |_rd_=`x0`, _rs1_{ne}``x0``, _fm_=0, and either _pred_=0 or _succ_=0| 2^10^−63 + +|FENCE |_rd_{ne}``x0``, _rs1_=`x0`, _fm_=0, and either _pred_=0 or _succ_=0| 2^10^−63 + +|FENCE |_rd_=_rs1_=`x0`, _fm_=0, _pred_=0, _succ_{ne}0 |15 + +|FENCE |_rd_=_rs1_=`x0`, _fm_=0, _pred_{ne}W, _succ_=0 |15 + +|FENCE |_rd_=_rs1_=`x0`, _fm_=0, _pred_=W, _succ_=0 |1 |PAUSE + +4+| + +|SLTI |_rd_=`x0` |2^17^ .7+<.^m|_Designated for custom use_ + +|SLTIU |_rd_=`x0` |2^17^ + +|SLLI |_rd_=`x0`, and either _rs1_{ne}``x0`` or _shamt_{ne}31 |2^10^−1 + +|SRLI |_rd_=`x0` |2^10^ + +|SRAI |_rd_=`x0`, and either _rs1_{ne}``x0`` or _shamt_{ne}7 |2^10^−1 + +|SLT |_rd_=`x0` |2^10^ + +|SLTU |_rd_=`x0` |2^10^ +|=== + +NOTE: `slli x0, x0, 0x1f` and `srai x0, x0, 7` were previously designated as +custom HINTs, but they have been appropriated for use in semihosting calls, as +described in <>. +To reflect their usage in practice, the base ISA spec has been changed to +designate them as standard HINTs. diff --git a/param_extraction/chunks/chunk_039.txt.license b/param_extraction/chunks/chunk_039.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_039.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_040.txt b/param_extraction/chunks/chunk_040.txt new file mode 100644 index 0000000000..27003e213c --- /dev/null +++ b/param_extraction/chunks/chunk_040.txt @@ -0,0 +1,57 @@ +# Chunk: chunk_040 +# Source: rv32e.adoc +# Lines: 1-47 (of 47) +# Content starts: line 1 +# Line count: 47 +# Sections: 3 +# == RV32E and RV64E Base Integer Instruction Sets, Version 2.0 +# === RV32E and RV64E Programmers’ Model +# === RV32E and RV64E Instruction Set Encoding +# +[[rv32e]] +== RV32E and RV64E Base Integer Instruction Sets, Version 2.0 +This chapter describes the RV32E and RV64E base integer +instruction sets, designed for microcontrollers in embedded systems. +RV32E and RV64E are reduced versions of RV32I and RV64I, respectively: +the only change is to reduce the number of integer registers to 16. This +chapter only outlines the differences between RV32E/RV64E and +RV32I/RV64I, and so should be read after <> and <>. +(((RV32E, design))) +[NOTE] +==== +RV32E was designed to provide an even smaller base core for embedded +microcontrollers. There is also interest in RV64E for microcontrollers +within large SoC designs, and to reduce context state for highly +threaded 64-bit processors. + +Unless otherwise stated, standard extensions compatible with RV32I and +RV64I are also compatible with RV32E and RV64E, respectively. +==== + +=== RV32E and RV64E Programmers’ Model +RV32E and RV64E reduce the integer register count to 16 general-purpose +registers, (`x0-x15`), where `x0` is a dedicated zero register. + +[NOTE] +==== +We have found that in the small RV32I core implementations, the upper 16 +registers consume around one quarter of the total area of the core +excluding memories, thus their removal saves around 25% core area with a +corresponding core power reduction. +==== + +=== RV32E and RV64E Instruction Set Encoding +(((RV32E, difference from RV32I))) +[[norm:diff-rv32e-rv32i]] +RV32E and RV64E use the same instruction-set encoding as RV32I and RV64I +respectively, except that only registers `x0-x15` are provided. All +encodings specifying the other registers `x16-x31` are reserved. + +[NOTE] +==== +The previous draft of this chapter made all encodings using the +`x16-x31` registers available as custom. This version takes a more +conservative approach, making these reserved so that they can be +allocated between custom space or new standard encodings at a later +date. +==== diff --git a/param_extraction/chunks/chunk_040.txt.license b/param_extraction/chunks/chunk_040.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_040.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_041.txt b/param_extraction/chunks/chunk_041.txt new file mode 100644 index 0000000000..3ff4bc95cf --- /dev/null +++ b/param_extraction/chunks/chunk_041.txt @@ -0,0 +1,274 @@ +# Chunk: chunk_041 +# Source: rv64.adoc +# Lines: 1-260 (of 260) +# Content starts: line 1 +# Line count: 260 +# Sections: 7 +# == RV64I Base Integer Instruction Set, Version 2.1 +# === Register State +# === Integer Computational Instructions +# ==== Integer Register-Immediate Instructions +# ==== Integer Register-Register Operations +# === Load and Store Instructions +# === HINT Instructions +# +[[rv64]] +== RV64I Base Integer Instruction Set, Version 2.1 + +This chapter describes the RV64I base integer instruction set, which +builds upon the RV32I variant described in <>. +This chapter presents only the differences with RV32I, so should be read +in conjunction with the earlier chapter. + +=== Register State + +[#norm:rv64i_xreg_sz]#RV64I widens the integer registers and supported user address space to +64 bits (XLEN=64 in <>).# + +=== Integer Computational Instructions + +Most integer computational instructions operate on XLEN-bit values. +Additional instruction variants are provided to manipulate 32-bit values +in RV64I, indicated by a 'W' suffix to the opcode. [#norm:rv64_w_sex]#These "*W" +instructions ignore the upper 32 bits of their inputs and always produce +32-bit signed values, sign-extending them to 64 bits, i.e. bits XLEN-1 +through 31 are equal.# + +[NOTE] +==== +The compiler and calling convention maintain an invariant that all +32-bit values are held in a sign-extended format in 64-bit registers. +Even 32-bit unsigned integers extend bit 31 into bits 63 through 32. +Consequently, conversion between unsigned and signed 32-bit integers is +a no-op, as is conversion from a signed 32-bit integer to a signed +64-bit integer. Existing 64-bit wide SLTU and unsigned branch compares +still operate correctly on unsigned 32-bit integers under this +invariant. Similarly, existing 64-bit wide logical operations on 32-bit +sign-extended integers preserve the sign-extension property. A few new +instructions (ADD[I]W/SUBW/SxxW) are required for addition and shifts to +ensure reasonable performance for 32-bit values. +==== +(((RV64I, shifts))) +(((RV64I, compares))) + +==== Integer Register-Immediate Instructions + +include::images/wavedrom/rv64i-base-int.edn[] +[[rv64i-base-int]] +//.RV64I register-immediate instructions + +[#norm:addiw_op]#ADDIW is an RV64I instruction that adds the sign-extended 12-bit +immediate to register _rs1_ and produces the proper sign extension of a +32-bit result in _rd_.# [#norm:addiw_overflow]#Overflows are ignored and the result is the low +32 bits of the result sign-extended to 64 bits.# Note, ADDIW _rd, rs1, 0_ +writes the sign extension of the lower 32 bits of register _rs1_ into +register _rd_ (assembler pseudoinstruction SEXT.W). + +include::images/wavedrom/rv64i-slli.edn[] +[[rv64i-slli]] +//.RV64I register-immediate (descr ADDIW) instructions + +Shifts by a constant are encoded as a specialization of the I-type +format using the same instruction opcode as RV32I. The operand to be +shifted is in _rs1_, and the shift amount is encoded in the lower 6 bits +of the I-immediate field for RV64I. The right-shift type is encoded in +bit 30. SLLI is a logical left shift (zeros are shifted into the lower +bits); SRLI is a logical right shift (zeros are shifted into the upper +bits); and SRAI is an arithmetic right shift (the original sign bit is +copied into the vacated upper bits). +(((RV64I, SLLI))) +(((RV64I, SRKIW))) +(((RV64I, SRLIW))) +(((RV64I, RV64I-only))) + +include::images/wavedrom/rv64i-slliw.edn[] +[[rv64i-slliw]] + +[#norm:slliw_srliw_sraiw_op]#SLLIW, SRLIW, and SRAIW are RV64I-only instructions that are analogously +defined but operate on 32-bit values and sign-extend their 32-bit +results to 64 bits.# [#norm:slliw_srliw_sraiw_imm5_rsv]#SLLIW, SRLIW, and SRAIW encodings with +_imm[5] {ne} 0_ are reserved.# + +[NOTE] +==== +Previously, SLLIW, SRLIW, and SRAIW with _imm[5] {ne} 0_ +were defined to cause illegal-instruction exceptions, whereas now they +are marked as reserved. This is a backwards-compatible change. +==== + +include::images/wavedrom/rv64-lui-auipc.edn[] +[[rv64_lui-auipc]] +//.RV64I register-immediate (descr) instructions + +LUI (load upper immediate) uses the same opcode as RV32I. +[#norm:lui_op_rv64i]#LUI places the +32-bit U-immediate into register _rd_, filling in the lowest 12 bits +with zeros. The 32-bit result is sign-extended to 64 bits.# +(((RV64I, LUI))) + +AUIPC (add upper immediate to `pc`) uses the same opcode as RV32I. AUIPC +is used to build `pc`-relative addresses and uses the U-type format. +[#norm:auipc_op_rv64i]#AUIPC forms a 32-bit offset from the U-immediate, filling in the lowest +12 bits with zeros, sign-extends the result to 64 bits, adds it to the +address of the AUIPC instruction, then places the result in register _rd_.# + +[NOTE] +==== +Note that the set of address offsets that can be formed by pairing LUI +with LD, AUIPC with JALR, etc. in RV64I is +[−2^31^−2^11^, 2^31^−2^11^−1]. +==== + +==== Integer Register-Register Operations + +//this diagramdoesn't match the tex specification +include::images/wavedrom/rv64i-int-reg-reg.edn[] +[[int_reg-reg]] +//.RV64I integer register-register instructions + +[#norm:addw_subw_op]#ADDW and SUBW are RV64I-only instructions that are defined analogously +to ADD and SUB but operate on 32-bit values and produce signed 32-bit results.# +[#norm:addw_subw_overflow]#Overflows are ignored, and the low 32-bits of the result is +sign-extended to 64-bits and written to the destination register.# +(((RV64I-only, ADDW))) +(((RV64I-only, SUBW))) + +SLL, SRL, and SRA perform logical left, logical right, and arithmetic +right shifts on the value in register _rs1_ by the shift amount held in +register _rs2_. [#norm:sll_srl_sra_sh_amt_rv64i]#In RV64I, only the low 6 bits of _rs2_ are considered +for the shift amount.# + +[#norm:sllw_srlw_sraw_op]#SLLW, SRLW, and SRAW are RV64I-only instructions that are analogously +defined but operate on 32-bit values and sign-extend their 32-bit +results to 64 bits. The shift amount is given by _rs2[4:0]_.# +(((RV64I-only, SLLW))) +(((RV64I-only, SRLW))) +(((RV64I-only, SRAW))) + +=== Load and Store Instructions + +RV64I extends the address space to 64 bits. The execution environment +will define what portions of the address space are legal to access. + +include::images/wavedrom/load-store.edn[] +[[load_store]] +//.Load and store instructions + +[#norm:ld_op_rv64i]#The LD instruction loads a 64-bit value from memory into register _rd_ +for RV64I.# +(((RV64I, LD))) + +[#norm:lw_op_rv64i]#The LW instruction loads a 32-bit value from memory and sign-extends +this to 64 bits before storing it in register _rd_ for RV64I.# +[#norm:lwu_op]#The LWU instruction, on the other hand, zero-extends the 32-bit value from +memory for RV64I.# [#norm:lh_lhu_lb_lbu_op_rv64i]#LH and LHU are defined analogously for 16-bit values, +as are LB and LBU for 8-bit values.# [#norm:sd_sw_sh_sb_op_rv64i]#The SD, SW, SH, and SB instructions +store 64-bit, 32-bit, 16-bit, and 8-bit values from the low bits of +register _rs2_ to memory respectively.# + +[[rv64i-hints]] +=== HINT Instructions + +All instructions that are microarchitectural HINTs in RV32I (see +<>) are also HINTs in RV64I.# +The additional computational instructions in RV64I expand both the +standard and custom HINT encoding spaces. +(((RV64I, HINT))) + +<> lists all RV64I HINT code points. 91% of the +HINT space is reserved for standard HINTs. The remainder of the HINT +space is designated for custom HINTs; no standard HINTs will ever be +defined in this subspace. + +[[rv64i-h]] +.RV64I HINT instructions. +[float="center",align="center",cols="<,<,^,<", options="header", grid="all"] +|=== +|Instruction |Constraints |Code Points |Purpose +|LUI |_rd_=`x0` |2^20^ .9+.^|_Designated for future standard use_ + +|AUIPC |_rd_=`x0` |2^20^ + +|ADDI |_rd_=`x0`, and either _rs1_≠`x0` or _imm_≠0 |2^17^−1 + +|ANDI |_rd_=`x0` |2^17^ + +|ORI |_rd_=`x0` |2^17^ + +|XORI |_rd_=`x0` |2^17^ + +|ADDIW |_rd_=`x0` |2^17^ + +|ADD |_rd_=`x0`, _rs1_≠`x0` |2^10^−32 + +|ADD |_rd_=`x0`, _rs1_=`x0`, _rs2_≠_x2_-_x5_ | 28 + +|ADD |_rd_=`x0`, _rs1_=`x0`, _rs2_=_x2_-_x5_| 4 | (_rs2_=_x2_) NTL.P1 + + (_rs2_=_x3_) NTL.PALL + + (_rs2_=_x4_) NTL.S1 + + (_rs2_=_x5_) NTL.ALL + +|SLLI |_rd_=`x0`, _rs1_=`x0`, _shamt_=31 |1|Semihosting entry marker + +|SRAI |_rd_=`x0`, _rs1_=`x0`, _shamt_=7 |1|Semihosting exit marker + +|SUB |_rd_=`x0` |2^10^ .16+.^| _Designated for future standard use_ + +|AND |_rd_=`x0` |2^10^ + +|OR |_rd_=`x0` |2^10^ + +|XOR |_rd_=`x0` |2^10^ + +|SLL |_rd_=`x0` |2^10^ + +|SRL |_rd_=`x0` |2^10^ + +|SRA |_rd_=`x0` |2^10^ + +|ADDW |_rd_=`x0` |2^10^ + +|SUBW |_rd_=`x0` |2^10^ + +|SLLW |_rd_=`x0` |2^10^ + +|SRLW |_rd_=`x0` |2^10^ + +|SRAW |_rd_=`x0` |2^10^ + +|FENCE |_rd_=`x0`, _rs1_{ne}``x0``, _fm_=0, and either _pred_=0 or _succ_=0| 2^10^−63 + +|FENCE |_rd_{ne}``x0``, _rs1_=`x0`, _fm_=0, and either _pred_=0 or _succ_=0| 2^10^−63 + +|FENCE |_rd_=_rs1_=`x0`, _fm_=0, _pred_=0, _succ_{ne}0 |15 + +|FENCE |_rd_=_rs1_=`x0`, _fm_=0, _pred_{ne}W, _succ_=0 |15 + +|FENCE |_rd_=_rs1_=`x0`, _fm_=0, _pred_=W, _succ_=0 |1 |PAUSE + +|SLTI |_rd_=`x0` |2^17^ .10+.^|_Designated for custom use_ + +|SLTIU |_rd_=`x0` |2^17^ + +|SLLI |_rd_=`x0`, and either _rs1_{ne}``x0`` or _shamt_{ne}31 |2^11^−1 + +|SRLI |_rd_=`x0` |2^11^ + +|SRAI |_rd_=`x0`, and either _rs1_{ne}``x0`` or _shamt_{ne}7 |2^11^−1 + +|SLLIW |_rd_=`x0` |2^10^ + +|SRLIW |_rd_=`x0` |2^10^ + +|SRAIW |_rd_=`x0` |2^10^ + +|SLT |_rd_=`x0` |2^10^ + +|SLTU |_rd_=`x0` |2^10^ +|=== + +NOTE: `slli x0, x0, 0x1f` and `srai x0, x0, 7` were previously designated as +custom HINTs, but they have been appropriated for use in semihosting calls, as +described in <>. +To reflect their usage in practice, the base ISA spec has been changed to +designate them as standard HINTs. diff --git a/param_extraction/chunks/chunk_041.txt.license b/param_extraction/chunks/chunk_041.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_041.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_042.txt b/param_extraction/chunks/chunk_042.txt new file mode 100644 index 0000000000..36c1b0a30a --- /dev/null +++ b/param_extraction/chunks/chunk_042.txt @@ -0,0 +1,834 @@ +# Chunk: chunk_042 +# Source: rvwmo.adoc +# Lines: 1-817 (of 817) +# Content starts: line 1 +# Line count: 817 +# Sections: 10 +# == RVWMO Memory Consistency Model, Version 2.0 +# === Definition of the RVWMO Memory Model +# ==== Memory Model Primitives +# ==== Syntactic Dependencies +# ==== Preserved Program Order +# ==== Memory Model Axioms +# ===== Load Value Axiom +# ===== Atomicity Axiom +# ===== Progress Axiom +# === CSR Dependency Tracking Granularity +# +[[memorymodel]] +== RVWMO Memory Consistency Model, Version 2.0 + +This chapter defines the RISC-V memory consistency model. A memory +consistency model is a set of rules specifying the values that can be +returned by loads of memory. RISC-V uses a memory model called "RVWMO" +(RISC-V Weak Memory Ordering) which is designed to provide flexibility +for architects to build high-performance scalable designs while +simultaneously supporting a tractable programming model. +(((design, high performance))) +(((design, scalable))) + +Under RVWMO, code running on a single hart appears to execute in order +from the perspective of other memory instructions in the same hart, but +memory instructions from another hart may observe the memory +instructions from the first hart being executed in a different order. +Therefore, multithreaded code may require explicit synchronization to +guarantee ordering between memory instructions from different harts. The +base RISC-V ISA provides a FENCE instruction for this purpose, described +in <>, while the atomics extension "A" additionally defines load-reserved/store-conditional and atomic read-modify-write instructions. +(((atomics, misaligned))) + +The standard ISA extension for total store ordering "Ztso" (<>) augments +RVWMO with additional rules specific to those extensions. + +The appendices to this specification provide both axiomatic and +operational formalizations of the memory consistency model as well as +additional explanatory material. +(((FENCE))) +(((SFENCE))) + +[NOTE] +==== +This chapter defines the memory model for regular main memory +operations. The interaction of the memory model with I/O memory, +instruction fetches, FENCE.I, page-table walks, and SFENCE.VMA is not +(yet) formalized. Some or all of the above may be formalized in a future +revision of this specification. Future ISA +extensions such as the V vector and J JIT extensions will need +to be incorporated into a future revision as well. + +Memory consistency models supporting overlapping memory accesses of +different widths simultaneously remain an active area of academic +research and are not yet fully understood. The specifics of how memory +accesses of different sizes interact under RVWMO are specified to the +best of our current abilities, but they are subject to revision should +new issues be uncovered. +==== + +[[rvwmo]] +=== Definition of the RVWMO Memory Model + +The RVWMO memory model is defined in terms of the _global memory order_, +a total ordering of the memory operations produced by all harts. In +general, a multithreaded program has many different possible executions, +with each execution having its own corresponding global memory order. +(((RVWMO))) + +The global memory order is defined over the primitive load and store +operations generated by memory instructions. It is then subject to the +constraints defined in the rest of this chapter. Any execution +satisfying all of the memory model constraints is a legal execution (as +far as the memory model is concerned). + +[[rvwmo-primitives]] +==== Memory Model Primitives + +The _program order_ over memory operations reflects the order in which +the instructions that generate each load and store are logically laid +out in that hart's dynamic instruction stream; i.e., the order in which +a simple in-order processor would execute the instructions of that hart. + +Memory-accessing instructions give rise to _memory operations_. A memory +operation can be either a _load operation_, a _store operation_, or both +simultaneously. All memory operations are single-copy atomic: they can +never be observed in a partially complete state. +(((operations, memory))) + +Each aligned memory instruction that accesses XLEN or fewer bits gives rise +to exactly one memory operation, unless specified otherwise. An aligned AMO +gives rise to a single memory operation that is both a load operation and a +store operation simultaneously. + +[NOTE] +==== +Among instructions in RV32GC and RV64GC, the following are exceptions to the +rule that an aligned memory instruction gives rise to exactly one memory +operation: + +* An unsuccessful SC instruction does not give rise to any memory operations. +* Floating-point load and store instructions that access more than XLEN bits + (e.g., FLD/FSD in RV32) may each give rise to multiple memory operations. + +ISA extensions such as *V* (Vector) and the upcoming *P* (SIMD) may give rise +to multiple memory operations. However, the memory model for these extensions +has not yet been formalized. +==== + +A misaligned load or store instruction may be decomposed into a set of +component memory operations of any granularity. +A floating-point load or store of more than XLEN bits may also be decomposed +into a set of component memory operations of any granularity. +The memory +operations generated by such instructions are not ordered with respect +to each other in program order, but they are ordered normally with +respect to the memory operations generated by preceding and subsequent +instructions in program order. +The atomics extension "A" does not require execution environments to support +misaligned atomic instructions at all. +However, if misaligned atomics are supported via the misaligned atomicity +granule PMA, then AMOs within an atomicity granule are not decomposed, nor are +loads and stores defined in the base ISAs, nor are loads and stores of no more +than XLEN bits defined in the F, D, and Q extensions. +(((decomposition))) + +[NOTE] +==== +The decomposition of misaligned memory operations down to byte +granularity facilitates emulation on implementations that do not +natively support misaligned accesses. Such implementations might, for +example, simply iterate over the bytes of a misaligned access one by +one. +==== + +An LR instruction and an SC instruction are said to be _paired_ if the +LR precedes the SC in program order and if there are no other LR or SC +instructions in between; the corresponding memory operations are said to +be paired as well (except in case of a failed SC, where no store +operation is generated). The complete list of conditions determining +whether an SC must succeed, may succeed, or must fail is defined in +<>. + +Load and store operations may also carry one or more ordering +annotations from the following set: "acquire-RCpc", "acquire-RCsc", +"release-RCpc", and "release-RCsc". An AMO or LR instruction with +_aq_ set has an "acquire-RCsc" annotation. An AMO or SC instruction +with _rl_ set has a "release-RCsc" annotation. An AMO, LR, or SC +instruction with both _aq_ and _rl_ set has both "acquire-RCsc" and +"release-RCsc" annotations. + +For convenience, we use the term "acquire annotation" to refer to an +acquire-RCpc annotation or an acquire-RCsc annotation. Likewise, a +"release annotation" refers to a release-RCpc annotation or a +release-RCsc annotation. An "RCpc annotation" refers to an +acquire-RCpc annotation or a release-RCpc annotation. An _RCsc +annotation_ refers to an acquire-RCsc annotation or a release-RCsc +annotation. + +[NOTE] +==== +In the memory model literature, the term "RCpc" stands for release +consistency with processor-consistent synchronization operations, and +the term "RCsc" stands for release consistency with sequentially +consistent synchronization operations. + +While there are many different definitions for acquire and release +annotations in the literature, in the context of RVWMO these terms are +concisely and completely defined by <> rules 5-7. + +"RCpc" annotations are currently only used when implicitly assigned to +every memory access per the standard extension "Ztso" +(<>). Furthermore, although the ISA does not +currently contain native load-acquire or store-release instructions, nor +RCpc variants thereof, the RVWMO model itself is designed to be +forwards-compatible with the potential addition of any or all of the +above into the ISA in a future extension. +==== + +[[mem-dependencies]] +==== Syntactic Dependencies + +The definition of the RVWMO memory model depends in part on the notion +of a syntactic dependency, defined as follows. + +In the context of defining dependencies, a _register_ refers either to +an entire general-purpose register, some portion of a CSR, or an entire +CSR. The granularity at which dependencies are tracked through CSRs is +specific to each CSR and is defined in +<>. + +Syntactic dependencies are defined in terms of instructions' _source +registers_, instructions' _destination registers_, and the way +instructions _carry a dependency_ from their source registers to their +destination registers. This section provides a general definition of all +of these terms; however, <> provides a +complete listing of the specifics for each instruction. + +In general, a register _r_ other than `x0` is a _source +register_ for an instruction _i_ if any of the following +hold: + +* In the opcode of _i_, _rs1_, _rs2_, or _rs3_ is set to +_r_ +* _i_ is a CSR instruction, and in the opcode of +_i_, _csr_ is set to _r_, unless _i_ +is CSRRW or CSRRWI and _rd_ is set to `x0` +* _r_ is a CSR and an implicit source register for +_i_, as defined in <> +* _r_ is a CSR that aliases with another source register for +_i_ + +Memory instructions also further specify which source registers are +_address source registers_ and which are _data source registers_. + +In general, a register _r_ other than `x0` is a _destination +register_ for an instruction _i_ if any of the following +hold: + +* In the opcode of _i_, _rd_ is set to _r_ +* _i_ is a CSR instruction, and in the opcode of +_i_, _csr_ is set to _r_, unless _i_ +is CSRRS or CSRRC and _rs1_ is set to `x0` or _i_ is CSRRSI +or CSRRCI and uimm[4:0] is set to zero. +* _r_ is a CSR and an implicit destination register for +_i_, as defined in <> +* _r_ is a CSR that aliases with another destination +register for _i_ + +Most non-memory instructions _carry a dependency_ from each of their +source registers to each of their destination registers. However, there +are exceptions to this rule; see <>. + +Instruction _j_ has a _syntactic dependency_ on instruction +_i_ via destination register _s_ of +_i_ and source register _r_ of _j_ +if either of the following hold: + +* _s_ is the same as _r_, and no instruction +program-ordered between _i_ and _j_ has +_r_ as a destination register +* There is an instruction _m_ program-ordered between +_i_ and _j_ such that all of the following hold: +. _j_ has a syntactic dependency on _m_ via +destination register _q_ and source register _r_ +. _m_ has a syntactic dependency on _i_ via +destination register _s_ and source register _p_ +. _m_ carries a dependency from _p_ to +_q_ + +Finally, in the definitions that follow, let _a_ and +_b_ be two memory operations, and let _i_ and +_j_ be the instructions that generate _a_ and +_b_, respectively. + +_b_ has a _syntactic address dependency_ on _a_ +if _r_ is an address source register for _j_ and +_j_ has a syntactic dependency on _i_ via source +register _r_ + +_b_ has a _syntactic data dependency_ on _a_ if +_b_ is a store operation, _r_ is a data source +register for _j_, and _j_ has a syntactic +dependency on _i_ via source register _r_ + +_b_ has a _syntactic control dependency_ on _a_ +if there is an instruction _m_ program-ordered between +_i_ and _j_ such that _m_ is a +branch or indirect jump and _m_ has a syntactic dependency +on _i_. + +[NOTE] +==== +Generally speaking, non-AMO load instructions do not have data source +registers, and unconditional non-AMO store instructions do not have +destination registers. However, a successful SC instruction is +considered to have the register specified in _rd_ as a destination +register, and hence it is possible for an instruction to have a +syntactic dependency on a successful SC instruction that precedes it in +program order. +==== + +==== Preserved Program Order +[[ppo]] +The global memory order for any given execution of a program respects +some but not all of each hart’s program order. The subset of program +order that must be respected by the global memory order is known as +_preserved program order_. + +The complete definition of preserved program order is as follows (and +note that AMOs are simultaneously both loads and stores): memory +operation _a_ precedes memory operation _b_ in +preserved program order (and hence also in the global memory order) if +_a_ precedes _b_ in program order, +_a_ and _b_ both access regular main memory +(rather than I/O regions), and any of the following hold: + +[[overlapping-ordering]] +* Overlapping-Address Orderings: +. _b_ is a store, and +_a_ and _b_ access overlapping memory addresses +. _a_ and _b_ are loads, +_x_ is a byte read by both _a_ and +_b_, there is no store to _x_ between +_a_ and _b_ in program order, and +_a_ and _b_ return values for _x_ +written by different memory operations +. _a_ is +generated by an AMO or SC instruction, _b_ is a load, and +_b_ returns a value written by _a_ +* Explicit Synchronization +[start=4] +. There is a FENCE instruction that +orders _a_ before _b_ +. _a_ has an acquire +annotation +. _b_ has a release annotation +. _a_ and _b_ both have +RCsc annotations +. _a_ is paired with +_b_ +* Syntactic Dependencies +[start=9] +. _b_ has a syntactic address +dependency on _a_ +. _b_ has a syntactic data +dependency on _a_ +. _b_ is a store, and +_b_ has a syntactic control dependency on _a_ +* Pipeline Dependencies +[start=12] +. _b_ is a +load, and there exists some store _m_ between +_a_ and _b_ in program order such that +_m_ has an address or data dependency on _a_, +and _b_ returns a value written by _m_ +. _b_ is a store, and +there exists some instruction _m_ between _a_ +and _b_ in program order such that _m_ has an +address dependency on _a_ + +==== Memory Model Axioms + +An execution of a RISC-V program obeys the RVWMO memory consistency +model only if there exists a global memory order conforming to preserved +program order and satisfying the _load value axiom_, the _atomicity +axiom_, and the _progress axiom_. + +[[ax-load]] +===== Load Value Axiom + +Each byte of each load _i_ returns the value written to that +byte by the store that is the latest in global memory order among the +following stores: + +. Stores that write that byte and that precede _i_ in the +global memory order +. Stores that write that byte and that precede _i_ in +program order + +[[ax-atom]] +===== Atomicity Axiom + +If _r_ and _w_ are paired load and store +operations generated by aligned LR and SC instructions in a hart +_h_, _s_ is a store to byte _x_, and +_r_ returns a value written by _s_, then +_s_ must precede _w_ in the global memory order, +and there can be no store from a hart other than _h_ to byte +_x_ following _s_ and preceding _w_ +in the global memory order. +[NOTE] +==== +The <> theoretically supports LR/SC pairs of different widths and to +mismatched addresses, since implementations are permitted to allow SC +operations to succeed in such cases. However, in practice, we expect +such patterns to be rare, and their use is discouraged. +==== + +[[ax-prog]] +===== Progress Axiom + +No memory operation may be preceded in the global memory order by an +infinite sequence of other memory operations. + +[[csr-granularity]] +=== CSR Dependency Tracking Granularity + +.Granularities at which syntactic dependencies are tracked through CSRs +[%autowidth,float="center",align="center",cols="<,<,<",options="header",] +|=== +|Name |Portions Tracked as Independent Units |Aliases +|_fflags_ |Bits 4, 3, 2, 1, 0 |_fcsr_ +|_frm_ |entire CSR |_fcsr_ +|_fcsr_ |Bits 7-5, 4, 3, 2, 1, 0 |_fflags_, _frm_ +|=== + +Note: read-only CSRs are not listed, as they do not participate in the +definition of syntactic dependencies. + +[[source-dest-regs]] +=== Source and Destination Register Listings + +This section provides a concrete listing of the source and destination +registers for each instruction. These listings are used in the +definition of syntactic dependencies in +<>. + +The term "accumulating CSR" is used to describe a CSR that is both a +source and a destination register, but which carries a dependency only +from itself to itself. + +Instructions carry a dependency from each source register in the +"Source Registers" column to each destination register in the +"Destination Registers" column, from each source register in the +"Source Registers" column to each CSR in the "Accumulating CSRs" +column, and from each CSR in the "Accumulating CSRs" column to itself, +except where annotated otherwise. + +Key: + +- ^A^Address source register + +- ^D^Data source register + +- † The instruction does not carry a dependency from +any source register to any destination register + +- ‡ The instruction carries dependencies from source +register(s) to destination register(s) as specified + +.RV32I Base Integer Instruction Set +[%autowidth,float="center",align="center",cols="<,<,<,<,<",options="header"] +|=== +||Source Registers |Destination Registers|Accumulating CSRs| + +|LUI | |_rd_ | | + +|AUIPC | |_rd_ || + +|JAL | |_rd_ || + +|JALR† |_rs1_ |_rd_ || + +|BEQ |_rs1_, _rs2_ | || + +|BNE |_rs1_, _rs2_ | || + +|BLT |_rs1_, _rs2_ | || + +|BGE |_rs1_, _rs2_ | || + +|BLTU |_rs1_, _rs2_ | || + +|BGEU |_rs1_, _rs2_ | || + +|LB † | _rs1_ ^A^ | _rd_ || + +|LH † | _rs1_ ^A^ | _rd_ || + +|LW † | _rs1_ ^A^ | _rd_ || + +|LBU † | _rs1_ ^A^ | _rd_ || + +|LHU † | _rs1_ ^A^ | _rd_ || + +|SB |_rs1_ ^A^, _rs2_ ^D^ | || + +|SH |_rs1_ ^A^, _rs2_ ^D^ | || + +|SW |_rs1_ ^A^, _rs2_ ^D^ | || + +|ADDI |_rs1_ |_rd_ || + +|SLTI |_rs1_ |_rd_ || + +|SLTIU |_rs1_ |_rd_ || + +|XORI |_rs1_ |_rd_ || + +|ORI |_rs1_ |_rd_ || + +|ANDI |_rs1_ |_rd_ || + +|SLLI |_rs1_ |_rd_ || + +|SRLI |_rs1_ |_rd_ || + +|SRAI |_rs1_ |_rd_ || + +|ADD |_rs1_, _rs2_ |_rd_ || + +|SUB |_rs1_, _rs2_ |_rd_ || + +|SLL |_rs1_, _rs2_ |_rd_ || + +|SLT |_rs1_, _rs2_ |_rd_ || + +|SLTU |_rs1_, _rs2_ |_rd_ || + +|XOR |_rs1_, _rs2_ |_rd_ || + +|SRL |_rs1_, _rs2_ |_rd_ || + +|SRA |_rs1_, _rs2_ |_rd_ || + +|OR |_rs1_, _rs2_ |_rd_ || + +|AND |_rs1_, _rs2_ |_rd_ || + +|FENCE | | || + +|FENCE.I | | || + +|ECALL | | || + +|EBREAK | | || + +|CSRRW‡ |_rs1_, _csr_^*^ | _rd_, _csr_ | |^*^unless _rd_=`x0` + +5+| ‡ carries a dependency from _rs1_ to _csr_ and from _csr_ to _rd_ + +|CSRRS‡ |_rs1_, _csr_ |_rd_, _csr_^*^ | |^*^unless _rs1_=`x0` + +|CSRRC‡ |_rs1_, _csr_ |_rd_, _csr_^*^ | |^*^unless _rs1_=`x0` + +5+| ‡ carries a dependency from _csr_ and _rs1_ to _csr_ and from _csr_ to _rd_ + +|CSRRWI ‡ |_csr_ ^*^ |_rd_, _csr_ | |^*^unless _rd_=_x0_ + +5+| ‡ carries a dependency from _csr_ to _rd_ + +|CSRRSI ‡ |_csr_ |_rd_, _csr_^*^ | |^*^unless uimm[4:0]=0 + +|CSRRCI ‡ |_csr_ |_rd_, _csr_^*^ | |^*^unless uimm[4:0]=0 + +5+| ‡ carries a dependency from _csr_ to _rd_ and _csr_ +|=== + +.RV64I Base Integer Instruction Set +[%autowidth.stretch,float="center",align="center",cols="<,<,<,<,<",options="header"] +|=== +| |Source Registers |Destination Registers |Accumulating CSRs| + +|_LWU_ † |_rs1_ ^A^ |_rd_ | | + +|_LD_ † |_rs1_ ^A^ |_rd_ | | + +|SD |_rs1_ ^A^, _rs2_ ^D^ | | | + +|SLLI | _rs1_ | _rd_ | | + +|SRLI | _rs1_ | _rd_ | | + +|SRAI | _rs1_ | _rd_ | | + +|ADDIW | _rs1_ | _rd_ | | + +|SLLIW | _rs1_ | _rd_ | | + +|SRLIW | _rs1_ | _rd_ | | + +|SRAIW | _rs1_ | _rd_ | | + +|ADDW | _rs1_, _rs2_ |_rd_ || + +|SUBW | _rs1_, _rs2_ |_rd_ || + +|SLLW | _rs1_, _rs2_ |_rd_ || + +|SRLW | _rs1_, _rs2_ |_rd_ || + +|SRAW | _rs1_, _rs2_ |_rd_ || +|=== + +.RV32M Standard Extension +[%autowidth.stretch,float="center",align="center",cols="<,<,<,<,<",options="header"] +|=== +| |Source Registers |Destination Registers |Accumulating CSRs| + +|MUL | _rs1_, _rs2_ |_rd_ || + +|MULH | _rs1_, _rs2_ |_rd_ || + +|MULHSU |_rs1_, _rs2_ |_rd_ || + +|MULHU |_rs1_, _rs2_ |_rd_ || + +|DIV |_rs1_, _rs2_ |_rd_ || + +|DIVU |_rs1_, _rs2_ |_rd_ || + +|REM |_rs1_, _rs2_ |_rd_ || + +|REMU |_rs1_, _rs2_ |_rd_ || +|=== + +.RV64M Standard Extension +[%autowidth.stretch,float="center",align="center",cols="<,<,<,<,<",options="header"] +|=== +||Source Registers |Destination Registers |Accumulating CSRs| + +|MULW |_rs1_, _rs2_ |_rd_ || + +|DIVW |_rs1_, _rs2_ |_rd_ || + +|DIVUW |_rs1_, _rs2_ |_rd_ || + +|REMW |_rs1_, _rs2_ |_rd_ || + +|REMUW |_rs1_, _rs2_ |_rd_ || +|=== + +.RV32A Standard Extension +[%autowidth.stretch,float="center",align="center",cols="<,<,<,<,<",options="header"] +|=== +||Source Registers |Destination Registers |Accumulating CSRs| + +|LR.W† | _rs1_ ^A^ | _rd_ | | + +|SC.W† | _rs1_ ^A^, _rs2_ ^D^ | _rd_ ^*^ | | ^*^ if successful + +|AMOSWAP.W† |_rs1_ ^A^, _rs2_ ^D^ |_rd_ | | + +|AMOADD.W† |_rs1_ ^A^, _rs2_ ^D^ |_rd_ | | + +|AMOXOR.W† |_rs1_ ^A^, _rs2_ ^D^ |_rd_ | | + +|AMOAND.W† |_rs1_ ^A^, _rs2_ ^D^ |_rd_ | | + +|AMOOR.W† |_rs1_ ^A^, _rs2_^D^ |_rd_ | | + +|AMOMIN.W† |_rs1_ ^A^, _rs2_ ^D^ |_rd_ | | + +|AMOMAX.W† |_rs1_ ^A^, _rs2_ ^D^ |_rd_ | | + +|AMOMINU.W† |_rs1_ ^A^, _rs2_ ^D^ |_rd_ | | + +|AMOMAXU.W† |_rs1_ ^A^, _rs2_ ^D^ |_rd_ | | + +|=== + +.RV64A Standard Extension +[%autowidth.stretch,float="center",align="center",cols="<,<,<,<,<",options="header"] +|=== + +| |Source Registers |Destination Registers |Accumulating CSRs| + +|LR.D† |_rs1_ ^A^ |_rd_ | | + +|SC.D† |_rs1_ ^A^, _rs2_ ^D^ |_rd_ ^*^ | |^*^if successful + +|AMOSWAP.D† |_rs1_ ^A^, _rs2_ ^D^ |_rd_ | | + +|AMOADD.D† |_rs1_ ^A^, _rs2_ ^D^ |_rd_ | | + +|AMOXOR.D† |_rs1_ ^A^, _rs2_ ^D^ |_rd_ | | + +|AMOAND.D† |_rs1_ ^A^, _rs2_^D^ |_rd_ | | + +|AMOOR.D† |_rs1_ ^A^, _rs2_^D^ |_rd_ | | + +|AMOMIN.D† |_rs1_ ^A^, _rs2_^D^ |_rd_ | | + +|AMOMAX.D† |_rs1_ ^A^, _rs2_^D^ |_rd_ | | + +|AMOMINU.D† |_rs1_ ^A^, _rs2_^D^ |_rd_ | | + +|AMOMAXU.D† |_rs1_ ^A^, _rs2_^D^ |_rd_ | | + +|=== + +.RV32F Standard Extension +[%autowidth.stretch,float="center",align="center",cols="<,<,<,<,<",options="header"] +|=== + +| |Source Registers |Destination Registers |Accumulating CSRs | + + +|FLW† |_rs1_ ^A^ |_rd_ | | + +|FSW |_rs1_ ^A^, _rs2_^D^ | | | + +|FMADD.S |_rs1_, _rs2_, _rs3_, frm^*^ |_rd_ |NV, OF, UF, NX |^*^if rm=111 + +|FMSUB.S |_rs1_, _rs2_, _rs3_, frm^*^ |_rd_ |NV, OF, UF, NX |^*^if rm=111 + +|FNMSUB.S |_rs1_, _rs2_, _rs3_, frm^*^ |_rd_ |NV, OF, UF, NX |^*^if rm=111 + +|FNMADD.S |_rs1_, _rs2_, _rs3_, frm^*^ |_rd_ |NV, OF, UF, NX |^*^if rm=111 + +|FADD.S |_rs1_, _rs2_, frm^*^ |_rd_ |NV, OF, NX |^*^if rm=111 + +|FSUB.S |_rs1_, _rs2_, frm^*^ |_rd_ |NV, OF, NX |^*^if rm=111 + +|FMUL.S |_rs1_, _rs2_, frm^*^ |_rd_ |NV, OF, UF, NX |^*^if rm=111 + +|FDIV.S |_rs1_, _rs2_, frm^*^ |_rd_ |NV, DZ, OF, UF, NX |^*^if rm=111 + +|FSQRT.S |_rs1_, frm^*^ |_rd_ |NV, NX |^*^if rm=111 + +|FSGNJ.S |_rs1_, _rs2_ |_rd_ | | + +|FSGNJN.S |_rs1_, _rs2_ |_rd_ | | + +|FSGNJX.S |_rs1_, _rs2_ |_rd_ | | + +|FMIN.S |_rs1_, _rs2_ |_rd_ |NV | + +|FMAX.S |_rs1_, _rs2_ |_rd_ |NV | + +|FCVT.W.S |_rs1_, frm^*^ |_rd_ |NV, NX |^*^if rm=111 + +|FCVT.WU.S |_rs1_, frm^*^ |_rd_ |NV, NX |^*^if rm=111 + +|FMV.X.W |_rs1_ |_rd_ | | + +|FEQ.S |_rs1_, _rs2_ |_rd_ |NV | + +|FLT.S |_rs1_, _rs2_ |_rd_ |NV | + +|FLE.S |_rs1_, _rs2_ |_rd_ |NV | + +|FCLASS.S |_rs1_ |_rd_ | | + +|FCVT.S.W |_rs1_, frm^*^ |_rd_ |NX |^*^if rm=111 + +|FCVT.S.WU |_rs1_, frm^*^ |_rd_ |NX |^*^if rm=111 + +|FMV.W.X |_rs1_ |_rd_ | | + +|=== + +.RV64F Standard Extension +[%autowidth.stretch,float="center",align="center",cols="<,<,<,<,<",options="header"] +|=== +| |Source Registers |Destination Registers |Accumulating CSRs| + +|FCVT.L.S |_rs1_, frm^*^ |_rd_ |NV, NX |^*^if rm=111 + +|FCVT.LU.S |_rs1_, frm^*^ |_rd_ |NV, NX |^*^if rm=111 + +|FCVT.S.L |_rs1_, frm^*^ |_rd_ |NX |^*^if rm=111 + +|FCVT.S.LU |_rs1_, frm^*^ |_rd_ |NX |^*^if rm=111 + +|=== + +.RV32D Standard Extension +[%autowidth.stretch,float="center",align="center",cols="<,<,<,<,<",options="header"] +|=== + +| |Source Registers|Destination Registers |Accumulating CSRs | + + +|FLD† |_rs1_ ^A^ |_rd_ | | + +|FSD |_rs1_ ^A^, _rs2_^D^ | | | + +|FMADD.D |_rs1_, _rs2_, _rs3_, frm^*^ |_rd_ |NV, OF, UF, NX |^*^if rm=111 + +|FMSUB.D |_rs1_, _rs2_, _rs3_, frm^*^ |_rd_ |NV, OF, UF, NX |^*^if rm=111 + +|FNMSUB.D |_rs1_, _rs2_, _rs3_, frm^*^ |_rd_ |NV, OF, UF, NX |^*^if rm=111 + +|FNMADD.D |_rs1_, _rs2_, _rs3_, frm^*^ |_rd_ |NV, OF, UF, NX |^*^if rm=111 + +|FADD.D |_rs1_, _rs2_, frm^*^ |_rd_ |NV, OF, NX |^*^if rm=111 + +|FSUB.D |_rs1_, _rs2_, frm^*^ |_rd_ |NV, OF, NX |^*^if rm=111 + +|FMUL.D |_rs1_, _rs2_, frm^*^ |_rd_ |NV, OF, UF, NX |^*^if rm=111 + +|FDIV.D |_rs1_, _rs2_, frm^*^ |_rd_ |NV, DZ, OF, UF, NX |^*^if rm=111 + +|FSQRT.D |_rs1_, frm^*^ |_rd_ |NV, NX |^*^if rm=111 + +|FSGNJ.D |_rs1_, _rs2_ |_rd_ | | + +|FSGNJN.D |_rs1_, _rs2_ |_rd_ | | + +|FSGNJX.D |_rs1_, _rs2_ |_rd_ | | + +|FMIN.D |_rs1_, _rs2_ |_rd_ |NV | + +|FMAX.D |_rs1_, _rs2_ |_rd_ |NV | + +|FCVT.S.D |_rs1_, frm^*^ |_rd_ |NV, OF, UF, NX |^*^if rm=111 + +|FCVT.D.S |_rs1_ |_rd_ |NV | + +|FEQ.D |_rs1_, _rs2_ |_rd_ |NV | + +|FLT.D |_rs1_, _rs2_ |_rd_ |NV | + +|FLE.D |_rs1_, _rs2_ |_rd_ |NV | + +|FCLASS.D |_rs1_ |_rd_ | | + +|FCVT.W.D |_rs1_, frm^*^ |_rd_ |NV, NX |^*^if rm=111 + +|FCVT.WU.D |_rs1_, frm^*^ |_rd_ |NV, NX |^*^if rm=111 + +|FCVT.D.W |_rs1_ |_rd_ | | + +|FCVT.D.WU |_rs1_ |_rd_ | | + +|=== + +.RV64D Standard Extension +[%autowidth.stretch,float="center",align="center",cols="<,<,<,<,<",options="header"] +|=== + +| |Source Registers |Destination Registers |Accumulating CSRs | + +|FCVT.L.D |_rs1_, frm^*^ |_rd_ |NV, NX |^*^if rm=111 + +|FCVT.LU.D |_rs1_, frm^*^ |_rd_ |NV, NX |^*^if rm=111 + +|FMV.X.D |_rs1_ |_rd_ | | + +|FCVT.D.L |_rs1_, frm^*^ |_rd_ |NX |^*^if rm=111 + +|FCVT.D.LU |_rs1_, frm^*^ |_rd_ |NX |^*^if rm=111 + +|FMV.D.X |_rs1_ |_rd_ | | + +|=== diff --git a/param_extraction/chunks/chunk_042.txt.license b/param_extraction/chunks/chunk_042.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_042.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_043.txt b/param_extraction/chunks/chunk_043.txt new file mode 100644 index 0000000000..af452fd64a --- /dev/null +++ b/param_extraction/chunks/chunk_043.txt @@ -0,0 +1,3475 @@ +# Chunk: chunk_043 +# Source: scalar-crypto.adoc +# Lines: 1-3448 (of 5590) +# Content starts: line 1 +# Line count: 3448 +# Sections: 20 +# == Cryptography Extensions: Scalar & Entropy Source Instructions, Version 1.0.1 +# === Introduction +# ==== Intended Audience +# ==== Sail Specifications +# ==== Policies +# === Extensions Overview +# ==== `Zbkb` - Bitmanip instructions for Cryptography +# ==== `Zbkc` - Carry-less multiply instructions +# ==== `Zbkx` - Crossbar permutation instructions +# ==== `Zknd` - NIST Suite: AES Decryption +# ==== `Zkne` - NIST Suite: AES Encryption +# ==== `Zknh` - NIST Suite: Hash Function Instructions +# ==== `Zksed` - ShangMi Suite: SM4 Block Cipher Instructions +# ==== `Zksh` - ShangMi Suite: SM3 Hash Function Instructions +# ==== `Zkr` - Entropy Source Extension +# ==== `Zkn` - NIST Algorithm Suite +# ==== `Zks` - ShangMi Algorithm Suite +# ==== `Zk` - Standard scalar cryptography extension +# ==== `Zkt` - Data Independent Execution Latency +# === Instructions +# +[[crypto_scalar_instructions]] +== Cryptography Extensions: Scalar & Entropy Source Instructions, Version 1.0.1 + +[[crypto_scalar_introduction]] +=== Introduction + +This document describes the _scalar_ cryptography +extension for RISC-V. +All instructions described herein use the general-purpose `X` +registers, and obey the 2-read-1-write register access constraint. +These instructions are designed to be lightweight and suitable +for `32` and `64` bit base architectures; from embedded IoT class +cores to large, application class cores which do not implement a +vector unit. + +This document also describes the architectural interface to an +Entropy Source, which can be used to generate cryptographic secrets. +This is found in <>. + +It also contains a mechanism allowing core implementers to provide +_"Constant Time Execution"_ guarantees in <>. + +[[crypto_scalar_audience]] +==== Intended Audience + +Cryptography is a specialised subject, requiring people with many different +backgrounds to cooperate in its secure and efficient implementation. +Where possible, we have written this specification to be understandable by +all, though we recognise that the motivations and references to +algorithms or other specifications and standards may be unfamiliar to those +who are not domain experts. + +This specification anticipates being read and acted on by various people +with different backgrounds. +We have tried to capture these backgrounds +here, with a brief explanation of what we expect them to know, and how +it relates to the specification. +We hope this aids people's understanding of which aspects of the specification +are particularly relevant to them, and which they may (safely!) ignore or +pass to a colleague. + +Cryptographers and cryptographic software developers:: +These are the people we expect to write code using the instructions +in this specification. +They should understand fairly obviously the motivations for the +instructions we include, and be familiar with most of the algorithms +and outside standards to which we refer. +We expect the sections on constant time execution +(<>) +and the entropy source +(<>) +to be chiefly understood with their help. + +Computer architects:: +We do not expect architects to have a cryptography background. +We nonetheless expect architects to be able to examine our instructions +for implementation issues, understand how the instructions will be used +in context, and advise on how best to fit the functionality the +cryptographers want to the ISA interface. + +Digital design engineers & micro-architects:: +These are the people who will implement the specification inside a +core. Again, no cryptography expertise is assumed, but we expect them to +interpret the specification and anticipate any hardware implementation +issues, e.g., where high-frequency design considerations apply, or where +latency/area tradeoffs exist etc. +In particular, they should be aware of the literature around efficiently +implementing AES and SM4 SBoxes in hardware. + +Verification engineers:: +Responsible for ensuring the correct implementation of the extension +in hardware. +No cryptography background is assumed. +We expect them to identify interesting test cases from the +specification. An understanding of their real-world usage will help with this. +We do not expect verification engineers in this sense to be experts +in entropy source design or certification, since this is a very +specialised area. +We do expect them however to identify all of the _architectural_ +test cases around the entropy source interface. + +These are by no means the only people concerned with the specification, +but they are the ones we considered most while writing it. + +[[crypto_scalar_sail_specifications]] +==== Sail Specifications + +RISC-V maintains a +link:https://github.com/riscv/sail-riscv[formal model] +of the ISA specification, +implemented in the Sail ISA specification language +cite:[sail]. +Note that _Sail_ refers to the specification language itself, +and that there is a _model of RISC-V_, written using Sail. +It is not correct to refer to "the Sail model". +This is ambiguous, given there are many models of different ISAs implemented +using Sail. We refer to the Sail implementation of RISC-V as +"the RISC-V Sail model". + +The Cryptography extension uses inline Sail code snippets from the +actual model to give canonical descriptions of instruction +functionality. +Each instruction is accompanied by its expression in Sail, and includes +calls to supporting functions which are too verbose to include directly +in the specification. +This supporting code is listed in +<>. +The +link:https://alasdair.github.io/manual.html[Sail Manual] +is recommended reading in order to best understand the code snippets. + +Note that this document contains only a subset of the formal model: refer to +the formal model GitHub +link:https://github.com/riscv/sail-riscv[repository] +for the complete model. + +[[crypto_scalar_policies]] +==== Policies + +In creating this proposal, we tried to adhere to the following +policies: + +* Where there is a choice between: + . supporting diverse implementation strategies for an algorithm + or + . supporting a single implementation style which is more performant / + less expensive; + the crypto extension will pick the more constrained but performant + option. + This fits a common pattern in other parts of the RISC-V specification, + where recommended (but not required) instruction sequences for performing + particular tasks are given as an example, such that both hardware and + software implementers can optimise for only a single use-case. + +* The extension will be designed to support _existing_ standardised + cryptographic constructs well. + It will not try to support proposed standards, or cryptographic + constructs which exist only in academia. + Cryptographic standards which are settled upon concurrently with or after + the RISC-V cryptographic extension standardisation will be dealt with + by future additions to, or versions of, the RISC-V cryptographic + standard extension. It is anticipated that the NIST Lightweight + Cryptography contest and the NIST Post-Quantum Cryptography contest + may be dealt with this way, depending on timescales. + +* Historically, there has been some discussion + cite:[LSYRR:04] + on how newly supported operations in general-purpose computing might + enable new bases for cryptographic algorithms. + The standard will not try to anticipate new useful low-level + operations which _may_ be useful as building blocks for + future cryptographic constructs. + +* Regarding side-channel countermeasures: + Where relevant, proposed instructions must aim to remove the + possibility of any timing side-channels. + For side-channels based on power or electro-magnetic (EM) measurements, + the extension will not aim to support countermeasures which are + implemented above the ISA abstraction layer. + Recommendations will be given where relevant on how micro-architectures + can implement instructions in a power/EM side-channel resistant way. + +[[crypto_scalar_extensions]] +=== Extensions Overview + +The group of extensions introduced by the Scalar Cryptography Instruction Set +Extension is listed here. + +Detection of individual cryptography extensions uses the +unified software-based RISC-V discovery method. + +[NOTE] +==== +At the time of writing, these discovery mechanisms are still a work in +progress. +==== + +.A note on extension rationale +[NOTE, caption="SH"] +==== +Specialist encryption and decryption instructions are separated into different +functional groups because some use cases (e.g., Galois/Counter +Mode in TLS 1.3) do not require decryption functionality. + +The NIST and ShangMi algorithms suites are separated because their +usefulness is heavily dependent on the countries a device is expected to +operate in. NIST ciphers are a part of most standardised internet +protocols, while ShangMi ciphers are required for use in China. +==== + +[[zbkb-sc,Zbkb]] +==== `Zbkb` - Bitmanip instructions for Cryptography + +This extension contains bit-manipulation instructions that are particularly +useful for cryptography, most of which are also in the `Zbb` extension. +Please refer to <>. + +[[zbkc-sc,Zbkc]] +==== `Zbkc` - Carry-less multiply instructions + +Constant time carry-less multiply for Galois/Counter Mode. +These are separated from the <> because they +have a considerable implementation overhead which cannot be amortised +across other instructions. + +Please refer to <>. + +[[zbkx-sc,Zbkx]] +==== `Zbkx` - Crossbar permutation instructions + +These instructions are useful for implementing SBoxes in constant time, and +potentially with DPA protections. +These are separated from the <> because they +have an implementation overhead which cannot be amortised +across other instructions. + +Please refer to <>. + +[[zknd,Zknd]] +==== `Zknd` - NIST Suite: AES Decryption + +Instructions for accelerating the decryption and key-schedule functions of +the AES block cipher. + +[%header,cols="^1,^1,4,8"] +|=== +|RV32 +|RV64 +|Mnemonic +|Instruction + +| {check} | | aes32dsi | <> +| {check} | | aes32dsmi | <> +| | {check} | aes64ds | <> +| | {check} | aes64dsm | <> +| | {check} | aes64im | <> +| | {check} | aes64ks1i | <> +| | {check} | aes64ks2 | <> +|=== + +NOTE: The <> and <> instructions are +present in both the <> and <> extensions. + +[[zkne,Zkne]] +==== `Zkne` - NIST Suite: AES Encryption + +Instructions for accelerating the encryption and key-schedule functions of +the AES block cipher. + +[%header,cols="^1,^1,4,8"] +|=== +|RV32 +|RV64 +|Mnemonic +|Instruction + +| {check} | | aes32esi | <> +| {check} | | aes32esmi | <> +| | {check} | aes64es | <> +| | {check} | aes64esm | <> +| | {check} | aes64ks1i | <> +| | {check} | aes64ks2 | <> +|=== + +NOTE: The +<> +and +<> +instructions are present in both the <> and <> extensions. + +[[zknh,Zknh]] +==== `Zknh` - NIST Suite: Hash Function Instructions + +Instructions for accelerating the SHA2 family of cryptographic hash functions, +as specified in cite:[nist:fips:180:4]. + +[%header,cols="^1,^1,4,8"] +|=== +|RV32 +|RV64 +|Mnemonic +|Instruction + +| {check} | {check} | sha256sig0 | <> +| {check} | {check} | sha256sig1 | <> +| {check} | {check} | sha256sum0 | <> +| {check} | {check} | sha256sum1 | <> +| {check} | | sha512sig0h | <> +| {check} | | sha512sig0l | <> +| {check} | | sha512sig1h | <> +| {check} | | sha512sig1l | <> +| {check} | | sha512sum0r | <> +| {check} | | sha512sum1r | <> +| | {check} | sha512sig0 | <> +| | {check} | sha512sig1 | <> +| | {check} | sha512sum0 | <> +| | {check} | sha512sum1 | <> +|=== + +[[zksed,Zksed]] +==== `Zksed` - ShangMi Suite: SM4 Block Cipher Instructions + +Instructions for accelerating the SM4 Block Cipher. +Note that unlike AES, this cipher uses the same core operation for +encryption and decryption, hence there is only one +extension for it. + +[%header,cols="^1,^1,4,8"] +|=== +|RV32 +|RV64 +|Mnemonic +|Instruction + +| {check} | {check} | sm4ed | <> +| {check} | {check} | sm4ks | <> +|=== + +[[zksh,Zksh]] +==== `Zksh` - ShangMi Suite: SM3 Hash Function Instructions + +Instructions for accelerating the SM3 hash function. + +[%header,cols="^1,^1,4,8"] +|=== +|RV32 +|RV64 +|Mnemonic +|Instruction + +| {check} | {check} | sm3p0 | <> +| {check} | {check} | sm3p1 | <> +|=== + +[[zkr,Zkr]] +==== `Zkr` - Entropy Source Extension + +The entropy source extension defines the `seed` CSR at address `0x015`. +This CSR provides up to 16 physical `entropy` bits that can be used to +seed cryptographic random bit generators. + +See <> for the normative specification and access control +notes. <> contains design rationale and further +recommendations to implementers. + +[[zkn,Zkn]] +==== `Zkn` - NIST Algorithm Suite + +This extension is shorthand for the following set of other extensions: + +[%header,cols="^1,4"] +|=== +|Included Extension +|Description + +| <> | Bitmanipulation instructions for cryptography. +| <> | Carry-less multiply instructions. +| <> | Cross-bar Permutation instructions. +| <> | AES encryption instructions. +| <> | AES decryption instructions. +| <> | SHA2 hash function instructions. +|=== + +A core which implements `Zkn` must implement all of the above extensions. + +[[zks,Zks]] +==== `Zks` - ShangMi Algorithm Suite + +This extension is shorthand for the following set of other extensions: + +[%header,cols="^1,4"] +|=== +|Included Extension +|Description + +| <> | Bitmanipulation instructions for cryptography. +| <> | Carry-less multiply instructions. +| <> | Cross-bar Permutation instructions. +| <> | SM4 block cipher instructions. +| <> | SM3 hash function instructions. +|=== + +A core which implements `Zks` must implement all of the above extensions. + +[[zk,Zk]] +==== `Zk` - Standard scalar cryptography extension + +This extension is shorthand for the following set of other extensions: + +[%header,cols="^1,4"] +|=== +|Included Extension +|Description + +| <> | NIST Algorithm suite extension. +| <> | Entropy Source extension. +| <> | Data independent execution latency extension. +|=== + +A core which implements `Zk` must implement all of the above extensions. + +==== `Zkt` - Data Independent Execution Latency + +This extension allows CPU implementers to indicate to +cryptographic software developers that a subset of RISC-V instructions +are guaranteed to be implemented such that their execution latency +is independent of the data values they operate on. +A complete description of this extension is found in +<>. + +// ------------------------------------------------------------ + +[[crypto_scalar_insns, reftext="Scalar Cryptography Instructions"]] +=== Instructions + +[#insns-aes32dsi, reftext="AES final round decrypt (RV32)"] +==== aes32dsi + +Synopsis:: +AES final round decryption instruction for RV32. + +Mnemonic:: +aes32dsi rd, rs1, rs2, bs + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 0x33}, +{bits: 5, name: 'rd'}, +{bits: 3, name: 0x0}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 'rs2'}, +{bits: 5, name: 0x15}, +{bits: 2, name: 'bs'}, +]} +.... + +Description:: +This instruction sources a single byte from `rs2` according to `bs`. +To this it applies the inverse AES SBox operation, and XOR's the result with +`rs1`. +This instruction must _always_ be implemented such that its execution +latency does not depend on the data being operated on. + +Operation:: +[source,sail] +-- +function clause execute (AES32DSI (bs,rs2,rs1,rd)) = { + let shamt : bits( 5) = bs @ 0b000; /* shamt = bs*8 */ + let si : bits( 8) = (X(rs2)[31..0] >> shamt)[7..0]; /* SBox Input */ + let so : bits(32) = 0x000000 @ aes_sbox_inv(si); + let result : bits(32) = X(rs1)[31..0] ^ rol32(so, unsigned(shamt)); + X(rd) = EXTS(result); RETIRE_SUCCESS +} +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +| <> (RV32) +| v1.0.0 +| Ratified +| <> (RV32) +| v1.0.0 +| Ratified +| <> (RV32) +| v1.0.0 +| Ratified +|=== + +<<< + +[#insns-aes32dsmi, reftext="AES middle round decrypt (RV32)"] +==== aes32dsmi + +Synopsis:: +AES middle round decryption instruction for RV32. + +Mnemonic:: +aes32dsmi rd, rs1, rs2, bs + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 0x33}, +{bits: 5, name: 'rd'}, +{bits: 3, name: 0x0}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 'rs2'}, +{bits: 5, name: 0x17}, +{bits: 2, name: 'bs'}, +]} +.... + +Description:: +This instruction sources a single byte from `rs2` according to `bs`. +To this it applies the inverse AES SBox operation, and a partial inverse +MixColumn, before XOR'ing the result with `rs1`. +This instruction must _always_ be implemented such that its execution +latency does not depend on the data being operated on. + +Operation:: +[source,sail] +-- +function clause execute (AES32DSMI (bs,rs2,rs1,rd)) = { + let shamt : bits( 5) = bs @ 0b000; /* shamt = bs*8 */ + let si : bits( 8) = (X(rs2)[31..0] >> shamt)[7..0]; /* SBox Input */ + let so : bits( 8) = aes_sbox_inv(si); + let mixed : bits(32) = aes_mixcolumn_byte_inv(so); + let result : bits(32) = X(rs1)[31..0] ^ rol32(mixed, unsigned(shamt)); + X(rd) = EXTS(result); RETIRE_SUCCESS +} +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +| <> (RV32) +| v1.0.0 +| Ratified +| <> (RV32) +| v1.0.0 +| Ratified +| <> (RV32) +| v1.0.0 +| Ratified +|=== + +<<< + +[#insns-aes32esi, reftext="AES final round encrypt (RV32)"] +==== aes32esi + +Synopsis:: +AES final round encryption instruction for RV32. + +Mnemonic:: +aes32esi rd, rs1, rs2, bs + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 0x33}, +{bits: 5, name: 'rd'}, +{bits: 3, name: 0x0}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 'rs2'}, +{bits: 5, name: 0x11}, +{bits: 2, name: 'bs'}, +]} +.... + +Description:: +This instruction sources a single byte from `rs2` according to `bs`. +To this it applies the forward AES SBox operation, +before XOR'ing the result with `rs1`. +This instruction must _always_ be implemented such that its execution +latency does not depend on the data being operated on. + +Operation:: +[source,sail] +-- +function clause execute (AES32ESI (bs,rs2,rs1,rd)) = { + let shamt : bits( 5) = bs @ 0b000; /* shamt = bs*8 */ + let si : bits( 8) = (X(rs2)[31..0] >> shamt)[7..0]; /* SBox Input */ + let so : bits(32) = 0x000000 @ aes_sbox_fwd(si); + let result : bits(32) = X(rs1)[31..0] ^ rol32(so, unsigned(shamt)); + X(rd) = EXTS(result); RETIRE_SUCCESS +} +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +| <> (RV32) +| v1.0.0 +| Ratified +| <> (RV32) +| v1.0.0 +| Ratified +| <> (RV32) +| v1.0.0 +| Ratified +|=== + +<<< + +[#insns-aes32esmi, reftext="AES middle round encrypt (RV32)"] +==== aes32esmi + +Synopsis:: +AES middle round encryption instruction for RV32. + +Mnemonic:: +aes32esmi rd, rs1, rs2, bs + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 0x33}, +{bits: 5, name: 'rd'}, +{bits: 3, name: 0x0}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 'rs2'}, +{bits: 5, name: 0x13}, +{bits: 2, name: 'bs'}, +]} +.... + +Description:: +This instruction sources a single byte from `rs2` according to `bs`. +To this it applies the forward AES SBox operation, and a partial forward +MixColumn, before XOR'ing the result with `rs1`. +This instruction must _always_ be implemented such that its execution +latency does not depend on the data being operated on. + +Operation:: +[source,sail] +-- +function clause execute (AES32ESMI (bs,rs2,rs1,rd)) = { + let shamt : bits( 5) = bs @ 0b000; /* shamt = bs*8 */ + let si : bits( 8) = (X(rs2)[31..0] >> shamt)[7..0]; /* SBox Input */ + let so : bits( 8) = aes_sbox_fwd(si); + let mixed : bits(32) = aes_mixcolumn_byte_fwd(so); + let result : bits(32) = X(rs1)[31..0] ^ rol32(mixed, unsigned(shamt)); + X(rd) = EXTS(result); RETIRE_SUCCESS +} +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +| <> (RV32) +| v1.0.0 +| Ratified +| <> (RV32) +| v1.0.0 +| Ratified +| <> (RV32) +| v1.0.0 +| Ratified +|=== + +<<< + +[#insns-aes64ds, reftext="AES decrypt final round (RV64)"] +==== aes64ds + +Synopsis:: +AES final round decryption instruction for RV64. + +Mnemonic:: +aes64ds rd, rs1, rs2 + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 0x33}, +{bits: 5, name: 'rd'}, +{bits: 3, name: 0x0}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 'rs2'}, +{bits: 5, name: 0x1d}, +{bits: 2, name: 0x0}, +]} +.... + +Description:: +Uses the two 64-bit source registers to represent the entire AES state, +and produces _half_ of the next round output, applying the Inverse ShiftRows +and SubBytes steps. +This instruction must _always_ be implemented such that its execution +latency does not depend on the data being operated on. + +.Note To Software Developers +[NOTE,caption="SH"] +==== +The following code snippet shows the final round of the AES block decryption. +`t0` and `t1` hold the current round state. +`t2` and `t3` hold the next round state. + + aes64ds t2, t0, t1 + aes64ds t3, t1, t0 + +Note the reversed register order of the second instruction. +==== + +Operation:: +[source,sail] +-- +function clause execute (AES64DS(rs2, rs1, rd)) = { + let sr : bits(64) = aes_rv64_shiftrows_inv(X(rs2)[63..0], X(rs1)[63..0]); + let wd : bits(64) = sr[63..0]; + X(rd) = aes_apply_inv_sbox_to_each_byte(wd); + RETIRE_SUCCESS +} +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +| <> (RV64) +| v1.0.0 +| Ratified +| <> (RV64) +| v1.0.0 +| Ratified +| <> (RV64) +| v1.0.0 +| Ratified +|=== + +<<< + +[#insns-aes64dsm, reftext="AES decrypt middle round (RV64)"] +==== aes64dsm + +Synopsis:: +AES middle round decryption instruction for RV64. + +Mnemonic:: +aes64dsm rd, rs1, rs2 + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 0x33}, +{bits: 5, name: 'rd'}, +{bits: 3, name: 0x0}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 'rs2'}, +{bits: 5, name: 0x1f}, +{bits: 2, name: 0x0}, +]} +.... + +Description:: +Uses the two 64-bit source registers to represent the entire AES state, +and produces _half_ of the next round output, applying the Inverse ShiftRows, +SubBytes and MixColumns steps. +This instruction must _always_ be implemented such that its execution +latency does not depend on the data being operated on. + +.Note To Software Developers +[NOTE,caption="SH"] +==== +The following code snippet shows one middle round of the AES block decryption. +`t0` and `t1` hold the current round state. +`t2` and `t3` hold the next round state. + + aes64dsm t2, t0, t1 + aes64dsm t3, t1, t0 + +Note the reversed register order of the second instruction. +==== + +Operation:: +[source,sail] +-- +function clause execute (AES64DSM(rs2, rs1, rd)) = { + let sr : bits(64) = aes_rv64_shiftrows_inv(X(rs2)[63..0], X(rs1)[63..0]); + let wd : bits(64) = sr[63..0]; + let sb : bits(64) = aes_apply_inv_sbox_to_each_byte(wd); + X(rd) = aes_mixcolumn_inv(sb[63..32]) @ aes_mixcolumn_inv(sb[31..0]); + RETIRE_SUCCESS +} +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +| <> (RV64) +| v1.0.0 +| Ratified +| <> (RV64) +| v1.0.0 +| Ratified +| <> (RV64) +| v1.0.0 +| Ratified +|=== + +<<< + +[#insns-aes64es, reftext="AES encrypt final round instruction (RV64)"] +==== aes64es + +Synopsis:: +AES final round encryption instruction for RV64. + +Mnemonic:: +aes64es rd, rs1, rs2 + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 0x33}, +{bits: 5, name: 'rd'}, +{bits: 3, name: 0x0}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 'rs2'}, +{bits: 5, name: 0x19}, +{bits: 2, name: 0x0}, +]} +.... + +Description:: +Uses the two 64-bit source registers to represent the entire AES state, +and produces _half_ of the next round output, applying the ShiftRows and +SubBytes steps. +This instruction must _always_ be implemented such that its execution +latency does not depend on the data being operated on. + +.Note To Software Developers +[NOTE,caption="SH"] +==== +The following code snippet shows the final round of the AES block encryption. +`t0` and `t1` hold the current round state. +`t2` and `t3` hold the next round state. + + aes64es t2, t0, t1 + aes64es t3, t1, t0 + +Note the reversed register order of the second instruction. +==== + +Operation:: +[source,sail] +-- +function clause execute (AES64ES(rs2, rs1, rd)) = { + let sr : bits(64) = aes_rv64_shiftrows_fwd(X(rs2)[63..0], X(rs1)[63..0]); + let wd : bits(64) = sr[63..0]; + X(rd) = aes_apply_fwd_sbox_to_each_byte(wd); + RETIRE_SUCCESS +} +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +| <> (RV64) +| v1.0.0 +| Ratified +| <> (RV64) +| v1.0.0 +| Ratified +| <> (RV64) +| v1.0.0 +| Ratified +|=== + +<<< + +[#insns-aes64esm, reftext="AES encrypt middle round instruction (RV64)"] +==== aes64esm + +Synopsis:: +AES middle round encryption instruction for RV64. + +Mnemonic:: +aes64esm rd, rs1, rs2 + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 0x33}, +{bits: 5, name: 'rd'}, +{bits: 3, name: 0x0}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 'rs2'}, +{bits: 5, name: 0x1b}, +{bits: 2, name: 0x0}, +]} +.... + +Description:: +Uses the two 64-bit source registers to represent the entire AES state, +and produces _half_ of the next round output, applying the ShiftRows, +SubBytes and MixColumns steps. +This instruction must _always_ be implemented such that its execution +latency does not depend on the data being operated on. + +.Note To Software Developers +[NOTE,caption="SH"] +==== +The following code snippet shows one middle round of the AES block encryption. +`t0` and `t1` hold the current round state. +`t2` and `t3` hold the next round state. + + aes64esm t2, t0, t1 + aes64esm t3, t1, t0 + +Note the reversed register order of the second instruction. +==== + +Operation:: +[source,sail] +-- +function clause execute (AES64ESM(rs2, rs1, rd)) = { + let sr : bits(64) = aes_rv64_shiftrows_fwd(X(rs2)[63..0], X(rs1)[63..0]); + let wd : bits(64) = sr[63..0]; + let sb : bits(64) = aes_apply_fwd_sbox_to_each_byte(wd); + X(rd) = aes_mixcolumn_fwd(sb[63..32]) @ aes_mixcolumn_fwd(sb[31..0]); + RETIRE_SUCCESS +} +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +| <> (RV64) +| v1.0.0 +| Ratified +| <> (RV64) +| v1.0.0 +| Ratified +| <> (RV64) +| v1.0.0 +| Ratified +|=== + +<<< + +[#insns-aes64im, reftext="AES Decrypt KeySchedule MixColumns (RV64)"] +==== aes64im + +Synopsis:: +This instruction accelerates the inverse MixColumns step of the AES +Block Cipher, and is used to aid creation of the decryption KeySchedule. + +Mnemonic:: +aes64im rd, rs1 + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 0x13}, +{bits: 5, name: 'rd'}, +{bits: 3, name: 0x1}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 0x0}, +{bits: 5, name: 0x18}, +{bits: 2, name: 0x0}, +]} +.... + +Description:: +The instruction applies the inverse MixColumns +transformation to two columns of the state array, packed into a single +64-bit register. +It is used to create the inverse cipher KeySchedule, according to +the equivalent inverse cipher construction in +cite:[nist:fips:197] (Page 23, Section 5.3.5). +This instruction must _always_ be implemented such that its execution +latency does not depend on the data being operated on. + +Operation:: +[source,sail] +-- +function clause execute (AES64IM(rs1, rd)) = { + let w0 : bits(32) = aes_mixcolumn_inv(X(rs1)[31.. 0]); + let w1 : bits(32) = aes_mixcolumn_inv(X(rs1)[63..32]); + X(rd) = w1 @ w0; + RETIRE_SUCCESS +} +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +| <> (RV64) +| v1.0.0 +| Ratified +| <> (RV64) +| v1.0.0 +| Ratified +| <> (RV64) +| v1.0.0 +| Ratified +|=== + +<<< + +[#insns-aes64ks1i, reftext="AES Key Schedule Instruction 1 (RV64)"] +==== aes64ks1i + +Synopsis:: +This instruction implements part of the KeySchedule operation for the +AES Block cipher involving the SBox operation. + +Mnemonic:: +aes64ks1i rd, rs1, rnum + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 0x13}, +{bits: 5, name: 'rd'}, +{bits: 3, name: 0x1}, +{bits: 5, name: 'rs1'}, +{bits: 4, name: 'rnum'}, +{bits: 1, name: 0x1}, +{bits: 5, name: 0x18}, +{bits: 2, name: 0}, +]} +.... + +Description:: +This instruction implements the rotation, SubBytes and Round Constant +addition steps of the AES block cipher Key Schedule. +This instruction must _always_ be implemented such that its execution +latency does not depend on the data being operated on. +Note that `rnum` must be in the range `0x0..0xA`. +The values `0xB..0xF` are reserved. + +Operation:: +[source,sail] +-- +function clause execute (AES64KS1I(rnum, rs1, rd)) = { + if(unsigned(rnum) > 10) then { + handle_illegal(); RETIRE_SUCCESS + } else { + let tmp1 : bits(32) = X(rs1)[63..32]; + let rc : bits(32) = aes_decode_rcon(rnum); /* round number -> round constant */ + let tmp2 : bits(32) = if (rnum ==0xA) then tmp1 else ror32(tmp1, 8); + let tmp3 : bits(32) = aes_subword_fwd(tmp2); + let result : bits(64) = (tmp3 ^ rc) @ (tmp3 ^ rc); + X(rd) = EXTZ(result); + RETIRE_SUCCESS + } +} +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +| <> (RV64) +| v1.0.0 +| Ratified +| <> (RV64) +| v1.0.0 +| Ratified +| <> (RV64) +| v1.0.0 +| Ratified +| <> (RV64) +| v1.0.0 +| Ratified +|=== + +<<< + +[#insns-aes64ks2, reftext="AES Key Schedule Instruction 2 (RV64)"] +==== aes64ks2 + +Synopsis:: +This instruction implements part of the KeySchedule operation for the +AES Block cipher. + +Mnemonic:: +aes64ks2 rd, rs1, rs2 + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 0x33}, +{bits: 5, name: 'rd'}, +{bits: 3, name: 0x0}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 'rs2'}, +{bits: 5, name: 0x1f}, +{bits: 2, name: 0x1}, +]} +.... + +Description:: +This instruction implements the additional XOR'ing of key words as +part of the AES block cipher Key Schedule. +This instruction must _always_ be implemented such that its execution +latency does not depend on the data being operated on. + +Operation:: +[source,sail] +-- +function clause execute (AES64KS2(rs2, rs1, rd)) = { + let w0 : bits(32) = X(rs1)[63..32] ^ X(rs2)[31..0]; + let w1 : bits(32) = X(rs1)[63..32] ^ X(rs2)[31..0] ^ X(rs2)[63..32]; + X(rd) = w1 @ w0; + RETIRE_SUCCESS +} +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +| <> (RV64) +| v1.0.0 +| Ratified +| <> (RV64) +| v1.0.0 +| Ratified +| <> (RV64) +| v1.0.0 +| Ratified +| <> (RV64) +| v1.0.0 +| Ratified +|=== + +<<< + +[#insns-andn-sc,reftext="AND with inverted operand"] +==== andn + +Synopsis:: +AND with inverted operand + +Mnemonic:: +andn _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x33, attr: ['OP'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x7, attr: ['ANDN']}, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'rs2' }, + { bits: 7, name: 0x20, attr: ['ANDN'] }, +]} +.... + +Description:: +This instruction performs the bitwise logical AND operation between _rs1_ and the bitwise inversion of _rs2_. + +Operation:: +[source,sail] +-- +X(rd) = X(rs1) & ~X(rs2); +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbb (<<#zbb>>) +|1.0.0 +|Ratified + +|Zbkb (<<#zbkb-sc>>) +|v1.0.0-rc4 +|Ratified +|=== + +<<< + +[#insns-brev8-sc,reftext="Reverse bits in bytes"] +==== brev8 + +Synopsis:: +Reverse the bits in each byte of a source register. + +Mnemonic:: +brev8 _rd_, _rs_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x13, attr: ['OP-IMM'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x5 }, + { bits: 5, name: 'rs' }, + { bits: 12, name: 0x687 } +]} +.... + +Description:: +This instruction reverses the order of the bits in every byte of a register. + +Operation:: +[source,sail] +-- +result : xlenbits = EXTZ(0b0); +foreach (i from 0 to sizeof(xlen) by 8) { + result[i+7..i] = reverse_bits_in_byte(X(rs1)[i+7..i]); +}; +X(rd) = result; +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbkb (<<#zbkb-sc>>) +|v1.0.0-rc4 +|Ratified +|=== + +<<< + +[#insns-clmul-sc,reftext="Carry-less multiply (low-part)"] +==== clmul + +Synopsis:: +Carry-less multiply (low-part) + +Mnemonic:: +clmul _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x33, attr: ['OP'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x1, attr: ['CLMUL'] }, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'rs2' }, + { bits: 7, name: 0x5, attr: ['MINMAX/CLMUL'] }, +]} +.... + +Description:: +clmul produces the lower half of the 2·XLEN carry-less product. + +Operation:: +[source,sail] +-- +let rs1_val = X(rs1); +let rs2_val = X(rs2); +let output : xlenbits = 0; + +foreach (i from 0 to (xlen - 1) by 1) { + output = if ((rs2_val >> i) & 1) + then output ^ (rs1_val << i); + else output; +} + +X[rd] = output +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbc (<<#zbc>>) +|1.0.0 +|Ratified + +|Zbkc (<<#zbkc-sc>>) +|v1.0.0-rc4 +|Ratified +|=== + +<<< + +[#insns-clmulh-sc,reftext="Carry-less multiply (high-part)"] +==== clmulh + +Synopsis:: +Carry-less multiply (high-part) + +Mnemonic:: +clmulh _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x33, attr: ['OP'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x3, attr: ['CLMULH'] }, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'rs2' }, + { bits: 7, name: 0x5, attr: ['MINMAX/CLMUL'] }, +]} +.... + +Description:: +clmulh produces the upper half of the 2·XLEN carry-less product. + +Operation:: +[source,sail] +-- +let rs1_val = X(rs1); +let rs2_val = X(rs2); +let output : xlenbits = 0; + +foreach (i from 1 to xlen by 1) { + output = if ((rs2_val >> i) & 1) + then output ^ (rs1_val >> (xlen - i)); + else output; +} + +X[rd] = output +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbc (<<#zbc>>) +|1.0.0 +|Ratified + +|Zbkc (<<#zbkc-sc>>) +|v1.0.0-rc4 +|Ratified +|=== + +<<< + +[#insns-orn-sc,reftext="OR with inverted operand"] +==== orn + +Synopsis:: +OR with inverted operand + +Mnemonic:: +orn _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x33, attr: ['OP'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x6, attr: ['ORN']}, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'rs2' }, + { bits: 7, name: 0x20, attr: ['ORN'] }, +]} +.... + +Description:: +This instruction performs the bitwise logical OR operation between _rs1_ and the bitwise inversion of _rs2_. + +Operation:: +[source,sail] +-- +X(rd) = X(rs1) | ~X(rs2); +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbb (<<#zbb>>) +|v1.0.0 +|Ratified + +|Zbkb (<<#zbkb-sc>>) +|v1.0.0-rc4 +|Ratified +|=== + +<<< + +[#insns-pack-sc,reftext="Pack low halves of registers"] +==== pack + +Synopsis:: +Pack the low halves of _rs1_ and _rs2_ into _rd_. + +Mnemonic:: +pack _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + {bits: 7, name: 0x33, attr: ['OP'] }, + {bits: 5, name: 'rd'}, + {bits: 3, name: 0x4, attr:['PACK']}, + {bits: 5, name: 'rs1'}, + {bits: 5, name: 'rs2'}, + {bits: 7, name: 0x4, attr:['PACK']}, +]} +.... + +Description:: +The pack instruction packs the XLEN/2-bit lower halves of _rs1_ and _rs2_ into +_rd_, with _rs1_ in the lower half and _rs2_ in the upper half. + +Operation:: +[source,sail] +-- +let lo_half : bits(xlen/2) = X(rs1)[xlen/2-1..0]; +let hi_half : bits(xlen/2) = X(rs2)[xlen/2-1..0]; +X(rd) = EXTZ(hi_half @ lo_half); +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbkb (<<#zbkb-sc>>) +|v1.0.0-rc4 +|Ratified +|=== + +<<< + +[#insns-packh-sc,reftext="Pack low bytes of registers"] +==== packh + +Synopsis:: +Pack the low bytes of _rs1_ and _rs2_ into _rd_. + +Mnemonic:: +packh _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + {bits: 7, name: 0x33, attr: ['OP'] }, + {bits: 5, name: 'rd'}, + {bits: 3, name: 0x7, attr: ['PACKH']}, + {bits: 5, name: 'rs1'}, + {bits: 5, name: 'rs2'}, + {bits: 7, name: 0x4, attr: ['PACKH']}, +]} +.... + +Description:: +And the packh instruction packs the least-significant bytes of +_rs1_ and _rs2_ into the 16 least-significant bits of _rd_, +zero extending the rest of _rd_. + +Operation:: +[source,sail] +-- +let lo_half : bits(8) = X(rs1)[7..0]; +let hi_half : bits(8) = X(rs2)[7..0]; +X(rd) = EXTZ(hi_half @ lo_half); +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbkb (<<#zbkb-sc>>) +|v1.0.0-rc4 +|Ratified +|=== + +<<< + +[#insns-packw-sc,reftext="Pack low 16-bits of registers (RV64)"] +==== packw + +Synopsis:: +Pack the low 16-bits of _rs1_ and _rs2_ into _rd_ on RV64. + +Mnemonic:: +packw _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 2, name: 0x3}, +{bits: 5, name: 0xe}, +{bits: 5, name: 'rd'}, +{bits: 3, name: 0x4}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 'rs2'}, +{bits: 7, name: 0x4}, +]} +.... + +Description:: +This instruction packs the low 16 bits of +_rs1_ and _rs2_ into the 32 least-significant bits of _rd_, +sign extending the 32-bit result to the rest of _rd_. +This instruction only exists on RV64 based systems. + +Operation:: +[source,sail] +-- +let lo_half : bits(16) = X(rs1)[15..0]; +let hi_half : bits(16) = X(rs2)[15..0]; +X(rd) = EXTS(hi_half @ lo_half); +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbkb (<<#zbkb-sc>>) +|v1.0.0-rc4 +|Ratified +|=== + +<<< + +[#insns-rev8-sc,reftext="Byte-reverse register"] +==== rev8 + +Synopsis:: +Byte-reverse register + +Mnemonic:: +rev8 _rd_, _rs_ + +Encoding (RV32):: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x13, attr: ['OP-IMM'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x5 }, + { bits: 5, name: 'rs' }, + { bits: 12, name: 0x698 } +]} +.... + +Encoding (RV64):: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x13, attr: ['OP-IMM'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x5 }, + { bits: 5, name: 'rs' }, + { bits: 12, name: 0x6b8 } +]} +.... + +Description:: +This instruction reverses the order of the bytes in _rs_. + +Operation:: +[source,sail] +-- +let input = X(rs); +let output : xlenbits = 0; +let j = xlen - 1; + +foreach (i from 0 to (xlen - 8) by 8) { + output[i..(i + 7)] = input[(j - 7)..j]; + j = j - 8; +} + +X[rd] = output +-- + +.Note +[NOTE, caption="A" ] +=============================================================== +The *rev8* mnemonic corresponds to different instruction encodings in RV32 and RV64. +=============================================================== + +.Software Hint +[NOTE, caption="SH" ] +=============================================================== +The byte-reverse operation is only available for the full register +width. To emulate word-sized and halfword-sized byte-reversal, +perform a `rev8 rd,rs` followed by a `srai rd,rd,K`, where K is +XLEN-32 and XLEN-16, respectively. +=============================================================== + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbb (<<#zbb>>) +|v1.0.0 +|Ratified + +|Zbkb (<<#zbkb-sc>>) +|v1.0.0-rc4 +|Ratified +|=== + +<<< + +[#insns-rol-sc,reftext="Rotate left (Register)"] +==== rol + +Synopsis:: +Rotate Left (Register) + +Mnemonic:: +rol _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x33, attr: ['OP'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x1, attr: ['ROL']}, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'rs2' }, + { bits: 7, name: 0x30, attr: ['ROL'] }, +]} +.... + +Description:: +This instruction performs a rotate left of _rs1_ by the amount in least-significant log2(XLEN) bits of _rs2_. + +Operation:: +[source,sail] +-- +let shamt = if xlen == 32 + then X(rs2)[4..0] + else X(rs2)[5..0]; +let result = (X(rs1) << shamt) | (X(rs1) >> (xlen - shamt)); + +X(rd) = result; +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbb (<<#zbb>>) +|v1.0.0 +|Ratified + +|Zbkb (<<#zbkb-sc>>) +|v1.0.0-rc4 +|Ratified +|=== + +<<< + +[#insns-rolw-sc,reftext="Rotate Left Word (Register)"] +==== rolw + +Synopsis:: +Rotate Left Word (Register) + +Mnemonic:: +rolw _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x3b, attr: ['OP-32'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x1, attr: ['ROLW']}, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'rs2' }, + { bits: 7, name: 0x30, attr: ['ROLW'] }, +]} +.... + +Description:: +This instruction performs a rotate left on the least-significant word of _rs1_ by the amount in least-significant 5 bits of _rs2_. +The resulting word value is sign-extended by copying bit 31 to all of the more-significant bits. + +Operation:: +[source,sail] +-- +let rs1 = EXTZ(X(rs1)[31..0]) +let shamt = X(rs2)[4..0]; +let result = (rs1 << shamt) | (rs1 >> (32 - shamt)); +X(rd) = EXTS(result[31..0]); +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbb (<<#zbb>>) +|v1.0.0 +|Ratified + +|Zbkb (<<#zbkb-sc>>) +|v1.0.0-rc4 +|Ratified +|=== + +<<< + +[#insns-ror-sc, reftext="Rotate right (Register)"] +==== ror + +Synopsis:: +Rotate Right + +Mnemonic:: +ror _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x33, attr: ['OP'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x5, attr: ['ROR']}, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'rs2' }, + { bits: 7, name: 0x30, attr: ['ROR'] }, +]} +.... + +Description:: +This instruction performs a rotate right of _rs1_ by the amount in least-significant log2(XLEN) bits of _rs2_. + +Operation:: +[source,sail] +-- +let shamt = if xlen == 32 + then X(rs2)[4..0] + else X(rs2)[5..0]; +let result = (X(rs1) >> shamt) | (X(rs1) << (xlen - shamt)); + +X(rd) = result; +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbb (<<#zbb>>) +|v1.0.0 +|Ratified + +|Zbkb (<<#zbkb-sc>>) +|v1.0.0-rc4 +|Ratified +|=== + +<<< + +[#insns-rori-sc,reftext="Rotate right (Immediate)"] +==== rori + +Synopsis:: +Rotate Right (Immediate) + +Mnemonic:: +rori _rd_, _rs1_, _shamt_ + +Encoding (RV32):: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x13, attr: ['OP-IMM'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x5, attr: ['RORI']}, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'shamt' }, + { bits: 7, name: 0x30, attr: ['RORI'] }, +]} +.... + +Encoding (RV64):: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x13, attr: ['OP-IMM'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x5, attr: ['RORI']}, + { bits: 5, name: 'rs1' }, + { bits: 6, name: 'shamt' }, + { bits: 6, name: 0x18, attr: ['RORI'] }, +]} +.... + +Description:: +This instruction performs a rotate right of _rs1_ by the amount in the least-significant log2(XLEN) bits of _shamt_. +For RV32, the encodings corresponding to shamt[5]=1 are reserved. + +Operation:: +[source,sail] +-- +let shamt = if xlen == 32 + then shamt[4..0] + else shamt[5..0]; +let result = (X(rs1) >> shamt) | (X(rs1) << (xlen - shamt)); + +X(rd) = result; +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbb (<<#zbb>>) +|v1.0.0 +|Ratified + +|Zbkb (<<#zbkb-sc>>) +|v1.0.0-rc4 +|Ratified +|=== + +<<< + +[#insns-roriw-sc,reftext="Rotate right Word (Immediate)"] +==== roriw + +Synopsis:: +Rotate Right Word by Immediate + +Mnemonic:: +roriw _rd_, _rs1_, _shamt_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x1b, attr: ['OP-IMM-32'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x5, attr: ['RORIW']}, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'shamt' }, + { bits: 7, name: 0x30, attr: ['RORIW'] }, +]} +.... + +Description:: +This instruction performs a rotate right on the least-significant word +of _rs1_ by the amount in the least-significant log2(XLEN) bits of +_shamt_. +The resulting word value is sign-extended by copying bit 31 to all of +the more-significant bits. + + +Operation:: +[source,sail] +-- +let rs1_data = EXTZ(X(rs1)[31..0]; +let result = (rs1_data >> shamt) | (rs1_data << (32 - shamt)); +X(rd) = EXTS(result[31..0]); +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbb (<<#zbb>>) +|v1.0.0 +|Ratified + +|Zbkb (<<#zbkb-sc>>) +|v1.0.0-rc4 +|Ratified +|=== + +<<< + +[#insns-rorw-sc,reftext="Rotate right Word (Register)"] +==== rorw + +Synopsis:: +Rotate Right Word (Register) + +Mnemonic:: +rorw _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x3b, attr: ['OP-32'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x5, attr: ['RORW']}, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'rs2' }, + { bits: 7, name: 0x30, attr: ['RORW'] }, +]} +.... + +Description:: +This instruction performs a rotate right on the least-significant word of _rs1_ by the amount in least-significant 5 bits of _rs2_. +The resultant word is sign-extended by copying bit 31 to all of the more-significant bits. + +Operation:: +[source,sail] +-- +let rs1 = EXTZ(X(rs1)[31..0]) +let shamt = X(rs2)[4..0]; +let result = (rs1 >> shamt) | (rs1 << (32 - shamt)); +X(rd) = EXTS(result); +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbb (<<#zbb>>) +|v1.0.0 +|Ratified + +|Zbkb (<<#zbkb-sc>>) +|v1.0.0-rc4 +|Ratified +|=== + +<<< + +[#insns-sha256sig0, reftext="SHA2-256 Sigma0 instruction"] +==== sha256sig0 + +Synopsis:: +Implements the Sigma0 transformation function as used in +the SHA2-256 hash function cite:[nist:fips:180:4]. + +Mnemonic:: +sha256sig0 rd, rs1 + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 0x13}, +{bits: 5, name: 'rd'}, +{bits: 3, name: 0x1}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 0x2}, +{bits: 5, name: 0x8}, +{bits: 2, name: 0x0}, +]} +.... + +Description:: +This instruction is supported for both RV32 and RV64 base architectures. +For RV32, the entire `XLEN` source register is operated on. +For RV64, the low `32` bits of the source register are operated on, and the +result sign extended to `XLEN` bits. +Though named for SHA2-256, the instruction works for both the +SHA2-224 and SHA2-256 parameterizations as described in +cite:[nist:fips:180:4]. +This instruction must _always_ be implemented such that its execution +latency does not depend on the data being operated on. + +Operation:: +[source,sail] +-- +function clause execute (SHA256SIG0(rs1,rd)) = { + let inb : bits(32) = X(rs1)[31..0]; + let result : bits(32) = ror32(inb, 7) ^ ror32(inb, 18) ^ (inb >> 3); + X(rd) = EXTS(result); + RETIRE_SUCCESS +} +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +| <> +| v1.0.0 +| Ratified +| <> +| v1.0.0 +| Ratified +| <> +| v1.0.0 +| Ratified +|=== + +<<< + +[#insns-sha256sig1, reftext="SHA2-256 Sigma1 instruction"] +==== sha256sig1 + +Synopsis:: +Implements the Sigma1 transformation function as used in +the SHA2-256 hash function cite:[nist:fips:180:4]. + +Mnemonic:: +sha256sig1 rd, rs1 + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 0x13}, +{bits: 5, name: 'rd'}, +{bits: 3, name: 0x1}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 0x3}, +{bits: 5, name: 0x8}, +{bits: 2, name: 0x0}, +]} +.... + +Description:: +This instruction is supported for both RV32 and RV64 base architectures. +For RV32, the entire `XLEN` source register is operated on. +For RV64, the low `32` bits of the source register are operated on, and the +result sign extended to `XLEN` bits. +Though named for SHA2-256, the instruction works for both the +SHA2-224 and SHA2-256 parameterizations as described in +cite:[nist:fips:180:4]. +This instruction must _always_ be implemented such that its execution +latency does not depend on the data being operated on. + +Operation:: +[source,sail] +-- +function clause execute (SHA256SIG1(rs1,rd)) = { + let inb : bits(32) = X(rs1)[31..0]; + let result : bits(32) = ror32(inb, 17) ^ ror32(inb, 19) ^ (inb >> 10); + X(rd) = EXTS(result); + RETIRE_SUCCESS +} +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +| <> +| v1.0.0 +| Ratified +| <> +| v1.0.0 +| Ratified +| <> +| v1.0.0 +| Ratified +|=== + +<<< + +[#insns-sha256sum0, reftext="SHA2-256 Sum0 instruction"] +==== sha256sum0 + +Synopsis:: +Implements the Sum0 transformation function as used in +the SHA2-256 hash function cite:[nist:fips:180:4]. + +Mnemonic:: +sha256sum0 rd, rs1 + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 0x13}, +{bits: 5, name: 'rd'}, +{bits: 3, name: 0x1}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 0x0}, +{bits: 5, name: 0x8}, +{bits: 2, name: 0x0}, +]} +.... + +Description:: +This instruction is supported for both RV32 and RV64 base architectures. +For RV32, the entire `XLEN` source register is operated on. +For RV64, the low `32` bits of the source register are operated on, and the +result sign extended to `XLEN` bits. +Though named for SHA2-256, the instruction works for both the +SHA2-224 and SHA2-256 parameterizations as described in +cite:[nist:fips:180:4]. +This instruction must _always_ be implemented such that its execution +latency does not depend on the data being operated on. + +Operation:: +[source,sail] +-- +function clause execute (SHA256SUM0(rs1,rd)) = { + let inb : bits(32) = X(rs1)[31..0]; + let result : bits(32) = ror32(inb, 2) ^ ror32(inb, 13) ^ ror32(inb, 22); + X(rd) = EXTS(result); + RETIRE_SUCCESS +} +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +| <> +| v1.0.0 +| Ratified +| <> +| v1.0.0 +| Ratified +| <> +| v1.0.0 +| Ratified +|=== + +<<< + +[#insns-sha256sum1, reftext="SHA2-256 Sum1 instruction"] +==== sha256sum1 + +Synopsis:: +Implements the Sum1 transformation function as used in +the SHA2-256 hash function cite:[nist:fips:180:4]. + +Mnemonic:: +sha256sum1 rd, rs1 + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 0x13}, +{bits: 5, name: 'rd'}, +{bits: 3, name: 0x1}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 0x1}, +{bits: 5, name: 0x8}, +{bits: 2, name: 0x0}, +]} +.... + +Description:: +This instruction is supported for both RV32 and RV64 base architectures. +For RV32, the entire `XLEN` source register is operated on. +For RV64, the low `32` bits of the source register are operated on, and the +result sign extended to `XLEN` bits. +Though named for SHA2-256, the instruction works for both the +SHA2-224 and SHA2-256 parameterizations as described in +cite:[nist:fips:180:4]. +This instruction must _always_ be implemented such that its execution +latency does not depend on the data being operated on. + +Operation:: +[source,sail] +-- +function clause execute (SHA256SUM1(rs1,rd)) = { + let inb : bits(32) = X(rs1)[31..0]; + let result : bits(32) = ror32(inb, 6) ^ ror32(inb, 11) ^ ror32(inb, 25); + X(rd) = EXTS(result); + RETIRE_SUCCESS +} +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +| <> +| v1.0.0 +| Ratified +| <> +| v1.0.0 +| Ratified +| <> +| v1.0.0 +| Ratified +|=== + +<<< + +[#insns-sha512sig0h, reftext="SHA2-512 Sigma0 high (RV32)"] +==== sha512sig0h + +Synopsis:: +Implements the _high half_ of the Sigma0 transformation, as +used in the SHA2-512 hash function cite:[nist:fips:180:4]. + +Mnemonic:: +sha512sig0h rd, rs1, rs2 + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 0x33}, +{bits: 5, name: 'rd'}, +{bits: 3, name: 0x0}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 'rs2'}, +{bits: 5, name: 0xe}, +{bits: 2, name: 0x1}, +]} +.... + +Description:: +This instruction is implemented on RV32 only. +Used to compute the Sigma0 transform of the SHA2-512 hash function +in conjunction with the <> instruction. +The transform is a 64-bit to 64-bit function, so the input and output +are each represented by two 32-bit registers. +This instruction must _always_ be implemented such that its execution +latency does not depend on the data being operated on. + +[NOTE] +.Note to software developers +==== +The entire Sigma0 transform for SHA2-512 may be computed on RV32 +using the following instruction sequence: + + sha512sig0l t0, a0, a1 + sha512sig0h t1, a1, a0 + +==== + +Operation:: +[source,sail] +-- +function clause execute (SHA512SIG0H(rs2, rs1, rd)) = { + X(rd) = EXTS((X(rs1) >> 1) ^ (X(rs1) >> 7) ^ (X(rs1) >> 8) ^ + (X(rs2) << 31) ^ (X(rs2) << 24) ); + RETIRE_SUCCESS +} +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +| <> (RV32) +| v1.0.0 +| Ratified +| <> (RV32) +| v1.0.0 +| Ratified +| <> (RV32) +| v1.0.0 +| Ratified +|=== + +<<< + +[#insns-sha512sig0l, reftext="SHA2-512 Sigma0 low (RV32)"] +==== sha512sig0l + +Synopsis:: +Implements the _low half_ of the Sigma0 transformation, as +used in the SHA2-512 hash function cite:[nist:fips:180:4]. + +Mnemonic:: +sha512sig0l rd, rs1, rs2 + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 0x33}, +{bits: 5, name: 'rd'}, +{bits: 3, name: 0x0}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 'rs2'}, +{bits: 5, name: 0xa}, +{bits: 2, name: 0x1}, +]} +.... + +Description:: +This instruction is implemented on RV32 only. +Used to compute the Sigma0 transform of the SHA2-512 hash function +in conjunction with the <> instruction. +The transform is a 64-bit to 64-bit function, so the input and output +are each represented by two 32-bit registers. +This instruction must _always_ be implemented such that its execution +latency does not depend on the data being operated on. + +[NOTE] +.Note to software developers +==== +The entire Sigma0 transform for SHA2-512 may be computed on RV32 +using the following instruction sequence: + + sha512sig0l t0, a0, a1 + sha512sig0h t1, a1, a0 + +==== + +Operation:: +[source,sail] +-- +function clause execute (SHA512SIG0L(rs2, rs1, rd)) = { + X(rd) = EXTS((X(rs1) >> 1) ^ (X(rs1) >> 7) ^ (X(rs1) >> 8) ^ + (X(rs2) << 31) ^ (X(rs2) << 25) ^ (X(rs2) << 24) ); + RETIRE_SUCCESS +} +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +| <> (RV32) +| v1.0.0 +| Ratified +| <> (RV32) +| v1.0.0 +| Ratified +| <> (RV32) +| v1.0.0 +| Ratified +|=== + +<<< + +[#insns-sha512sig1h, reftext="SHA2-512 Sigma1 high (RV32)"] +==== sha512sig1h + +Synopsis:: +Implements the _high half_ of the Sigma1 transformation, as +used in the SHA2-512 hash function cite:[nist:fips:180:4]. + +Mnemonic:: +sha512sig1h rd, rs1, rs2 + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 0x33}, +{bits: 5, name: 'rd'}, +{bits: 3, name: 0x0}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 'rs2'}, +{bits: 5, name: 0xf}, +{bits: 2, name: 0x1}, +]} +.... + +Description:: +This instruction is implemented on RV32 only. +Used to compute the Sigma1 transform of the SHA2-512 hash function +in conjunction with the <> instruction. +The transform is a 64-bit to 64-bit function, so the input and output +are each represented by two 32-bit registers. +This instruction must _always_ be implemented such that its execution +latency does not depend on the data being operated on. + +[NOTE] +.Note to software developers +==== +The entire Sigma1 transform for SHA2-512 may be computed on RV32 +using the following instruction sequence: + + sha512sig1l t0, a0, a1 + sha512sig1h t1, a1, a0 + +==== + +Operation:: +[source,sail] +-- +function clause execute (SHA512SIG1H(rs2, rs1, rd)) = { + X(rd) = EXTS((X(rs1) << 3) ^ (X(rs1) >> 6) ^ (X(rs1) >> 19) ^ + (X(rs2) >> 29) ^ (X(rs2) << 13) ); + RETIRE_SUCCESS +} +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +| <> (RV32) +| v1.0.0 +| Ratified +| <> (RV32) +| v1.0.0 +| Ratified +| <> (RV32) +| v1.0.0 +| Ratified +|=== + +<<< + +[#insns-sha512sig1l, reftext="SHA2-512 Sigma1 low (RV32)"] +==== sha512sig1l + +Synopsis:: +Implements the _low half_ of the Sigma1 transformation, as +used in the SHA2-512 hash function cite:[nist:fips:180:4]. + +Mnemonic:: +sha512sig1l rd, rs1, rs2 + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 0x33}, +{bits: 5, name: 'rd'}, +{bits: 3, name: 0x0}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 'rs2'}, +{bits: 5, name: 0xb}, +{bits: 2, name: 0x1}, +]} +.... + +Description:: +This instruction is implemented on RV32 only. +Used to compute the Sigma1 transform of the SHA2-512 hash function +in conjunction with the <> instruction. +The transform is a 64-bit to 64-bit function, so the input and output +are each represented by two 32-bit registers. +This instruction must _always_ be implemented such that its execution +latency does not depend on the data being operated on. + +[NOTE] +.Note to software developers +==== +The entire Sigma1 transform for SHA2-512 may be computed on RV32 +using the following instruction sequence: + + sha512sig1l t0, a0, a1 + sha512sig1h t1, a1, a0 + +==== + +Operation:: +[source,sail] +-- +function clause execute (SHA512SIG1L(rs2, rs1, rd)) = { + X(rd) = EXTS((X(rs1) << 3) ^ (X(rs1) >> 6) ^ (X(rs1) >> 19) ^ + (X(rs2) >> 29) ^ (X(rs2) << 26) ^ (X(rs2) << 13) ); + RETIRE_SUCCESS +} +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +| <> (RV32) +| v1.0.0 +| Ratified +| <> (RV32) +| v1.0.0 +| Ratified +| <> (RV32) +| v1.0.0 +| Ratified +|=== + +<<< + +[#insns-sha512sum0r, reftext="SHA2-512 Sum0 (RV32)"] +==== sha512sum0r + +Synopsis:: +Implements the Sum0 transformation, as +used in the SHA2-512 hash function cite:[nist:fips:180:4]. + +Mnemonic:: +sha512sum0r rd, rs1, rs2 + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 0x33}, +{bits: 5, name: 'rd'}, +{bits: 3, name: 0x0}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 'rs2'}, +{bits: 5, name: 0x8}, +{bits: 2, name: 0x1}, +]} +.... + +Description:: +This instruction is implemented on RV32 only. +Used to compute the Sum0 transform of the SHA2-512 hash function. +The transform is a 64-bit to 64-bit function, so the input and output +is represented by two 32-bit registers. +This instruction must _always_ be implemented such that its execution +latency does not depend on the data being operated on. + +[NOTE] +.Note to software developers +==== +The entire Sum0 transform for SHA2-512 may be computed on RV32 +using the following instruction sequence: + + sha512sum0r t0, a0, a1 + sha512sum0r t1, a1, a0 + +Note the reversed source register ordering. +==== + +Operation:: +[source,sail] +-- +function clause execute (SHA512SUM0R(rs2, rs1, rd)) = { + X(rd) = EXTS((X(rs1) << 25) ^ (X(rs1) << 30) ^ (X(rs1) >> 28) ^ + (X(rs2) >> 7) ^ (X(rs2) >> 2) ^ (X(rs2) << 4) ); + RETIRE_SUCCESS +} +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +| <> (RV32) +| v1.0.0 +| Ratified +| <> (RV32) +| v1.0.0 +| Ratified +| <> (RV32) +| v1.0.0 +| Ratified +|=== + +<<< + +[#insns-sha512sum1r, reftext="SHA2-512 Sum1 (RV32)"] +==== sha512sum1r + +Synopsis:: +Implements the Sum1 transformation, as +used in the SHA2-512 hash function cite:[nist:fips:180:4]. + +Mnemonic:: +sha512sum1r rd, rs1, rs2 + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 0x33}, +{bits: 5, name: 'rd'}, +{bits: 3, name: 0x0}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 'rs2'}, +{bits: 5, name: 0x9}, +{bits: 2, name: 0x1}, +]} +.... + +Description:: +This instruction is implemented on RV32 only. +Used to compute the Sum1 transform of the SHA2-512 hash function. +The transform is a 64-bit to 64-bit function, so the input and output +is represented by two 32-bit registers. +This instruction must _always_ be implemented such that its execution +latency does not depend on the data being operated on. + +[NOTE] +.Note to software developers +==== +The entire Sum1 transform for SHA2-512 may be computed on RV32 +using the following instruction sequence: + + sha512sum1r t0, a0, a1 + sha512sum1r t1, a1, a0 + +Note the reversed source register ordering. +==== + +Operation:: +[source,sail] +-- +function clause execute (SHA512SUM1R(rs2, rs1, rd)) = { + X(rd) = EXTS((X(rs1) << 23) ^ (X(rs1) >> 14) ^ (X(rs1) >> 18) ^ + (X(rs2) >> 9) ^ (X(rs2) << 18) ^ (X(rs2) << 14) ); + RETIRE_SUCCESS +} +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +| <> (RV32) +| v1.0.0 +| Ratified +| <> (RV32) +| v1.0.0 +| Ratified +| <> (RV32) +| v1.0.0 +| Ratified +|=== + +<<< + +[#insns-sha512sig0, reftext="SHA2-512 Sigma0 instruction (RV64)"] +==== sha512sig0 + +Synopsis:: +Implements the Sigma0 transformation function as used in +the SHA2-512 hash function cite:[nist:fips:180:4]. + +Mnemonic:: +sha512sig0 rd, rs1 + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 0x13}, +{bits: 5, name: 'rd'}, +{bits: 3, name: 0x1}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 0x6}, +{bits: 5, name: 0x8}, +{bits: 2, name: 0x0}, +]} +.... + +Description:: +This instruction is supported for the RV64 base architecture. +It implements the Sigma0 transform of the SHA2-512 hash function. +cite:[nist:fips:180:4]. +This instruction must _always_ be implemented such that its execution +latency does not depend on the data being operated on. + +Operation:: +[source,sail] +-- +function clause execute (SHA512SIG0(rs1, rd)) = { + X(rd) = ror64(X(rs1), 1) ^ ror64(X(rs1), 8) ^ (X(rs1) >> 7); + RETIRE_SUCCESS +} +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +| <> (RV64) +| v1.0.0 +| Ratified +| <> (RV64) +| v1.0.0 +| Ratified +| <> (RV64) +| v1.0.0 +| Ratified +|=== + +<<< + +[#insns-sha512sig1, reftext="SHA2-512 Sigma1 instruction (RV64)"] +==== sha512sig1 + +Synopsis:: +Implements the Sigma1 transformation function as used in +the SHA2-512 hash function cite:[nist:fips:180:4]. + +Mnemonic:: +sha512sig1 rd, rs1 + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 0x13}, +{bits: 5, name: 'rd'}, +{bits: 3, name: 0x1}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 0x7}, +{bits: 5, name: 0x8}, +{bits: 2, name: 0x0}, +]} +.... + +Description:: +This instruction is supported for the RV64 base architecture. +It implements the Sigma1 transform of the SHA2-512 hash function. +cite:[nist:fips:180:4]. +This instruction must _always_ be implemented such that its execution +latency does not depend on the data being operated on. + +Operation:: +[source,sail] +-- +function clause execute (SHA512SIG1(rs1, rd)) = { + X(rd) = ror64(X(rs1), 19) ^ ror64(X(rs1), 61) ^ (X(rs1) >> 6); + RETIRE_SUCCESS +} +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +| <> (RV64) +| v1.0.0 +| Ratified +| <> (RV64) +| v1.0.0 +| Ratified +| <> (RV64) +| v1.0.0 +| Ratified +|=== + +<<< + +[#insns-sha512sum0, reftext="SHA2-512 Sum0 instruction (RV64)"] +==== sha512sum0 + +Synopsis:: +Implements the Sum0 transformation function as used in +the SHA2-512 hash function cite:[nist:fips:180:4]. + +Mnemonic:: +sha512sum0 rd, rs1 + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 0x13}, +{bits: 5, name: 'rd'}, +{bits: 3, name: 0x1}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 0x4}, +{bits: 5, name: 0x8}, +{bits: 2, name: 0x0}, +]} +.... + +Description:: +This instruction is supported for the RV64 base architecture. +It implements the Sum0 transform of the SHA2-512 hash function. +cite:[nist:fips:180:4]. +This instruction must _always_ be implemented such that its execution +latency does not depend on the data being operated on. + +Operation:: +[source,sail] +-- +function clause execute (SHA512SUM0(rs1, rd)) = { + X(rd) = ror64(X(rs1), 28) ^ ror64(X(rs1), 34) ^ ror64(X(rs1) ,39); + RETIRE_SUCCESS +} +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +| <> (RV64) +| v1.0.0 +| Ratified +| <> (RV64) +| v1.0.0 +| Ratified +| <> (RV64) +| v1.0.0 +| Ratified +|=== + +<<< + +[#insns-sha512sum1, reftext="SHA2-512 Sum1 instruction (RV64)"] +==== sha512sum1 + +Synopsis:: +Implements the Sum1 transformation function as used in +the SHA2-512 hash function cite:[nist:fips:180:4]. + +Mnemonic:: +sha512sum1 rd, rs1 + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 0x13}, +{bits: 5, name: 'rd'}, +{bits: 3, name: 0x1}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 0x5}, +{bits: 5, name: 0x8}, +{bits: 2, name: 0x0}, +]} +.... + +Description:: +This instruction is supported for the RV64 base architecture. +It implements the Sum1 transform of the SHA2-512 hash function. +cite:[nist:fips:180:4]. +This instruction must _always_ be implemented such that its execution +latency does not depend on the data being operated on. + +Operation:: +[source,sail] +-- +function clause execute (SHA512SUM1(rs1, rd)) = { + X(rd) = ror64(X(rs1), 14) ^ ror64(X(rs1), 18) ^ ror64(X(rs1) ,41); + RETIRE_SUCCESS +} +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +| <> (RV64) +| v1.0.0 +| Ratified +| <> (RV64) +| v1.0.0 +| Ratified +| <> (RV64) +| v1.0.0 +| Ratified +|=== + +<<< + +[#insns-sm3p0, reftext="SM3 P0 transform"] +==== sm3p0 + +Synopsis:: +Implements the _P0_ transformation function as used in +the SM3 hash function cite:[gbt:sm3,iso:sm3]. + +Mnemonic:: +sm3p0 rd, rs1 + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 0x13}, +{bits: 5, name: 'rd'}, +{bits: 3, name: 0x1}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 0x8}, +{bits: 5, name: 0x8}, +{bits: 2, name: 0x0}, +]} +.... + +Description:: +This instruction is supported for the RV32 and RV64 base architectures. +It implements the _P0_ transform of the SM3 hash function cite:[gbt:sm3,iso:sm3]. +This instruction must _always_ be implemented such that its execution +latency does not depend on the data being operated on. + +.Supporting Material +[NOTE] +==== +This instruction is based on work done in cite:[MJS:LWSHA:20]. +==== + +Operation:: +[source,sail] +-- +function clause execute (SM3P0(rs1, rd)) = { + let r1 : bits(32) = X(rs1)[31..0]; + let result : bits(32) = r1 ^ rol32(r1, 9) ^ rol32(r1, 17); + X(rd) = EXTS(result); + RETIRE_SUCCESS +} +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +| <> +| v1.0.0 +| Ratified +| <> +| v1.0.0 +| Ratified +|=== + +<<< + +[#insns-sm3p1, reftext="SM3 P1 transform"] +==== sm3p1 + +Synopsis:: +Implements the _P1_ transformation function as used in +the SM3 hash function cite:[gbt:sm3,iso:sm3]. + +Mnemonic:: +sm3p1 rd, rs1 + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 0x13}, +{bits: 5, name: 'rd'}, +{bits: 3, name: 0x1}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 0x9}, +{bits: 5, name: 0x8}, +{bits: 2, name: 0x0}, +]} +.... + +Description:: +This instruction is supported for the RV32 and RV64 base architectures. +It implements the _P1_ transform of the SM3 hash function cite:[gbt:sm3,iso:sm3]. +This instruction must _always_ be implemented such that its execution +latency does not depend on the data being operated on. + +.Supporting Material +[NOTE] +==== +This instruction is based on work done in cite:[MJS:LWSHA:20]. +==== + +Operation:: +[source,sail] +-- +function clause execute (SM3P1(rs1, rd)) = { + let r1 : bits(32) = X(rs1)[31..0]; + let result : bits(32) = r1 ^ rol32(r1, 15) ^ rol32(r1, 23); + X(rd) = EXTS(result); + RETIRE_SUCCESS +} +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +| <> +| v1.0.0 +| Ratified +| <> +| v1.0.0 +| Ratified +|=== + +<<< + +[#insns-sm4ed, reftext="SM4 Encrypt/Decrypt Instruction"] +==== sm4ed + +Synopsis:: +Accelerates the block encrypt/decrypt operation of the SM4 block cipher +cite:[gbt:sm4, iso:sm4]. + +Mnemonic:: +sm4ed rd, rs1, rs2, bs + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 0x33}, +{bits: 5, name: 'rd'}, +{bits: 3, name: 0x0}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 'rs2'}, +{bits: 5, name: 0x18}, +{bits: 2, name: 'bs'}, +]} +.... + +Description:: +Implements a T-tables in hardware style approach to accelerating the +SM4 round function. +A byte is extracted from `rs2` based on `bs`, to which the SBox and +linear layer transforms are applied, before the result is XOR'd with +`rs1` and written back to `rd`. +This instruction exists on RV32 and RV64 base architectures. +On RV64, the 32-bit result is sign extended to XLEN bits. +This instruction must _always_ be implemented such that its execution +latency does not depend on the data being operated on. + +Operation:: +[source,sail] +-- +function clause execute (SM4ED (bs,rs2,rs1,rd)) = { + let shamt : bits(5) = bs @ 0b000; /* shamt = bs*8 */ + let sb_in : bits(8) = (X(rs2)[31..0] >> shamt)[7..0]; + let x : bits(32) = 0x000000 @ sm4_sbox(sb_in); + let y : bits(32) = x ^ (x << 8) ^ ( x << 2) ^ + (x << 18) ^ ((x & 0x0000003F) << 26) ^ + ((x & 0x000000C0) << 10); + let z : bits(32) = rol32(y, unsigned(shamt)); + let result: bits(32) = z ^ X(rs1)[31..0]; + X(rd) = EXTS(result); + RETIRE_SUCCESS +} +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +| <> +| v1.0.0 +| Ratified +| <> +| v1.0.0 +| Ratified +|=== + +<<< + +[#insns-sm4ks, reftext="SM4 Key Schedule Instruction"] +==== sm4ks + +Synopsis:: +Accelerates the Key Schedule operation of the SM4 block cipher +cite:[gbt:sm4, iso:sm4]. + +Mnemonic:: +sm4ks rd, rs1, rs2, bs + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 0x33}, +{bits: 5, name: 'rd'}, +{bits: 3, name: 0x0}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 'rs2'}, +{bits: 5, name: 0x1a}, +{bits: 2, name: 'bs'}, +]} +.... + +Description:: +Implements a T-tables in hardware style approach to accelerating the +SM4 Key Schedule. +A byte is extracted from `rs2` based on `bs`, to which the SBox and +linear layer transforms are applied, before the result is XOR'd with +`rs1` and written back to `rd`. +This instruction exists on RV32 and RV64 base architectures. +On RV64, the 32-bit result is sign extended to XLEN bits. +This instruction must _always_ be implemented such that its execution +latency does not depend on the data being operated on. + +Operation:: +[source,sail] +-- +function clause execute (SM4KS (bs,rs2,rs1,rd)) = { + let shamt : bits(5) = (bs @ 0b000); /* shamt = bs*8 */ + let sb_in : bits(8) = (X(rs2)[31..0] >> shamt)[7..0]; + let x : bits(32) = 0x000000 @ sm4_sbox(sb_in); + let y : bits(32) = x ^ ((x & 0x00000007) << 29) ^ ((x & 0x000000FE) << 7) ^ + ((x & 0x00000001) << 23) ^ ((x & 0x000000F8) << 13) ; + let z : bits(32) = rol32(y, unsigned(shamt)); + let result: bits(32) = z ^ X(rs1)[31..0]; + X(rd) = EXTS(result); + RETIRE_SUCCESS +} +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +| <> +| v1.0.0 +| Ratified +| <> +| v1.0.0 +| Ratified +|=== + +<<< + +[#insns-unzip-sc,reftext="Bit deinterleave"] +==== unzip + +Synopsis:: +Place odd and even bits of the source register into upper and lower halves of +the destination register, respectively. + +Mnemonic:: +unzip _rd_, _rs_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 2, name: 0x3}, +{bits: 5, name: 0x4}, +{bits: 5, name: 'rd'}, +{bits: 3, name: 0x5}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 0xf}, +{bits: 7, name: 0x4}, +]} +.... + +Description:: +This instruction scatters all of the odd and even bits of a source word into +the high and low halves of a destination word. +It is the inverse of the <> instruction. +This instruction is available only on RV32. + +Operation:: +[source,sail] +-- +foreach (i from 0 to xlen/2-1) { + X(rd)[i] = X(rs1)[2*i] + X(rd)[i+xlen/2] = X(rs1)[2*i+1] +} +-- + +.Software Hint +[NOTE, caption="SH" ] +=============================================================== +This instruction is useful for implementing the SHA3 cryptographic +hash function on a 32-bit architecture, as it implements the +bit-interleaving operation used to speed up the 64-bit rotations +directly. +=============================================================== + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbkb (<<#zbkb-sc>>) (RV32) +|v1.0.0-rc4 +|Ratified +|=== + +<<< + +[#insns-xnor-sc,reftext="Exclusive NOR"] +==== xnor + +Synopsis:: +Exclusive NOR + +Mnemonic:: +xnor _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x33, attr: ['OP'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x4, attr: ['XNOR']}, + { bits: 5, name: 'rs1' }, + { bits: 5, name: 'rs2' }, + { bits: 7, name: 0x20, attr: ['XNOR'] }, +]} +.... + +Description:: +This instruction performs the bit-wise exclusive-NOR operation on _rs1_ and _rs2_. + +Operation:: +[source,sail] +-- +X(rd) = ~(X(rs1) ^ X(rs2)); +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbb (<<#zbb>>) +|v1.0.0 +|Ratified + +|Zbkb (<<#zbkb-sc>>) +|v1.0.0-rc4 +|Ratified +|=== + +<<< +[#insns-xperm8-sc,reftext="Crossbar permutation (bytes)"] +==== xperm8 + +Synopsis:: +Byte-wise lookup of indices into a vector in registers. + +Mnemonic:: +xperm8 _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 2, name: 0x3}, +{bits: 5, name: 0xc}, +{bits: 5, name: 'rd'}, +{bits: 3, name: 0x4}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 'rs2'}, +{bits: 7, name: 0x14}, +]} +.... + +Description:: +The xperm8 instruction operates on bytes. +The _rs1_ register contains a vector of XLEN/8 8-bit elements. +The _rs2_ register contains a vector of XLEN/8 8-bit indexes. +The result is each element in _rs2_ replaced by the indexed element in _rs1_, +or zero if the index into _rs2_ is out of bounds. + +Operation:: +[source,sail] +-- +val xperm8_lookup : (bits(8), xlenbits) -> bits(8) +function xperm8_lookup (idx, lut) = { + (lut >> (idx @ 0b000))[7..0] +} + +function clause execute ( XPERM8 (rs2,rs1,rd)) = { + result : xlenbits = EXTZ(0b0); + foreach(i from 0 to xlen by 8) { + result[i+7..i] = xperm8_lookup(X(rs2)[i+7..i], X(rs1)); + }; + X(rd) = result; + RETIRE_SUCCESS +} +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbkx (<<#zbkx>>) +|v1.0 +|Ratified +|=== + +<<< + +[#insns-xperm4-sc,reftext="Crossbar permutation (nibbles)"] +==== xperm4 + +Synopsis:: +Nibble-wise lookup of indices into a vector. + +Mnemonic:: +xperm4 _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 2, name: 0x3}, +{bits: 5, name: 0xc}, +{bits: 5, name: 'rd'}, +{bits: 3, name: 0x2}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 'rs2'}, +{bits: 7, name: 0x14}, +]} +.... + +Description:: +The xperm4 instruction operates on nibbles. +The _rs1_ register contains a vector of XLEN/4 4-bit elements. +The _rs2_ register contains a vector of XLEN/4 4-bit indexes. +The result is each element in _rs2_ replaced by the indexed element in _rs1_, +or zero if the index into _rs2_ is out of bounds. + +Operation:: +[source,sail] +-- +val xperm4_lookup : (bits(4), xlenbits) -> bits(4) +function xperm4_lookup (idx, lut) = { + (lut >> (idx @ 0b00))[3..0] +} + +function clause execute ( XPERM4 (rs2,rs1,rd)) = { + result : xlenbits = EXTZ(0b0); + foreach(i from 0 to xlen by 4) { + result[i+3..i] = xperm4_lookup(X(rs2)[i+3..i], X(rs1)); + }; + X(rd) = result; + RETIRE_SUCCESS +} +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbkx (<<#zbkx>>) +|v1.0 +|Ratified +|=== + +<<< + +[#insns-zip-sc,reftext="Bit interleave"] diff --git a/param_extraction/chunks/chunk_043.txt.license b/param_extraction/chunks/chunk_043.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_043.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_044.txt b/param_extraction/chunks/chunk_044.txt new file mode 100644 index 0000000000..e974370e0b --- /dev/null +++ b/param_extraction/chunks/chunk_044.txt @@ -0,0 +1,2200 @@ +# Chunk: chunk_044 +# Source: scalar-crypto.adoc +# Lines: 3419-5590 (of 5590) +# Content starts: line 3449 +# Line count: 2172 +# Overlap from line: 3419 +# Sections: 20 +# ==== zip +# === Entropy Source +# ==== The `seed` CSR +# ==== Entropy Source Requirements +# ===== NIST SP 800-90B / FIPS 140-3 Requirements +# ===== BSI AIS-31 PTG.2 / Common Criteria Requirements +# ===== Virtual Sources: Security Requirement +# ==== Access Control to `seed` +# === Data Independent Execution Latency Subset: Zkt +# ==== Scope and Goal +# ==== Background +# ==== Specific Instruction Rationale +# ==== Programming Information +# ==== Zkt listings +# ===== RVI (Base Instruction Set) +# ===== RVM (Multiply) +# ===== RVC (Compressed) +# ===== Zcb Extension +# ===== RVK (Scalar Cryptography) +# ===== RVB (Bitmanip) +# +val xperm4_lookup : (bits(4), xlenbits) -> bits(4) +function xperm4_lookup (idx, lut) = { + (lut >> (idx @ 0b00))[3..0] +} + +function clause execute ( XPERM4 (rs2,rs1,rd)) = { + result : xlenbits = EXTZ(0b0); + foreach(i from 0 to xlen by 4) { + result[i+3..i] = xperm4_lookup(X(rs2)[i+3..i], X(rs1)); + }; + X(rd) = result; + RETIRE_SUCCESS +} +-- + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbkx (<<#zbkx>>) +|v1.0 +|Ratified +|=== + +<<< + +[#insns-zip-sc,reftext="Bit interleave"] +==== zip + +Synopsis:: +Interleave upper and lower halves of the source register into odd and even +bits of the destination register, respectively. + +Mnemonic:: +zip _rd_, _rs_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 2, name: 0x3}, +{bits: 5, name: 0x4}, +{bits: 5, name: 'rd'}, +{bits: 3, name: 0x1}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 0xf}, +{bits: 7, name: 0x4}, +]} +.... + +Description:: +This instruction gathers bits from the high and low halves of the source +word into odd/even bit positions in the destination word. +It is the inverse of the <> instruction. +This instruction is available only on RV32. + +Operation:: +[source,sail] +-- +foreach (i from 0 to xlen/2-1) { + X(rd)[2*i] = X(rs1)[i] + X(rd)[2*i+1] = X(rs1)[i+xlen/2] +} +-- + +.Software Hint +[NOTE, caption="SH" ] +=============================================================== +This instruction is useful for implementing the SHA3 cryptographic +hash function on a 32-bit architecture, as it implements the +bit-interleaving operation used to speed up the 64-bit rotations +directly. +=============================================================== + +Included in:: +[%header,cols="4,2,2"] +|=== +|Extension +|Minimum version +|Lifecycle state + +|Zbkb (<<#zbkb-sc>>) (RV32) +|v1.0.0-rc4 +|Ratified +|=== + +<<< + +[[crypto_scalar_es]] +=== Entropy Source + +The `seed` CSR provides an interface to a NIST SP 800-90B cite:[TuBaKe:18] +or BSI AIS-31 cite:[KiSc11] compliant physical Entropy Source (ES). + +An entropy source, by itself, is not a cryptographically secure Random +Bit Generator (RBG), but can be used to build standard (and nonstandard) +RBGs of many types with the help of symmetric cryptography. Expected usage +is to condition (typically with SHA-2/3) the output from an entropy source and +use it to seed a cryptographically secure Deterministic Random Bit Generator +(DRBG) such as AES-based `CTR_DRBG` cite:[BaKe15]. +The combination of an Entropy Source, Conditioning, and a DRBG can be used +to create random bits securely cite:[BaKeRo:21]. +See <> for a non-normative description of a +certification and self-certification procedures, design rationale, and more +detailed suggestions on how the entropy source output can be used. + +[[crypto_scalar_seed_csr]] +==== The `seed` CSR + +`seed` is an unprivileged CSR located at address `0x015`. +The 32-bit contents of `seed` are as follows: + +[%autowidth.stretch,cols="^,^,<",options="header",] +|======================================================================= +|Bits |Name |Description + +|`31:30` |`OPST` |Status: `BIST` (00), `WAIT` (01), `ES16` (10), `DEAD` +(11). + +|`29:24` |_reserved_ |For future use by the RISC-V specification. + +|`23:16` |_custom_ |Designated for custom and experimental use. + +|`15: 0` |`entropy` |16 bits of randomness, only when `OPST=ES16`. +|======================================================================= + +Attempts to access the `seed` CSR using a read-only CSR-access instruction +(`CSRRS`/`CSRRC` with _rs1_=`x0` or `CSRRSI`/`CSRRCI` with _uimm_=0) raise an +illegal-instruction exception; any other CSR-access instruction may be used +to access `seed`. +The write value (in `rs1` or `uimm`) must be ignored by implementations. +The purpose of the write is to signal polling and flushing. + +Software normally uses the instruction `csrrw rd, seed, x0` to read the `seed` +CSR. + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 0x73, attr: "SYSTEM"}, +{bits: 5, name: 'rd'}, +{bits: 3, name: 0x1, attr: "CSRRW"}, +{bits: 5, name: 0x0, attr: "x0"}, +{bits: 12, name: 0x15, attr: "seed = 0x015"}, +]} +.... + +The `seed` CSR is also access controlled by execution mode, and attempted +read or write access will raise an illegal-instruction exception outside M mode +unless access is explicitly granted. See <> for +more details. + +The status bits `seed[31:30]` = `OPST` may be `ES16` (10), +indicating successful polling, or one of three entropy polling failure +statuses `BIST` (00), `WAIT` (01), or `DEAD` (11), discussed below. + +Each returned `seed[15:0]` = `entropy` value represents unique randomness +when `OPST`=`ES16` (`seed[31:30]` = `10`), even if its numerical value is +the same as that of a previously polled `entropy` value. The implementation +requirements of `entropy` bits are defined in <>. +When `OPST` is not `ES16`, `entropy` must be set to 0. +An implementation may safely set reserved and custom bits to zeros. + +For security reasons, the interface guarantees that secret `entropy` +words are not made available multiple times. Hence polling (reading) must +also have the side effect of clearing (wipe-on-read) the `entropy` contents and +changing the state to `WAIT` (unless there is `entropy` +immediately available for `ES16`). Other states (`BIST`, `WAIT`, and `DEAD`) +may be unaffected by polling. + +The Status Bits returned in `seed[31:30]`=`OPST`: + +* `00` - `BIST` +indicates that Built-In Self-Test "on-demand" (BIST) testing is being +performed. If `OPST` returns temporarily to `BIST` from any other +state, this signals a non-fatal self-test alarm, +which is non-actionable, apart from being logged. +Such a `BIST` alarm must be latched until polled at least once to enable +software to record its occurrence. + +* `01` - `WAIT` +means that a sufficient amount of entropy is not yet available. This +is not an error condition and may (in fact) be more frequent than ES16 +since physical entropy sources often have low bandwidth. + +* `10` - `ES16` +indicates success; the low bits `seed[15:0]` will have 16 bits of +randomness (`entropy`), which is guaranteed to meet certain minimum entropy +requirements, regardless of implementation. + +* `11` - `DEAD` +is an unrecoverable self-test error. This may indicate a hardware +fault, a security issue, or (extremely rarely) a type-1 statistical +false positive in the continuous testing procedures. In case of a fatal +failure, an immediate lockdown may also be an appropriate response in +dedicated security devices. + +**Example.** `0x8000ABCD` is a valid `ES16` status output, with `0xABCD` +being the `entropy` value. `0xFFFFFFFF` is an invalid output (`DEAD`) with +no `entropy` value. + +[[crypto_scalar_es_state,reftext="Entropy Source State Transition Diagram"]] +==== +image::es_state.svg[title="Entropy Source state transition diagram.", align="center",scaledwidth=40%] +Normally the operational state alternates between WAIT +(no data) and ES16, which means that 16 bits of randomness (`entropy`) +have been polled. BIST (Built-in Self-Test) only occurs after reset +or to signal a non-fatal self-test alarm (if reached after WAIT or +ES16). DEAD is an unrecoverable error state. +==== + +[[crypto_scalar_es_req]] +==== Entropy Source Requirements + +The output `entropy` (`seed[15:0]` in ES16 state) is not necessarily +fully conditioned randomness due to hardware and energy limitations +of smaller, low-powered implementations. However, minimum requirements are +defined. The main requirement is that 2-to-1 cryptographic post-processing +in 256-bit input blocks will yield 128-bit "full entropy" output blocks. +Entropy source users may make this conservative assumption but are not +prohibited from using more than twice the number of seed bits relative +to the desired resulting entropy. + +An implementation of the entropy source should meet at least one of the +following requirements sets in order to be considered a secure and +safe design: + +* <>: A physical entropy source meeting + NIST SP 800-90B cite:[TuBaKe:18] criteria with evaluated min-entropy + of 192 bits for each 256 output bits (min-entropy rate 0.75). + +* <>: A physical entropy source meeting the + AIS-31 PTG.2 cite:[KiSc11] criteria, implying average Shannon entropy + rate 0.997. The source must also meet the NIST 800-90B + min-entropy rate 192/256 = 0.75. + +* <>: A virtual entropy source is a DRBG + seeded from a physical entropy source. It must have at least a + 256-bit (Post-Quantum Category 5) internal security level. + +All implementations must signal initialization, test mode, and health +alarms as required by respective standards. This may require the implementer +to add non-standard (custom) test interfaces in a secure and safe manner, +an example of which is described in <> + + +[[crypto_scalar_es_req_90b]] +===== NIST SP 800-90B / FIPS 140-3 Requirements + +All NIST SP 800-90B cite:[TuBaKe:18] required components and health test +mechanisms must be implemented. + +The entropy requirement is satisfied if 128 bits of _full entropy_ can be +obtained from each 256-bit (16*16 -bit) successful, but possibly +non-consecutive `entropy` (ES16) output sequence using a vetted conditioning +algorithm such as a cryptographic hash (See Section 3.1.5.1.1, SP 800-90B +cite:[TuBaKe:18]). In practice, a min-entropy rate of 0.75 or larger is +required for this. + +Note that 128 bits of estimated input min-entropy does not yield 128 bits of +conditioned, full entropy in SP 800-90B/C evaluation. Instead, the +implication is that every 256-bit sequence should have min-entropy of at +least 128+64 = 192 bits, as discussed in SP 800-90C cite:[BaKeRo:21]; +the likelihood of successfully "guessing" an individual 256-bit output +sequence should not be higher than 2^-192^ even with (almost) +unconstrained amount of entropy source data and computational power. + +Rather than attempting to define all the mathematical and architectural +properties that the entropy source must satisfy, we define that the physical +entropy source be strong and robust enough to pass the equivalent of +NIST SP 800-90 evaluation and certification for full entropy when +conditioned cryptographically in ratio 2:1 with 128-bit output blocks. + +Even though the requirement is defined in terms of 128-bit full entropy +blocks, we recommend 256-bit security. This can be accomplished by using +at least 512 `entropy` bits to initialize a DRBG that has 256-bit security. + +[[crypto_scalar_es_req_ptg2]] +===== BSI AIS-31 PTG.2 / Common Criteria Requirements + +For alternative Common Criteria certification (or self-certification), +AIS 31 PTG.2 class cite:[KiSc11] (Sect. 4.3.) required hardware components +and mechanisms must be implemented. +In addition to AIS-31 PTG.2 randomness requirements (Shannon entropy rate of +0.997 as evaluated in that standard), the overall min-entropy requirement of +remains, as discussed in <>. Note that 800-90B +min-entropy can be significantly lower than AIS-31 Shannon entropy. These +two metrics should not be equated or confused with each other. + + +[[crypto_scalar_es_req_virt]] +===== Virtual Sources: Security Requirement + +NOTE: A virtual source is not an ISA compliance requirement. It is defined +for the benefit of the RISC-V security ecosystem so that virtual systems +may have a consistent level of security. + +A virtual source is not a physical entropy source but provides +additional protection against covert channels, depletion attacks, and host +identification in operating environments that can not be entirely trusted +with direct access to a hardware resource. Despite limited trust, +implementers should try to guarantee that even such environments have +sufficient entropy available for secure cryptographic operations. + +A virtual source traps access to the `seed` CSR, emulates it, or +otherwise implements it, possibly without direct access to a physical entropy +source. The output can be cryptographically secure pseudorandomness +instead of real entropy, but must have at least 256-bit security, as defined +below. A virtual source is intended especially for guest operating +systems, sandboxes, emulators, and similar use cases. + +As a technical definition, a random-distinguishing attack against +the output should require computational resources comparable or greater +than those required for exhaustive key search on a secure block cipher +with a 256-bit key (e.g., AES 256). This applies to both classical +and quantum computing models, but only classical information flows. +The virtual source security requirement maps to Post-Quantum Security +Category 5 cite:[NI16]. + +Any implementation of the `seed` CSR that limits the security +strength shall not reduce it to less than 256 bits. If the security +level is under 256 bits, then the interface must not be available. + +A virtual entropy source does not need to implement `WAIT` or `BIST` states. +It should fail (`DEAD`) if the host DRBG or entropy source fails and +there is insufficient seeding material for the host DRBG. + + +[[crypto_scalar_es_access]] +==== Access Control to `seed` + +The Zkr extension adds the `SSEED` and `USEED` fields to the `mseccfg` CSR to +control access to the `seed` CSR from U, S, or HS modes (see Privileged ISA +specification). + +Systems should implement carefully considered access control policies from +lower privilege modes to physical entropy sources. The system can trap +attempted access to `seed` and feed a less privileged client +_virtual entropy source_ data (<>) instead of +invoking an SP 800-90B (<>) or PTG.2 +(<>) _physical entropy source_. Emulated `seed` +data generation is made with an appropriately seeded, secure software DRBG. +See <> for security considerations related +to direct access to entropy sources. + +Implementations may implement `mseccfg` such that `[s,u]seed` is a read-only +constant value `0`. Software may discover if access to the `seed` CSR can be +enabled in U and S mode by writing a `1` to `[s,u]seed` and reading back +the result. + +[[crypto_scalar_zkt]] + +=== Data Independent Execution Latency Subset: Zkt + +The Zkt extension attests that the machine has data-independent execution +time for a safe subset of instructions. This property is commonly called +_"constant-time"_ although should not be taken with that literal meaning. + +All currently defined cryptographic instructions (Zk* and Zbk* extensions) are on +this list, together with a set of relevant supporting instructions from +I, M, C, and B extensions. + + +.Note to software developers +[NOTE,caption="SH"] +==== +Failure to prevent leakage of sensitive parameters via the direct +timing channel is considered a serious security vulnerability and will +typically result in a CERT CVE security advisory. +==== + +==== Scope and Goal + +An "ISA contract" is made between a programmer and the RISC-V implementation +that Zkt instructions do not leak information about processed secret data +(plaintext, keying information, or other "sensitive security parameters" -- +FIPS 140-3 term) through differences in execution latency. Zkt does _not_ +define a set of instructions available in the core; it just restricts the +behaviour of certain instructions if those are implemented. + +Currently, the scope of this document is within scalar RV32/RV64 processors. +Vector cryptography instructions (and appropriate vector support instructions) +will be added later, as will other security-related functions that wish +to assert leakage-free execution latency properties. + +Loads, stores, conditional branches are excluded, along with a set of +instructions that are rarely necessary to process secret data. Also excluded +are instructions for which workarounds exist in standard cryptographic +middleware due to the limitations of other ISA processors. + +The stated goal is that OpenSSL, BoringSSL (Android), the Linux Kernel, +and similar trusted software will not have directly observable +timing side channels when compiled and running on a Zkt-enabled RISC-V target. +The Zkt extension explicitly states many of the common latency assumptions +made by cryptography developers. + +Vendors do not have to implement all of the list's instructions to be Zkt +compliant; however, if they claim to have Zkt and implement any of the listed instructions, it must have data-independent latency. + +For example, many simple RV32I and RV64I cores (without Multiply, Compressed, +Bitmanip, or Cryptographic extensions) are technically compliant with Zkt. +A constant-time AES can be implemented on them using "bit-slice" techniques, +but it will be excruciatingly slow when compared to implementation with AES +instructions. There are no guarantees that even a bit-sliced cipher +implementation (largely based on boolean logic instructions) is secure on a +core without Zkt attestation. + +Out-of-order implementations adhering to Zkt are still free to fuse, crack, +change or even ignore sequences of instructions, so long as the optimisations +are applied deterministically, and not based on operand data. +The guiding principle should be that no information about the data being +operated on should be leaked based on the execution latency. + +[NOTE] +==== +It is left to future extensions or other techniques to tackle the problem +of data-independent execution in implementations which advanced out-of-order +capabilities which use value prediction, or which are otherwise data-dependent. +==== + +.Note to software developers +[WARNING,caption="SH"] +==== +Programming techniques can only mitigate leakage directly caused by +arithmetic, caches, and branches. Other ISAs have had micro-architectural +issues such as Spectre, Meltdown, Speculative Store Bypass, Rogue System +Register Read, Lazy FP State Restore, Bounds Check Bypass Store, TLBleed, +and L1TF/Foreshadow, etc. See e.g. +link:https://github.com/nsacyber/Hardware-and-Firmware-Security-Guidance[NSA Hardware and Firmware Security Guidance] + +It is not within the remit of this proposal to mitigate these +_micro-architectural_ leakages. +==== + +==== Background + +* Timing attacks are much more powerful than was realised before the 2010s, +which has led to a significant mitigation effort in current cryptographic +code-bases. +* Cryptography developers use static and dynamic security testing tools +to trace the handling of secret information and detect occasions where it +influences a branch or is used for a table lookup. +* Architectural testing for Zkt can be pragmatic and semi-formal; +_security by design_ against basic timing attacks can usually be achieved via +conscious implementation (of relevant iterative multi-cycle instructions or +instructions composed of micro-ops) in way that avoids data-dependent latency. +* Laboratory testing may utilize statistical timing attack leakage analysis +techniques such as those described in ISO/IEC 17825 cite:[IS16]. +* Binary executables should not contain secrets in the instruction encodings +(Kerckhoffs's principle), so instruction timing may leak information about +immediates, ordering of input registers, etc. There may be an exception to this +in systems where a binary loader modifies the executable for purposes of +relocation -- and it is desirable to keep the execution location (PC) secret. +This is why instructions such as LUI, AUIPC, and ADDI are on the list. +* The rules used by audit tools are relatively simple to understand. +Very briefly; we call the plaintext, secret keys, expanded keys, nonces, +and other such variables "secrets". A secret variable (arithmetically) +modifying any other variable/register turns that into a secret too. +If a secret ends up in address calculation affecting a load or store, that +is a violation. If a secret affects a branch's condition, that is also a +violation. A secret variable location or register becomes a non-secret via +specific zeroization/sanitisation or by being declared ciphertext +(or otherwise no-longer-secret information). In essence, secrets can only +"touch" instructions on the Zkt list while they are secrets. + +==== Specific Instruction Rationale + +* HINT instruction forms (typically encodings with _rd_=`x0`) are excluded from +the data-independent time requirement. +* Floating point (F, D, Q, L extensions) are currently excluded from the +constant-time requirement as they have very few applications in standardised +cryptography. We may consider adding floating point add, sub, multiply as a +constant time requirement for some floating point extension in case a specific +algorithm (such as the PQC Signature algorithm Falcon) becomes critical. +* Cryptographers typically assume division to be variable-time (while +multiplication is constant time) and implement their Montgomery reduction +routines with that assumption. +* Zicsr, Zifencei are excluded. +* Some instructions are on the list simply because we see no harm in +including them in testing scope. + + +==== Programming Information + +For background information on secure programming "models", see: + +* Thomas Pornin: _"Why Constant-Time Crypto?"_ (A great introduction to timing assumptions.) https://www.bearssl.org/constanttime.html +* Jean-Philippe Aumasson: _"Guidelines for low-level cryptography software."_ +(A list of recommendations.) https://github.com/veorq/cryptocoding +* Peter Schwabe: _"Timing Attacks and Countermeasures."_ +(Lecture slides -- nice references.) +https://summerschool-croatia.cs.ru.nl/2016/slides/PeterSchwabe.pdf +* Adam Langley: _"ctgrind."_ (This is from 2010 but is still relevant.) +https://www.imperialviolet.org/2010/04/01/ctgrind.html +* Kris Kwiatkowski: _"Constant-time code verification with Memory Sanitizer."_ +https://www.amongbytes.com/post/20210709-testing-constant-time/ +* For early examples of timing attack vulnerabilities, see +https://www.kb.cert.org/vuls/id/997481 and related academic papers. + + +==== Zkt listings + +The following instructions are included in the `Zkt` subset +They are listed here grouped by their original parent extension. + +.Note to implementers +[NOTE, caption="SH"] +==== +You do not need to implement all of these instructions to implement `Zkt`. +Rather, every one of these instructions that the core does implement must +adhere to the requirements of `Zkt`. +==== + +===== RVI (Base Instruction Set) + +Only basic arithmetic and `slt*` (for carry computations) are included. +The data-independent timing requirement does not apply to HINT instruction +encoding forms of these instructions. + +[%header,cols="^1,^1,4"] +|=== +|RV32 +|RV64 +|Mnemonic + +| {check} | {check} | lui _rd_, _imm_ +| {check} | {check} | auipc _rd_, _imm_ +| {check} | {check} | addi _rd_, _rs1_, _imm_ +| {check} | {check} | slti _rd_, _rs1_, _imm_ +| {check} | {check} | sltiu _rd_, _rs1_, _imm_ +| {check} | {check} | xori _rd_, _rs1_, _imm_ +| {check} | {check} | ori _rd_, _rs1_, _imm_ +| {check} | {check} | andi _rd_, _rs1_, _imm_ +| {check} | {check} | slli _rd_, _rs1_, _imm_ +| {check} | {check} | srli _rd_, _rs1_, _imm_ +| {check} | {check} | srai _rd_, _rs1_, _imm_ +| {check} | {check} | add _rd_, _rs1_, _rs2_ +| {check} | {check} | sub _rd_, _rs1_, _rs2_ +| {check} | {check} | sll _rd_, _rs1_, _rs2_ +| {check} | {check} | slt _rd_, _rs1_, _rs2_ +| {check} | {check} | sltu _rd_, _rs1_, _rs2_ +| {check} | {check} | xor _rd_, _rs1_, _rs2_ +| {check} | {check} | srl _rd_, _rs1_, _rs2_ +| {check} | {check} | sra _rd_, _rs1_, _rs2_ +| {check} | {check} | or _rd_, _rs1_, _rs2_ +| {check} | {check} | and _rd_, _rs1_, _rs2_ +| | {check} | addiw _rd_, _rs1_, _imm_ +| | {check} | slliw _rd_, _rs1_, _imm_ +| | {check} | srliw _rd_, _rs1_, _imm_ +| | {check} | sraiw _rd_, _rs1_, _imm_ +| | {check} | addw _rd_, _rs1_, _rs2_ +| | {check} | subw _rd_, _rs1_, _rs2_ +| | {check} | sllw _rd_, _rs1_, _rs2_ +| | {check} | srlw _rd_, _rs1_, _rs2_ +| | {check} | sraw _rd_, _rs1_, _rs2_ +|=== + +===== RVM (Multiply) + +Multiplication is included; division and remaindering excluded. + +[%header,cols="^1,^1,4"] +|=== +|RV32 +|RV64 +|Mnemonic + +| {check} | {check} | mul _rd_, _rs1_, _rs2_ +| {check} | {check} | mulh _rd_, _rs1_, _rs2_ +| {check} | {check} | mulhsu _rd_, _rs1_, _rs2_ +| {check} | {check} | mulhu _rd_, _rs1_, _rs2_ +| | {check} | mulw _rd_, _rs1_, _rs2_ +|=== + +===== RVC (Compressed) + +Same criteria as in RVI. Organised by quadrants. + +[%header,cols="^1,^1,4"] +|=== +|RV32 +|RV64 +|Mnemonic + +| {check} | {check} | c.nop +| {check} | {check} | c.addi +| | {check} | c.addiw +| {check} | {check} | c.lui +| {check} | {check} | c.srli +| {check} | {check} | c.srai +| {check} | {check} | c.andi +| {check} | {check} | c.sub +| {check} | {check} | c.xor +| {check} | {check} | c.or +| {check} | {check} | c.and +| | {check} | c.subw +| | {check} | c.addw +| {check} | {check} | c.slli +| {check} | {check} | c.mv +| {check} | {check} | c.add +|=== + +===== Zcb Extension + +These instructions are compressed versions of I and M instructions that are +included in Zkt. + +[%header,cols="^1,^1,4,8"] +|=== +|RV32 +|RV64 +|Mnemonic +|Instruction + +| {check} | {check} | c.mul | <> +| {check} | {check} | c.not | <> +| {check} | {check} | c.zext.b | <> +|=== + +===== RVK (Scalar Cryptography) + +All K-specific instructions are included. +Additionally, `seed` CSR latency should be independent of `ES16` state output +`entropy` bits, as that is a sensitive security parameter. +See <>. + +[%header,cols="^1,^1,4,8"] +|=== +|RV32 +|RV64 +|Mnemonic +|Instruction + +| {check} | | aes32dsi | <> +| {check} | | aes32dsmi | <> +| {check} | | aes32esi | <> +| {check} | | aes32esmi | <> +| | {check} | aes64ds | <> +| | {check} | aes64dsm | <> +| | {check} | aes64es | <> +| | {check} | aes64esm | <> +| | {check} | aes64im | <> +| | {check} | aes64ks1i | <> +| | {check} | aes64ks2 | <> +| {check} | {check} | sha256sig0 | <> +| {check} | {check} | sha256sig1 | <> +| {check} | {check} | sha256sum0 | <> +| {check} | {check} | sha256sum1 | <> +| {check} | | sha512sig0h | <> +| {check} | | sha512sig0l | <> +| {check} | | sha512sig1h | <> +| {check} | | sha512sig1l | <> +| {check} | | sha512sum0r | <> +| {check} | | sha512sum1r | <> +| | {check} | sha512sig0 | <> +| | {check} | sha512sig1 | <> +| | {check} | sha512sum0 | <> +| | {check} | sha512sum1 | <> +| {check} | {check} | sm3p0 | <> +| {check} | {check} | sm3p1 | <> +| {check} | {check} | sm4ed | <> +| {check} | {check} | sm4ks | <> +|=== + + +===== RVB (Bitmanip) + +The <>, <> and <> extensions are included in their entirety. + +[%header,cols="^1,^1,4,8"] +|=== +|RV32 +|RV64 +|Mnemonic +|Instruction + +| {check} | {check} | clmul | <> +| {check} | {check} | clmulh | <> +| {check} | {check} | xperm4 | <> +| {check} | {check} | xperm8 | <> +| {check} | {check} | ror | <> +| {check} | {check} | rol | <> +| {check} | {check} | rori | <> +| | {check} | rorw | <> +| | {check} | rolw | <> +| | {check} | roriw | <> +| {check} | {check} | andn | <> +| {check} | {check} | orn | <> +| {check} | {check} | xnor | <> +| {check} | {check} | pack | <> +| {check} | {check} | packh | <> +| | {check} | packw | <> +| {check} | {check} | brev8 | <> +| {check} | {check} | rev8 | <> +| {check} | | zip | <> +| {check} | | unzip | <> +|=== + +[[crypto_scalar_appx_rationale]] +=== Instruction Rationale + +This section contains various rationale, design notes and usage +recommendations for the instructions in the scalar cryptography +extension. It also tries to record how the designs of instructions were +derived, or where they were contributed from. + +==== AES Instructions + +The 32-bit instructions were derived from work in cite:[MJS:LWAES:20] and +contributed to the RISC-V cryptography extension. +The 64-bit instructions were developed collaboratively by task group +members on our mailing list. + +Supporting material, including rationale and a design space exploration +for all of the AES instructions in the specification can be found in the paper +_"link:https://doi.org/10.46586/tches.v2021.i1.109-136[The design of scalar AES Instruction Set Extensions for RISC-V]"_ cite:[MNPSW:20]. + + +==== SHA2 Instructions + +These instructions were developed based on academic +work at the University of Bristol as part of the XCrypto project +cite:[MPP:19], and contributed to the RISC-V cryptography extension. + +The RV32 SHA2-512 instructions were based on this work, and developed +in cite:[MJS:LWSHA:20], before being contributed in the same way. + +==== SM3 and SM4 Instructions + +The SM4 instructions were derived from work in cite:[MJS:LWAES:20], and +are hence very similar to the RV32 AES instructions. + +The SM3 instructions were inspired by the SHA2 instructions, and +based on development work done in cite:[MJS:LWSHA:20], before being +contributed to the RISC-V cryptography extension. + +[[crypto_scalar_zkb]] +==== Bitmanip Instructions for Cryptography + +Many of the primitive operations used in symmetric key cryptography +and cryptographic hash functions are well supported by the +RISC-V Bitmanip extensions (see <>). + +NOTE: This section repeats much of the information in +<>, +<> +and +<>, +but includes more rationale. + +We proposed that the scalar cryptographic extension _reuse_ a +subset of the instructions from the Bitmanip extensions `Zb[abc]` directly. +Specifically, this would mean that +a core implementing +_either_ +the scalar cryptographic extensions, +_or_ +the `Zb[abc]`, +_or_ +both, +would be required to implement these instructions. + +===== Rotations + +---- +RV32, RV64: RV64 only: + ror rd, rs1, rs2 rorw rd, rs1, rs2 + rol rd, rs1, rs2 rolw rd, rs1, rs2 + rori rd, rs1, imm roriw rd, rs1, imm +---- + +See <> for details of these instructions. + +.Notes to software developers +[NOTE,caption="SH"] +==== +Standard bitwise rotation is a primitive operation in many block ciphers +and hash functions; it features particularly in the ARX (Add, Rotate, Xor) +class of block ciphers and stream ciphers. + +* Algorithms making use of 32-bit rotations: + SHA256, AES (Shift Rows), ChaCha20, SM3. +* Algorithms making use of 64-bit rotations: + SHA512, SHA3. +==== + +===== Bit & Byte Permutations + +---- +RV32, RV64: + brev8 rd, rs1 + rev8 rd, rs1 +---- + +See <> for details of these instructions. + +.Notes to software developers +[NOTE,caption="SH"] +==== +Reversing bytes in words is very common in cryptography when setting a +standard endianness for input and output data. +Bit reversal within bytes is used for implementing the GHASH component +of Galois/Counter Mode (GCM) cite:[nist:gcm]. +==== + +---- +RV32: + zip rd, rs1 + unzip rd, rs1 +---- + +See <> for details of these instructions. + +.Notes to software developers +[NOTE,caption="SH"] +==== +These instructions perform a bit-interleave (or de-interleave) operation, and +are useful for implementing the 64-bit rotations in the +SHA3 cite:[nist:fips:202] algorithm on +a 32-bit architecture. +On RV64, the relevant operations in SHA3 can be done natively using +rotation instructions, so `zip` and `unzip` are not required. +==== + +===== Carry-less Multiply + +---- +RV32, RV64: + clmul rd, rs1, rs2 + clmulh rd, rs1, rs2 +---- + +See <> for details of these instructions. +See <> for additional implementation +requirements for these instructions, related to data independent +execution latency. + +.Notes to software developers +[NOTE,caption="SH"] +==== +As is mentioned there, obvious cryptographic use-cases for carry-less +multiply are for Galois Counter Mode (GCM) block cipher operations. +GCM is recommended by NIST as a block cipher mode of operation +cite:[nist:gcm], and is the only _required_ mode for the TLS 1.3 +protocol. +==== + +===== Logic With Negate + +---- +RV32, RV64: + andn rd, rs1, rs2 + orn rd, rs1, rs2 + xnor rd, rs1, rs2 +---- + +See <> for details of these instructions. +These instructions are useful inside hash functions, block ciphers and +for implementing software based side-channel countermeasures like masking. +The `andn` instruction is also useful for constant time word-select +in systems without the ternary Bitmanip `cmov` instruction. + +.Notes to software developers +[NOTE,caption="SH"] +==== +In the context of Cryptography, these instructions are useful for: +SHA3/Keccak Chi step, +Bit-sliced function implementations, +Software based power/EM side-channel countermeasures based on masking. +==== + +===== Packing + +---- +RV32, RV64: RV64: + pack rd, rs1, rs2 packw rd, rs1, rs2 + packh rd, rs1, rs2 +---- + +See <> for details of these instructions. + +.Notes to software developers +[NOTE,caption="SH"] +==== +The `pack*` instructions are +useful for re-arranging halfwords within words, and +generally getting data into the right shape prior to applying transforms. +This is particularly useful for cryptographic algorithms which pass inputs +around as (potentially un-aligned) byte strings, but can operate on words +made out of those byte strings. +This occurs (for example) in AES when loading blocks and keys (which may not +be word aligned) into registers to perform the round functions. +==== + +===== Crossbar Permutation Instructions + +---- +RV32, RV64: + xperm4 rd, rs1, rs2 + xperm8 rd, rs1, rs2 +---- + +See <> for a complete description of these instructions. + +The `xperm4` instruction operates on nibbles. +`GPR[rs1]` contains a vector of `XLEN/4` 4-bit elements. +`GPR[rs2]` contains a vector of `XLEN/4` 4-bit indexes. +The result is each element in `GPR[rs2]` replaced by the indexed element +in `GPR[rs1]`, or zero if the index into `GPR[rs2]` is out of bounds. + +The `xperm8` instruction operates on bytes. +`GPR[rs1]` contains a vector of `XLEN/8` 8-bit elements. +`GPR[rs2]` contains a vector of `XLEN/8` 8-bit indexes. +The result is each element in `GPR[rs2]` replaced by the indexed element +in `GPR[rs1]`, or zero if the index into `GPR[rs2]` is out of bounds. + +.Notes to software developers +[NOTE,caption="SH"] +==== +The instruction can be used to implement arbitrary bit +permutations. +For cryptography, they can accelerate bit-sliced implementations, +permutation layers of block ciphers, masking based countermeasures +and SBox operations. + +Lightweight block ciphers using 4-bit SBoxes include: +PRESENT cite:[block:present], +Rectangle cite:[block:rectangle], +GIFT cite:[block:gift], +Twine cite:[block:twine], +Skinny, MANTIS cite:[block:skinny], +Midori cite:[block:midori]. + +National ciphers using 8-bit SBoxes include: +Camellia cite:[block:camellia] (Japan), +Aria cite:[block:aria] (Korea), +AES cite:[nist:fips:197] (USA, Belgium), +SM4 cite:[gbt:sm4] (China) +Kuznyechik (Russia). + +All of these SBoxes can be implemented efficiently, in constant +time, using the `xperm8` instruction +footnote:l[link:http://svn.clairexen.net/handicraft/2020/lut4perm/demo02.cc[]]. +Note that this technique is also suitable for masking based +side-channel countermeasures. +==== + +[[crypto_scalar_appx_es]] + +=== Entropy Source Rationale and Recommendations + +This *non-normative* appendix focuses on the rationale, security, +self-certification, and implementation aspects of entropy sources. Hence we +also discuss non-ISA system features that may be needed for cryptographic +standards compliance and security testing. + +==== Checklists for Design and Self-Certification + +The security of cryptographic systems is based on secret bits and keys. +These bits need to be random and originate from cryptographically secure +Random Bit Generators (RBGs). An Entropy Source (ES) is required to +construct secure RBGs. + +While entropy source implementations do not have to be certified +designs, RISC-V expects that they behave in a compatible manner and do not +create unnecessary security risks to users. Self-evaluation and testing +following appropriate security standards is usually needed to achieve this. + +* *ISA Architectural Tests.* Verify, to the extent possible, that RISC-V ISA + requirements in this specification are correctly implemented. This includes + the state transitions (<> and + <>), access control + (<>), and that `seed` ES16 `entropy` words + can only be read destructively. + The scope of RISC-V ISA architectural tests are those behaviors that + are independent of the physical entropy source details. A smoke test ES + module may be helpful in design phase. +* *Technical justification for entropy.* This may take the form of a + stochastic model or a heuristic argument that explains why the noise + source output is from a random, rather than pseudorandom (deterministic) + process, and is not easily predictable or externally observable. + A complete physical model is not necessary; research literature can be + cited. For example, one can show that a good ring oscillator noise derives + an amount of physical entropy from local, spontaneously occurring + Johnson-Nyquist thermal noise cite:[Sa21], and is therefore not merely + "random-looking". +* *Entropy Source Design Review.* An entropy source is more than a noise + source, and must have features such as health tests + (<>), + a conditioner (<>), and a security + boundary with clearly defined interfaces. One may tabulate the SHALL + statements of SP 800-90B cite:[TuBaKe:18], FIPS 140-3 Implementation + Guidance cite:[NICC21], AIS-31 cite:[KiSc11] or other standards being + used. Official and non-official checklist tables are available: + https://github.com/usnistgov/90B-Shall-Statements +* *Experimental Tests.* The raw noise source is subjected to entropy + estimation as defined in NIST 800-90B, Section 3 cite:[TuBaKe:18]. + The interface described in <> can used be to + record datasets for this purpose. One also needs to show experimentally + that the conditioner and health test components work appropriately to + meet the ES16 output entropy requirements of <>. + For SP 800-90B, NIST has made a min-entropy estimation + package freely available: + https://github.com/usnistgov/SP800-90B_EntropyAssessment +* **Resilience.** Above physical engineering steps should consider the + operational environment of the device, which may be unexpected or + hostile (actively attempting to exploit vulnerabilities in the design). + +See <> for a discussion of various +implementation options. + +NOTE: It is one of the goals of the RISC-V Entropy Source specification +that a standard 90B Entropy Source Module or AIS-31 RNG IP may be licensed +from a third party and integrated with a RISC-V processor design. Compared +to older (FIPS 140-2) RNG and DRBG modules, an entropy source module may +have a relatively small area (just a few thousand NAND2 gate equivalent). +CMVP is introducing an "Entropy Source Validation Scope" which potentially +allows 90B validations to be reused for different (FIPS 140-3) modules. + +==== Standards and Terminology + +As a fundamental security function, the generation of random numbers is +governed by numerous standards and technical evaluation methods, the main +ones being FIPS 140-3 cite:[NI19,NICC21] required for U.S. Federal use, +and Common Criteria Methodology cite:[Cr17] used in high-security evaluations +internationally. + +Note that FIPS 140-3 is a significantly updated standard compared +to its predecessor FIPS 140-2 and is only coming into use in the 2020s. + +These standards set many of the technical requirements for the RISC-V +entropy source design, and we use their terminology if possible. + + +[[crypto_scalar_es_fig_rng,reftext="TRNG Components"]] +==== +image::es_dataflow.svg[align="center",scaledwidth=50%] +The `seed` CSR provides an Entropy Source (ES) interface, not a stateful +random number generator. As a result, it can support arbitrary +security levels. Cryptographic (AES, SHA-2/3) ISA Extensions +can be used to construct high-speed DRBGs that are seeded from the +entropy source. +==== + +[[crypto_scalar_appx_es_intro-es]] +===== Entropy Source (ES) + +Entropy sources are built by sampling and processing data from a noise +source (<>). +We will only consider physical sources of true randomness in this work. +Since these are directly based on natural phenomena and are subject to +environmental conditions (which may be adversarial), they require features +that monitor the "health" and quality of those sources. + +The requirements for physical entropy sources are specified in +NIST SP 800-90B cite:[TuBaKe:18] (<>) +for U.S. Federal FIPS 140-3 cite:[NI19] evaluations and +in BSI AIS-31 cite:[KiSc01,KiSc11] (<>) +for high-security Common Criteria evaluations. +There is some divergence in the types of health tests and entropy metrics +mandated in these standards, and RISC-V enables support for both alternatives. + +[[crypto_scalar_appx_es_intro-cond]] +===== Conditioning: Cryptographic and Non-Cryptographic + +Raw physical randomness (noise) sources are rarely statistically +perfect, and some generate very large amounts of bits, which need to be +"debiased" and reduced to a smaller number of bits. This process is +called conditioning. A secure hash function is an example of a +cryptographic conditioner. It is important to note that even though +hashing may make any data look random, it does not increase its +entropy content. + +Non-cryptographic conditioners and extractors such as von Neumann's +"debiased coin tossing" cite:[Ne51] are easier to implement +efficiently but may reduce entropy content (in individual bits removed) +more than cryptographic hashes, which mix the input entropy very +efficiently. However, they do not require cryptanalytic or computational +hardness assumptions and are therefore inherently more future-proof. +See <> for a more detailed +discussion. + +[[crypto_scalar_appx_es_intro-prng]] +===== Pseudorandom Number Generator (PRNG) + +Pseudorandom Number Generators (PRNGs) use deterministic mathematical +formulas to create abundant random numbers from a smaller amount of +"seed" randomness. PRNGs are also divided into cryptographic and +non-cryptographic ones. + +Non-cryptographic PRNGs, such as LFSRs and the linear-congruential +generators found in many programming libraries, may generate statistically +satisfactory random numbers but must never be used for cryptographic +keying. This is because they are not designed to resist +_cryptanalysis_; it is usually possible to take some output and +mathematically derive the "seed" or the internal state of the PRNG +from it. This is a security problem since knowledge of the state +allows the attacker to compute future or past outputs. + +[[crypto_scalar_appx_es_intro-drbg]] +===== Deterministic Random Bit Generator (DRBG) + +Cryptographic PRNGs are also known as Deterministic Random Bit +Generators (DRBGs), a term used by SP 800-90A cite:[BaKe15]. A strong +cryptographic algorithm such as AES cite:[nist:fips:197] or SHA-2/3 +cite:[nist:fips:202,nist:fips:180:4] +is used to produce random bits from a seed. The secret +seed material is like a cryptographic key; determining the seed +from the DRBG output is as hard as breaking AES or a strong hash function. +This also illustrates that the seed/key needs to be long enough and +come from a trusted Entropy Source. The DRBG should still be frequently +refreshed (reseeded) for forward and backward security. + +==== Specific Rationale and Considerations + +===== The `seed` CSR + +See <>. + +The interface was designed to be simple so that a vendor- and +device-independent driver component (e.g., in Linux kernel, +embedded firmware, or a cryptographic library) may use `seed` to +generate truly random bits. + +An entropy source does not require a high-bandwidth interface; +a single DRBG source initialization only requires 512 bits +(256 bits of entropy), and DRBG output can be shared by any number of +callers. Once initiated, a DRBG requires new entropy only to mitigate +the risk of state compromise. + +From a security perspective, it is essential that the side effect of +flushing the secret entropy bits occurs upon reading. Hence we mandate +a write operation on this particular CSR. + +A blocking instruction may have been easier to use, but most users should +be querying a (D)RBG instead of an entropy source. +Without a polling-style mechanism, the entropy source could hang for +thousands of cycles under some circumstances. A `wfi` or `pause` +mechanism (at least potentially) allows energy-saving sleep on MCUs +and context switching on higher-end CPUs. + +The reason for the particular `OPST = seed[31:0]` two-bit mechanism is to +provide redundancy. The "fault" bit combinations `11` (`DEAD`) and `00` +(`BIST`) are more likely for electrical reasons if feature discovery fails +and the entropy source is actually not available. + +The 16-bit bandwidth was a compromise motivated by the desire to +provide redundancy in the return value, some protection against +potential Power/EM leakage (further alleviated by the 2:1 cryptographic +conditioning discussed in <>), +and the desire to have all of the bits "in the same place" on +both RV32 and RV64 architectures for programming convenience. + +===== NIST SP 800-90B + +See <>. + +SP 800-90C cite:[BaKeRo:21] states that each conditioned block of n bits +is required to have n+64 bits of input entropy to attain full entropy. +Hence NIST SP 800-90B cite:[TuBaKe:18] min-entropy assessment must +guarantee at least 128 + 64 = 192 bits input entropy per 256-bit block +(cite:[BaKeRo:21], Sections 4.1. and 4.3.2). +Only then a hashing of 16 * 16 = 256 bits from the entropy source +will produce the desired 128 bits of full entropy. This follows from +the specific requirements, threat model, and distinguishability proof +contained in SP 800-90C cite:[BaKeRo:21], Appendix A. +The implied min-entropy rate is 192/256=12/16=0.75. The expected +Shannon entropy is much larger. + +In FIPS 140-3 / SP 800-90 classification, an RBG2(P) construction is a +cryptographically secure RBG with continuous access to a physical entropy +source (`seed`) and output generated by a fully seeded, secure DRBG. +The entropy source can also be used to build RBG3 +full entropy sources cite:[BaKeRo:21]. The concatenation of output words +corresponds to the `Get_ES_Bitstring` function. + +The 128-bit output block size was selected because that is the output +size of the CBC-MAC conditioner specified in Appendix F of cite:[TuBaKe:18] +and also the smallest key size we expect to see in applications. + +If NIST SP 800-90B certification is chosen, the entropy source +should implement at least the health tests defined in +Section 4.4 of cite:[TuBaKe:18]: the repetition count test and adaptive +proportion test, or show that the same flaws will be detected +by vendor-defined tests. + +===== BSI AIS-31 + +See <>. + +PTG.2 is one of the security and functionality classes defined in +BSI AIS 20/31 cite:[KiSc11]. The PTG.2 source requirements work as a +building block for other types of BSI generators (e.g., DRBGs, or +PTG.3 TRNG with appropriate software post-processing). + +For validation purposes, the PTG.2 requirements may be mapped to +security controls T1-3 (<>) and the +interface as follows: + +* P1 *[PTG.2.1]* Start-up tests map to T1 and reset-triggered (on-demand) +`BIST` tests. +* P2 *[PTG.2.2]* Continuous testing total failure maps to T2 and the +`DEAD` state. +* P3 *[PTG.2.3]* Online tests are continuous tests of T2 – entropy output +is prevented in the `BIST` state. +* P4 *[PTG.2.4]* Is related to the design of effective entropy source +health tests, which we encourage. +* P5 *[PTG.2.5]* Raw random sequence may be checked via the GetNoise +interface (<>). +* P6 *[PTG.2.6]* Test Procedure A cite:[KiSc11] (Sect 2.4.4.1) is a +part of the evaluation process, and we suggest self-evaluation using these +tests even if AIS-31 certification is not sought. +* P7 *[PTG.2.7]* Average Shannon entropy of "internal random bits" +exceeds 0.997. + +Note how P7 concerns Shannon entropy, not min-entropy as with NIST +sources. Hence the min-entropy requirement needs to be also stated. +PTG.2 modules built and certified to the AIS-31 standard can also meet the +"full entropy" condition after 2:1 cryptographic conditioning, but not +necessarily so. The technical validation process is somewhat different. + +===== Virtual Sources + +<>. + +All sources that are not direct physical sources (meeting the SP 800-90B +or the AIS-31 PTG.2 requirements) need to meet the security requirements +of virtual entropy sources. It is assumed that a virtual entropy source +is not a limiting, shared bandwidth resource (but a software DRBG). + +DRBGs can be used to feed other (virtual) DRBGs, but that does not +increase the absolute amount of entropy in the system. +The entropy source must be able to support current and future security +standards and applications. The 256-bit requirement maps to +"Category 5" of NIST Post-Quantum Cryptography (4.A.5 +"Security Strength Categories" in cite:[NI16]) and TOP SECRET schemes +in Suite B and the newer U.S. Government CNSA Suite cite:[NS15]. + +[[crypto_scalar_appx_es_access]] +===== Security Considerations for Direct Hardware Access + +<>. + +The ISA implementation and system design must try to ensure that the +hardware-software interface minimizes avenues for adversarial +information flow even if not explicitly forbidden in the specification. + +For security, virtualization requires both conditioning and DRBG processing +of physical entropy output. It is recommended if a single physical entropy +source is shared between multiple different virtual machines or if the +guest OS is untrusted. A virtual entropy source is significantly more +resistant to depletion attacks and also lessens the risk from covert channels. + +The direct `mseccfg.[s,u]seed` option allows one to draw a security boundary +around a component in relation to Sensitive Security Parameter (SSP) flows, +even if that component is not in M mode. This is +helpful when implementing trusted enclaves. Such modules can enforce the +entire key lifecycle from birth (in the entropy source) to death +(zeroization) to occur without the key being passed across the boundary +to external code. + +*Depletion.* +Active polling may deny the entropy source to another simultaneously +running consumer. This can (for example) delay the instantiation of that +virtual machine if it requires entropy to initialize fully. + +*Covert Channels.* +Direct access to a component such as the entropy source can be used to +establish communication channels across security boundaries. Active +polling from one consumer makes the resource unavailable WAIT instead of +ES16 to another (which is polling infrequently). Such interactions can +be used to establish low-bandwidth channels. + +*Hardware Fingerprinting.* +An entropy source (and its noise source circuits) may have a uniquely +identifiable hardware "signature." This can be harmless or even useful +in some applications (as random sources may exhibit Physically Un-clonable +Function (PUF) -like features) +but highly undesirable in others (anonymized virtualized environments +and enclaves). A DRBG masks such statistical features. + +*Side Channels.* +Some of the most devastating practical attacks against real-life +cryptosystems have used inconsequential-looking additional +information, such as padding error messages cite:[BaFoKa:12] +or timing information cite:[MoSuEi:20]. + +We urge implementers against creating unnecessary information flows +via status or custom bits or to allow any other mechanism to disable or +affect the entropy source output. All information flows and interaction +mechanisms must be considered from an adversarial viewpoint: +the fewer the better. + +As an example of side-channel analysis, we note that the entropy +polling interface is typically not "constant time." One needs to +analyze what kind of information is revealed via the timing oracle; +one way of doing it is to model `seed` as a rejection +sampler. Such a timing oracle can reveal information about the noise +source type and entropy source usage, but not about the random output +`entropy` bits themselves. If it does, additional countermeasures are +necessary. + +[[crypto_scalar_es_security_controls]] +==== Security Controls and Health Tests + +The primary purpose of a cryptographic entropy source is to produce +secret keying material. In almost all cases, a hardware entropy source +must implement appropriate _security controls_ to guarantee +unpredictability, prevent leakage, detect attacks, and deny adversarial +control over the entropy output or ts generation mechanism. Explicit +security controls are required for security testing and certification. + +Many of the security controls built into the device are called "health +checks." Health checks can take the form of integrity checks, start-up +tests, and on-demand tests. These tests can be implemented in hardware +or firmware, typically both. Several are mandated by standards such as +NIST SP 800-90B cite:[NI19]. +The choice of appropriate health tests depends on the +certification target, system architecture, threat model, entropy +source type, and other factors. + +Health checks are not intended for hardware diagnostics but for detecting +security issues. Hence the default action in case of a failure should be +aimed at damage control: Limiting further output and preventing weak +crypto keys from being generated. + +We discuss three specific testing requirements T1-T3. The testing requirement +follows from the definition of an Entropy Source; without it, the module is +simply a noise source and can't be trusted to safely generate keying material. + +===== T1: On-demand testing + +A sequence of simple tests is invoked via resetting, rebooting, or +powering up the hardware (not an ISA signal). The implementation will +simply return `BIST` during the initial start-up self-test period; +in any case, the driver must wait for them to finish before starting +cryptographic operations. Upon failure, the entropy source will enter +a no-output `DEAD` state. + +*Rationale.* +Interaction with hardware self-test mechanisms +from the software side should be minimal; the term "on-demand" does not +mean that the end-user or application program should be able to invoke +them in the field (the term is a throwback to an age of discrete, +non-autonomous crypto devices with human operators). + +===== T2: Continuous checks + +If an error is detected in continuous tests or +environmental sensors, the entropy source will enter a no-output state. +We define that a non-critical alarm is signaled if the entropy source +returns to `BIST` state from live (`WAIT` or `ES16`) states. Critical +failures will result in `DEAD` state immediately. A hardware-based +continuous testing mechanism must not make statistical information +externally available, and it must be zeroized periodically or upon +demand via reset, power-up, or similar signal. + +*Rationale.* +Physical attacks can occur while the device is running. The design +should avoid guiding such active attacks by revealing detailed +status information. Upon detection of an attack, the default action +should be aimed at damage control -- to prevent weak crypto keys from +being generated. + +The statistical nature of some tests makes "type-1" false +positives a possibility. There may also be requirements for signaling +of non-fatal alarms; AIS 31 specifies "noise alarms" that can go off +with non-negligible probability even if the device is functioning +correctly; these can be signaled with `BIST`. +There rarely is anything that can or should be done about a non-fatal +alarm condition in an operator-free, autonomous system. + +The state of statistical runtime health checks (such as counters) +is potentially correlated with some secret keying material, hence +the zeroization requirement. + +===== T3: Fatal error states + +Since the security of most cryptographic operations depends on the +entropy source, a system-wide "default deny" security policy approach +is appropriate for most entropy source failures. A hardware test failure +should at least result in the `DEAD` state and possibly reset/halt. +It’s a show stopper: The entropy source (or its cryptographic client +application) _must not_ be allowed to run if its secure operation +can’t be guaranteed. + +*Rationale.* +These tests can complement other integrity and tamper resistance +mechanisms (See Chapter 18 of cite:[An20] for examples). + +Some hardware random generators are, by their physical construction, +exposed to relatively non-adversarial environmental and manufacturing +issues. However, even such "innocent" failure modes may indicate +a _fault attack_ cite:[KaScVe13] and therefore should be addressed +as a system integrity failure rather than as a diagnostic issue. + +Security architects will understand to use +permanent or hard-to-recover "security-fuse" lockdowns only if the +threshold of a test is such that the probability of false-positive is +negligible over the entire device lifetime. + +===== Information Flows + +Some of the most devastating practical attacks +against real-life cryptosystems have used inconsequential-looking +additional information, such as padding error messages cite:[BaFoKa:12] +or timing information cite:[MoSuEi:20]. In cryptography, such +out-of-band information sources are called "oracles." + +To guarantee that no sensitive data is read twice and that different +callers don’t get correlated output, it is required that hardware +implements _wipe-on-read_ on the randomness pathway during each read +(successful poll). For the same reasons, only complete and fully +processed random words shall be made available via `entropy` (ES16 status +of `seed`). + +This also applies to the raw noise source. The raw source interface has +been delegated to an optional vendor-specific test interface. +Importantly the test interface and the main interface should not be +operational at the same time. + +[quote, NIST SP 800-90B, Noise Source Requirements] +The noise source state shall be protected from adversarial +knowledge or influence to the greatest extent possible. The methods +used for this shall be documented, including a description of the +(conceptual) security boundary's role in protecting the noise source +from adversarial observation or influence. + +An entropy source is a singular resource, subject to depletion +and also covert channels cite:[EvPo16]. Observation of the entropy +can be the same as the observation of the noise source output, as +cryptographic conditioning is mandatory only as a post-processing step. +SP 800-90B and other security standards mandate protection of +noise bits from observation and also influence. + +[[crypto_scalar_appx_es_implementation]] +==== Implementation Strategies + +As a general rule, RISC-V specifies the ISA only. We provide some +additional suggestions so that portable, vendor-independent middleware +and kernel components can be created. The actual hardware implementation +and certification are left to vendors and circuit designers; +the discussion in this Section is purely informational. + +When considering implementation options and trade-offs, one must look +at the entire information flow. + +. *A Noise Source* generates private, unpredictable signals + from stable and well-understood physical random events. +. *Sampling* digitizes the noise signal into a raw stream of + bits. This raw data also needs to be protected by the design. +. *Continuous health tests* ensure that the noise source + and its environment meet their operational parameters. +. *Non-cryptographic conditioners* remove much of the bias + and correlation in input noise. +. *Cryptographic conditioners* produce full entropy + output, completely indistinguishable from ideal random. +. *DRBG* takes in `>=256` bits of seed entropy as keying + material and uses a "one way" cryptographic process to rapidly + generate bits on demand (without revealing the seed/state). + +Steps 1-4 (possibly 5) are considered to be part of the Entropy +Source (ES) and provided by the `seed` CSR. +Adding the software-side cryptographic steps 5-6 and control logic +complements it into a True Random Number Generator (TRNG). + +[[crypto_scalar_appx_es_noise_sources]] +===== Ring Oscillators + +We will give some examples of common noise sources that can be +implemented in the processor itself (using standard cells). + +The most common entropy source type in production use today is +based on "free running" ring oscillators and their timing jitter. +Here, an odd number of inverters is connected into a loop from which +noise source bits are sampled in relation to a reference clock +cite:[BaLuMi:11]. The sampled bit sequence may be expected to be +relatively uncorrelated (close to IID) if the sample rate is suitably low +cite:[KiSc11]. However, further processing is usually required. + +AMD cite:[AM17], ARM cite:[AR17], and IBM cite:[LiBaBo:13] are +examples of ring oscillator TRNGs intended for high-security +applications. + +There are related metastability-based generator designs such as +Transition Effect Ring Oscillator (TERO) cite:[VaDr10]. +The differential/feedback Intel construction cite:[HaKoMa12] is slightly +different but also falls into the same general metastable +oscillator-based category. + +The main benefits of ring oscillators are: (1) They can be implemented +with standard cell libraries without external components -- +and even on FPGAs cite:[VaFiAu:10], (2) there is an established theory +for their behavior cite:[HaLe98,HaLiLe99,BaLuMi:11], and (3) ample +precedent exists for testing and certifying them at the highest security +levels. + +Ring oscillators also have well-known implementation pitfalls. +Their output is sometimes highly dependent on temperature, +which must be taken into account in testing and modeling. +If the ring oscillator construction is parallelized, it is important +that the number of stages and/or inverters in each chain is suitable to +avoid entropy reduction due to harmonic "Huyghens synchronization" +cite:[Ba86]. +Such harmonics can also be inserted maliciously in a frequency +injection attack, which can have devastating results cite:[MaMo09]. +Countermeasures are related to circuit design; environmental sensors, +electrical filters, and usage of a differential oscillator may help. + +===== Shot Noise + +A category of random sources consisting of discrete events +and modeled as a Poisson process is called "shot noise." +There's a long-established precedent of certifying them; the +AIS 31 document cite:[KiSc11] itself offers reference designs based on +noisy diodes. Shot noise sources are often more resistant to +temperature changes than ring oscillators. +Some of these generators can also be fully implemented with standard +cells (The Rambus / Inside Secure generic TRNG IP cite:[Ra20] is +described as a Shot Noise generator). + +===== Other types of noise + +It may be possible to certify more exotic noise sources and designs, +although their stochastic model needs to be equally well understood, +and their CPU interfaces must be secure. +See <> for a discussion of Quantum +entropy sources. + +[[crypto_scalar_appx_es_cont-tests]] +===== Continuous Health Tests + +Health monitoring requires some state information related +to the noise source to be maintained. The tests should be designed +in a way that a specific number of samples guarantees a state +flush (no hung states). We suggest flush size `W =< 1024` to +match with the NIST SP 800-90B required tests (See Section 4.4 in +cite:[TuBaKe:18]). The state is also fully zeroized in a system reset. + +The two mandatory tests can be built with minimal circuitry. +Full histograms are not required, only simple counter registers: +repetition count, window count, and sample count. +Repetition count is reset every time the output sample value +changes; if the count reaches a certain cutoff limit, a noise alarm +(`BIST`) or failure (`DEAD`) is signaled. The window counter is +used to save every W'th output (typically `W` in { 512, 1024 }). +The frequency of this reference sample in the following window is +counted; cutoff values are defined in the standard. We see that the +structure of the mandatory tests is such that, if well implemented, +no information is carried beyond a limit of `W` samples. + +Section 4.5 of cite:[TuBaKe:18] explicitly permits additional +developer-defined tests, and several more were defined in early +versions of FIPS 140-1 before being "crossed out." The choice +of additional tests depends on the nature and implementation of the +physical source. + +Especially if a non-cryptographic conditioner is used in hardware, +it is possible that the AIS 31 cite:[KiSc11] online tests are +implemented by driver software. They can also be implemented in hardware. +For some security profiles, AIS 31 mandates that their tolerances are +set in a way that the probability of an alarm is at least 10^-6^ +yearly under "normal usage." Such requirements are problematic +in modern applications since their probability is too high for +critical systems. + +There rarely is anything that can or should be done about a non-fatal +alarm condition in an operator-free, autonomous system. However, +AIS 31 allows the DRBG component to keep running despite a failure in +its Entropy Source, so we suggest re-entering a temporary `BIST` +state (<>) to signal a non-fatal +statistical error if such (non-actionable) signaling is necessary. +Drivers and applications can react to this appropriately (or simply +log it), but it will not directly affect the availability of the TRNG. +A permanent error condition should result in `DEAD` state. + +[[crypto_scalar_appx_es_noncrypto]] +===== Non-cryptographic Conditioners + +As noted in <>, physical randomness +sources generally require a post-processing step called _conditioning_ to +meet the desired quality requirements, which are outlined in +<>. + +The approach taken in this interface is to allow a combination of +non-cryptographic and cryptographic filtering to take place. The +first stage (hardware) merely needs to be able to distill the entropy +comfortably above the necessary level. + +* One may take a set of bits from a noise source and XOR them + together to produce a less biased (and more independent) bit. + However, such an XOR may introduce "pseudorandomness" and + make the output difficult to analyze. +* The von Neumann extractor cite:[Ne51] looks at consecutive + pairs of bits, rejects 00 and 11, and outputs 0 or 1 for + 01 and 10, respectively. It will reduce the number of bits to + less than 25% of the original, but the output is provably unbiased + (assuming independence). +* Blum's extractor cite:[Bl86] can be used on sources + whose behavior resembles N-state Markov chains. If its + assumptions hold, it also removes dependencies, creating an + independent and identically distributed (IID) source. +* Other linear and non-linear correctors such as those + discussed by Dichtl and Lacharme cite:[La08]. + +Note that the hardware may also implement a full cryptographic conditioner +in the entropy source, even though the software driver still needs +a cryptographic conditioner, too (<>). + +*Rationale:* +The main advantage of non-cryptographic extractors is in their +energy efficiency, relative simplicity, and amenability to mathematical +analysis. If well designed, they can be evaluated in +conjunction with a stochastic model of the noise source itself. +They do not require computational hardness assumptions. + +[[crypto_scalar_appx_es_crypto-cond]] +===== Cryptographic Conditioners + +For secure use, cryptographic conditioners are always required on the +software side of the ISA boundary. They may also be implemented on the +hardware side if necessary. In any case, the `entropy` ES16 output must +always be compressed 2:1 (or more) before being used as keying material +or considered "full entropy." + +Examples of cryptographic conditioners include the random pool of the +Linux operating system, secure hash functions (SHA-2/3, SHAKE +cite:[nist:fips:202,nist:fips:180:4]), and the AES / CBC-MAC +construction in Appendix F, SP 800-90B cite:[TuBaKe:18]. + +In some constructions, such as the Linux RNG and SHA-3/SHAKE +cite:[nist:fips:202] based generators, the cryptographic conditioning +and output (DRBG) generation are provided by the same component. + +*Rationale:* +For many low-power targets constructions the type of hardware AES CBC-MAC +conditioner used by Intel cite:[Me18] and AMD cite:[AM17] would be too +complex and energy-hungry to implement solely to serve the `seed` CSR. +On the other hand, simpler non-cryptographic conditioners may be too +wasteful on input entropy if high-quality random output is required -- +(ARM TrustZone TRBG cite:[AR17] outputs only 10Kbit/sec at 200 MHz.) +Hence a resource-saving compromise is made between hardware and software +generation. + +[[crypto_scalar_appx_es_drbgs]] +===== The Final Random: DRBGs + +All random bits reaching end users and applications must come from a +cryptographic DRBG. These are generally implemented by the driver +component in software. The RISC-V AES and SHA instruction set extensions +should be used if available since they offer additional +security features such as timing attack resistance. + +Currently recommended DRBGs are defined in NIST SP 800-90A (Rev 1) +cite:[BaKe15]: `CTR_DRBG`, `Hash_DRBG`, and `HMAC_DRBG`. +Certification often requires known answer tests (KATs) for the symmetric +components and the DRBG as a whole. These are significantly easier to +implement in software than in hardware. In addition to the directly +certifiable SP 800-90A DRBGs, a Linux-style random pool construction +based on ChaCha20 cite:[Mu20] can be used, or an appropriate construction +based on SHAKE256 cite:[nist:fips:202]. + +These are just recommendations; programmers can adjust the usage of the +CPU Entropy Source to meet future requirements. + +[[crypto_scalar_appx_es_quantum]] +===== Quantum vs. Classical Random + +[quote,U.K. NCSC QRNG Guidance, March 2020] +The NCSC believes that classical RNGs will continue to +meet our needs for government and military applications for the +foreseeable future. + +A Quantum Random Number Generator (QRNG) is a TRNG whose source of +randomness can be unambiguously identified to be a specific +quantum phenomenon such as quantum state superposition, quantum state +entanglement, Heisenberg uncertainty, quantum tunneling, spontaneous +emission, or radioactive decay cite:[IT19]. + +Direct quantum entropy is theoretically the best possible kind of +entropy. A typical TRNG based on electronic noise is also largely +based on quantum phenomena and is equally unpredictable - the difference +is that the relative amount of quantum and classical physics involved is +difficult to quantify for a classical TRNG. + +QRNGs are designed in a way that allows the amount of quantum-origin +entropy to be modeled and estimated. This distinction is important in +the security model used by QKD (Quantum Key Distribution) security +mechanisms which can be used to protect the physical layer (such as +fiber optic cables) against interception by using quantum mechanical +effects directly. + +This security model means that many of the available QRNG devices do +not use cryptographic conditioning and may fail cryptographic statistical +requirements cite:[HuHe20]. Many implementers may consider them to be +entropy sources instead. + +Relatively little research has gone into QRNG implementation security, +but many QRNG designs are arguably more susceptible to leakage than +classical generators (such as ring oscillators) as they tend to employ +external components and mixed materials. As an example, amplification of +a photon detector signal may be observable in power analysis, +which classical noise-based sources are designed to resist. + +===== Post-Quantum Cryptography + +PQC public-key cryptography standards cite:[NI16] do not require +quantum-origin randomness, just sufficiently secure keying material. +Recall that cryptography aims to protect the confidentiality and +integrity of data itself and does not place any requirements on +the physical communication channel (like QKD). + +Classical good-quality TRNGs are perfectly suitable +for generating the secret keys for PQC protocols that are hard for +quantum computers to break but implementable on classical computers. +What matters in cryptography is that the secret keys have enough true +randomness (entropy) and that they are generated and stored securely. + +Of course, one must avoid DRBGs that are based on problems that are +easily solvable with quantum computers, such as factoring cite:[Sh94] +in the case of the Blum-Blum-Shub generator cite:[BlBlSh86]. +Most symmetric algorithms are not affected as the best quantum +attacks are still exponential to key size cite:[Gr96]. + +As an example, the original Intel RNG cite:[Me18], whose output generation +is based on AES-128, can be attacked using Grover's algorithm +with approximately square-root effort cite:[JaNaRo:20]. +While even "64-bit" quantum security is extremely difficult to +break, many applications specify a higher security requirement. +NIST cite:[NI16] defines AES-128 to be "Category 1" equivalent +post-quantum security, while AES-256 is "Category 5" (highest). +We avoid this possible future issue by exposing direct access +to the entropy source which can derive its security from +information-theoretic assumptions only. + +[[crypto_scalar_es_getnoise]] +==== Suggested GetNoise Test Interface + +Compliance testing, characterization, and configuration of entropy sources +require access to raw, unconditioned noise samples. This conceptual test +interface is named GetNoise in Section 2.3.2 of NIST SP 800-90B +cite:[TuBaKe:18]. + +Since this type of interface is both necessary for security testing +and also constitutes a potential backdoor to the cryptographic key generation +process, we define a safety behavior that compliant implementations can +have for temporarily disabling the entropy source `seed` CSR interface during +test. + +In order for shared RISC-V self-certification scripts (and drivers) to +accommodate the test interface in a secure fashion, we suggest that it is +implemented as a custom, M-mode only CSR, denoted here as `mnoise`. + +This non-normative interface is not intended to be used as a source of +randomness or for other production use. +We define the semantics for single bit for this interface, `mnoise[31]`, +which is named `NOISE_TEST`, which will affect the behavior of `seed` +if implemented. + +When `NOISE_TEST = 1` in `mnoise`, the `seed` CSR must not return +anything via `ES16`; it should be in `BIST` state unless the source +is `DEAD`. When `NOISE_TEST` is again disabled, the entropy source +shall return from `BIST` via an appropriate zeroization and self-test +mechanism. + +The behavior of other input and output bits is largely left to the vendor +(as they depend on the technical details of the physical entropy source), +as is the address of the custom `mnoise` CSR. Other contents and behavior of the +CSR only can be interpreted in the context of `mvendorid`, `marchid`, and +`mimpid` CSR identifiers. + +When not implemented (e.g., in virtual machines), `mnoise` can permanently +read zero (`0x00000000`) and ignore writes. +When available, but `NOISE_TEST = 0`, `mnoise` can return a +nonzero constant (e.g. `0x00000001`) but no noise samples. + +[[crypto_scalar_es_noistest,reftext="Custom Entropy Test Mode Diagram"]] +==== +image::es_noisetest.svg[title="Entropy source can't be read in test mode.", align="center",scaledwidth=66%] +In `NOISE_TEST` mode, the WAIT and ES16 states are unreachable, +and no entropy is output. Implementation of test interfaces that directly +affect ES16 entropy output from the `seed` CSR interface is discouraged. +Such vendor test interfaces have been exploited in attacks. For example, +an ECDSA cite:[nist:fips:186:4] signature process without sufficient +entropy will not only create an insecure signature but can also reveal +the secret signing key, that can be used for authentication forgeries by +attackers. Hence even a temporary lapse in `entropy` security may have serious +security implications. +==== + +[[crypto_scalar_appx_materials]] +=== Supplementary Materials + +While this document contains the specifications for the RISC-V cryptography +extensions, numerous supplementary materials and example codes have +also been developed. +All of the materials related to the RISC-V Cryptography +extension live in a GitHub Repository, located at +https://github.com/riscv/riscv-crypto + +* `doc/` + Contains the source code for this document. + +* `doc/supp/` + Contains supplementary information and recommendations for implementers of + software and hardware. + +* `benchmarks/` + Example software implementations. + +* `rtl/` + Example Verilog implementations of each instruction. + +* `sail/` + Formal model implementations in Sail. + +[[crypto_scalar_appx_sail]] +=== Supporting Sail Code + +This section contains the supporting Sail code referenced by the +instruction descriptions throughout the specification. +The +link:https://alasdair.github.io/manual.html[Sail Manual] +is recommended reading in order to best understand the supporting code. + +[source,sail] +---- +/* Auxiliary function for performing GF multiplication */ +val xt2 : bits(8) -> bits(8) +function xt2(x) = { + (x << 1) ^ (if bit_to_bool(x[7]) then 0x1b else 0x00) +} + +val xt3 : bits(8) -> bits(8) +function xt3(x) = x ^ xt2(x) + +/* Multiply 8-bit field element by 4-bit value for AES MixCols step */ +val gfmul : (bits(8), bits(4)) -> bits(8) +function gfmul( x, y) = { + (if bit_to_bool(y[0]) then x else 0x00) ^ + (if bit_to_bool(y[1]) then xt2( x) else 0x00) ^ + (if bit_to_bool(y[2]) then xt2(xt2( x)) else 0x00) ^ + (if bit_to_bool(y[3]) then xt2(xt2(xt2(x))) else 0x00) +} + +/* 8-bit to 32-bit partial AES Mix Column - forwards */ +val aes_mixcolumn_byte_fwd : bits(8) -> bits(32) +function aes_mixcolumn_byte_fwd(so) = { + gfmul(so, 0x3) @ so @ so @ gfmul(so, 0x2) +} + +/* 8-bit to 32-bit partial AES Mix Column - inverse*/ +val aes_mixcolumn_byte_inv : bits(8) -> bits(32) +function aes_mixcolumn_byte_inv(so) = { + gfmul(so, 0xb) @ gfmul(so, 0xd) @ gfmul(so, 0x9) @ gfmul(so, 0xe) +} + +/* 32-bit to 32-bit AES forward MixColumn */ +val aes_mixcolumn_fwd : bits(32) -> bits(32) +function aes_mixcolumn_fwd(x) = { + let s0 : bits (8) = x[ 7.. 0]; + let s1 : bits (8) = x[15.. 8]; + let s2 : bits (8) = x[23..16]; + let s3 : bits (8) = x[31..24]; + let b0 : bits (8) = xt2(s0) ^ xt3(s1) ^ (s2) ^ (s3); + let b1 : bits (8) = (s0) ^ xt2(s1) ^ xt3(s2) ^ (s3); + let b2 : bits (8) = (s0) ^ (s1) ^ xt2(s2) ^ xt3(s3); + let b3 : bits (8) = xt3(s0) ^ (s1) ^ (s2) ^ xt2(s3); + b3 @ b2 @ b1 @ b0 /* Return value */ +} + +/* 32-bit to 32-bit AES inverse MixColumn */ +val aes_mixcolumn_inv : bits(32) -> bits(32) +function aes_mixcolumn_inv(x) = { + let s0 : bits (8) = x[ 7.. 0]; + let s1 : bits (8) = x[15.. 8]; + let s2 : bits (8) = x[23..16]; + let s3 : bits (8) = x[31..24]; + let b0 : bits (8) = gfmul(s0, 0xE) ^ gfmul(s1, 0xB) ^ gfmul(s2, 0xD) ^ gfmul(s3, 0x9); + let b1 : bits (8) = gfmul(s0, 0x9) ^ gfmul(s1, 0xE) ^ gfmul(s2, 0xB) ^ gfmul(s3, 0xD); + let b2 : bits (8) = gfmul(s0, 0xD) ^ gfmul(s1, 0x9) ^ gfmul(s2, 0xE) ^ gfmul(s3, 0xB); + let b3 : bits (8) = gfmul(s0, 0xB) ^ gfmul(s1, 0xD) ^ gfmul(s2, 0x9) ^ gfmul(s3, 0xE); + b3 @ b2 @ b1 @ b0 /* Return value */ +} + +/* Turn a round number into a round constant for AES. Note that the + AES64KS1I instruction is defined such that the r argument is always + in the range 0x0..0xA. Values of rnum outside the range 0x0..0xA + do not decode to the AES64KS1I instruction. The 0xA case is used + specifically for the AES-256 KeySchedule, and this function is never + called in that case. */ +val aes_decode_rcon : bits(4) -> bits(32) +function aes_decode_rcon(r) = { + assert(r <_u 0xA); + match r { + 0x0 => 0x00000001, + 0x1 => 0x00000002, + 0x2 => 0x00000004, + 0x3 => 0x00000008, + 0x4 => 0x00000010, + 0x5 => 0x00000020, + 0x6 => 0x00000040, + 0x7 => 0x00000080, + 0x8 => 0x0000001b, + 0x9 => 0x00000036, + _ => internal_error(__FILE__, __LINE__, "Unexpected AES r") /* unreachable -- required to silence Sail warning */ + } +} + +/* SM4 SBox - only one sbox for forwards and inverse */ +let sm4_sbox_table : vector(256, bits(8)) = [ +0xD6, 0x90, 0xE9, 0xFE, 0xCC, 0xE1, 0x3D, 0xB7, 0x16, 0xB6, 0x14, 0xC2, 0x28, +0xFB, 0x2C, 0x05, 0x2B, 0x67, 0x9A, 0x76, 0x2A, 0xBE, 0x04, 0xC3, 0xAA, 0x44, +0x13, 0x26, 0x49, 0x86, 0x06, 0x99, 0x9C, 0x42, 0x50, 0xF4, 0x91, 0xEF, 0x98, +0x7A, 0x33, 0x54, 0x0B, 0x43, 0xED, 0xCF, 0xAC, 0x62, 0xE4, 0xB3, 0x1C, 0xA9, +0xC9, 0x08, 0xE8, 0x95, 0x80, 0xDF, 0x94, 0xFA, 0x75, 0x8F, 0x3F, 0xA6, 0x47, +0x07, 0xA7, 0xFC, 0xF3, 0x73, 0x17, 0xBA, 0x83, 0x59, 0x3C, 0x19, 0xE6, 0x85, +0x4F, 0xA8, 0x68, 0x6B, 0x81, 0xB2, 0x71, 0x64, 0xDA, 0x8B, 0xF8, 0xEB, 0x0F, +0x4B, 0x70, 0x56, 0x9D, 0x35, 0x1E, 0x24, 0x0E, 0x5E, 0x63, 0x58, 0xD1, 0xA2, +0x25, 0x22, 0x7C, 0x3B, 0x01, 0x21, 0x78, 0x87, 0xD4, 0x00, 0x46, 0x57, 0x9F, +0xD3, 0x27, 0x52, 0x4C, 0x36, 0x02, 0xE7, 0xA0, 0xC4, 0xC8, 0x9E, 0xEA, 0xBF, +0x8A, 0xD2, 0x40, 0xC7, 0x38, 0xB5, 0xA3, 0xF7, 0xF2, 0xCE, 0xF9, 0x61, 0x15, +0xA1, 0xE0, 0xAE, 0x5D, 0xA4, 0x9B, 0x34, 0x1A, 0x55, 0xAD, 0x93, 0x32, 0x30, +0xF5, 0x8C, 0xB1, 0xE3, 0x1D, 0xF6, 0xE2, 0x2E, 0x82, 0x66, 0xCA, 0x60, 0xC0, +0x29, 0x23, 0xAB, 0x0D, 0x53, 0x4E, 0x6F, 0xD5, 0xDB, 0x37, 0x45, 0xDE, 0xFD, +0x8E, 0x2F, 0x03, 0xFF, 0x6A, 0x72, 0x6D, 0x6C, 0x5B, 0x51, 0x8D, 0x1B, 0xAF, +0x92, 0xBB, 0xDD, 0xBC, 0x7F, 0x11, 0xD9, 0x5C, 0x41, 0x1F, 0x10, 0x5A, 0xD8, +0x0A, 0xC1, 0x31, 0x88, 0xA5, 0xCD, 0x7B, 0xBD, 0x2D, 0x74, 0xD0, 0x12, 0xB8, +0xE5, 0xB4, 0xB0, 0x89, 0x69, 0x97, 0x4A, 0x0C, 0x96, 0x77, 0x7E, 0x65, 0xB9, +0xF1, 0x09, 0xC5, 0x6E, 0xC6, 0x84, 0x18, 0xF0, 0x7D, 0xEC, 0x3A, 0xDC, 0x4D, +0x20, 0x79, 0xEE, 0x5F, 0x3E, 0xD7, 0xCB, 0x39, 0x48 +] + +let aes_sbox_fwd_table : vector(256, bits(8)) = [ +0x63, 0x7c, 0x77, 0x7b, 0xf2, 0x6b, 0x6f, 0xc5, 0x30, 0x01, 0x67, 0x2b, 0xfe, +0xd7, 0xab, 0x76, 0xca, 0x82, 0xc9, 0x7d, 0xfa, 0x59, 0x47, 0xf0, 0xad, 0xd4, +0xa2, 0xaf, 0x9c, 0xa4, 0x72, 0xc0, 0xb7, 0xfd, 0x93, 0x26, 0x36, 0x3f, 0xf7, +0xcc, 0x34, 0xa5, 0xe5, 0xf1, 0x71, 0xd8, 0x31, 0x15, 0x04, 0xc7, 0x23, 0xc3, +0x18, 0x96, 0x05, 0x9a, 0x07, 0x12, 0x80, 0xe2, 0xeb, 0x27, 0xb2, 0x75, 0x09, +0x83, 0x2c, 0x1a, 0x1b, 0x6e, 0x5a, 0xa0, 0x52, 0x3b, 0xd6, 0xb3, 0x29, 0xe3, +0x2f, 0x84, 0x53, 0xd1, 0x00, 0xed, 0x20, 0xfc, 0xb1, 0x5b, 0x6a, 0xcb, 0xbe, +0x39, 0x4a, 0x4c, 0x58, 0xcf, 0xd0, 0xef, 0xaa, 0xfb, 0x43, 0x4d, 0x33, 0x85, +0x45, 0xf9, 0x02, 0x7f, 0x50, 0x3c, 0x9f, 0xa8, 0x51, 0xa3, 0x40, 0x8f, 0x92, +0x9d, 0x38, 0xf5, 0xbc, 0xb6, 0xda, 0x21, 0x10, 0xff, 0xf3, 0xd2, 0xcd, 0x0c, +0x13, 0xec, 0x5f, 0x97, 0x44, 0x17, 0xc4, 0xa7, 0x7e, 0x3d, 0x64, 0x5d, 0x19, +0x73, 0x60, 0x81, 0x4f, 0xdc, 0x22, 0x2a, 0x90, 0x88, 0x46, 0xee, 0xb8, 0x14, +0xde, 0x5e, 0x0b, 0xdb, 0xe0, 0x32, 0x3a, 0x0a, 0x49, 0x06, 0x24, 0x5c, 0xc2, +0xd3, 0xac, 0x62, 0x91, 0x95, 0xe4, 0x79, 0xe7, 0xc8, 0x37, 0x6d, 0x8d, 0xd5, +0x4e, 0xa9, 0x6c, 0x56, 0xf4, 0xea, 0x65, 0x7a, 0xae, 0x08, 0xba, 0x78, 0x25, +0x2e, 0x1c, 0xa6, 0xb4, 0xc6, 0xe8, 0xdd, 0x74, 0x1f, 0x4b, 0xbd, 0x8b, 0x8a, +0x70, 0x3e, 0xb5, 0x66, 0x48, 0x03, 0xf6, 0x0e, 0x61, 0x35, 0x57, 0xb9, 0x86, +0xc1, 0x1d, 0x9e, 0xe1, 0xf8, 0x98, 0x11, 0x69, 0xd9, 0x8e, 0x94, 0x9b, 0x1e, +0x87, 0xe9, 0xce, 0x55, 0x28, 0xdf, 0x8c, 0xa1, 0x89, 0x0d, 0xbf, 0xe6, 0x42, +0x68, 0x41, 0x99, 0x2d, 0x0f, 0xb0, 0x54, 0xbb, 0x16 +] + +let aes_sbox_inv_table : vector(256, bits(8)) = [ +0x52, 0x09, 0x6a, 0xd5, 0x30, 0x36, 0xa5, 0x38, 0xbf, 0x40, 0xa3, 0x9e, 0x81, +0xf3, 0xd7, 0xfb, 0x7c, 0xe3, 0x39, 0x82, 0x9b, 0x2f, 0xff, 0x87, 0x34, 0x8e, +0x43, 0x44, 0xc4, 0xde, 0xe9, 0xcb, 0x54, 0x7b, 0x94, 0x32, 0xa6, 0xc2, 0x23, +0x3d, 0xee, 0x4c, 0x95, 0x0b, 0x42, 0xfa, 0xc3, 0x4e, 0x08, 0x2e, 0xa1, 0x66, +0x28, 0xd9, 0x24, 0xb2, 0x76, 0x5b, 0xa2, 0x49, 0x6d, 0x8b, 0xd1, 0x25, 0x72, +0xf8, 0xf6, 0x64, 0x86, 0x68, 0x98, 0x16, 0xd4, 0xa4, 0x5c, 0xcc, 0x5d, 0x65, +0xb6, 0x92, 0x6c, 0x70, 0x48, 0x50, 0xfd, 0xed, 0xb9, 0xda, 0x5e, 0x15, 0x46, +0x57, 0xa7, 0x8d, 0x9d, 0x84, 0x90, 0xd8, 0xab, 0x00, 0x8c, 0xbc, 0xd3, 0x0a, +0xf7, 0xe4, 0x58, 0x05, 0xb8, 0xb3, 0x45, 0x06, 0xd0, 0x2c, 0x1e, 0x8f, 0xca, +0x3f, 0x0f, 0x02, 0xc1, 0xaf, 0xbd, 0x03, 0x01, 0x13, 0x8a, 0x6b, 0x3a, 0x91, +0x11, 0x41, 0x4f, 0x67, 0xdc, 0xea, 0x97, 0xf2, 0xcf, 0xce, 0xf0, 0xb4, 0xe6, +0x73, 0x96, 0xac, 0x74, 0x22, 0xe7, 0xad, 0x35, 0x85, 0xe2, 0xf9, 0x37, 0xe8, +0x1c, 0x75, 0xdf, 0x6e, 0x47, 0xf1, 0x1a, 0x71, 0x1d, 0x29, 0xc5, 0x89, 0x6f, +0xb7, 0x62, 0x0e, 0xaa, 0x18, 0xbe, 0x1b, 0xfc, 0x56, 0x3e, 0x4b, 0xc6, 0xd2, +0x79, 0x20, 0x9a, 0xdb, 0xc0, 0xfe, 0x78, 0xcd, 0x5a, 0xf4, 0x1f, 0xdd, 0xa8, +0x33, 0x88, 0x07, 0xc7, 0x31, 0xb1, 0x12, 0x10, 0x59, 0x27, 0x80, 0xec, 0x5f, +0x60, 0x51, 0x7f, 0xa9, 0x19, 0xb5, 0x4a, 0x0d, 0x2d, 0xe5, 0x7a, 0x9f, 0x93, +0xc9, 0x9c, 0xef, 0xa0, 0xe0, 0x3b, 0x4d, 0xae, 0x2a, 0xf5, 0xb0, 0xc8, 0xeb, +0xbb, 0x3c, 0x83, 0x53, 0x99, 0x61, 0x17, 0x2b, 0x04, 0x7e, 0xba, 0x77, 0xd6, +0x26, 0xe1, 0x69, 0x14, 0x63, 0x55, 0x21, 0x0c, 0x7d +] + +/* Lookup function - takes an index and a table, and retrieves the + * x'th element of that table. Note that the Sail vector literals + * start at index 255, and go down to 0. + */ +val sbox_lookup : (bits(8), vector(256, bits(8))) -> bits(8) +function sbox_lookup(x, table) = { + table[255 - unsigned(x)] +} + +/* Easy function to perform a forward AES SBox operation on 1 byte. */ +val aes_sbox_fwd : bits(8) -> bits(8) +function aes_sbox_fwd(x) = sbox_lookup(x, aes_sbox_fwd_table) + +/* Easy function to perform an inverse AES SBox operation on 1 byte. */ +val aes_sbox_inv : bits(8) -> bits(8) +function aes_sbox_inv(x) = sbox_lookup(x, aes_sbox_inv_table) + +/* AES SubWord function used in the key expansion + * - Applies the forward sbox to each byte in the input word. + */ +val aes_subword_fwd : bits(32) -> bits(32) +function aes_subword_fwd(x) = { + aes_sbox_fwd(x[31..24]) @ + aes_sbox_fwd(x[23..16]) @ + aes_sbox_fwd(x[15.. 8]) @ + aes_sbox_fwd(x[ 7.. 0]) +} + +/* AES Inverse SubWord function. + * - Applies the inverse sbox to each byte in the input word. + */ +val aes_subword_inv : bits(32) -> bits(32) +function aes_subword_inv(x) = { + aes_sbox_inv(x[31..24]) @ + aes_sbox_inv(x[23..16]) @ + aes_sbox_inv(x[15.. 8]) @ + aes_sbox_inv(x[ 7.. 0]) +} + +/* Easy function to perform an SM4 SBox operation on 1 byte. */ +val sm4_sbox : bits(8) -> bits(8) +function sm4_sbox(x) = sbox_lookup(x, sm4_sbox_table) + +val aes_get_column : (bits(128), nat) -> bits(32) +function aes_get_column(state,c) = (state >> (to_bits(7, 32 * c)))[31..0] + +/* 64-bit to 64-bit function which applies the AES forward sbox to each byte + * in a 64-bit word. + */ +val aes_apply_fwd_sbox_to_each_byte : bits(64) -> bits(64) +function aes_apply_fwd_sbox_to_each_byte(x) = { + aes_sbox_fwd(x[63..56]) @ + aes_sbox_fwd(x[55..48]) @ + aes_sbox_fwd(x[47..40]) @ + aes_sbox_fwd(x[39..32]) @ + aes_sbox_fwd(x[31..24]) @ + aes_sbox_fwd(x[23..16]) @ + aes_sbox_fwd(x[15.. 8]) @ + aes_sbox_fwd(x[ 7.. 0]) +} + +/* 64-bit to 64-bit function which applies the AES inverse sbox to each byte + * in a 64-bit word. + */ +val aes_apply_inv_sbox_to_each_byte : bits(64) -> bits(64) +function aes_apply_inv_sbox_to_each_byte(x) = { + aes_sbox_inv(x[63..56]) @ + aes_sbox_inv(x[55..48]) @ + aes_sbox_inv(x[47..40]) @ + aes_sbox_inv(x[39..32]) @ + aes_sbox_inv(x[31..24]) @ + aes_sbox_inv(x[23..16]) @ + aes_sbox_inv(x[15.. 8]) @ + aes_sbox_inv(x[ 7.. 0]) +} + +/* + * AES full-round transformation functions. + */ + +val getbyte : (bits(64), int) -> bits(8) +function getbyte(x, i) = (x >> to_bits(6, i * 8))[7..0] + +val aes_rv64_shiftrows_fwd : (bits(64), bits(64)) -> bits(64) +function aes_rv64_shiftrows_fwd(rs2, rs1) = { + getbyte(rs1, 3) @ + getbyte(rs2, 6) @ + getbyte(rs2, 1) @ + getbyte(rs1, 4) @ + getbyte(rs2, 7) @ + getbyte(rs2, 2) @ + getbyte(rs1, 5) @ + getbyte(rs1, 0) +} + +val aes_rv64_shiftrows_inv : (bits(64), bits(64)) -> bits(64) +function aes_rv64_shiftrows_inv(rs2, rs1) = { + getbyte(rs2, 3) @ + getbyte(rs2, 6) @ + getbyte(rs1, 1) @ + getbyte(rs1, 4) @ + getbyte(rs1, 7) @ + getbyte(rs2, 2) @ + getbyte(rs2, 5) @ + getbyte(rs1, 0) +} + +/* 128-bit to 128-bit implementation of the forward AES ShiftRows transform. + * Byte 0 of state is input column 0, bits 7..0. + * Byte 5 of state is input column 1, bits 15..8. + */ +val aes_shift_rows_fwd : bits(128) -> bits(128) +function aes_shift_rows_fwd(x) = { + let ic3 : bits(32) = aes_get_column(x, 3); + let ic2 : bits(32) = aes_get_column(x, 2); + let ic1 : bits(32) = aes_get_column(x, 1); + let ic0 : bits(32) = aes_get_column(x, 0); + let oc0 : bits(32) = ic0[31..24] @ ic1[23..16] @ ic2[15.. 8] @ ic3[ 7.. 0]; + let oc1 : bits(32) = ic1[31..24] @ ic2[23..16] @ ic3[15.. 8] @ ic0[ 7.. 0]; + let oc2 : bits(32) = ic2[31..24] @ ic3[23..16] @ ic0[15.. 8] @ ic1[ 7.. 0]; + let oc3 : bits(32) = ic3[31..24] @ ic0[23..16] @ ic1[15.. 8] @ ic2[ 7.. 0]; + (oc3 @ oc2 @ oc1 @ oc0) /* Return value */ +} + +/* 128-bit to 128-bit implementation of the inverse AES ShiftRows transform. + * Byte 0 of state is input column 0, bits 7..0. + * Byte 5 of state is input column 1, bits 15..8. + */ +val aes_shift_rows_inv : bits(128) -> bits(128) +function aes_shift_rows_inv(x) = { + let ic3 : bits(32) = aes_get_column(x, 3); /* In column 3 */ + let ic2 : bits(32) = aes_get_column(x, 2); + let ic1 : bits(32) = aes_get_column(x, 1); + let ic0 : bits(32) = aes_get_column(x, 0); + let oc0 : bits(32) = ic0[31..24] @ ic3[23..16] @ ic2[15.. 8] @ ic1[ 7.. 0]; + let oc1 : bits(32) = ic1[31..24] @ ic0[23..16] @ ic3[15.. 8] @ ic2[ 7.. 0]; + let oc2 : bits(32) = ic2[31..24] @ ic1[23..16] @ ic0[15.. 8] @ ic3[ 7.. 0]; + let oc3 : bits(32) = ic3[31..24] @ ic2[23..16] @ ic1[15.. 8] @ ic0[ 7.. 0]; + (oc3 @ oc2 @ oc1 @ oc0) /* Return value */ +} + +/* Applies the forward sub-bytes step of AES to a 128-bit vector + * representation of its state. + */ +val aes_subbytes_fwd : bits(128) -> bits(128) +function aes_subbytes_fwd(x) = { + let oc0 : bits(32) = aes_subword_fwd(aes_get_column(x, 0)); + let oc1 : bits(32) = aes_subword_fwd(aes_get_column(x, 1)); + let oc2 : bits(32) = aes_subword_fwd(aes_get_column(x, 2)); + let oc3 : bits(32) = aes_subword_fwd(aes_get_column(x, 3)); + (oc3 @ oc2 @ oc1 @ oc0) /* Return value */ +} + +/* Applies the inverse sub-bytes step of AES to a 128-bit vector + * representation of its state. + */ +val aes_subbytes_inv : bits(128) -> bits(128) +function aes_subbytes_inv(x) = { + let oc0 : bits(32) = aes_subword_inv(aes_get_column(x, 0)); + let oc1 : bits(32) = aes_subword_inv(aes_get_column(x, 1)); + let oc2 : bits(32) = aes_subword_inv(aes_get_column(x, 2)); + let oc3 : bits(32) = aes_subword_inv(aes_get_column(x, 3)); + (oc3 @ oc2 @ oc1 @ oc0) /* Return value */ +} + +/* Applies the forward MixColumns step of AES to a 128-bit vector + * representation of its state. + */ +val aes_mixcolumns_fwd : bits(128) -> bits(128) +function aes_mixcolumns_fwd(x) = { + let oc0 : bits(32) = aes_mixcolumn_fwd(aes_get_column(x, 0)); + let oc1 : bits(32) = aes_mixcolumn_fwd(aes_get_column(x, 1)); + let oc2 : bits(32) = aes_mixcolumn_fwd(aes_get_column(x, 2)); + let oc3 : bits(32) = aes_mixcolumn_fwd(aes_get_column(x, 3)); + (oc3 @ oc2 @ oc1 @ oc0) /* Return value */ +} + +/* Applies the inverse MixColumns step of AES to a 128-bit vector + * representation of its state. + */ +val aes_mixcolumns_inv : bits(128) -> bits(128) +function aes_mixcolumns_inv(x) = { + let oc0 : bits(32) = aes_mixcolumn_inv(aes_get_column(x, 0)); + let oc1 : bits(32) = aes_mixcolumn_inv(aes_get_column(x, 1)); + let oc2 : bits(32) = aes_mixcolumn_inv(aes_get_column(x, 2)); + let oc3 : bits(32) = aes_mixcolumn_inv(aes_get_column(x, 3)); + (oc3 @ oc2 @ oc1 @ oc0) /* Return value */ +} +---- diff --git a/param_extraction/chunks/chunk_044.txt.license b/param_extraction/chunks/chunk_044.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_044.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_045.txt b/param_extraction/chunks/chunk_045.txt new file mode 100644 index 0000000000..5beac63fc4 --- /dev/null +++ b/param_extraction/chunks/chunk_045.txt @@ -0,0 +1,159 @@ +# Chunk: chunk_045 +# Source: smcdeleg.adoc +# Lines: 1-147 (of 147) +# Content starts: line 1 +# Line count: 147 +# Sections: 5 +# == "Smcdeleg/Ssccfg" Counter Delegation Extensions, Version 1.0 +# === Counter Delegation +# === Supervisor Counter Inhibit (`scountinhibit`) Register +# === Virtualizing `scountovf` +# === Virtualizing Local-Counter-Overflow Interrupts +# +[[smcdeleg]] +== "Smcdeleg/Ssccfg" Counter Delegation Extensions, Version 1.0 + +In modern “Rich OS” environments, hardware performance monitoring +resources are managed by the kernel, kernel driver, and/or hypervisor. +Counters may be configured with differing scopes, in some cases counting +events system-wide, while in others counting events on behalf of a +single virtual machine or application. In such environments, the latency +of counter writes has a direct impact on overall profiling overhead as a +result of frequent counter writes during: + +. Sample collection, to clear overflow indication, and reload overflowed +counter(s) +. Context switch, between processes, threads, containers, or virtual +machines + +These extensions provide a means for M-mode to allow writing select +counters and event selectors from S/HS-mode. The purpose is to avert +transitions to and from M-mode that add latency to these performance +critical supervisor/hypervisor code sections. These extensions also +defines one new CSR, scountinhibit. + +For a Machine-level environment, extension *Smcdeleg* (‘Sm’ for +Privileged architecture and Machine-level extension, ‘cdeleg’ for +Counter Delegation) encompasses all added CSRs and all behavior +modifications for a hart, over all privilege levels. For a +Supervisor-level environment, extension *Ssccfg* (‘Ss’ for Privileged +architecture and Supervisor-level extension, ‘ccfg’ for Counter +Configuration) provides access to delegated counters, and to new +supervisor-level state. For a RISC-V hardware platform, Smcdeleg and +Ssccfg must always be implemented in tandem. + +=== Counter Delegation + +The `mcounteren` register allows M-mode to provide the next-lower +privilege mode with read access to select counters. When the Smcdeleg/Ssccfg +extensions are enabled (`menvcfg`.CDE=1), it further allows M-mode to delegate select +counters to S-mode. + +The `siselect` (and `vsiselect`) index range 0x40-0x5F is reserved for +delegated counter access. When a counter _i_ is delegated +(`mcounteren`[_i_]=1 and `menvcfg`.CDE=1), the register state associated +with counter _i_ can be read or written via `sireg*`, while `siselect` holds +0x40+__i__. The counter state accessible via alias CSRs is shown in +the table below. + +.Indirect HPM State Mappings +[#indirect-hpm-state-mappings] +[width="100%",cols="21%,20%,21%,18%,20%",options="header",] +|=== +|*`siselect` value* |*`sireg*` |*`sireg4`* |*`sireg2`* |*`sireg5`* +|0x40 |`cycle`^1^ |`cycleh`^1^ |`cyclecfg`^14^ |`cyclecfgh`^14^ +|0x41 4+^|_See below_ +|0x42 |`instret`^1^ |`instreth`^1^ |`instretcfg`^14^ |`instretcfgh`^14^ +|0x43 |`hpmcounter3`^2^ |`hpmcounter3h`^2^ |`hpmevent3`^2^ |`hpmevent3h`^23^ +|… |… |… |… |… +|0x5F |`hpmcounter31`^2^ |`hpmcounter31h`^2^ |`hpmevent31`^2^ |`hpmevent31h`^23^ +|=== + +^1^ Depends on Zicntr support + +^2^ Depends on Zihpm support + +^3^ Depends on Sscofpmf support + +^4^ Depends on Smcntrpmf support + +`hpmevent__i__` may represent a subset of the state accessed by the `mhpmevent__i__` register. Specifically, if Sscofpmf is implemented, event selector bit +62 (MINH) is read-only 0 when accessed through `sireg*`. + +Likewise, `cyclecfg` and `instretcfg` may represent a subset of the state accessed by the `mcyclecfg` and `minstretcfg` registers, respectively. If +Smcntrpmf is implemented, counter configuration register bit 62 (MINH) is read-only 0 when accessed through `sireg*`. + +If extension Smstateen is implemented, refer to extensions Smcsrind/Sscsrind (<>) for how setting bit 60 of CSR +`mstateen0` to zero prevents access to registers `siselect`, `sireg*`, +`vsiselect`, and `vsireg*` from privileged modes less privileged than +M-mode, and likewise how setting bit 60 of `hstateen0` to zero prevents +access to `siselect` and `sireg*` (really `vsiselect` and `vsireg*`) from +VS-mode. + +The remaining rules of this section apply only when access to a CSR is +not blocked by `mstateen0`[60] = 0 or `hstateen0`[60] = 0. + +While the privilege mode is M or S and `siselect` holds a value in the +range 0x40-0x5F, illegal-instruction exceptions are raised for the +following cases: + +* attempts to access any `sireg*` when `menvcfg`.CDE = 0; +* attempts to access `sireg3` or `sireg6`; +* attempts to access `sireg4` or `sireg5` when XLEN = 64; +* attempts to access `sireg*` when `siselect` = 0x41, or when the counter +selected by `siselect` is not delegated to S-mode (the corresponding bit +in `mcounteren` = 0). + +NOTE: _The memory-mapped `mtime` register is not a performance monitoring +counter to be managed by supervisor software, hence the special +treatment of `siselect` value 0x41 described above._ + +For each `siselect` and `sireg*` combination defined in <>, the table +further indicates the extensions upon which the underlying counter state +depends. If any extension upon which the underlying state depends is not +implemented, an attempt from M or S mode to access the given state +through `sireg*` raises an illegal-instruction exception. + +If the hypervisor (H) extension is also implemented, then as specified +by extensions Smcsrind/Sscsrind, a virtual-instruction exception is +raised for attempts from VS-mode or VU-mode to directly access `vsiselect` +or `vsireg*`, or attempts from VU-mode to access `siselect` or `sireg*`. Furthermore, while `vsiselect` holds a value in the range 0x40-0x5F: + +* An attempt to access any `vsireg*` from M or S mode raises an illegal-instruction exception. +* An attempt from VS-mode to access any `sireg*` (really `vsireg*`) raises an illegal-instruction exception if `menvcfg`.CDE = 0, or a +virtual-instruction exception if `menvcfg`.CDE = 1. + +=== Supervisor Counter Inhibit (`scountinhibit`) Register + +Smcdeleg/Ssccfg defines a new `scountinhibit` register, a masked alias of +`mcountinhibit`. For counters delegated to S-mode, the associated +`mcountinhibit` bits can be accessed via `scountinhibit`. For counters not +delegated to S-mode, the associated bits in `scountinhibit` are read-only +zero. + +When `menvcfg`.CDE=0, attempts to access `scountinhibit` raise an illegal-instruction +exception. When Supervisor Counter Delegation +is enabled, attempts to access `scountinhibit` from VS-mode or VU-mode +raise a virtual-instruction exception. + +=== Virtualizing `scountovf` + +For implementations that support Smcdeleg/Ssccfg, Sscofpmf, and the H +extension, when `menvcfg`.CDE=1, attempts to read `scountovf` from VS-mode +or VU-mode raise a virtual-instruction exception. + +=== Virtualizing Local-Counter-Overflow Interrupts + +For implementations that support Smcdeleg, Sscofpmf, and Smaia, the +local-counter-overflow interrupt (LCOFI) bit (bit 13) in each of CSRs +`mvip` and `mvien` is implemented and writable. + +For implementations that support Smcdeleg/Ssccfg, Sscofpmf, +Smaia/Ssaia, and the H extension, the LCOFI bit (bit 13) in each of `hvip` +and `hvien` is implemented and writable. + +[NOTE] +==== +_The `hvip` register is defined by the hypervisor (H) extension, while the `mvien` and `hvien` registers are defined by the Smaia/Ssaia extensions._ + +_By virtue of implementing `hvip`.LCOFI, it is implicit that the LCOFI bit (bit 13) in each of `vsie` and `vsip` is also implemented._ + +_Requiring support for the LCOFI bits listed above ensures that virtual LCOFIs can be delivered to an OS running in S-mode, and to a guest OS running in VS-mode. It is optional whether the LCOFI bit (bit 13) in each of `mideleg` and `hideleg`, which allows all LCOFIs to be delegated to S-mode and VS-mode, respectively, is implemented and writable._ +==== diff --git a/param_extraction/chunks/chunk_045.txt.license b/param_extraction/chunks/chunk_045.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_045.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_046.txt b/param_extraction/chunks/chunk_046.txt new file mode 100644 index 0000000000..9385e6ed25 --- /dev/null +++ b/param_extraction/chunks/chunk_046.txt @@ -0,0 +1,81 @@ +# Chunk: chunk_046 +# Source: smcntrpmf.adoc +# Lines: 1-69 (of 69) +# Content starts: line 1 +# Line count: 69 +# Sections: 5 +# == "Smcntrpmf" Cycle and Instret Privilege Mode Filtering, Version 1.0 +# === Introduction +# === CSRs +# ==== Machine Counter Configuration (`mcyclecfg`, `minstretcfg`) Registers +# === Counter Behavior +# +[[smcntrpmf]] + +== "Smcntrpmf" Cycle and Instret Privilege Mode Filtering, Version 1.0 + +=== Introduction + +The cycle and instret counters serve to support user mode self-profiling usages, wherein a user can read the counter(s) twice and compute the delta(s) to evaluate user software performance and behavior. By default, these counters are not filtered by privilege mode, and thus they continue to increment while traps (e.g., page faults or interrupts) to more privileged code are handled. This causes two problems: + +* It introduces unpredictable noise to the counter values observed by the user. +* It leaks information about privileged software execution to user mode. + +Smcntrpmf remedies these issues by introducing privilege mode filtering for the cycle and instret counters. + +=== CSRs + +==== Machine Counter Configuration (`mcyclecfg`, `minstretcfg`) Registers + +mcyclecfg and minstretcfg are 64-bit registers that configure privilege mode filtering for the cycle and instret counters, respectively. + +[cols="^1,^1,^1,^1,^1,^1,^5",stripes=even,options="header"] +|==== +|63 |62 |61 |60 |59 |58 |57:0 +|0 |MINH |SINH |UINH |VSINH |VUINH |_WPRI_ +|==== + +[cols="15%,85%",options="header"] +|==== +| Field | Description +| MINH | If set, then counting of events in M-mode is inhibited +| SINH | If set, then counting of events in S/HS-mode is inhibited +| UINH | If set, then counting of events in U-mode is inhibited +| VSINH | If set, then counting of events in VS-mode is inhibited +| VUINH | If set, then counting of events in VU-mode is inhibited +|==== + +When all __x__INH bits are zero, event counting is enabled in all modes. + +For each bit in 61:58, if the associated privilege mode is not implemented, the bit is read-only zero. + +For RV32, bits 63:32 of mcyclecfg can be accessed via the mcyclecfgh CSR, and bits 63:32 of minstretcfg can be accessed via the minstretcfgh CSR. + +The content of these registers may be accessible from Supervisor level if the Smcdeleg/Ssccfg extensions are implemented. + +[NOTE] +==== +The more natural CSR number for mcyclecfg would be 0x320, but that was allocated to mcountinhibit. + +This register format matches that specified for programmable counters by Sscofpmf. The bit position for the OF bit (bit 63) is read-only 0, since these counters do not generate local-counter-overflow interrupts on overflow. +==== + +=== Counter Behavior + +The fundamental behavior of cycle and instret is modified in that counting does not occur while executing in an inhibited privilege mode. Further, the following defines how transitions between a non-inhibited privilege mode and an inhibited privilege mode are counted. + +The cycle counter will simply count CPU cycles while the CPU is in a non-inhibited privilege mode. Mode transition operations (traps and trap returns) may take multiple clock cycles, and the change of privilege mode may be reported as occurring in any one of those cycles (possibly different for each occurrence of a trap or trap return). + +[NOTE] +==== +The RISC-V ISA has no requirement that the number of cycles for a trap or trap return be the same for all occurrences. Implementations are free to determine the extent to which this number may be consistent and predictable (or not), and the same is true for the specific cycle in which privilege mode changes. +==== + +For the instret counter, most instructions do not affect mode transitions, so for those the behavior is clear: instructions that retire in a non-inhibited mode increment instret, and instructions that retire in an inhibited mode do not. There are two types of instructions that can affect a privilege mode change: instructions that cause synchronous exceptions to a more privileged mode, and xRET instructions that return to a less privileged mode. The former are not considered to retire, and hence do not increment instret. The latter do retire, and should increment instret only if the originating privilege mode is not inhibited. + +[NOTE] +==== +The instret definition above is intended to ensure that the counter increments in a predictable fashion. For example, consider a scenario where minstretcfg is configured such that all modes other than U-mode are inhibited. A user mode load should increment only once, even if it takes a page fault or other exception. With this definition, the faulting execution of the load will not increment (it does not retire), the handler instructions will not increment (they execute in an inhibited mode), including the xRET (it arguably retires in a non-inhibited mode, but it originates in an inhibited mode). Only once the load is re-executed and retires will it increment instret. + +In cases where an instruction is emulated by software running in a privilege mode that is inhibited in minstretcfg, the emulation routine must emulate the instret increment. +==== diff --git a/param_extraction/chunks/chunk_046.txt.license b/param_extraction/chunks/chunk_046.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_046.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_047.txt b/param_extraction/chunks/chunk_047.txt new file mode 100644 index 0000000000..332116419c --- /dev/null +++ b/param_extraction/chunks/chunk_047.txt @@ -0,0 +1,780 @@ +# Chunk: chunk_047 +# Source: smctr.adoc +# Lines: 1-763 (of 763) +# Content starts: line 1 +# Line count: 763 +# Sections: 10 +# == "Smctr" Control Transfer Records Extension, Version 1.0 +# === CSRs +# ==== Machine Control Transfer Records Control Register (`mctrctl`) +# ==== Supervisor Control Transfer Records Control Register (`sctrctl`) +# ==== Virtual Supervisor Control Transfer Records Control Register (`vsctrctl`) +# ==== Supervisor Control Transfer Records Depth Register (`sctrdepth`) +# ==== Supervisor Control Transfer Records Status Register (`sctrstatus`) +# === Entry Registers +# ==== Control Transfer Record Source Register (`ctrsource`) +# ==== Control Transfer Record Target Register (`ctrtarget`) +# +[[smctr]] + +== "Smctr" Control Transfer Records Extension, Version 1.0 + +A method for recording control flow transfer history is valuable not only for performance profiling but also for debugging. Control flow transfers refer to jump instructions (including function calls and returns), taken branch instructions, traps, and trap returns. Profiling tools, such as Linux perf, collect control transfer history when sampling software execution, thereby enabling tools, like AutoFDO, to identify hot paths for optimization. + +Control flow trace capabilities offer very deep transfer history, but the volume of data produced can result in significant performance overheads due to memory bandwidth consumption, buffer management, and decoder overhead. The Control Transfer Records (CTR) extension provides a method to record a limited history in register-accessible internal chip storage, with the intent of dramatically reducing the performance overhead and complexity of collecting transfer history. + +CTR defines a circular (FIFO) buffer. Each buffer entry holds a record for a single recorded control flow transfer. [#norm:CTR_DEPTH]#The number of records that can be held in the buffer depends upon both the implementation (the maximum supported depth) and the CTR configuration (the software selected depth).# + +[#norm:Smctr_recording_criteria]#Only qualified transfers are recorded. Qualified transfers are those that meet the filtering criteria, which include the privilege mode and the transfer type.# + +[#norm:Smctr_transfer_steps]#Recorded transfers are inserted at the write pointer, which is then incremented, while older recorded transfers may be overwritten once the buffer is full. Or the user can enable RAS (Return Address Stack) emulation mode, where only function calls are recorded, and function returns pop the last call record. The source PC, target PC, and some optional metadata (transfer type, elapsed cycles) are stored for each recorded transfer.# + +[#norm:Smctr_CTR_CSR_interface]#The CTR buffer is accessible through an indirect CSR interface, such that software can specify which logical entry in the buffer it wishes to read or write. Logical entry 0 always corresponds to the youngest recorded transfer, followed by entry 1 as the next youngest, and so on.# + +[#norm:Smctr_scope]#The machine-level extension, *Smctr*, encompasses all newly added Control Status Registers (CSRs), instructions, and behavior modifications for a hart across all privilege levels.# [#norm:Ssctr_transfer_steps]#The corresponding supervisor-level extension, *Ssctr*, is essentially identical to Smctr, except that it excludes machine-level CSRs and behaviors not intended to be directly accessible at the supervisor level.# + +[#norm:Smctr_Ssctr_depend]#Smctr and Ssctr depend on both the implementation of S-mode and the Sscsrind extension.# + +=== CSRs + +==== Machine Control Transfer Records Control Register (`mctrctl`) + +[#norm:Ssctr_mctrctl-sz_acc_op]#The `mctrctl` register is a 64-bit read/write register that enables and configures the CTR capability.# + +.Machine Control Transfer Records Control Register Format +[%unbreakable] +[wavedrom, , svg] +.... +{reg: [ + {bits: 1, name: 'U'}, + {bits: 1, name: 'S'}, + {bits: 1, name: 'M'}, + {bits: 4, name: 'WPRI'}, + {bits: 1, name: 'RASEMU'}, + {bits: 1, name: 'STE'}, + {bits: 1, name: 'MTE'}, + {bits: 1, name: 'WPRI'}, + {bits: 1, name: 'BPFRZ'}, + {bits: 1, name: 'LCOFIFRZ'}, + {bits: 20, name: 'WPRI'}, + {bits: 1, name: 'EXCINH'}, + {bits: 1, name: 'INTRINH'}, + {bits: 1, name: 'TRETINH'}, + {bits: 1, name: 'NTBREN'}, + {bits: 1, name: 'TKBRINH'}, + {bits: 2, name: 'WPRI'}, + {bits: 1, name: 'INDCALLINH'}, + {bits: 1, name: 'DIRCALLINH'}, + {bits: 1, name: 'INDJMPINH'}, + {bits: 1, name: 'DIRJMPINH'}, + {bits: 1, name: 'CORSWAPINH'}, + {bits: 1, name: 'RETINH'}, + {bits: 1, name: 'INDLJMPINH'}, + {bits: 1, name: 'DIRLJMPINH'}, + {bits: 12, name: 'WPRI'}, + {bits: 4, name: 'Custom'}, +], config:{lanes: 8, hspace:1024}} +.... + +.Machine Control Transfer Records Control Register Field Definitions +[%unbreakable] +[width="100%",cols="20%,80%",options="header",] +|=== +|Field |Description +|M, S, U |[#norm:mctrctl-mode_op]#Enable transfer recording in the selected privileged mode(s).# + +|RASEMU |[#norm:mctrctl-rasemu_op]#Enables RAS (Return Address Stack) Emulation Mode.# See <>. + +|MTE |[#norm:mctrctl-mte_op]#Enables recording of traps to M-mode when M=0.# See <>. + +|STE |[#norm:mctrctl-ste_op]#Enables recording of traps to S-mode when S=0.# See <>. + +|BPFRZ |[#norm:mctrctl-bpfrz_op]#Set `sctrstatus`.FROZEN on a breakpoint exception that traps to M-mode or S-mode.# See <>. + +|LCOFIFRZ |[#norm:mctrctl-lcofifrz_op]#Set `sctrstatus`.FROZEN on local-counter-overflow interrupt (LCOFI) that traps to M-mode or S-mode.# See <>. + +|EXCINH |[#norm:mctrctl-excinh_op]#Inhibit recording of exceptions.# See <>. + +|INTRINH |[#norm:mctrctl-intrinh_op]#Inhibit recording of interrupts.# See <>. + +|TRETINH |[#norm:mctrctl-tretinh_op]#Inhibit recording of trap returns.# See <>. + +|NTBREN |[#norm:mctrctl-ntbren_op]#Enable recording of not-taken branches.# See <>. + +|TKBRINH |[#norm:mctrctl-tkbrinh_op]#Inhibit recording of taken branches.# See <>. + +|INDCALLINH |[#norm:mctrctl-indcallinh_op]#Inhibit recording of indirect calls.# See <>. + +|DIRCALLINH |[#norm:mctrctl-dircallinh_op]#Inhibit recording of direct calls.# See <>. + +|INDJMPINH |[#norm:mctrctl-indjmpinh_op]#Inhibit recording of indirect jumps (without linkage).# See <>. + +|DIRJMPINH |[#norm:mctrctl-dirjmpinh_op]#Inhibit recording of direct jumps (without linkage).# See <>. + +|CORSWAPINH |[#norm:mctrctl-corswapinh_op]#Inhibit recording of co-routine swaps.# See <>. + +|RETINH |[#norm:mctrctl-retinh_op]#Inhibit recording of function returns.# See <>. + +|INDLJMPINH |[#norm:mctrctl-indljmpinh_op]#Inhibit recording of other indirect jumps (with linkage).# See <>. + +|DIRLJMPINH |[#norm:mctrctl-dirljmpinh_op]#Inhibit recording of other direct jumps (with linkage).# See <>. +|Custom[3:0] | [#norm:mctrctl-custom_op]#WARL bits designated for custom use.# The value 0 must correspond to standard behavior. See <>. +|=== + +[%unbreakable] +-- +[#norm:mctrctl-impl]#All fields are optional except for M, S, U, and BPFRZ. All unimplemented fields are read-only 0, while all implemented fields are writable. If the Sscofpmf extension is implemented, LCOFIFRZ must be writable.# +-- + +[NOTE] +==== +_Because the ROI of CTR is perceived to be low for RV32 implementations, CTR does not fully support RV32. While control flow transfers in RV32 can be recorded, RV32 cannot access_ `x__ctrctl__` _bits 63:32. A future extension could add support for RV32 by adding 3 new CSRs (`mctrctlh`, `sctrctlh`, and `vsctrctlh`) to provide this access._ +==== + +==== Supervisor Control Transfer Records Control Register (`sctrctl`) + +[#norm:Ssctr_sctrctl_op]#The `sctrctl` register provides supervisor mode access to a subset of `mctrctl`.# + +[#norm:Ssctr_sctrctl_acc]#Bits 2 and 9 in `sctrctl` are read-only 0. As a result, the M and MTE fields in `mctrctl` are not accessible through `sctrctl`. All other `mctrctl` fields are accessible through `sctrctl`.# + +==== Virtual Supervisor Control Transfer Records Control Register (`vsctrctl`) + +[#norm:Ssctr_vsctrctl_sz_acc_op]#If the H extension is implemented, the `vsctrctl` register is a 64-bit read/write register that is VS-mode's version of supervisor register `sctrctl`. When V=1, `vsctrctl` substitutes for the usual `sctrctl`, so instructions that normally read or modify `sctrctl` actually access `vsctrctl` instead.# + +.Virtual Supervisor Control Transfer Records Control Register Format +[%unbreakable] +[wavedrom, , svg] +.... +{reg: [ + {bits: 1, name: 'U'}, + {bits: 1, name: 'S'}, + {bits: 5, name: 'WPRI'}, + {bits: 1, name: 'RASEMU'}, + {bits: 1, name: 'STE'}, + {bits: 2, name: 'WPRI'}, + {bits: 1, name: 'BPFRZ'}, + {bits: 1, name: 'LCOFIFRZ'}, + {bits: 20, name: 'WPRI'}, + {bits: 1, name: 'EXCINH'}, + {bits: 1, name: 'INTRINH'}, + {bits: 1, name: 'TRETINH'}, + {bits: 1, name: 'NTBREN'}, + {bits: 1, name: 'TKBRINH'}, + {bits: 2, name: 'WPRI'}, + {bits: 1, name: 'INDCALLINH'}, + {bits: 1, name: 'DIRCALLINH'}, + {bits: 1, name: 'INDJMPINH'}, + {bits: 1, name: 'DIRJMPINH'}, + {bits: 1, name: 'CORSWAPINH'}, + {bits: 1, name: 'RETINH'}, + {bits: 1, name: 'INDLJMPINH'}, + {bits: 1, name: 'DIRLJMPINH'}, + {bits: 12, name: 'WPRI'}, + {bits: 4, name: 'Custom'}, +], config:{lanes: 8, hspace:1024}} +.... + +.Virtual Supervisor Control Transfer Records Control Register Field Definitions +[%unbreakable] +[width="100%",cols="20%,80%",options="header",] +|=== +|Field |Description +|S |[#norm:vsctr-s_op]#Enable transfer recording in VS-mode.# +|U |[#norm:vsctrctl-u_op]#Enable transfer recording in VU-mode.# +|STE |[#norm:vsctrctl-ste_op]#Enables recording of traps to VS-mode when S=0.# See <>. +|BPFRZ |[#norm:vsctrctl-bpfrz_op]#Set `sctrstatus`.FROZEN on a breakpoint exception that traps to VS-mode.# See <>. +|LCOFIFRZ |[#norm:vsctrctl-lcofifrz_op]#Set `sctrstatus`.FROZEN on local-counter-overflow interrupt (LCOFI) that traps to VS-mode.# See <>. +2+|Other field definitions match those of `sctrctl`. The optional fields implemented in `vsctrctl` should match those implemented in `sctrctl`. +|=== + +[NOTE] +[%unbreakable] +==== +_Unlike the CTR status register or the CTR entry registers, the CTR control register has a VS-mode version. This allows a guest to manage the CTR configuration directly, without requiring traps to HS-mode, while ensuring that the guest configuration (most notably the privilege mode enable bits) do not impact CTR behavior when V=0._ +==== + +==== Supervisor Control Transfer Records Depth Register (`sctrdepth`) + +[#norm:sctrdepth] +The 32-bit `sctrdepth` register specifies the depth of the CTR buffer. + +.Supervisor Control Transfer Records Depth Register Format +[%unbreakable] +[wavedrom, , svg] +.... +{reg: [ + {bits: 3, name: 'DEPTH'}, + {bits: 29, name: 'WPRI'}, +], config:{lanes: 1, hspace:1024}} +.... + +.Supervisor Control Transfer Records Depth Register Field Definitions +[%unbreakable] +[width="100%",cols="15%,85%",options="header",] +|=== +|Field |Description +|DEPTH |[#norm:sctrdepth-depth_op0]#WARL field that selects the depth of the CTR buffer.# Encodings: + +‘000 - 16 + +‘001 - 32 + +‘010 - 64 + +‘011 - 128 + +‘100 - 256 + +'11x - reserved + +[#norm:sctrdepth-depth_op1]#The depth of the CTR buffer dictates the number of entries to which the hardware records transfers. For a depth of N, the hardware records transfers to entries 0..N-1. All <<_entry_registers, Entry Registers>> read as '0' and are read-only when the selected entry is in the range N to 255. When the depth is increased, the newly accessible entries contain unspecified but legal values.# + +[#norm:sctrdepth-depth_param]#It is implementation-specific which DEPTH value(s) are supported.# +|=== + +[#norm:sctrdepth_mode]#Attempts to access `sctrdepth` from VS-mode or VU-mode raise a virtual-instruction exception, unless CTR state enable access restrictions apply.# See <>. + +[NOTE] +[%unbreakable] +==== +_It is expected that operating systems (OSs) will access `sctrdepth` only at boot, to select the maximum supported depth value. More frequent accesses may result in reduced performance in virtualization scenarios, as a result of traps from VS-mode incurred._ + +_There may be scenarios where software chooses to operate on only a subset of the entries, to reduce overhead. In such cases tools may choose to read only the lower entries, and OSs may choose to save/restore only on the lower entries while using SCTRCLR to clear the others._ + +_The value in configurable depth lies in supporting VM migration. It is expected that a platform spec may specify that one or more CTR depth values must be supported. A hypervisor may wish to restrict guests to using one of these required depths, in order to ensure that such guests can be migrated to any system that complies with the platform spec. The trapping behavior specified for VS-mode accesses to `sctrdepth` ensures that the hypervisor can impose such restrictions._ +==== + +==== Supervisor Control Transfer Records Status Register (`sctrstatus`) + +[#norm:sctrstatus]#The 32-bit `sctrstatus` register grants access to CTR status information and is updated by the hardware whenever CTR is active. CTR is active when the current privilege mode is enabled for recording and CTR is not frozen.# + +.Supervisor Control Transfer Records Status Register Format +[%unbreakable] +[wavedrom, , svg] +.... +{reg: [ + {bits: 8, name: 'WRPTR'}, + {bits: 23, name: 'WPRI'}, + {bits: 1, name: 'FROZEN'}, +], config:{lanes: 2, hspace:1024}} +.... + +.Supervisor Control Transfer Records Status Register Field Definitions +[%unbreakable] +[width="100%",cols="15%,85%",options="header",] +|=== +|Field |Description +|WRPTR |[#norm:sctrstatus-wrptr]#WARL field that indicates the physical CTR buffer entry to be written next. It is incremented after new transfers are recorded (see <>), though there are exceptions when `__x__ctrctl`.RASEMU=1, see <>. For a given CTR depth (where depth = 2^(DEPTH+4)^), WRPTR wraps to 0 on an increment when the value matches depth-1, and to depth-1 on a decrement when the value is 0. Bits above those needed to represent depth-1 (e.g., bits 7:4 for a depth of 16) are read-only 0. On depth changes, WRPTR holds an unspecified but legal value.# +|FROZEN |[#norm:sctrstatus-frozen_op]#Inhibit transfer recording.# See <>. +|=== + +[#norm:Ssctr_sctrstatus_acc]#Undefined bits in `sctrstatus` are WPRI. Status fields may be added by future extensions, +and software should ignore but preserve any fields that it does not recognize. Undefined bits must be implemented as read-only 0, unless a custom extension is implemented and enabled# (see <>). + +[NOTE] +[%unbreakable] +==== +_Logical entry 0, accessed via `sireg*` when `siselect`=0x200, is always the physical buffer entry preceding the WRPTR entry. More generally, the physical buffer entry Y associated with logical entry X (X < depth) can be determined using the formula Y = (WRPTR - X - 1) % depth, where depth = 2^(DEPTH+4)^. Logical entries >= depth are read-only 0._ +==== +[NOTE] +[%unbreakable] +==== +_Because the `sctrstatus` register is updated by hardware, writes should be performed with caution. If a multi-instruction read-modify-write to `sctrstatus` is performed while CTR is active, and between the read and write a qualified transfer or trap that causes CTR freeze completes, a hardware update could be lost. Software may wish to ensure that CTR is inactive before performing a read-modify-write, by ensuring that either `sctrstatus`.FROZEN=1, or that the current privilege mode is not enabled for recording._ + +_When restoring CTR state, `sctrstatus` should be written before CTR entry state is restored. This ensures that the software writes to logical CTR entries modify the proper physical entries._ +==== + +[NOTE] +[%unbreakable] +==== +_Exposing the WRPTR provides a more efficient means for synthesizing CTR entries. If a qualified control transfer is emulated, the emulator can simply increment the WRPTR, then write the synthesized record to logical entry 0. If a qualified function return is emulated while RASEMU=1, the emulator can clear `ctrsource`.V for logical entry 0, then decrement the WRPTR._ + +_Exposing the WRPTR may also allow support for Linux perf's https://lwn.net/Articles/802821[[.underline]#stack stitching#] capability._ +==== + +[NOTE] +[%unbreakable] +==== +_Smctr/Ssctr depends upon implementation of S-mode because much of CTR state is accessible only through S-mode CSRs. If, in the future, it becomes desirable to remove this dependency, an extension could add `mctrdepth` and `mctrstatus` CSRs that reflect the same state as `sctrdepth` and `sctrstatus`, respectively. Further, such an extension should make CTR entries accessible via `miselect`/`mireg*`. See <>._ +==== + +=== Entry Registers + +Control transfer records are stored in a CTR buffer, such that each buffer entry stores information about a single transfer. The CTR buffer entries are logically accessed via the indirect register access mechanism defined by the Sscsrind extension. [#norm:siselect_acc_op]#The `siselect` index range 0x200 through 0x2FF is reserved for CTR logical entries 0 through 255. When `siselect` holds a value in this range, `sireg` provides access to `ctrsource`, `sireg2` provides access to `ctrtarget`, and `sireg3` provides access to `ctrdata`. `sireg4`, `sireg5`, and `sireg6` are read-only 0.# + +[#norm:vsiselect_op]#When `vsiselect` holds a value in 0x200..0x2FF, the `vsireg*` registers provide access to the same CTR entry register state as the analogous `sireg*` registers. There is not a separate set of entry registers for V=1.# + +See <> for cases where CTR accesses from S-mode and VS-mode may be restricted. + +==== Control Transfer Record Source Register (`ctrsource`) + +[#norm:ctrsource_op]#The `ctrsource` register contains the source program counter, which is the `pc` of the recorded control transfer instruction, or the epc of the recorded trap.# [#norm:ctrsource_ctrtartget_ctrdata_Vbit]#The valid (V) bit is set by the hardware when a transfer is recorded in the selected CTR buffer entry, and implies that data in `ctrsource`, `ctrtarget`, and `ctrdata` is valid for this entry.# + +[#norm:Ssctr_ctrsource_sz_acc_op]#`ctrsource` is an MXLEN-bit WARL register that must be able to hold all valid virtual or physical addresses that can serve as a `pc`. It need not be able to hold any invalid addresses; implementations may convert an invalid address into a valid address that the register is capable of holding. When XLEN < MXLEN, both explicit writes (by software) and implicit writes (for recorded transfers) will be zero-extended.# + +.Control Transfer Record Source Register Format for MXLEN=64 +[%unbreakable] +[wavedrom, , svg] +.... +{reg: [ + {bits: 1, name: 'V'}, + {bits: 63, name: 'PC[63:1]'}, +], config:{lanes: 1, hspace: 1024}} +.... + +[NOTE] +[%unbreakable] +==== +_CTR entry registers are defined as MXLEN, despite the_ `x__ireg*__` _CSRs used to access them being XLEN, to ensure that entries recorded in RV64 are not truncated, as a result of CSR Width Modulation, on a transition to RV32._ +==== + +==== Control Transfer Record Target Register (`ctrtarget`) + +[#norm:ctrtarget_op]#The `ctrtarget` register contains the target (destination) program counter +of the recorded transfer.# +[#norm:ctrtarget_pc_next_br]#For a not-taken branch, `ctrtarget` holds the PC of the next sequential instruction following the branch.# +[#norm:ctrtarget_misp]#The optional MISP bit is set by the hardware +when the recorded transfer is an instruction whose target or +taken/not-taken direction was mispredicted by the branch predictor. MISP +is read-only 0 when not implemented.# + +[#norm:ctrtarget_sz_acc]#`ctrtarget` is an MXLEN-bit WARL register that must be able to hold all valid virtual or physical addresses that can serve as a `pc`. It need not be able to hold any invalid addresses; implementations may convert an invalid address into a valid address that the register is capable of holding. When XLEN < MXLEN, both explicit writes (by software) and implicit writes (by recorded transfers) will be zero-extended.# + +.Control Transfer Record Target Register Format for MXLEN=64 +[%unbreakable] +[wavedrom, , svg] +.... +{reg: [ + {bits: 1, name: 'MISP'}, + {bits: 31, name: 'PC[31:1]'}, + {bits: 32, name: 'PC[63:32]'}, +], config:{lanes: 2, hspace: 1024}} +.... + +==== Control Transfer Record Metadata Register (`ctrdata`) + +[#norm:ctrdata_sz_acc]#The `ctrdata` register contains metadata for the recorded transfer. This +register must be implemented, though all fields within it are optional. +Unimplemented fields are read-only 0. `ctrdata` is a 64-bit register.# + +.Control Transfer Record Metadata Register Format +[%unbreakable] +[wavedrom, , svg] +.... +{reg: [ + {bits: 4, name: 'TYPE'}, + {bits: 11, name: 'WPRI'}, + {bits: 1, name: 'CCV'}, + {bits: 16, name: 'CC'}, + {bits: 32, name: 'WPRI'}, +], config:{lanes: 2, hspace: 1024}} +.... + +.Control Transfer Record Metadata Register Field Definitions +[%unbreakable] +[width="100%",cols="15%,75%,10%",options="header",] +|=== +|Field |Description |Access +|TYPE[3:0] a| +[#norm:ctrdata-type]#Identifies the type of the control flow transfer recorded in the entry, using the encodings listed in xref:transfer-type-defs[xrefstyle=short]. Implementations that do not support this field will report 0.# +|WARL + +|CCV |[#norm:ctrdata-ccv]#Cycle Count Valid.# See <>. |WARL + +|CC[15:0] |[#norm:ctrdata-cc]#Cycle Count, composed of the Cycle Count Exponent (CCE, in +CC[15:12]) and Cycle Count Mantissa (CCM, in CC[11:0]).# See +<>. |WARL +|=== + +[#norm:ctrdata_undef]#Undefined bits in `ctrdata` are WPRI. Undefined bits must be implemented as read-only 0, unless a <<_custom_extensions, custom extension>> is implemented and enabled.# + +[NOTE] +[%unbreakable] +==== +_Like the <<_transfer_type_filtering, Transfer Type Filtering>> bits in `mctrctl`, the `ctrdata`.TYPE bits leverage the E-trace itype encodings._ +==== + +=== Instructions +==== Supervisor CTR Clear Instruction + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'SYSTEM'], type: 8}, + {bits: 5, name: 'rd', attr: ['5', '0'], type: 2}, + {bits: 3, name: 'funct3', attr: ['3', '0'], type: 8}, + {bits: 5, name: 'rs1', attr: ['5', '0'], type: 4}, + {bits: 12, name: 'func12', attr: ['12', 'SCTRCLR (0x104)'], type: 8}, +]} +.... + +The SCTRCLR instruction performs the following operations: + +* [#norm:sctrclr_op1]#Zeroes all CTR <<_entry_registers, Entry Registers>>, for all DEPTH values# +* [#norm:sctrclr_op2]#Zeroes the CTR cycle counter and CCV# (see <>) + +[#norm:sctrclr_acc]#Any read of `ctrsource`, `ctrtarget`, or `ctrdata` that follows SCTRCLR, such that it precedes the next qualified control transfer, will return the value 0. Further, the first recorded transfer following SCTRCLR will have `ctrdata`.CCV=0.# + +[#norm:sctrclr_exceptions]#SCTRCLR raises an illegal-instruction exception in U-mode, and a virtual-instruction exception in VU-mode, unless CTR state enable access restrictions apply.# See <>. + +=== State Enable Access Control + +When Smstateen is implemented, the `mstateen0`.CTR bit controls access to CTR register state from privilege modes less privileged than M-mode. [#norm:mstateen_ctr1]#When `mstateen0`.CTR=1, accesses to CTR register state behave as described in <> and <> above, while SCTRCLR behaves as described in <>.# [#norm:mstateen_ctr0]#When `mstateen0`.CTR=0 and the privilege mode is less privileged than M-mode, the following operations raise an illegal-instruction exception:# + +* [#norm:mstateen_ctr0_execpt1]#Attempts to access `sctrctl`, `vsctrctl`, `sctrdepth`, or `sctrstatus`# +* [#norm:mstateen_ctr0_execpt2]#Attempts to access `sireg*` when `siselect` is in 0x200..0x2FF, or `vsireg*` when `vsiselect` is in 0x200..0x2FF# +* [#norm:mstateen_ctr0_execpt3]#Execution of the SCTRCLR instruction# + +[#norm:mstateen_ctr0_qualified_transfer]#When `mstateen0`.CTR=0, qualified control transfers executed in privilege modes less privileged than M-mode will continue to implicitly update entry registers and `sctrstatus`.# + +[#norm:hstateen_ctr]#If the H extension is implemented and `mstateen0`.CTR=1, the `hstateen0`.CTR bit controls access to supervisor CTR state when V=1. This state includes `sctrctl` (really `vsctrctl`), `sctrstatus`, and `sireg*` (really `vsireg*`) when `siselect` (really `vsiselect`) is in 0x200..0x2FF. `hstateen0`.CTR is read-only 0 when `mstateen0`.CTR=0.# + +[#norm:hstateen_vs]#When `mstateen0`.CTR=1 and `hstateen0`.CTR=1, VS-mode accesses to supervisor CTR state behave as described in <> and <> above, while SCTRCLR behaves as described in <>. When `mstateen0`.CTR=1 and `hstateen0`.CTR=0, both VS-mode accesses to supervisor CTR state and VS-mode execution of SCTRCLR raise a virtual-instruction exception.# + +[NOTE] +[%unbreakable] +==== +`__sctrdepth__` _is not included in the above list of supervisor CTR state controlled by `hstateen0`.CTR since accesses to `sctrdepth` from VS-mode raise a virtual-instruction exception regardless of the value of `hstateen0`.CTR._ +==== + +[#norm:hstateen0_CTR0-V1_op]#When `hstateen0`.CTR=0, qualified control transfers executed while V=1 will continue to implicitly update entry registers and `sctrstatus`.# + +[NOTE] +[%unbreakable] +==== +_See <> for how bit 60 in `mstateen0` and `hstateen0` can also restrict access to `sireg*`/`siselect` and `vsireg*`/`vsiselect` from privilege modes less privileged than M-mode._ +==== + +[NOTE] +[%unbreakable] +==== +_Implementations that support Smctr/Ssctr but not Smstateen/Ssstateen may observe reduced performance. Because Smctr/Ssctr introduces a significant number of new CSRs, it is desirable to avoid save/restore of CTR state when possible. A hypervisor is likely to leverage State Enable to trap on the initial guest access to CTR state, delegating CTR and enabling save/restore of guest CTR state only once the guest has begun to use it. Without Smstateen/Ssstateen, a hypervisor is required to save/restore guest CTR state on every context switch._ +==== + +=== Behavior + +[#norm:ctr_behavior]#CTR records qualified control transfers. Control transfers are qualified if they meet the following criteria:# + +* [#norm:ctr_behavior_criteria0]#The current privilege mode is enabled# +* [#norm:ctr_behavior_criteri1]#The transfer type is not inhibited# +* [#norm:ctr_behavior_criteria2]#`sctrstatus`.FROZEN is not set# +* [#norm:ctr_behavior_criteria3]#The transfer completes/retires# + +[#norm:ctr_stack]#Such qualified transfers update the <<_entry_registers, Entry Registers>> at logical entry 0. As a result, older entries are pushed down the stack; the record previously in logical entry 0 moves to logical entry 1, the record in logical entry 1 moves to logical entry 2, and so on. If the CTR buffer is full, the oldest recorded entry (previously at entry depth-1) is lost.# + +[#norm:ctr_validbit]#Recorded transfers will set the `ctrsource`.V bit to 1, and will update all implemented record fields.# + +[NOTE] +[%unbreakable] +==== +_In order to collect accurate and representative performance profiles while using CTR, it is recommended that hardware recording of control transfers incurs no added performance overhead, e.g., in the form of retirement or instruction execution restrictions that are not present when CTR is not active._ +==== + +==== Privilege Mode Transitions + +Transfers that change the privilege mode are a special case. What is +recorded, if anything, depends on whether the source privilege mode +and/or target privilege mode are enabled for recording, and on the transfer type (trap +or trap return). + +[#norm:trap_enabled]#Traps between enabled privilege modes are recorded as normal.# [#norm:trap_disabled_src]#Traps from a disabled privilege mode to an enabled privilege mode are partially recorded, such that the `ctrsource`.PC is 0.# [#norm:trap_disabled_tgt]#Traps from an enabled mode to a disabled mode, known as external traps, are not recorded by default.# See <> for how they can be recorded. + +Trap returns have similar treatment. [#norm:trapret_enabled]#Trap returns between enabled privilege modes are recorded as normal.# [#norm:trapret_to_disabled]#Trap returns from an enabled mode back to a disabled mode are partially recorded, such that `ctrtarget`.PC is 0.# [#norm:trapret_from_disabled]#Trap returns from a disabled mode to an enabled mode are not recorded.# + +[NOTE] +==== +_If privileged software is configuring CTR on behalf of less privileged software, it should ensure that its privilege mode enable bit (e.g., `sctrctl`.S for Supervisor software) is cleared before a trap return to the less privileged mode. Otherwise the trap return will be recorded, leaking the privileged source `pc`._ +==== + +[#norm:debug_recording_inhibited]#Recording in Debug Mode is always inhibited. Transfers into and out of Debug Mode are never recorded.# + +The table below provides details on recording of privilege mode transitions. Standard dependencies on FROZEN and transfer type inhibits also apply, but are not covered by the table. + +.Trap and Trap Return Recording +[%unbreakable] +[width="100%",cols="18%,17%,30%,35%",] +|=== +.2+|*Transfer Type* .2+| *Source Mode* 2+|*Target Mode* +|*Enabled* |*Disabled* +.2+|*Trap* |*Enabled* |[#norm:trap_ee]#Recorded#. | [#norm:trap_ed]#External trap. Not recorded by default,# but see <>. + +|*Disabled* |[#norm:trap_de]#Recorded, `ctrsource`.PC is 0.# |[#norm:trap_dd]#Not recorded.# + +.2+|*Trap Return* |*Enabled* |[#norm:trapret_ee]#Recorded.# |[#norm:trapret_ed]#Recorded, `ctrtarget`.PC is 0.# + +|*Disabled* |[#norm:trapret_de]#Not recorded.# |[#norm:trapret_dd]#Not recorded.# +|=== + +===== Virtualization Mode Transitions + +Transitions between VS/VU-mode and M/HS-mode are unique in that they effect a change in the active CTR control register, and hence the CTR configuration. What is recorded, if anything, on these virtualization mode transitions depends upon fields from both `[ms]ctrctl` and `vsctrctl`. + +* `mctrctl`.M, `sctrctl`.S, and `vsctrctl`.{S,U} are used to determine whether the source and target modes are enabled; +* `mctrctl`.MTE, `sctrctl`.STE, and `vsctrctl`.STE are used to determine whether an external trap is recorded (see <>); +* `sctrctl`.LCOFIFRZ and `sctrctl`.BPFRZ determine whether CTR becomes frozen (see <>) +* For all other `__x__ctrctl` fields, the value in `vsctrctl` is used. + +[NOTE] +==== +_Consider an exception that traps from VU-mode to HS-mode, with `vsctrctl`.U=1 and `sctrctl`.S=1. Because both the source mode and target mode are enabled for recording, whether the trap is recorded then depends on the CTR configuration (e.g., the <<_transfer_type_filtering, transfer type filter>> bits) in `vsctrctl`, not in `sctrctl`._ +==== + +===== External Traps + +[#norm:exttrap_def]#External traps are traps from a privilege mode enabled for CTR recording to a privilege mode that is not enabled for CTR recording. By default external traps are not recorded, but privileged software running in the target mode of the trap can opt-in to allowing CTR to record external traps into that mode. The `__x__ctrctl`.__x__TE bits allow M-mode, S-mode, and VS-mode to opt-in separately.# + +[#norm:exttrap_requirements]#External trap recording depends not only on the target mode, but on any intervening modes, which are modes that are more privileged than the source mode but less privileged than the target mode. Not only must the external trap enable bit for the target mode be set, but the external trap enable bit(s) for any intervening modes must also be set.# See the table below for details. + +[NOTE] +[%unbreakable] +==== +_Requiring intervening modes to be enabled for external traps simplifies software management of CTR. Consider a scenario where S-mode software is configuring CTR for U-mode contexts A and B, such that external traps (to any mode) are enabled for A but not for B. When switching between the two contexts, S-mode can simply toggle `sctrctl`.STE, rather than requiring a trap to M-mode to additionally toggle `mctrctl`.MTE._ + +_This method does not provide the flexibility to record external traps to a more privileged mode but not to all intervening mode(s). Because it is expected that profiling tools generally wish to observe all external traps or none, this is not considered a meaningful limitation._ +==== + +.External Trap Enable Requirements +[%unbreakable] +[options="header", width="85%", cols="23%,23%,54%"] +|=== +|Source Mode |Target Mode |External Trap Enable(s) Required +.2+|U-mode | S-mode | [#norm:exttrap_us]#`sctrctl`.STE# +|M-mode | [#norm:exttrap_um]#`mctrctl`.MTE, `sctrctl`.STE# +|S-mode | M-mode | [#norm:exttrap_sm]#`mctrctl`.MTE# +.3+|VU-mode | VS-mode | [#norm:exttrap_vuvs]#`vsctrctl`.STE# +| HS-mode | [#norm:exttrap_vuhs]#`sctrctl`.STE, `vsctrctl`.STE# +| M-mode | [#norm:exttrap_vum]#`mctrctl`.MTE, `sctrctl`.STE, `vsctrctl`.STE# +.2+| VS-mode | HS-mode | [#norm:exttrap_vshs]#`sctrctl`.STE# +| M-mode | [#norm:exttrap_vsm]#`mctrctl`.MTE, `sctrctl`.STE# +|=== + +[#norm:exttrap_ctrtarget0]#In records for external traps, the `ctrtarget`.PC is 0.# + +[NOTE] +[%unbreakable] +==== +_No mechanism exists for recording external trap returns, because +the external trap record includes all relevant information, and gives +the trap handler (e.g., an emulator) the opportunity to modify the +record._ +==== + +[NOTE] +[%unbreakable] +==== +_Note that external trap recording does not depend on EXCINH/INTRINH. Thus, when external traps are enabled, both external interrupts and external exceptions are recorded._ + +_STE allows recording of traps from U-mode to S-mode as well as from VS/VU-mode to HS-mode. The hypervisor can flip `sctrctl`.STE before entering a guest if it wants different behavior for U-to-S vs VS/VU-to-HS._ +==== + +[#norm:exttrap_implreq]#If external trap recording is implemented, `mctrctl`.MTE and `sctrctl`.STE must be implemented, while `vsctrctl`.STE must be implemented if the H extension is implemented.# + +==== Transfer Type Filtering + +[#norm:ttf_default]#Default CTR behavior, when all transfer type filter bits (`__x__ctrctl`[47:32]) are unimplemented or 0, is to record all control transfers within enabled privileged modes. By setting transfer type filter bits, software can opt out of recording select transfer types, or opt into recording non-default operations. All transfer type filter bits are optional.# + +[NOTE] +[%unbreakable] +==== +_Because not-taken branches are not recorded by default, the polarity of the associated enable bit (NTBREN) is the opposite of other bits associated with transfer type filtering (TKBRINH, RETINH, etc). Non-default operations require opt-in rather than opt-out._ +==== + +The transfer type filter bits leverage the type definitions specified +in the +https://github.com/riscv-non-isa/riscv-trace-spec/releases/download/v2.0rc2/riscv-trace-spec.pdf[[.underline]#RISC-V Efficient Trace Spec v2.0#] (Table 4.4 and Section 4.1.1). For completeness, the definitions are reproduced below. + +[NOTE] +==== +_Here "indirect" is used interchangeably with "uninferrable", which is used in the trace spec. Both imply that the target of the jump is not encoded in the opcode._ +==== + +.Control Transfer Type Definitions +[#transfer-type-defs] +[%unbreakable] +[width="60%", cols="22%,78%", options="header",] +|=== +| Encoding | Transfer Type Name +| 0 | [#norm:ttype0]#_Not used by CTR_# +| 1 | [#norm:ttype1]#Exception# +| 2 | [#norm:ttype2]#Interrupt# +| 3 | [#norm:ttype3]#Trap return# +| 4 | [#norm:ttype4]#Not-taken branch# +| 5 | [#norm:ttype5]#Taken branch# +| 6 | _reserved_ +| 7 | _reserved_ +| 8 | [#norm:ttype8]#Indirect call# +| 9 | [#norm:ttype9]#Direct call# +| 10 | [#norm:ttype10]#Indirect jump (without linkage)# +| 11 | [#norm:ttype11]#Direct jump (without linkage)# +| 12 | [#norm:ttype12]#Co-routine swap# +| 13 | [#norm:ttype13]#Function return# +| 14 | [#norm:ttype14]#Other indirect jump (with linkage)# +| 15 | [#norm:ttype15]#Other direct jump (with linkage)# +|=== + +[#norm:various_jump_enc]#Encodings 8 through 15 refer to various encodings of jump instructions. The types are distinguished as described below.# + +.Control Transfer Type Definitions +[%unbreakable] +[cols="37%,63%", options="header",] +|=== +| Transfer Type Name | Associated Opcodes +.3+| Indirect call | JALR _x1_, _rs_ where _rs_ != _x5_ +| JALR _x5_, _rs_ where _rs_ != _x1_ +| C.JALR _rs1_ where _rs1_ != _x5_ +.4+| Direct call | JAL _x1_ +| JAL _x5_ +| C.JAL +| CM.JALT _index_ +.2+| Indirect jump (without linkage) | JALR _x0_, _rs_ where _rs_ != (_x1_ or _x5_) +| C.JR _rs1_ where _rs1_ != (_x1_ or _x5_) +.3+| Direct jump (without linkage) | JAL _x0_ +| C.J +| CM.JT _index_ +.3+| Co-routine swap | JALR _x1_, _x5_ +| JALR _x5_, _x1_ +| C.JALR _x5_ +.3+| Function return | JALR _rd_, _rs_ where _rs_ == (_x1_ or _x5_) and _rd_ != (_x1_ or _x5_) +| C.JR _rs1_ where _rs1_ == (_x1_ or _x5_) +| CM.POPRET(Z) +| Other indirect jump (with linkage) | JALR _rd_, _rs_ where _rs_ != (_x1_ or _x5_) and _rd_ != (_x0_, _x1_, or _x5_) +| Other direct jump (with linkage) | JAL _rd_ where _rd_ != (_x0_, _x1_, or _x5_) +|=== + + +[NOTE] +[%unbreakable] +==== +_If implementation of any transfer type filter bit results in reduced software performance, perhaps due to additional retirement restrictions, it is strongly recommended that this reduced performance apply only when the bit is set. Alternatively, support for the bit may be omitted. Maintaining software performance for the default CTR configuration, when all transfer type bits are cleared, is recommended._ +==== + +==== Cycle Counting + +[#norm:ctrdata_cc_supported_param]#The `ctrdata` register may optionally include a count of CPU cycles elapsed since the prior CTR record. The elapsed cycle count value is represented by the CC field, which has a 12-bit mantissa component (Cycle Count Mantissa, or CCM) and a 4-bit exponent component (Cycle Count Exponent, or CCE).# + +[#norm:ccounter_inc]#The elapsed cycle counter (CtrCycleCounter) increments at the same rate as the `mcycle` counter. Only cycles while CTR is active are counted, where active implies that the current privilege mode is enabled for recording and CTR is not frozen. The CC field is encoded such that CCE holds 0 if the CtrCycleCounter value is less than 4096, otherwise it holds the index of the most significant one bit in the CtrCycleCounter value, minus 11. CCM holds CtrCycleCounter bits CCE+10:CCE-1.# + +The elapsed cycle count can then be calculated by software using the following formula: + +[subs="specialchars,quotes"] +[%unbreakable] +---- +if (CCE==0): + return CCM +else: + return (2^12^ + CCM) << CCE-1 +endif +---- + +[#norm:ccounter_reset]#The CtrCycleCounter is reset on writes to `__x__ctrctl`, and on execution of SCTRCLR, to ensure that any accumulated cycle counts do not persist across a context switch.# + +[#norm:ccounter_impl]#An implementation that supports cycle counting must implement CCV and all +CCM bits, but may implement 0..4 exponent bits in CCE. Unimplemented CCE +bits are read-only 0. For implementations that support transfer type +filtering, it is recommended to implement at least 3 exponent bits. This +allows capturing the full latency of most functions, when recording only +calls and returns.# + +The size of the CtrCycleCounter required to support each CCE width is given in the table below. + +.Cycle Counter Size Options +[%unbreakable] +[width="70%", cols="20%,38%,42%", options="header",] +|=== +| CCE bits | CtrCycleCounter bits | Max elapsed cycle value +| 0 | 12 | [#norm:ccsize0]#4095# +| 1 | 13 | [#norm:ccsize1]#8191# +| 2 | 15 | [#norm:ccsize2]#32764# +| 3 | 19 | [#norm:ccsize3]#524224# +| 4 | 27 | [#norm:ccsize4]#134201344# +|=== + +[NOTE] +[%unbreakable] +==== +_When CCE>1, the granularity of the reported cycle count is reduced. For example, when CCE=3, the bottom 2 bits of the cycle counter are not reported, and thus the reported value increments only every 4 cycles. As a result, the reported value represents an undercount of elapsed cycles for most cases (when the unreported bits are non-zero). On average, the undercount will be (2^CCE-1^-1)/2. Software can reduce the average undercount to 0 by adding (2^CCE-1^-1)/2 to each computed cycle count value when CCE>1._ + +_Though this compressed method of representation results in some imprecision for larger cycle count values, it produces meaningful area savings, reducing storage per entry from 27 bits to 16._ +==== + +[#norm:ccounter_sat]#The CC value saturates when all implemented bits in CCM and CCE are 1.# + +[#norm:ccounter_ccv]#The CC value is valid only when the Cycle Count Valid (CCV) bit is set. If CCV=0, the CC value might not hold the correct count of elapsed active cycles since the last recorded transfer. The next record will have CCV=0 after a write to `__x__ctrctl`, or execution of SCTRCLR, since CtrCycleCounter is reset. CCV should additionally be cleared after any other implementation-specific scenarios where active cycles might not be counted in CtrCycleCounter.# + +==== RAS (Return Address Stack) Emulation Mode + +[#norm:ctrctl_rasemu_op]#When the optional `__x__ctrctl`.RASEMU bit is implemented and set to 1, transfer recording behavior is altered to emulate the behavior of a return-address stack (RAS).# + +* Indirect and direct calls are recorded as normal +* Function returns pop the most recent call, by decrementing the WRPTR then invalidating the WRPTR entry (by setting ctrsource.V=0). As a result, logical entry 0 is invalidated and moves to logical entry depth-1, while logical entries 1..depth-1 move to 0..depth-2. +* Co-routine swaps affect both a return and a call. Logical entry 0 is +overwritten, and WRPTR is not modified. +* Other transfer types are inhibited +* Transfer type filtering bits (`__x__ctrctl`[47:32]) and external trap enable bits (`__x__ctrctl`.__x__TE) are ignored + +[NOTE] +[%unbreakable] +==== +_Profiling tools often collect call stacks along with each sample. Stack +walking, however, is a complex and often slow process that may require +recompilation (e.g., -fno-omit-frame-pointer) to work reliably. With RAS +emulation, tools can ask CTR hardware to save call stacks even for +unmodified code._ + +_CTR RAS emulation has limitations. The CTR buffer will contain only partial stacks in cases where the call stack depth was greater than the CTR depth, CTR recording was enabled at a lower point in the call stack than main(), or where the CTR buffer was cleared since main()._ + +_The CTR stack may be corrupted in cases where calls and returns are not symmetric, such as with stack unwinding (e.g., setjmp/longjmp, C++ exceptions), where stale call entries may be left on the CTR stack, or user stack switching, where calls from multiple stacks may be intermixed._ +==== + +[NOTE] +[%unbreakable] +==== +_As described in <>, +when CCV=1, the CC field provides the elapsed cycles since the prior CTR +entry was recorded. This introduces implementation challenges when +RASEMU=1 because, for each recorded call, there may have been several +recorded calls (and returns which “popped” them) since the prior +remaining call entry was recorded (see <>). The implication is that returns that +pop a call entry not only do not reset the cycle counter, but instead +add the CC field from the popped entry to the counter. For simplicity, +an implementation may opt to record CCV=0 for all calls, or those whose parent call was popped, when RASEMU=1._ +==== + +==== Freeze + +When `sctrstatus`.FROZEN=1, transfer recording is inhibited. This bit can be set by hardware, as described below, or by software. + +[#norm:sctrstatus-frozen_set]#When `sctrctl`.LCOFIFRZ=1 and a local-counter-overflow interrupt +(LCOFI) traps (as a result of an HPM counter overflow) to M-mode or to S-mode, `sctrstatus`.FROZEN is set by hardware. This inhibits CTR recording until software clears FROZEN. The LCOFI trap itself is not recorded.# +[NOTE] +[%unbreakable] +==== +_Freeze on LCOFI ensures that the execution path leading to the sampled +instruction (`__x__epc`) is preserved, and that the local-counter-overflow +interrupt (LCOFI) and associated Interrupt Service Routine (ISR) do not +displace any recorded transfer history state. It is the responsibility +of the ISR to clear FROZEN before __x__RET, if continued control transfer +recording is desired._ + +_LCOFI refers only to architectural traps directly caused by a local counter overflow. If a local-counter-overflow interrupt is recognized without a trap, FROZEN is not automatically set. For instance, no freeze occurs if the LCOFI is pended while interrupts are masked, and software recognizes the LCOFI (perhaps by reading `stopi` or `sip`) and clears `sip`.LCOFIP before the trap is raised. As a result, some or all CTR history may be overwritten while handling the LCOFI. Such cases are expected to be very rare; for most usages (e.g., application profiling) privilege mode filtering is sufficient to ensure that CTR updates are inhibited while interrupts are handled in a more privileged mode._ +==== +[#norm:freeze_bp]#Similarly, on a breakpoint exception that traps to M-mode or S-mode with `sctrctl`.BPFRZ=1, FROZEN is set by hardware. The breakpoint exception itself is not recorded.# + +[NOTE] +[%unbreakable] +==== +_Breakpoint exception refers to synchronous exceptions with a cause value of Breakpoint (3), regardless of source (ebreak, c.ebreak, Sdtrig); it does not include entry into Debug Mode, even in cores where this is implemented as an exception._ +==== + +[#norm:freeze_vs]#If the H extension is implemented, freeze behavior for LCOFIs and breakpoint exceptions that trap to VS-mode is determined by the LCOFIFRZ and BPFRZ values, respectively, in `vsctrctl`. This includes virtual LCOFIs pended by a hypervisor.# + +[NOTE] +[%unbreakable] +==== +_When a guest uses the SBI Supervisor Software Events (SSE) extension, the LCOFI will trap to HS-mode, which will then invoke a registered VS-mode LCOFI handler routine. If `vsctrctl`.LCOFIFRZ=1, the HS-mode handler will need to emulate the freeze by setting `sctrstatus`.FROZEN=1 before invoking the registered handler routine._ +==== + + +=== Custom Extensions + +[#norm:custom_bits]#Any custom CTR extension must be associated with a non-zero value within the designated custom bits in `__x__ctrctl`. When the custom bits hold a non-zero value that enables a custom extension, the extension may alter standard CTR behavior, and may define new custom status fields within `sctrstatus` or the CTR <<_entry_registers, Entry Registers>>. All custom status fields, and standard status fields whose behavior is altered by the custom extension, must revert to standard behavior when the custom bits hold zero. This includes read-only 0 behavior for any bits undefined by any implemented standard extensions.# diff --git a/param_extraction/chunks/chunk_047.txt.license b/param_extraction/chunks/chunk_047.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_047.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_048.txt b/param_extraction/chunks/chunk_048.txt new file mode 100644 index 0000000000..be1a5ba5f9 --- /dev/null +++ b/param_extraction/chunks/chunk_048.txt @@ -0,0 +1,25 @@ +# Chunk: chunk_048 +# Source: smdbltrp.adoc +# Lines: 1-17 (of 17) +# Content starts: line 1 +# Line count: 17 +# Sections: 1 +# == "Smdbltrp" Double Trap Extension, Version 1.0 +# +[[smdbltrp]] +== "Smdbltrp" Double Trap Extension, Version 1.0 + +The Smdbltrp extension addresses a double trap (See <>) in +M-mode. [#norm:Smdbltrp_with_Smrnmi_op]#When the Smrnmi extension (<>) is implemented, it enables +invocation of the RNMI handler on a double trap in M-mode to handle the +critical error.# If the Smrnmi extension is not implemented or if a double trap +occurs during the RNMI handler's execution, this extension helps transition the +hart to a critical error state and enables signaling the critical error to the +platform. + +To improve error diagnosis and resolution, this extension supports debugging +harts in a critical error state. The extension introduces a mechanism to enter +Debug Mode instead of asserting a critical-error signal to the platform when the +hart is in a critical error state. See cite:[DEBUG_SPEC] for details. + +See <> for the operational details. diff --git a/param_extraction/chunks/chunk_048.txt.license b/param_extraction/chunks/chunk_048.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_048.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_049.txt b/param_extraction/chunks/chunk_049.txt new file mode 100644 index 0000000000..f57b27de72 --- /dev/null +++ b/param_extraction/chunks/chunk_049.txt @@ -0,0 +1,88 @@ +# Chunk: chunk_049 +# Source: smepmp.adoc +# Lines: 1-77 (of 77) +# Content starts: line 1 +# Line count: 77 +# Sections: 4 +# == "Smepmp" Extension for PMP Enhancements for memory access and execution prevention in Machine mode, Version 1.0 +# === Threat model +# === Smepmp Physical Memory Protection Rules +# === Smepmp software discovery +# +[[smepmp]] +== "Smepmp" Extension for PMP Enhancements for memory access and execution prevention in Machine mode, Version 1.0 + +Being able to access the memory of a process running at a high privileged execution mode, such as the Supervisor or Machine mode, from a lower privileged mode such as the User mode, introduces an obvious attack vector since it allows for an attacker to perform privilege escalation, and tamper with the code and/or data of that process. A less obvious attack vector exists when the reverse happens, in which case an attacker instead of tampering with code and/or data that belong to a high-privileged process, can tamper with the memory of an unprivileged / less-privileged process and trick the high-privileged process to use or execute it. + +Two mechanisms combine to prevent this attack vector. +The first one prevents the OS from accessing the memory of an unprivileged +process unless a specific code path is followed, and the second one prevents +the OS from executing the memory of an unprivileged process at all times. +RISC-V already includes support for the former through the ``sstatus.SUM`` bit, +and for the latter by always denying supervisor execution of virtual memory +pages marked with the U bit. + +[NOTE] +==== +Terms: + +* *PMP Entry*: A pair of ``pmpcfg[i]`` / ``pmpaddr[i]`` registers. +* *PMP Rule*: The contents of a pmpcfg register and its associated pmpaddr register(s), that encode a valid protected physical memory region, where ``pmpcfg[i].A != OFF``, and if ``pmpcfg[i].A == TOR``, ``pmpaddr[i-1] < pmpaddr[i]``. +* *Ignored*: Any permissions set by a matching PMP rule are ignored, and _all_ accesses to the requested address range are allowed. +* *Enforced*: Only access types configured in the PMP rule matching the requested address range are allowed; failures will cause an access-fault exception. +* *Denied*: Any permissions set by a matching PMP rule are ignored, and _no_ accesses to the requested address range are allowed.; failures will cause an access-fault exception. +* *Locked*: A PMP rule/entry where the ``pmpcfg.L`` bit is set. +* *PMP reset*: A reset process where all PMP settings of the hart, including locked rules/settings, are re-initialized to a set of safe defaults, before releasing the hart (back) to the firmware / OS / application. +==== + +[[smepmp_threat]] +=== Threat model + +The rationale that guided development of this extension is included in +Section <>. + +Without the Smepmp extension, it is not possible for a PMP rule to be *enforced* only on non-Machine modes and *denied* on Machine mode, in order to allow access to a memory region solely by less-privileged modes. It is only possible to have a *locked* rule that will be *enforced* on all modes, or a rule that will be *enforced* on non-Machine modes and be *ignored* by Machine mode. So for any physical memory region which is not protected with a Locked rule, Machine mode has unlimited access, including the ability to execute it. + +Without being able to protect less-privileged modes from Machine mode, it is not possible to prevent the mentioned attack vector. This becomes even more important for RISC-V than on other architectures, since implementations are allowed where a hart only has Machine and User modes available, so the whole OS will run on Machine mode instead of the non-existent Supervisor mode. In such implementations the attack surface is greatly increased, and the same kind of attacks performed on Supervisor mode and mitigated through the virtual-memory system, can be performed on Machine mode without any available mitigations. Even on implementations with Supervisor mode present attacks are still possible against the Firmware and/or the Secure Monitor running on Machine mode. + +=== Smepmp Physical Memory Protection Rules + +To address the threat model outlined in Section <>, this +extension introduces the `RLB`, `MMWP`, and `MML` fields in the `mseccfg` CSR +and their associated rules. See <> for the detailed specification of +these fields and the corresponding rules. + +The physical memory protection rules when `mseccfg.MML` is set to 1 are +summarized in the truth table below. + +[cols="^1,^1,^1,^1,^3,^3",stripes=even,options="header"] +|=== +4+|Bits on _pmpcfg_ register {set:cellbgcolor:green} 2+|Result +|L|R|W|X|M Mode|S/U Mode +|{set:cellbgcolor:!} 0|0|0|0 2+|Inaccessible region (Access Exception) +|0|0|0|1|Access Exception|Execute-only region +|0|0|1|0 2+|Shared data region: Read/write on M mode, read-only on S/U mode +|0|0|1|1 2+|Shared data region: Read/write for both M and S/U mode +|0|1|0|0|Access Exception|Read-only region +|0|1|0|1|Access Exception|Read/Execute region +|0|1|1|0|Access Exception|Read/Write region +|0|1|1|1|Access Exception|Read/Write/Execute region +|1|0|0|0 2+|Locked inaccessible region* (Access Exception) +|1|0|0|1|Locked Execute-only region*|Access Exception +|1|0|1|0 2+|Locked Shared code region: Execute only on both M and S/U mode.* +|1|0|1|1 2+|Locked Shared code region: Execute only on S/U mode, read/execute on M mode.* +|1|1|0|0|Locked Read-only region*|Access Exception +|1|1|0|1|Locked Read/Execute region*|Access Exception +|1|1|1|0|Locked Read/Write region*|Access Exception +|1|1|1|1 2+|Locked Shared data region: Read only on both M and S/U mode.* +|=== + +*: *Locked* rules cannot be removed or modified until a *PMP reset*, unless ``mseccfg.RLB`` is set. + +A visual representation of these rules is as follows: + +image::smepmp-visual-representation.png[] + +=== Smepmp software discovery + +Since all fields defined in ``mseccfg`` as part of this extension are locked when set (``MMWP``/``MML``) or locked when cleared (``RLB``), software can't poll them for determining the presence of Smepmp. It is expected that BootROM will set ``mseccfg.MMWP`` and/or ``mseccfg.MML`` during early boot, before jumping to the firmware, so that the firmware will be able to determine the presence of Smepmp by reading ``mseccfg`` and checking the state of ``mseccfg.MMWP`` and ``mseccfg.MML``. diff --git a/param_extraction/chunks/chunk_049.txt.license b/param_extraction/chunks/chunk_049.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_049.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_050.txt b/param_extraction/chunks/chunk_050.txt new file mode 100644 index 0000000000..0922fc0122 --- /dev/null +++ b/param_extraction/chunks/chunk_050.txt @@ -0,0 +1,384 @@ +# Chunk: chunk_050 +# Source: smstateen.adoc +# Lines: 1-373 (of 373) +# Content starts: line 1 +# Line count: 373 +# Sections: 4 +# == "Smstateen/Ssstateen" Extensions, Version 1.0 +# === State Enable Extensions +# === State Enable 0 Registers +# === Usage +# +[[smstateen]] +== "Smstateen/Ssstateen" Extensions, Version 1.0 + +The implementation of optional RISC-V extensions has the potential to open +covert channels between separate user threads, or between separate guest OSes +running under a hypervisor. The problem occurs when an extension adds processor +state -- usually explicit registers, but possibly other forms of state -- that +the main OS or hypervisor is unaware of (and hence won't context-switch) but +that can be modified/written by one user thread or guest OS and +perceived/examined/read by another. + +For example, the Advanced Interrupt Architecture (AIA) for RISC-V adds +to a hart as many as ten supervisor-level CSRs (`siselect`, `sireg`, `stopi`, +`sseteipnum`, `sclreipnum`, `sseteienum`, `sclreienum`, `sclaimei`, `sieh`, and `siph`) and +provides also the option for hardware to be backward-compatible with older, +pre-AIA software. Because an older hypervisor that is oblivious to the AIA will +not know to swap any of the AIA's new CSRs on context switches, the registers may +then be used as a covert channel between multiple guest OSes that run atop this +hypervisor. Although traditional practices might consider such a communication +channel harmless, the intense focus on security today argues that a means be +offered to plug such channels. + +The `f` registers of the RISC-V floating-point extensions and the `v` registers of +the vector extension would similarly be potential covert channels between user +threads, except for the existence of the FS and VS fields in the `sstatus` +register. Even if an OS is unaware of, say, the vector extension and its `v` +registers, access to those registers is blocked when the VS field is +initialized to zero, either at machine level or by the OS itself initializing +`sstatus`. + +Obviously, one way to prevent the use of new user-level CSRs as covert channels +would be to add to `mstatus` or `sstatus` an "XS" field for each relevant +extension, paralleling the V extension's VS field. However, this is not +considered a general solution to the problem due to the number of potential +future extensions that may add small amounts of state. Even with a 64-bit +`sstatus` (necessitating adding `sstatush` for RV32), it is not certain there are +enough remaining bits in `sstatus` to accommodate all future user-level +extensions. In any event, there is no need to strain `sstatus` (and add `sstatush`) +for this purpose. The "enable" flags that are needed to plug covert channels +are not generally expected to require swapping on context switches of user +threads, making them a less-than-compelling candidate for inclusion in `sstatus`. +Hence, a new place is provided for them instead. + +=== State Enable Extensions + +The Smstateen and Ssstateen extensions collectively specify machine-mode and +supervisor-mode features. The Smstateen extension specification comprises the +mstateen*, sstateen*, and hstateen* CSRs and their functionality. The Ssstateen +extension specification comprises only the sstateen* and hstateen* CSRs and their +functionality. + +For RV64 harts, this extension adds four new 64-bit CSRs at machine level: +`mstateen0` (Machine State Enable 0), `mstateen1`, `mstateen2`, and `mstateen3`. + +If supervisor mode is implemented, another four CSRs are defined at supervisor +level: +`sstateen0`, `sstateen1`, `sstateen2`, and `sstateen3`. + +And if the hypervisor extension is implemented, another set of CSRs is added: +`hstateen0`, `hstateen1`, `hstateen2`, and `hstateen3`. + +For RV32, there are CSR addresses for accessing the upper 32 bits of +corresponding machine-level and hypervisor CSRs: +`mstateen0h`, `mstateen1h`, `mstateen2h`, `mstateen3h`, +`hstateen0h`, `hstateen1h`, `hstateen2h`, and `hstateen3h`. + +For the supervisor-level `sstateen` registers, high-half CSRs are not added at +this time because it is expected the upper 32 bits of these registers will +always be zeros, as explained later below. + +Each bit of a `stateen` CSR controls less-privileged access to an extension's +state, for an extension that was not deemed "worthy" of a full XS field in +`sstatus` like the FS and VS fields for the F and V extensions. The number of +registers provided at each level is four because it is believed that 4 * 64 = +256 bits for machine and hypervisor levels, and 4 * 32 = 128 bits for +supervisor level, will be adequate for many years to come, perhaps for as long +as the RISC-V ISA is in use. The exact number four is an attempted compromise +between providing too few bits on the one hand and going overboard with CSRs +that will never be used on the other. A possible future doubling of the number +of `stateen` CSRs is covered later. + +The `stateen` registers at each level control access to state at all +less-privileged levels, but not at its own level. This is analogous to how the +existing `counteren` CSRs control access to performance counter registers. Just +as with the `counteren` CSRs, when a `stateen` CSR prevents access to state by +less-privileged levels, an attempt in one of those privilege modes to execute +an instruction that would read or write the protected state raises an illegal-instruction +exception, or, if executing in VS or VU mode and the circumstances +for a virtual-instruction exception apply, raises a virtual-instruction +exception instead of an illegal-instruction exception. + +When this extension is not implemented, all state added by an extension is +accessible as defined by that extension. + +When a `stateen` CSR prevents access to state for a privilege mode, attempting to +execute in that privilege mode an instruction that _implicitly_ updates the +state without reading it may or may not raise an illegal-instruction or virtual-instruction +exception. Such cases must be disambiguated by being explicitly +specified one way or the other. + +In some cases, the bits of the `stateen` CSRs will have a dual purpose as enables +for the ISA extensions that introduce the controlled state. + +Each bit of a supervisor-level `sstateen` CSR controls user-level access (from +U-mode or VU-mode) to an extension's state. The intention is to allocate the +bits of `sstateen` CSRs starting at the least-significant end, bit 0, through to +bit 31, and then on to the next-higher-numbered `sstateen` CSR. + +For every bit with a defined purpose in an `sstateen` CSR, the same bit is +defined in the matching `mstateen` CSR to control access below machine level to +the same state. The upper 32 bits of an `mstateen` CSR (or for RV32, the +corresponding high-half CSR) control access to state that is inherently +inaccessible to user level, so no corresponding enable bits in the +supervisor-level `sstateen` CSR are applicable. The intention is to allocate bits +for this purpose starting at the most-significant end, bit 63, through to bit +32, and then on to the next-higher `mstateen` CSR. If the rate that bits are +being allocated from the least-significant end for `sstateen` CSRs is +sufficiently low, allocation from the most-significant end of `mstateen` CSRs may +be allowed to encroach on the lower 32 bits before jumping to the next-higher +`mstateen` CSR. In that case, the bit positions of "encroaching" bits will remain +forever read-only zeros in the matching `sstateen` CSRs. + +With the hypervisor extension, the `hstateen` CSRs have identical encodings to +the `mstateen` CSRs, except controlling accesses for a virtual machine (from VS +and VU modes). + +Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or +one, subject to the following conditions. + +Bits in any `stateen` CSR that are defined to control state that a hart doesn't +implement are read-only zeros for that hart. Likewise, all reserved bits not +yet given a defined meaning are also read-only zeros. For every bit in an +`mstateen` CSR that is zero (whether read-only zero or set to zero), the same bit +appears as read-only zero in the matching `hstateen` and `sstateen` CSRs. For every +bit in an `hstateen` CSR that is zero (whether read-only zero or set to zero), +the same bit appears as read-only zero in `sstateen` when accessed in VS-mode. + +A bit in a supervisor-level `sstateen` CSR cannot be read-only one unless the +same bit is read-only one in the matching `mstateen` CSR and, if it exists, in +the matching `hstateen` CSR. A bit in an `hstateen` CSR cannot be read-only one +unless the same bit is read-only one in the matching `mstateen` CSR. + +On reset, all writable `mstateen` bits are initialized by the hardware to zeros. +If machine-level software changes these values, it is responsible for +initializing the corresponding writable bits of the `hstateen` and `sstateen` CSRs +to zeros too. Software at each privilege level should set its respective +`stateen` CSRs to indicate the state it is prepared to allow less-privileged +software to access. For OSes and hypervisors, this usually means the state that +the OS or hypervisor is prepared to swap on a context switch, or to manage in +some other way. + +For each `mstateen` CSR, bit 63 is defined to control access to the +matching `sstateen` and `hstateen` CSRs. That is, bit 63 of `mstateen0` controls +access to `sstateen0` and `hstateen0`; bit 63 of `mstateen1` controls access to +`sstateen1` and `hstateen1`; etc. Likewise, bit 63 of each `hstateen` +correspondingly controls access to the matching `sstateen` CSR. + +A hypervisor may need this control over accesses to the `sstateen` CSRs if it +ever must emulate for a virtual machine an extension that is supposed to be +affected by a bit in an `sstateen` CSR. Even if such emulation is uncommon, +it should not be excluded. + +Machine-level software needs identical control to be able to emulate the +hypervisor extension. That is, machine level needs control over accesses to the +supervisor-level `sstateen` CSRs in order to emulate the `hstateen` CSRs, which +have such control. + +Bit 63 of each `mstateen` CSR may be read-only zero only if the hypervisor +extension is not implemented and the matching supervisor-level `sstateen` CSR is +all read-only zeros. In that case, machine-level software should emulate +attempts to access the affected `sstateen` CSR from S-mode, ignoring writes and +returning zero for reads. Bit 63 of each `hstateen` CSR is always writable (not +read-only). + +=== State Enable 0 Registers + +.Machine State Enable 0 Register (`mstateen0`) +[wavedrom, ,svg] +.... +{reg: [ +{bits: 1, name: 'C'}, +{bits: 1, name: 'FCSR'}, +{bits: 1, name: 'JVT'}, +{bits: 51, name: 'WPRI'}, +{bits: 1, name: 'CTR'}, +{bits: 1, name: 'SRMCFG'}, +{bits: 1, name: 'P1P13'}, +{bits: 1, name: 'CONTEXT'}, +{bits: 1, name: 'IMSIC'}, +{bits: 1, name: 'AIA'}, +{bits: 1, name: 'CSRIND'}, +{bits: 1, name: 'WPRI'}, +{bits: 1, name: 'ENVCFG'}, +{bits: 1, name: 'SE0'}, +], config: {bits: 64, lanes: 4, hspace:1024}} +.... + +.Hypervisor State Enable 0 Register (`hstateen0`) +[wavedrom, ,svg] +.... +{reg: [ +{bits: 1, name: 'C'}, +{bits: 1, name: 'FCSR'}, +{bits: 1, name: 'JVT'}, +{bits: 51, name: 'WPRI'}, +{bits: 1, name: 'CTR'}, +{bits: 2, name: 'WPRI'}, +{bits: 1, name: 'CONTEXT'}, +{bits: 1, name: 'IMSIC'}, +{bits: 1, name: 'AIA'}, +{bits: 1, name: 'CSRIND'}, +{bits: 1, name: 'WPRI'}, +{bits: 1, name: 'ENVCFG'}, +{bits: 1, name: 'SE0'}, +], config: {bits: 64, lanes: 4, hspace:1024}} +.... + +.Supervisor State Enable 0 Register (`sstateen0`) +[wavedrom, ,svg] +.... +{reg: [ +{bits: 1, name: 'C'}, +{bits: 1, name: 'FCSR'}, +{bits: 1, name: 'JVT'}, +{bits: 29, name: 'WPRI'} +], config:{bits: 32, lanes: 2, hspace:1024}} +.... + +The C bit controls access to any and all custom state. +The C bit of these registers is not custom state itself; it is a +standard field of a standard CSR, either `mstateen0`, `hstateen0`, or +`sstateen0`. + +[NOTE] +==== +The requirements that non-standard extensions must meet to be conforming are not +relaxed due solely to changes in the value of this bit. In particular, if +software sets this bit but does not execute any custom instructions or access +any custom state, the software must continue to execute as specified by all +relevant RISC-V standards, or the hardware is not standard-conforming. +==== + +The FCSR bit controls access to `fcsr` for the case when floating-point +instructions operate on `x` registers instead of `f` registers as specified by +the Zfinx and related extensions (Zdinx, etc.). Whenever `misa.F` = 1, FCSR bit +of `mstateen0` is read-only zero (and hence read-only zero in `hstateen0` and +`sstateen0` too). For convenience, when the `stateen` CSRs are implemented and +`misa.F` = 0, then if the FCSR bit of a controlling `stateen0` CSR is zero, all +floating-point instructions cause an illegal-instruction exception (or virtual-instruction +exception, if relevant), as though they all access `fcsr`, regardless of +whether they really do. + +The JVT bit controls access to the `jvt` CSR provided by the Zcmt extension. + +The SE0 bit in `mstateen0` controls access to the `hstateen0`, `hstateen0h`, +and the `sstateen0` CSRs. The SE0 bit in `hstateen0` controls access to the +`sstateen0` CSR. + +The ENVCFG bit in `mstateen0` controls access to the `henvcfg`, `henvcfgh`, +and the `senvcfg` CSRs. The ENVCFG bit in `hstateen0` controls access to the +`senvcfg` CSRs. + +The CSRIND bit in `mstateen0` controls access to the `siselect`, `sireg*`, +`vsiselect`, and the `vsireg*` CSRs provided by the Sscsrind extensions. +The CSRIND bit in `hstateen0` controls access to the `siselect` and the +`sireg*`, (really `vsiselect` and `vsireg*`) CSRs provided by the Sscsrind +extensions. + +The IMSIC bit in `mstateen0` controls access to the IMSIC state, including +CSRs `stopei` and `vstopei`, provided by the Ssaia extension. The IMSIC bit in +`hstateen0` controls access to the guest IMSIC state, including CSRs `stopei` +(really `vstopei`), provided by the Ssaia extension. + +[NOTE] +==== +Setting the IMSIC bit in `hstateen0` to zero prevents a virtual machine from +accessing the hart's IMSIC the same as setting `hstatus`.VGEIN = 0. +==== + +The AIA bit in `mstateen0` controls access to all state introduced by the +Ssaia extension and not controlled by either the CSRIND or the IMSIC +bits. The AIA bit in `hstateen0` controls access to all state introduced by the +Ssaia extension and not controlled by either the CSRIND or the IMSIC +bits of `hstateen0`. + +The CONTEXT bit in `mstateen0` controls access to the `scontext` and +`hcontext` CSRs provided by the Sdtrig extension. The CONTEXT bit in +`hstateen0` controls access to the `scontext` CSR provided by the Sdtrig +extension. + +The P1P13 bit in `mstateen0` controls access to the `hedelegh` introduced by +Privileged Specification Version 1.13. + +The SRMCFG bit in `mstateen0` controls access to the `srmcfg` CSR introduced by +the Ssqosid <> extension. + +=== Usage + +After the writable bits of the machine-level `mstateen` CSRs are initialized to +zeros on reset, machine-level software can set bits in these registers to +enable less-privileged access to the controlled state. This may be either +because machine-level software knows how to swap the state or, more likely, +because machine-level software isn't swapping supervisor-level environments. +(Recall that the main reason the `mstateen` CSRs must exist is so machine level +can emulate the hypervisor extension. When machine level isn't emulating the +hypervisor extension, it is likely there will be no need to keep any +implemented `mstateen` bits zero.) + +If machine level sets any writable `mstateen` bits to nonzero, it must initialize +the matching `hstateen` CSRs, if they exist, by writing zeros to them. And if any +`mstateen` bits that are set to one have matching bits in the `sstateen` CSRs, +machine-level software must also initialize those `sstateen` CSRs by writing +zeros to them. Ordinarily, machine-level software will want to set bit 63 of +all `mstateen` CSRs, necessitating that it write zero to all `hstateen` CSRs. + +Software should ensure that all writable bits of `sstateen` CSRs are initialized +to zeros when an OS at supervisor level is first entered. The OS can then set +bits in these registers to enable user-level access to the controlled state, +presumably because it knows how to context-swap the state. + +For the `sstateen` CSRs whose access by a guest OS is permitted by bit 63 of the +corresponding `hstateen` CSRs, a hypervisor must include the `sstateen` CSRs in the +context it swaps for a guest OS. When it starts a new guest OS, it must ensure +the writable bits of those `sstateen` CSRs are initialized to zeros, and it must +emulate accesses to any other `sstateen` CSRs. + +If software at any privilege level does not support multiple contexts for +less-privilege levels, then it may choose to maximize less-privileged access to +all state by writing a value of all ones to the `stateen` CSRs at its level (the +`mstateen` CSRs for machine level, the `sstateen` CSRs for an OS, and the `hstateen` +CSRs for a hypervisor), without knowing all the state to which it is granting +access. This is justified because there is no risk of a covert channel between +execution contexts at the less-privileged level when only one context exists +at that level. This situation is expected to be common for machine level, and +it might also arise, for example, for a type-1 hypervisor that hosts only a +single guest virtual machine. + +[NOTE] +==== +If a need is anticipated, the set of `stateen` CSRs could in the future be +doubled by adding these: + +* `0x38C mstateen4`, `0x39C mstateen4h` + +* `0x38D mstateen5`, `0x39D mstateen5h` + +* `0x38E mstateen6`, `0x39E mstateen6h` + +* `0x38F mstateen7`, `0x39F mstateen7h` + +* `0x18C sstateen4` + +* `0x18D sstateen5` + +* `0x18E sstateen6` + +* `0x18F sstateen7` + +* `0x68C hstateen4`, `0x69C hstateen4h` + +* `0x68D hstateen5`, `0x69D hstateen5h` + +* `0x68E hstateen6`, `0x69E hstateen6h` + +* `0x68F hstateen7`, `0x69F hstateen7h` + +These additional CSRs are not a definite part of the original proposal because +it is unclear whether they will ever be needed, and it is believed the rate of +consumption of bits in the first group, registers numbered 0-3, will be slow +enough that any looming shortage will be perceptible many years in advance. At +the moment, it is not known even how many years it may take to exhaust just +`mstateen0`, `sstateen0`, and `hstateen0`. +==== diff --git a/param_extraction/chunks/chunk_050.txt.license b/param_extraction/chunks/chunk_050.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_050.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_051.txt b/param_extraction/chunks/chunk_051.txt new file mode 100644 index 0000000000..0259d3a356 --- /dev/null +++ b/param_extraction/chunks/chunk_051.txt @@ -0,0 +1,136 @@ +# Chunk: chunk_051 +# Source: sscofpmf.adoc +# Lines: 1-126 (of 126) +# Content starts: line 1 +# Line count: 126 +# Sections: 3 +# == "Sscofpmf" Extension for Count Overflow and Mode-Based Filtering, Version 1.0 +# === Count Overflow Control +# === Supervisor Count Overflow (`scountovf`) Register +# +[[Sscofpmf]] +== "Sscofpmf" Extension for Count Overflow and Mode-Based Filtering, Version 1.0 + +The current Privileged specification defines mhpmevent CSRs to select and +control event counting by the associated hpmcounter CSRs, but provides no +standardization of any fields within these CSRs. For at least Linux-class +rich-OS systems it is desirable to standardize certain basic features that are +broadly desired (and have come up over the past year plus on RISC-V lists, as +well as have been the subject of past proposals). This enables there to be +standard upstream software support that eliminates the need for implementations +to provide their own custom software support. + +This extension serves to accomplish exactly this within the existing mhpmevent +CSRs (and correspondingly avoids the unnecessary creation of whole new sets of +CSRs - past just one new CSR). + +This extension sticks to addressing two basic well-understood needs that have +been requested by various people. To make it easy to understand the deltas from +the current Priv 1.11/1.12 specs, this is written as the actual exact changes +to be made to existing paragraphs of Priv spec text (or additional paragraphs +within the existing text). + +The extension name is "Sscofpmf" ('Ss' for Privileged arch and Supervisor-level +extensions, and 'cofpmf' for Count OverFlow and Privilege Mode Filtering). + +Note that the new count overflow interrupt will be treated as a standard local +interrupt that is assigned to bit 13 in the mip/mie/sip/sie registers. + +=== Count Overflow Control + +The following bits are added to `mhpmevent`: + +[cols="^1,^1,^1,^1,^1,^1,^1,^1",stripes=even,options="header"] +|==== +|63 |62 |61 |60 |59 |58 |57 |56 +|OF |MINH |SINH |UINH |VSINH |VUINH |_WPRI_ |_WPRI_ +|==== + +[cols="15%,85%",options="header"] +|==== +| Field | Description +| OF | Overflow status and interrupt disable bit that is set when counter overflows +| MINH | If set, then counting of events in M-mode is inhibited +| SINH | If set, then counting of events in S/HS-mode is inhibited +| UINH | If set, then counting of events in U-mode is inhibited +| VSINH | If set, then counting of events in VS-mode is inhibited +| VUINH | If set, then counting of events in VU-mode is inhibited +| _WPRI_ | Reserved +| _WPRI_ | Reserved +|==== + +For each ``x``INH bit, if the associated privilege mode is not implemented, +the bit is read-only zero. + +Each of the five ``x``INH bits, when set, inhibit counting of events while in +privilege mode ``x``. All-zeroes for these bits results in counting of events in +all modes. + +The OF bit is set when the corresponding hpmcounter overflows, and remains set +until written by software. Since hpmcounter values are unsigned values, +overflow is defined as unsigned overflow of the implemented counter bits. Note +that there is no loss of information after an overflow since the counter wraps +around and keeps counting while the sticky OF bit remains set. + +If supervisor mode is implemented, the 32-bit scountovf register contains +read-only shadow copies of the OF bits in all 29 mhpmevent registers. + +If an hpmcounter overflows while the associated OF bit is zero, then a "count +overflow interrupt request" is generated. If the OF bit is one, then no +interrupt request is generated. Consequently the OF bit also functions as a +count overflow interrupt disable for the associated hpmcounter. + +Count overflow never results from writes to the mhpmcounter__n__ or +mhpmevent__n__ registers, only from hardware increments of counter registers. + +This count-overflow-interrupt-request signal is treated as a standard local +interrupt that corresponds to bit 13 in the `mip`/`mie`/`sip`/`sie` registers. +The `mip`/`sip` LCOFIP and `mie`/`sie` LCOFIE bits are, respectively, the +interrupt-pending and interrupt-enable bits for this interrupt. +('LCOFI' represents 'Local Count Overflow Interrupt'.) + +Generation of a count-overflow-interrupt request by an `hpmcounter` sets the +associated OF bit. +When an OF bit is set, it eventually, but not necessarily immediately, sets +the LCOFIP bit in the `mip`/`sip` registers. +The LCOFIP bit is cleared by software before servicing the count overflow +interrupt resulting from one or more count overflows. +The `mideleg` register controls the delegation of this interrupt to S-mode +versus M-mode. + +[NOTE] +==== +There are not separate overflow status and overflow interrupt enable bits. In +practice, enabling overflow interrupt generation (by clearing the OF bit) is +done in conjunction with initializing the counter to a starting value. Once a +counter has overflowed, it and the OF bit must be reinitialized before another +overflow interrupt can be generated. +==== + +[NOTE] +==== +Software can distinguish newly overflowed counters (yet to be serviced by an +overflow interrupt handler) from overflowed counters that have already been +serviced or that are configured to not generate an interrupt on overflow, by +maintaining a bit mask reflecting which counters are active and due to +eventually overflow. +==== + +=== Supervisor Count Overflow (`scountovf`) Register + +This extension adds the `scountovf` CSR, +a 32-bit read-only register that contains shadow copies of +the OF bits in the 29 mhpmevent CSRs (mhpmevent__3__ - mhpmevent__31__) - where +scountovf bit _X_ corresponds to mhpmevent__X__. + +This register enables supervisor-level overflow interrupt handler software to +quickly and easily determine which counter(s) have overflowed (without needing +to make an execution environment call or series of calls ultimately up to +M-mode). + +Read access to bit _X_ is subject to the same mcounteren (or mcounteren and +hcounteren) CSRs that mediate access to the hpmcounter CSRs by S-mode (or +VS-mode). In M-mode, scountovf bit _X_ is always readable. In S/HS-mode, scountovf bit _X_ is readable when mcounteren bit +_X_ is set, and otherwise reads as zero. Similarly, in VS mode, scountovf bit +_X_ is readable when mcounteren bit _X_ and hcounteren bit _X_ are both set, +and otherwise reads as zero. diff --git a/param_extraction/chunks/chunk_051.txt.license b/param_extraction/chunks/chunk_051.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_051.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_052.txt b/param_extraction/chunks/chunk_052.txt new file mode 100644 index 0000000000..1c3ec2c569 --- /dev/null +++ b/param_extraction/chunks/chunk_052.txt @@ -0,0 +1,23 @@ +# Chunk: chunk_052 +# Source: ssdbltrp.adoc +# Lines: 1-15 (of 15) +# Content starts: line 1 +# Line count: 15 +# Sections: 1 +# == "Ssdbltrp" Double Trap Extension, Version 1.0 +# +[[ssdbltrp]] +== "Ssdbltrp" Double Trap Extension, Version 1.0 + +The Ssdbltrp extension addresses a double trap (See <>) +privilege modes lower than M. [#norm:HS-mode_invoke_error]#It enables HS-mode to invoke a critical error +handler in a virtual machine on a double trap in VS-mode.# [#norm:M-mode_invoke_error]#It also allows M-mode +to invoke a critical error handler in the OS/Hypervisor on a double trap in +S/HS-mode.# + +[#norm:menvcfg_DTE]#The Ssdbltrp extension adds the `menvcfg`.DTE (See <>)# [#norm:sstatus_SDT]#and the +`sstatus`.SDT fields (See <>).# [#norm:henvcfg_DTE]#If the hypervisor extension is +additionally implemented, then the extension adds the `henvcfg`.DTE (See +<>)# [#norm:vsstatus_SDT]#and the `vsstatus`.SDT fields (See <>).# + +See <> for the operational details. diff --git a/param_extraction/chunks/chunk_052.txt.license b/param_extraction/chunks/chunk_052.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_052.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_053.txt b/param_extraction/chunks/chunk_053.txt new file mode 100644 index 0000000000..6614016c5a --- /dev/null +++ b/param_extraction/chunks/chunk_053.txt @@ -0,0 +1,32 @@ +# Chunk: chunk_053 +# Source: sstc.adoc +# Lines: 1-24 (of 24) +# Content starts: line 1 +# Line count: 24 +# Sections: 1 +# == "Sstc" Extension for Supervisor-mode Timer Interrupts, Version 1.0 +# +[[Sstc]] +== "Sstc" Extension for Supervisor-mode Timer Interrupts, Version 1.0 + +The current Privileged arch specification only defines a hardware mechanism for +generating machine-mode timer interrupts (based on the mtime and mtimecmp +registers). With the resultant requirement that timer services for +S-mode/HS-mode (and for VS-mode) have to all be provided by M-mode - via SBI +calls from S/HS-mode up to M-mode (or VS-mode calls to HS-mode and then to +M-mode). M-mode software then multiplexes these multiple logical timers onto +its one physical M-mode timer facility, and the M-mode timer interrupt handler +passes timer interrupts back down to the appropriate lower privilege mode. + +This extension serves to provide supervisor mode with its own CSR-based timer +interrupt facility that it can directly manage to provide its own timer service +(in the form of having its own `stimecmp` register) - thus eliminating the large +overheads for emulating S/HS-mode timers and timer interrupt generation up in +M-mode. Further, this extension adds a similar facility to the Hypervisor +extension for VS-mode. + +The extension name is "Sstc" ('Ss' for Privileged arch and Supervisor-level +extensions, and 'tc' for timecmp). This extension adds the S-level `stimecmp` +CSR (<>) and the VS-level `vstimecmp` CSR (<>. This +extension adds the `STCE` bit to the `menvcfg` (<>) and `henvcfg` +(<>) CSRs. diff --git a/param_extraction/chunks/chunk_053.txt.license b/param_extraction/chunks/chunk_053.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_053.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_054.txt b/param_extraction/chunks/chunk_054.txt new file mode 100644 index 0000000000..fddc9f9e81 --- /dev/null +++ b/param_extraction/chunks/chunk_054.txt @@ -0,0 +1,2657 @@ +# Chunk: chunk_054 +# Source: supervisor.adoc +# Lines: 1-2630 (of 2630) +# Content starts: line 1 +# Line count: 2630 +# Sections: 20 +# == Supervisor-Level ISA, Version 1.13 +# === Supervisor CSRs +# ==== Supervisor Status (`sstatus`) Register +# ===== Base ISA Control in `sstatus` Register +# ===== Memory Privilege in `sstatus` Register +# ===== Endianness Control in `sstatus` Register +# ===== Previous Expected Landing Pad (ELP) State in `sstatus` Register +# ===== Double Trap Control in `sstatus` Register +# ==== Supervisor Trap Vector Base Address (`stvec`) Register +# ==== Supervisor Interrupt (`sip` and `sie`) Registers +# ==== Supervisor Timers and Performance Counters +# ==== Counter-Enable (`scounteren`) Register +# ==== Supervisor Scratch (`sscratch`) Register +# ==== Supervisor Exception Program Counter (`sepc`) Register +# ==== Supervisor Cause (`scause`) Register +# ==== Supervisor Trap Value (`stval`) Register +# ==== Supervisor Environment Configuration (`senvcfg`) Register +# ==== Supervisor Address Translation and Protection (`satp`) Register +# ==== Supervisor Timer (`stimecmp`) Register +# === Supervisor Instructions +# +[[supervisor]] +== Supervisor-Level ISA, Version 1.13 + +This chapter describes the RISC-V supervisor-level architecture, which +contains a common core that is used with various supervisor-level +address translation and protection schemes. + +[NOTE] +==== +Supervisor mode is deliberately restricted in terms of interactions with +underlying physical hardware, such as physical memory and device +interrupts, to support clean virtualization. In this spirit, certain +supervisor-level facilities, including requests for timer and +interprocessor interrupts, are provided by implementation-specific +mechanisms. In some systems, a supervisor execution environment (SEE) +provides these facilities in a manner specified by a supervisor binary +interface (SBI). Other systems supply these facilities directly, through +some other implementation-defined mechanism. +==== + +=== Supervisor CSRs + +A number of CSRs are provided for the supervisor. + +[NOTE] +==== +The supervisor should only view CSR state that should be visible to a +supervisor-level operating system. In particular, there is no +information about the existence (or non-existence) of higher privilege +levels (machine level or other) visible in the CSRs accessible by the +supervisor. + +Many supervisor CSRs are a subset of the equivalent machine-mode CSR, +and the machine-mode chapter should be read first to help understand the +supervisor-level CSR descriptions. +==== + +[[sstatus]] +==== Supervisor Status (`sstatus`) Register + +[[norm:sstatus]] +The `sstatus` register is an SXLEN-bit read/write register formatted as +shown in <> when SXLEN=32 +and <> when SXLEN=64. The `sstatus` +register keeps track of the processor's current operating state. + +[[sstatusreg-rv32]] +.Supervisor-mode status (`sstatus`) register when SXLEN=32. +[wavedrom, ,svg] +.... +{reg: [ + {bits: 1, name: 'WPRI'}, + {bits: 1, name: 'SIE'}, + {bits: 3, name: 'WPRI'}, + {bits: 1, name: 'SPIE'}, + {bits: 1, name: 'UBE'}, + {bits: 1, name: 'WPRI'}, + {bits: 1, name: 'SPP'}, + {bits: 2, name: 'VS[1:0]'}, + {bits: 2, name: 'WPRI'}, + {bits: 2, name: 'FS[1:0]'}, + {bits: 2, name: 'XS[1:0]'}, + {bits: 1, name: 'WPRI'}, + {bits: 1, name: 'SUM'}, + {bits: 1, name: 'MXR'}, + {bits: 3, name: 'WPRI'}, + {bits: 1, name: 'SPELP'}, + {bits: 1, name: 'SDT'}, + {bits: 6, name: 'WPRI'}, + {bits: 1, name: 'SD'}, +], config:{lanes: 2, hspace:1024}} +.... + +[[sstatusreg]] +.Supervisor-mode status (`sstatus`) register when SXLEN=64. +[wavedrom, ,svg] +.... +{reg: [ + {bits: 1, name: 'WPRI'}, + {bits: 1, name: 'SIE'}, + {bits: 3, name: 'WPRI'}, + {bits: 1, name: 'SPIE'}, + {bits: 1, name: 'UBE'}, + {bits: 1, name: 'WPRI'}, + {bits: 1, name: 'SPP'}, + {bits: 2, name: 'VS[1:0]'}, + {bits: 2, name: 'WPRI'}, + {bits: 2, name: 'FS[1:0]'}, + {bits: 2, name: 'XS[1:0]'}, + {bits: 1, name: 'WPRI'}, + {bits: 1, name: 'SUM'}, + {bits: 1, name: 'MXR'}, + {bits: 3, name: 'WPRI'}, + {bits: 1, name: 'SPELP'}, + {bits: 1, name: 'SDT'}, + {bits: 7, name: 'WPRI'}, + {bits: 2, name: 'UXL[1:0]'}, + {bits: 29, name: 'WPRI'}, + {bits: 1, name: 'SD'}, +], config:{lanes: 4, hspace:1024}} +.... + +[[norm:sstatus-spp]] +The SPP bit indicates the privilege level at which a hart was executing +before entering supervisor mode. When a trap is taken, SPP is set to 0 +if the trap originated from user mode, or 1 otherwise. When an SRET +instruction (see <>) is executed to +return from the trap handler, the privilege level is set to user mode if +the SPP bit is 0, or supervisor mode if the SPP bit is 1; SPP is then +set to 0. + +[[norm:sstatus-sie]] +The SIE bit enables or disables all interrupts in supervisor mode. When +SIE is clear, interrupts are not taken while in supervisor mode. When +the hart is running in user-mode, the value in SIE is ignored, and +supervisor-level interrupts are enabled. The supervisor can disable +individual interrupt sources using the `sie` CSR. + +[[norm:sstatus-spie]] +The SPIE bit indicates whether supervisor interrupts were enabled prior +to trapping into supervisor mode. When a trap is taken into supervisor +mode, SPIE is set to SIE, and SIE is set to 0. When an SRET instruction +is executed, SIE is set to SPIE, then SPIE is set to 1. + +The `sstatus` register is a subset of the `mstatus` register. + +[NOTE] +==== +In a straightforward implementation, reading or writing any field in +`sstatus` is equivalent to reading or writing the homonymous field in +`mstatus`. +==== + +===== Base ISA Control in `sstatus` Register + +[[norm:sstatus-uxl]] +The UXL field controls the value of XLEN for U-mode, termed _UXLEN_, +which may differ from the value of XLEN for S-mode, termed _SXLEN_. The +encoding of UXL is the same as that of the MXL field of `misa`, shown in +<>. + +[[norm:sstatus-uxl_sz]] +When SXLEN=32, the UXL field does not exist, and UXLEN=32. When +SXLEN=64, it is a *WARL* field that encodes the current value of UXLEN. In +particular, an implementation may make UXL be a read-only field whose +value always ensures that UXLEN=SXLEN. + +[[norm:sstatus-uxl_behavior]] +If UXLEN≠SXLEN, instructions executed in the narrower +mode must ignore source register operand bits above the configured XLEN, +and must sign-extend results to fill the widest supported XLEN in the +destination register. + +If UXLEN < SXLEN, user-mode instruction-fetch addresses +and load and store effective addresses are taken modulo +2^UXLEN^. For example, when UXLEN=32 and SXLEN=64, +user-mode memory accesses reference the lowest 4 GiB of the address space. + +[[norm:hint_sxlen_param]] +Some HINT instructions are encoded as integer computational instructions that +overwrite their destination register with its current value, e.g., +`c.addi x8, 0`. +When such a HINT is executed with XLEN < SXLEN and bits SXLEN..XLEN of the +destination register not all equal to bit XLEN-1, it is implementation-defined +whether bits SXLEN..XLEN of the destination register are unchanged or are +overwritten with copies of bit XLEN-1. + +NOTE: This definition allows implementations to elide register write-back for +some HINTs, while allowing them to execute other HINTs in the same manner as +other integer computational instructions. +The implementation choice is observable only by S-mode with SXLEN > UXLEN; it +is invisible to U-mode. + +[[sum]] +===== Memory Privilege in `sstatus` Register + +[[norm:sstatus-mxr]] +The MXR (Make eXecutable Readable) bit modifies the privilege with which +loads access virtual memory. When MXR=0, only loads from pages marked +readable (R=1 in <>) will succeed. When +MXR=1, loads from pages marked either readable or executable (R=1 or +X=1) will succeed. MXR has no effect when page-based virtual memory is +not in effect. + +[[norm:sstatus-sum]] +The SUM (permit Supervisor User Memory access) bit modifies the +privilege with which S-mode loads and stores access virtual memory. When +SUM=0, S-mode memory accesses to pages that are accessible by U-mode +(U=1 in <>) will fault. When SUM=1, these +accesses are permitted. SUM has no effect when page-based virtual memory +is not in effect, nor when executing in U-mode. Note that S-mode can +never execute instructions from user pages, regardless of the state of +SUM. + +[[norm:sstatus-sum_satp-mode]] +SUM is read-only 0 if `satp`.MODE is read-only 0. + +[NOTE] +==== +The SUM mechanism prevents supervisor software from inadvertently +accessing user memory. Operating systems can execute the majority of +code with SUM clear; the few code segments that should access user +memory can temporarily set SUM. + +The SUM mechanism does not avail S-mode software of permission to +execute instructions in user code pages. Legitimate use cases for +execution from user memory in supervisor context are rare in general and +nonexistent in POSIX environments. However, bugs in supervisors that +lead to arbitrary code execution are much easier to exploit if the +supervisor exploit code can be stored in a user buffer at a virtual +address chosen by an attacker. + +Some non-POSIX single address space operating systems do allow certain +privileged software to partially execute in supervisor mode, while most +programs run in user mode, all in a shared address space. This use case +can be realized by mapping the physical code pages at multiple virtual +addresses with different permissions, possibly with the assistance of +the instruction page-fault handler to direct supervisor software to use +the alternate mapping. +==== + +===== Endianness Control in `sstatus` Register + +[[norm:sstatus-ube]] +The UBE bit is a *WARL* field that controls the endianness of explicit memory +accesses made from U-mode, which may differ from the endianness of +memory accesses in S-mode. An implementation may make UBE be a read-only +field that always specifies the same endianness as for S-mode. + +UBE controls whether explicit load and store memory accesses made from +U-mode are little-endian (UBE=0) or big-endian (UBE=1). + +[[norm:sstatus-ube_implicit]] +UBE has no effect on instruction fetches, which are _implicit_ memory +accesses that are always little-endian. + +For _implicit_ accesses to supervisor-level memory management data +structures, such as page tables, S-mode endianness always applies and +UBE is ignored. + +[NOTE] +==== +Standard RISC-V ABIs are expected to be purely little-endian-only or +big-endian-only, with no accommodation for mixing endianness. +Nevertheless, endianness control has been defined so as to permit an OS +of one endianness to execute user-mode programs of the opposite +endianness. +==== + +===== Previous Expected Landing Pad (ELP) State in `sstatus` Register + +[[norm:sstatus-spelp]] +Access to the `SPELP` field, added by Zicfilp, accesses the homonymous +fields of `mstatus` when `V=0`, and the homonymous fields of `vsstatus` +when `V=1`. + +[[supv-double-trap]] +===== Double Trap Control in `sstatus` Register + +[[norm:sstatus-sdt]] +The S-mode-disable-trap (`SDT`) bit is a WARL field introduced by the Ssdbltrp +extension to address double trap (See <>) at privilege +modes lower than M. + +[[norm:sstatus-sdt_sstatus-sie_overwrite]] +When the `SDT` bit is set to 1 by an explicit CSR write, the `SIE` (Supervisor +Interrupt Enable) bit is cleared to 0. This clearing occurs regardless of the +value written, if any, to the `SIE` bit by the same write. The `SIE` bit can +only be set to 1 by an explicit CSR write if the `SDT` bit is being set to 0 by +the same write or is already 0. + +[[norm:sstatus-sdt_trap]] +When a trap is to be taken into S-mode, if the `SDT` bit is currently 0, +it is then set to 1, and the trap is delivered as expected. However, if `SDT` is +already set to 1, then this is an _unexpected trap_. In the event of an +_unexpected trap_, a double-trap exception trap is delivered into M-mode. To +deliver this trap, the hart writes registers, except `mcause` and `mtval2`, with +the same information that the _unexpected trap_ would have written if it was +taken into M-mode. The `mtval2` register is then set to what would be otherwise +written into the `mcause` register by the _unexpected trap_. The `mcause` +register is set to 16, the double-trap exception code. + +[[norm:sstatus-sdt_sret]] +An `SRET` instruction sets the `SDT` bit to 0. + +[NOTE] +==== +After a trap handler has saved the state, such as `scause`, `sepc`, +and `stval`, needed for resuming from the trap and is reentrant, it +should clear the `SDT` bit. + +Resetting the `SDT` by an `SRET` enables the trap handler to detect a double +trap that may occur during the tail phase, where it restores critical state +to return from a trap. + +The consequence of this specification is that if a critical error condition was +caused by a guest-page fault, then the GPA will not be available in `mtval2` +when the double trap is delivered to M-mode. This condition arises if the +HS-mode invokes a hypervisor virtual-machine load or store instruction when +`SDT` is 1 and the instruction raises a guest-page fault. The use of such an +instruction in this phase of trap handling is not common. However, not recording +the GPA is considered benign because, if required, it can still be obtained +-- albeit with added effort -- through the process of walking the page tables. + +For a double trap that originates in VS-mode, M-mode should redirect the exception +to HS-mode by copying the values of M-mode CSRs updated by the trap to HS-mode +CSRs and should use an `MRET` to resume execution at the address in `stvec`. + +Supervisor Software Events (SSE), an extension to the SBI, provide a +mechanism for supervisor software to register and service system events +emanating from an SBI implementation, such as firmware or a hypervisor. In the +event of a double trap, HS-mode and M-mode can utilize the SSE mechanism to +invoke a critical-error handler in VS-mode or S/HS-mode, respectively. +Additionally, the implementation of an SSE protocol can be considered as an +optional measure to aid in the recovery from such critical errors. +==== + +==== Supervisor Trap Vector Base Address (`stvec`) Register + +[[norm:stvec]] +The `stvec` register is an SXLEN-bit read/write register that holds trap +vector configuration, consisting of a vector base address (BASE) and a +vector mode (MODE). + +.Supervisor trap vector base address (`stvec`) register. +include::images/bytefield/stvec.edn[] + +[[norm:stvec_op]] +The BASE field in `stvec` is a field that can hold any valid virtual or +physical address, subject to the following alignment constraints: the +address must be 4-byte aligned, and MODE settings other than Direct +might impose additional alignment constraints on the value in the BASE +field. +[[norm:stvec_sz_base]] +Note that the CSR contains only bits XLEN-1 through 2 of the address BASE. +When used as an address, the lower two bits are filled with zeroes to obtain +an XLEN-bit address that is always aligned on a 4-byte boundary. + +[[stvec-mode]] +.Encoding of `stvec` MODE field. +[%autowidth,float="center",align="center",cols=">,^,<",options="header",] +|=== +|Value |Name |Description +|0 + +1 + +{ge}2 +|Direct + +Vectored +|All exceptions set `pc` to BASE. + +Asynchronous interrupts set `pc` to BASE+4{times}cause. + +_Reserved_ +|=== + +The encoding of the MODE field is shown in +<>. When MODE=Direct, all traps into +supervisor mode cause the `pc` to be set to the address in the BASE +field. When MODE=Vectored, all synchronous exceptions into supervisor +mode cause the `pc` to be set to the address in the BASE field, whereas +interrupts cause the `pc` to be set to the address in the BASE field +plus four times the interrupt cause number. For example, a +supervisor-mode timer interrupt (see <>) +causes the `pc` to be set to BASE+`0x14`. Setting MODE=Vectored may +impose a stricter alignment constraint on BASE. + +==== Supervisor Interrupt (`sip` and `sie`) Registers + +[[norm:sip_sie]] +The `sip` register is an SXLEN-bit read/write register containing +information on pending interrupts, while `sie` is the corresponding +SXLEN-bit read/write register containing interrupt enable bits. +Interrupt cause number _i_ (as reported in CSR `scause`, +<>) corresponds with bit _i_ in both `sip` and +`sie`. Bits 15:0 are allocated to standard interrupt causes only, while +bits 16 and above are designated for platform use. + +.Supervisor interrupt-pending register (`sip`). +include::images/bytefield/sip.edn[] + +.Supervisor interrupt-enable register (`sie`). +include::images/bytefield/sie.edn[] + +[[norm:sie_sip_supervisor_strap]] +An interrupt _i_ will trap to S-mode if both of the following are true: +(a) either the current privilege mode is S and the SIE bit in the +`sstatus` register is set, or the current privilege mode has less +privilege than S-mode; and (b) bit _i_ is set in both `sip` and `sie`. + +[[norm:sie_sip_strap_time_constraint]] +These conditions for an interrupt trap to occur must be evaluated in a +bounded amount of time from when an interrupt becomes, or ceases to be, +pending in `sip`, and must also be evaluated immediately following the +execution of an SRET instruction or an explicit write to a CSR on which +these interrupt trap conditions expressly depend (including `sip`, `sie` +and `sstatus`). + +[[norm:s_interrupt_priority]] +Interrupts to S-mode take priority over any interrupts to lower +privilege modes. + +[#norm:sip_acc]#Each individual bit in register `sip` may be writable or may be +read-only.# [#norm:sip_op]#When bit _i_ in `sip` is writable, a pending interrupt _i_ +can be cleared by writing 0 to this bit. If interrupt _i_ can become +pending but bit _i_ in `sip` is read-only, the implementation must +provide some other mechanism for clearing the pending interrupt (which +may involve a call to the execution environment).# + +[#norm:sie_acc]#A bit in `sie` must be writable if the corresponding interrupt can ever +become pending. Bits of `sie` that are not writable are read-only zero.# + +[[norm:sip_sie_bits_sz]] +The standard portions (bits 15:0) of registers `sip` and `sie` are +formatted as shown in Figures <> +and <> respectively. + +[[sipreg-standard]] +.Standard portion (bits 15:0) of `sip`. +include::images/bytefield/sipreg-standard.edn[] + +[[siereg-standard]] +.Standard portion (bits 15:0) of `sie`. +include::images/bytefield/siereg-standard.edn[] + + +[[norm:sip-seip_sie-seie]] +Bits `sip`.SEIP and `sie`.SEIE are the interrupt-pending and +interrupt-enable bits for supervisor-level external interrupts. If +implemented, SEIP is read-only in `sip`, and is set and cleared by the +execution environment, typically through a platform-specific interrupt +controller. + +[[norm:sip-stip_sie-stie]] +Bits `sip`.STIP and `sie`.STIE are the interrupt-pending and interrupt-enable +bits for supervisor-level timer interrupts. If implemented, STIP is read-only in +`sip`. When the Sstc extension is not implemented, STIP is set and cleared by +the execution environment. When the Sstc extension is implemented, STIP reflects +the timer interrupt signal resulting from `stimecmp`. The `sip`.STIP bit, in +response to timer interrupts generated by `stimecmp`, is set by writing +`stimecmp` with a value that is less than or equal to `time`, and is cleared by +writing `stimecmp` with a value greater than `time`. + +[[norm:sip-ssip_sie-ssie]] +Bits `sip`.SSIP and `sie`.SSIE are the interrupt-pending and +interrupt-enable bits for supervisor-level software interrupts. If +implemented, SSIP is writable in `sip` and may also be set to 1 by a +platform-specific interrupt controller. + +[[norm:sip_sie_Sscofpmf]] +If the Sscofpmf extension is implemented, bits `sip`.LCOFIP and `sie`.LCOFIE +are the interrupt-pending and interrupt-enable bits for local-counter-overflow +interrupts. +LCOFIP is read-write in `sip` and reflects the occurrence of a local +counter-overflow overflow interrupt request resulting from any of the +`mhpmevent__n__`.OF bits being set. +If the Sscofpmf extension is not implemented, `sip`.LCOFIP and `sie`.LCOFIE are +read-only zeros. + +[NOTE] +==== +Interprocessor interrupts are sent to other harts by +implementation-specific means, which will ultimately cause the SSIP bit +to be set in the recipient hart’s `sip` register. +==== + +[[norm:sip_sie_unimpl]] +Each standard interrupt type (SEI, STI, SSI, or LCOFI) may not be implemented, +in which case the corresponding interrupt-pending and interrupt-enable +bits are read-only zeros. All bits in `sip` and `sie` are *WARL* fields. The +implemented interrupts may be found by writing one to every bit location +in `sie`, then reading back to see which bit positions hold a one. + +[NOTE] +==== +The `sip` and `sie` registers are subsets of the `mip` and `mie` +registers. Reading any implemented field, or writing any writable field, +of `sip`/`sie` effects a read or write of the homonymous field of +`mip`/`mie`. + +Bits 3, 7, and 11 of `sip` and `sie` correspond to the machine-mode +software, timer, and external interrupts, respectively. Since most +platforms will choose not to make these interrupts delegatable from +M-mode to S-mode, they are shown as 0 in +<> and <>. +==== + +[[norm:sip_sie_priority_bit_order]] +Multiple simultaneous interrupts destined for supervisor mode are +handled in the following decreasing priority order: SEI, SSI, STI, LCOFI. + +==== Supervisor Timers and Performance Counters + +Supervisor software uses the same hardware performance monitoring +facility as user-mode software, including the `time`, `cycle`, and +`instret` CSRs. The implementation should provide a mechanism to modify +the counter values. + +[[norm:supervisor_timer_scheduling]] +The implementation must provide a facility for scheduling timer +interrupts in terms of the real-time counter, `time`. + +==== Counter-Enable (`scounteren`) Register + +.Counter-enable (`scounteren`) register +include::images/bytefield/scounteren.edn[] + +[[norm:scounteren]] +The counter-enable (`scounteren`) CSR is a 32-bit register that +controls the availability of the hardware performance monitoring +counters to U-mode. + +[[norm:scounteren_op]] +When the CY, TM, IR, or HPM__n__ bit in the `scounteren` register is +clear, attempts to read the `cycle`, `time`, `instret`, or `hpmcountern` +register while executing in U-mode will cause an illegal-instruction +exception. When one of these bits is set, access to the corresponding +register is permitted. + +[[norm:scounteren_acc]] +`scounteren` must be implemented. However, any of the bits may be +read-only zero, indicating reads to the corresponding counter will cause +an exception when executing in U-mode. Hence, they are effectively +*WARL* fields. + +[NOTE] +==== +The setting of a bit in `mcounteren` does not affect whether the +corresponding bit in `scounteren` is writable. However, U-mode may only +access a counter if the corresponding bits in `scounteren` and +`mcounteren` are both set. +==== + +==== Supervisor Scratch (`sscratch`) Register + +[[norm:sscratch]] +The `sscratch` CSR is an SXLEN-bit read/write register, dedicated +for use by the supervisor. Typically, `sscratch` is used to hold a +pointer to the hart-local supervisor context while the hart is executing +user code. +At the beginning of a trap handler, software normally uses a CSRRW +instruction to swap `sscratch` with an integer register to obtain an +initial working register. + +.Supervisor Scratch Register +include::images/bytefield/sscratch.edn[] + +==== Supervisor Exception Program Counter (`sepc`) Register + +[[norm:sepc]] +`sepc` is an SXLEN-bit read/write CSR formatted as shown in +<>. The low bit of `sepc` (`sepc[0]`) is always zero. On implementations that support only IALIGN=32, the two low bits (`sepc[1:0]`) are always zero. + +[[norm:sepc_op_mask_ialign32]] +If an implementation allows IALIGN to be either 16 or 32 (by changing +CSR `misa`, for example), then, whenever IALIGN=32, bit `sepc[1]` is +masked on reads so that it appears to be 0. This masking occurs also for +the implicit read by the SRET instruction. Though masked, `sepc[1]` +remains writable when IALIGN=32. + +[[norm:sepc_acc_invalid_addr]] +`sepc` is a *WARL* register that must be able to hold all valid virtual +addresses. It need not be capable of holding all possible invalid +addresses. Prior to writing `sepc`, implementations may convert an +invalid address into some other invalid address that `sepc` is capable +of holding. + +[[norm:sepc_op_trap_write]] +When a trap is taken into S-mode, `sepc` is written with the virtual +address of the instruction that was interrupted or that encountered the +exception. Otherwise, `sepc` is never written by the implementation, +though it may be explicitly written by software. + +[[epcreg]] +.Supervisor exception program counter register. +include::images/bytefield/epcreg.edn[] + +[[scause]] +==== Supervisor Cause (`scause`) Register + +[[norm:scause]] +The `scause` CSR is an SXLEN-bit read-write register formatted as +shown in <>. When a trap is taken into +S-mode, `scause` is written with a code indicating the event that +caused the trap. Otherwise, `scause` is never written by the +implementation, though it may be explicitly written by software. + +[[norm:scause-interrupt]] +The Interrupt bit in the `scause` register is set if the trap was caused +by an interrupt. The Exception Code field contains a code identifying +the last exception or interrupt. <> lists +the possible exception codes for the current supervisor ISAs. [#norm:scause-exception_code_acc]#The +Exception Code is a *WLRL* field.# [#norm:scause-exception_code_sz]#It is required to hold the values 0–31 +(i.e., bits 4–0 must be implemented), but otherwise it is only +guaranteed to hold supported exception codes.# + +[[scausereg]] +.Supervisor Cause (`scause`) register. +include::images/bytefield/scausereg.edn[] + +[[scauses]] +.Supervisor cause (`scause`) register values after trap. Synchronous exception priorities are given by <>. +[%autowidth,float="center",align="center",cols=">,>,3",options="header"] +|=== +|Interrupt |Exception Code |Description +|1 + +1 + +1 + +1 + +1 + +1 + +1 + +1 + +1 + +1 +|0 + +1 + +2-4 + +5 + +6-8 + +9 + +10-12 + +13 + +14-15 + +{ge}16 +|_Reserved_ + +Supervisor software interrupt + +_Reserved_ + +Supervisor timer interrupt + +_Reserved_ + +Supervisor external interrupt + +_Reserved_ + +Counter-overflow interrupt + +_Reserved_ + +_Designated for platform use_ + +|0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 + +0 +|0 + +1 + +2 + +3 + +4 + +5 + +6 + +7 + +8 + +9 + +10-11 + +12 + +13 + +14 + +15 + +16-17 + +18 + +19 + +20-23 + +24-31 + +32-47 + +48-63 + +{ge}64 +|Instruction address misaligned + +Instruction access fault + +Illegal instruction + +Breakpoint + +Load address misaligned + +Load access fault + +Store/AMO address misaligned + +Store/AMO access fault + +Environment call from U-mode + +Environment call from S-mode + +_Reserved_ + +Instruction page fault + +Load page fault + +_Reserved_ + +Store/AMO page fault + +_Reserved_ + +Software check + +Hardware error + +_Reserved_ + +_Designated for custom use_ + +_Reserved_ + +_Designated for custom use_ + +_Reserved_ +|=== + +==== Supervisor Trap Value (`stval`) Register + +[[norm:stval]] +The `stval` CSR is an SXLEN-bit read-write register formatted as +shown in <>. When a trap is taken into +S-mode, `stval` is written with exception-specific information to assist +software in handling the trap. Otherwise, `stval` is never written by +the implementation, though it may be explicitly written by software. The +hardware platform will specify which exceptions must set `stval` +informatively, which may unconditionally set it to zero, and which may +exhibit either behavior, depending on the underlying event that caused the +exception. + +[[norm:stval_op_faulting_addr]] +If `stval` is written with a nonzero value when a breakpoint, +address-misaligned, access-fault, page-fault, or hardware-error exception +occurs on an +instruction fetch, load, or store, then `stval` will contain the +faulting virtual address. + +[[norm:stval_op_breakpoint]] +On a breakpoint exception raised by an EBREAK or C.EBREAK instruction, `stval` +is written with either zero or the virtual address of the instruction. + +[[stvalreg]] +.Supervisor Trap Value register. +include::images/bytefield/stvalreg.edn[] + +[[norm:stval_op_load_store_fault]] +If `stval` is written with a nonzero value when a misaligned load or +store causes an access-fault, page-fault, or hardware-error exception, +then `stval` will +contain the virtual address of the portion of the access that caused the +fault. + +[[norm:stval_faulting_address_variable_instr]] +If `stval` is written with a nonzero value when an instruction +access-fault, page-fault, or hardware-error exception occurs on a hart with +variable-length instructions, then `stval` will contain the virtual +address of the portion of the instruction that caused the fault, while +`sepc` will point to the beginning of the instruction. + +[[norm:stval_op_illegal_instr]] +The `stval` register can optionally also be used to return the faulting +instruction bits on an illegal-instruction exception (`sepc` points to +the faulting instruction in memory). If `stval` is written with a +nonzero value when an illegal-instruction exception occurs, then `stval` +will contain the shortest of: + +* the actual faulting instruction +* the first ILEN bits of the faulting instruction +* the first SXLEN bits of the faulting instruction + +[[norm:stval_op_illegal_instr_format]] +The value loaded into `stval` on an illegal-instruction exception is +right-justified and all unused upper bits are cleared to zero. + +[[norm:stval_exception_info]] +On a trap caused by a software-check exception, the `stval` register holds the +cause for the exception. The following encodings are defined: + +* 0 - No information provided. +* 2 - Landing Pad Fault. Defined by the Zicfilp extension (<>). +* 3 - Shadow Stack Fault. Defined by the Zicfiss extension (<>). + +[[norm:stval_op_other_traps]] +For other traps, `stval` is set to zero, but a future standard may +redefine `stval`’s setting for other traps. + +[[norm:stval_acc]] +`stval` is a *WARL* register that must be able to hold all valid virtual +addresses and the value 0. It need not be capable of holding all +possible invalid addresses. Prior to writing `stval`, implementations +may convert an invalid address into some other invalid address that +`stval` is capable of holding. If the feature to return the faulting +instruction bits is implemented, `stval` must also be able to hold all +values less than 2^_N_^, where _N_ is the smaller +of SXLEN and ILEN. + +[[sec:senvcfg]] +==== Supervisor Environment Configuration (`senvcfg`) Register + +[[norm:senvcfg]] +The `senvcfg` CSR is an SXLEN-bit read/write register, formatted as +shown in <>, that controls certain +characteristics of the U-mode execution environment. + +[[senvcfg]] +.Supervisor environment configuration register (`senvcfg`) for RV64. +[wavedrom, ,svg] +.... +{reg: [ + {bits: 1, name: 'FIOM'}, + {bits: 1, name: 'WPRI'}, + {bits: 1, name: 'LPE'}, + {bits: 1, name: 'SSE'}, + {bits: 2, name: 'CBIE'}, + {bits: 1, name: 'CBCFE'}, + {bits: 1, name: 'CBZE'}, + {bits: 24, name: 'WPRI'}, + {bits: 2, name: 'PMM'}, + {bits: 30, name: 'WPRI'}, +], config:{lanes: 4, hspace:1024}} +.... + +.Supervisor environment configuration register (`senvcfg`) for RV32. +[wavedrom, ,svg] +.... +{reg: [ + {bits: 1, name: 'FIOM'}, + {bits: 1, name: 'WPRI'}, + {bits: 1, name: 'LPE'}, + {bits: 1, name: 'SSE'}, + {bits: 2, name: 'CBIE'}, + {bits: 1, name: 'CBCFE'}, + {bits: 1, name: 'CBZE'}, + {bits: 24, name: 'WPRI'}, +], config:{lanes: 2, hspace:1024}} +.... + +[[norm:senvcfg-fiom]] +If bit FIOM (Fence of I/O implies Memory) is set to one in `senvcfg`, +FENCE instructions executed in U-mode are modified so the requirement to +order accesses to device I/O implies also the requirement to order main +memory accesses. <> details the modified +interpretation of FENCE instruction bits PI, PO, SI, and SO in U-mode +when FIOM=1. + +[[norm:senvcfg-fiom_op_atomic]] +Similarly, for U-mode when FIOM=1, if an atomic instruction that +accesses a region ordered as device I/O has its _aq_ and/or _rl_ bit +set, then that instruction is ordered as though it accesses both device +I/O and memory. + +[[norm:senvcfg-fiom_acc]] +If `satp`.MODE is read-only zero (always Bare), the implementation may +make FIOM read-only zero. + +[[senvcfg-FIOM]] +.Modified interpretation of FENCE predecessor and successor sets in U-mode when FIOM=1. +[%autowidth,float="center",align="center",cols="^,<",options="header"] +|=== +|Instruction bit |Meaning when set +|PI + +PO +|Predecessor device input and memory reads (PR implied) + +Predecessor device output and memory writes (PW implied) +|SI + +SO +|Successor device input and memory reads (SR implied) + +Successor device output and memory writes (SW implied) +|=== + +[NOTE] +==== +Bit FIOM exists for a specific circumstance when an I/O device is being +emulated for U-mode and both of the following are true: (a) the emulated +device has a memory buffer that should be I/O space but is actually +mapped to main memory via address translation, and (b) multiple physical +harts are involved in accessing this emulated device from U-mode. + +A hypervisor running in S-mode without the benefit of the hypervisor +extension of <> may need to emulate +a device for U-mode if paravirtualization cannot be employed. If the +same hypervisor provides a virtual machine (VM) with multiple virtual +harts, mapped one-to-one to real harts, then multiple harts may +concurrently access the emulated device, perhaps because: (a) the guest +OS within the VM assigns device interrupt handling to one hart while the +device is also accessed by a different hart outside of an interrupt +handler, or (b) control of the device (or partial control) is being +migrated from one hart to another, such as for interrupt load balancing +within the VM. For such cases, guest software within the VM is expected +to properly coordinate access to the (emulated) device across multiple +harts using mutex locks and/or interprocessor interrupts as usual, which +in part entails executing I/O fences. But those I/O fences may not be +sufficient if some of the device ``I/O'' is actually main memory, +unknown to the guest. Setting FIOM=1 modifies those fences (and all +other I/O fences executed in U-mode) to include main memory, too. + +Software can always avoid the need to set FIOM by never using main +memory to emulate a device memory buffer that should be I/O space. +However, this choice usually requires trapping all U-mode accesses to +the emulated buffer, which might have a noticeable impact on +performance. The alternative offered by FIOM is sufficiently inexpensive +to implement that we consider it worth supporting even if only rarely +enabled. +==== + +[[norm:senvcfg-cbze]] +The Zicboz extension adds the `CBZE` (Cache Block Zero instruction enable) field +to `senvcfg`. The `CBZE` field controls execution of the cache block zero +instruction (`CBO.ZERO`) in U-mode. Execution of `CBO.ZERO` in U-mode is enabled +only if execution of the instruction is enabled for use in S-mode and `CBZE` is +set to 1; otherwise, an illegal-instruction exception is raised. When the Zicboz +extension is not implemented, `CBZE` is read-only zero. + +[[norm:senvcfg-cbcfe]] +The Zicbom extension adds the `CBCFE` (Cache Block Clean and Flush instruction +Enable) field to `senvcfg` to control execution of the `CBO.CLEAN` and +`CBO.FLUSH` instructions in U-mode. Execution of these instructions in U-mode is +enabled only if execution of these instructions is enabled for use in S-mode and +`CBCFE` is set to 1; otherwise, an illegal-instruction exception is raised. When +the Zicbom extension is not implemented, `CBCFE` is read-only zero. + +[[norm:senvcfg-cbie]] +The Zicbom extension adds the `CBIE` (Cache Block Invalidate instruction Enable) +WARL field to `senvcfg` to control execution of the `CBO.INVAL` instruction in +U-mode. The encoding `10b` is reserved. When the Zicbom extension is not +implemented, `CBIE` is read-only zero. Execution of `CBO.INVAL` in U-mode is +enabled only if execution of the instruction is enabled for use in S-mode and +`CBIE` is set to `01b` or `11b`; otherwise, an illegal-instruction exception is +raised. + +[#norm:cbo-inval_s-mode_op0]#If `CBO.INVAL` is enabled in S-mode to perform a flush operation, then when the +instruction is enabled in U-mode it performs a flush operation, even if `CBIE` +is set to `11b`. Otherwise, the instruction behaves as follows, depending on the +`CBIE` encoding:# + +* [[norm:cbo-inval_s-mode_op1]]`01b` -- The instruction is executed and performs a flush operation. +* [[norm:cbo-inval_s-mode_op2]]`11b` -- The instruction is executed and performs an invalidate operation. + +[[norm:senvcfg-pmm_Ssnpm]] +If the Ssnpm extension is implemented, the `PMM` field enables or disables +pointer masking (see <>) for the next-lower privilege mode (U/VU), +according to the values in <>. If Ssnpm is not +implemented, `PMM` is read-only zero. The `PMM` field is read-only zero for +RV32. + +[[senvcfg-pmm-values]] + +[%header, cols="25%,75%", options="header"] +.Legal values of `PMM` WARL field +|=== +|Value|Description +|00|Pointer masking is disabled (PMLEN = 0) +|01|Reserved +|10|Pointer masking is enabled with PMLEN = XLEN - 57 (PMLEN = 7 on RV64) +|11|Pointer masking is enabled with PMLEN = XLEN - 48 (PMLEN = 16 on RV64) +|=== + +[[norm:senvcfg-lpe_Zicfilp]] +The Zicfilp extension adds the `LPE` field in `senvcfg`. When the `LPE` field is +set to 1, the Zicfilp extension is enabled in VU/U-mode. When the `LPE` field is +0, the Zicfilp extension is not enabled in VU/U-mode and the following rules +apply to VU/U-mode: + +* The hart does not update the `ELP` state; it remains as `NO_LP_EXPECTED`. +* The `LPAD` instruction operates as a no-op. + +[[norm:senvcfg-sse_Zicfilp]] +The Zicfiss extension adds the `SSE` field in `senvcfg`. When the `SSE` field is +set to 1, the Zicfiss extension is activated in VU/U-mode. When the `SSE` field +is 0, the Zicfiss extension remains inactive in VU/U-mode, and the following +rules apply: + +* 32-bit Zicfiss instructions will revert to their behavior as defined by Zimop. +* 16-bit Zicfiss instructions will revert to their behavior as defined by Zcmop. +* When `menvcfg.SSE` is one, `SSAMOSWAP.W/D` raises an illegal-instruction + exception in U-mode and a virtual-instruction exception in VU-mode. + +[[satp]] +==== Supervisor Address Translation and Protection (`satp`) Register + +[[norm:satp]] +The `satp` CSR is an SXLEN-bit read/write register, formatted as +shown in <> for SXLEN=32 and +<> for SXLEN=64, which controls +supervisor-mode address translation and protection. This register holds +the physical page number (PPN) of the root page table, i.e., its +supervisor physical address divided by 4 KiB; an address space identifier +(ASID), which facilitates address-translation fences on a +per-address-space basis; and the MODE field, which selects the current +address-translation scheme. Further details on the access to this +register are described in <>. + +[[rv32satp]] +.Supervisor address translation and protection (`satp`) register when SXLEN=32. +include::images/bytefield/rv32satp.edn[] + +[NOTE] +==== +Storing a PPN in `satp`, rather than a physical address, supports a +physical address space larger than 4 GiB for RV32. + +The `satp`.PPN field might not be capable of holding all physical page +numbers. Some platform standards might place constraints on the values +`satp`.PPN may assume, e.g., by requiring that all physical page numbers +corresponding to main memory be representable. +==== + +[[rv64satp]] +.Supervisor address translation and protection (`satp`) register when SXLEN=64, for MODE values Bare, Sv39, Sv48, and Sv57. +include::images/bytefield/rv64satp.edn[] + +[NOTE] +==== +We store the ASID and the page table base address in the same CSR to +allow the pair to be changed atomically on a context switch. Swapping +them non-atomically could pollute the old virtual address space with new +translations, or vice-versa. This approach also slightly reduces the +cost of a context switch. +==== + +[[norm:satp-mode]] +<> shows the encodings of the MODE field when +SXLEN=32 and SXLEN=64. When MODE=Bare, supervisor virtual addresses are +equal to supervisor physical addresses, and there is no additional +memory protection beyond the physical memory protection scheme described +in <>. To select MODE=Bare, software must write +zero to the remaining fields of `satp` (bits 30–0 when SXLEN=32, or bits +59–0 when SXLEN=64). Attempting to select MODE=Bare with a nonzero +pattern in the remaining fields has an UNSPECIFIED effect on the value that the +remaining fields assume and an UNSPECIFIED effect on address translation and +protection behavior. + +When SXLEN=32, the `satp` encodings corresponding to MODE=Bare and +ASID[8:7]=3 are designated for custom use, whereas the encodings +corresponding to MODE=Bare and ASID[8:7]≠3 are reserved +for future standard use. When SXLEN=64, all `satp` encodings +corresponding to MODE=Bare are reserved for future standard use. + +[NOTE] +==== +Version 1.11 of this standard stated that the remaining fields in `satp` +had no effect when MODE=Bare. Making these fields reserved facilitates +future definition of additional translation and protection modes, +particularly in RV32, for which all patterns of the existing MODE field +have already been allocated. +==== + +[[norm:satp-mode_sxlen32]] +When SXLEN=32, the only other valid setting for MODE is Sv32, a paged +virtual-memory scheme described in <>. + +[[norm:satp-mode_sxlen64]] +When SXLEN=64, three paged virtual-memory schemes are defined: Sv39, +Sv48, and Sv57, described in <>, <>, +and <>, respectively. One additional scheme, Sv64, will be +defined in a later version of this specification. The remaining MODE +settings are reserved for future use and may define different +interpretations of the other fields in `satp`. + +[[norm:satp-mode_op_unsupported]] +Implementations are not required to support all MODE settings, and if +`satp` is written with an unsupported MODE, the entire write has no +effect; no fields in `satp` are modified. + +[[norm:satp-asidlen]] +The number of ASID bits is UNSPECIFIED and may be zero. The number of implemented +ASID bits, termed _ASIDLEN_, may be determined by writing one to every +bit position in the ASID field, then reading back the value in `satp` to +see which bit positions in the ASID field hold a one. The +least-significant bits of ASID are implemented first: that is, if +ASIDLEN > 0, ASID[ASIDLEN-1:0] is writable. The maximal +value of ASIDLEN, termed ASIDMAX, is 9 for Sv32 or 16 for Sv39, Sv48, +and Sv57. + +<<< + +[[satp-mode]] +.Encoding of `satp` MODE field. +[%autowidth,float="center",align="center",cols="^,^,<",options="header"] +|=== +3+|SXLEN=32 +|Value |Name |Description +|0 + +1 +|Bare + +Sv32 +|No translation or protection. + +Page-based 32-bit virtual addressing (see <>). +3+|*SXLEN=64* +|Value |Name |Description +|0 + +1-7 + +8 + +9 + +10 + +11 + +12-13 + +14-15 +|Bare + +- + +Sv39 + +Sv48 + +Sv57 + +Sv64 + +- + +- +|No translation or protection. + +_Reserved for standard use_ + +Page-based 39-bit virtual addressing (see <>). + +Page-based 48-bit virtual addressing (see <>). + +Page-based 57-bit virtual addressing (see <>). + +_Reserved for page-based 64-bit virtual addressing._ + +_Reserved for standard use_ + +_Designated for custom use_ +|=== + +[NOTE] +==== +For many applications, the choice of page size has a substantial +performance impact. A large page size increases TLB reach and loosens +the associativity constraints on virtually indexed, physically tagged +caches. At the same time, large pages exacerbate internal fragmentation, +wasting physical memory and possibly cache capacity. + +After much deliberation, we have settled on a conventional page size of +4 KiB for both RV32 and RV64. We expect this decision to ease the +porting of low-level runtime software and device drivers. The TLB reach +problem is ameliorated by transparent superpage support in modern +operating systems. cite:[transparent-superpages] Additionally, multi-level TLB hierarchies are quite +inexpensive relative to the multi-level cache hierarchies whose address +space they map. +==== + +[[norm:satp_op_active]] +The `satp` CSR is considered _active_ when the effective privilege +mode is S-mode or U-mode. Executions of the address-translation +algorithm may only begin using a given value of `satp` when `satp` is +active. + +[NOTE] +==== +Translations that began while `satp` was active are not required to +complete or terminate when `satp` is no longer active, unless an +SFENCE.VMA instruction matching the address and ASID is executed. The +SFENCE.VMA instruction must be used to ensure that updates to the +address-translation data structures are observed by subsequent implicit +reads to those structures by a hart. +==== + +[[norm:satp_op_sfence-vma]] +Note that writing `satp` does not imply any ordering constraints between +page-table updates and subsequent address translations, nor does it +imply any invalidation of address-translation caches. If the new address +space’s page tables have been modified, or if an ASID is reused, it may +be necessary to execute an SFENCE.VMA instruction (see +<>) after, or in some cases before, writing +`satp`. + +[NOTE] +==== +Not imposing upon implementations to flush address-translation caches +upon `satp` writes reduces the cost of context switches, provided a +sufficiently large ASID space. +==== + +[[stimecmp]] +==== Supervisor Timer (`stimecmp`) Register + +[#norm:stimecmp-stimecmph_sz_acc]#The `stimecmp` CSR is a 64-bit register and +has 64-bit precision on all RV32 and RV64 systems. +In RV32 only, accesses to the `stimecmp` CSR access the low 32 bits, +while accesses to the `stimecmph` CSR access the high 32 bits of `stimecmp`.# + +[[norm:mip_sip-stip_op]] +A supervisor timer interrupt becomes pending, as reflected in the STIP bit in +the `mip` and `sip` registers whenever `time` contains a value greater than or +equal to `stimecmp`, treating the values as unsigned integers. +If the result of this comparison changes, it is guaranteed to be reflected in +STIP eventually, but not necessarily immediately. +The interrupt remains posted until `stimecmp` becomes greater than `time`, +typically as a result of writing `stimecmp`. +The interrupt will be taken based on the standard interrupt enable and +delegation rules. + +[NOTE] +==== +A spurious timer interrupt might occur if an interrupt handler advances +`stimecmp` then immediately returns, because STIP might not yet have fallen in +the interim. All software should be written to assume this event is possible, +but most software should assume this event is extremely unlikely. It is almost +always more performant to incur an occasional spurious timer interrupt than to +poll STIP until it falls. +==== + +[NOTE] +==== +In systems in which a supervisor execution environment (SEE) provides timer +facilities via an SBI function call, this SBI call will continue to support +requests to schedule a timer interrupt. The SEE will simply make use of +stimecmp, changing its value as appropriate. This ensures compatibility with +existing S-mode software that uses this SEE facility, while new S-mode software +takes advantage of stimecmp directly.) +==== + +=== Supervisor Instructions + +In addition to the SRET instruction defined in <>, one new supervisor-level instruction is provided. + +[[sfence.vma]] +==== Supervisor Memory-Management Fence Instruction +include::images/wavedrom/sfencevma.edn[] + + +[[norm:sfence-vma_op]] +The supervisor memory-management fence instruction SFENCE.VMA is used to +synchronize updates to in-memory memory-management data structures with +current execution. Instruction execution causes implicit reads and +writes to these data structures; however, these implicit references are +ordinarily not ordered with respect to explicit loads and stores. +[#norm:sfence-vma_ordering]#Executing an SFENCE.VMA instruction guarantees that any previous stores +already visible to the current RISC-V hart are ordered before certain +implicit references by subsequent instructions in that hart to the +memory-management data structures. The specific set of operations +ordered by SFENCE.VMA is determined by _rs1_ and _rs2_, as described +below.# [#norm:sfence-vma_invalidation]#SFENCE.VMA is also used to invalidate entries in the +address-translation cache associated with a hart (see <>).# Further details on the behavior of this instruction are described in <> and <>. + +[NOTE] +==== +The SFENCE.VMA is used to flush any local hardware caches related to +address translation. It is specified as a fence rather than a TLB flush +to provide cleaner semantics with respect to which instructions are +affected by the flush operation and to support a wider variety of +dynamic caching structures and memory-management schemes. SFENCE.VMA is +also used by higher privilege levels to synchronize page table writes +and the address translation hardware. +==== + +SFENCE.VMA orders only the local hart’s implicit references to the +memory-management data structures. + +[NOTE] +==== +Consequently, other harts must be notified separately when the +memory-management data structures have been modified. One approach is to +use 1) a local data fence to ensure local writes are visible globally, +then 2) an interprocessor interrupt to the other thread, then 3) a local +SFENCE.VMA in the interrupt handler of the remote thread, and finally 4) +signal back to originating thread that operation is complete. This is, +of course, the RISC-V analog to a TLB shootdown. +==== + +For the common case that the translation data structures have only been +modified for a single address mapping (i.e., one page or superpage), +_rs1_ can specify a virtual address within that mapping to effect a +translation fence for that mapping only. Furthermore, for the common +case that the translation data structures have only been modified for a +single address-space identifier, _rs2_ can specify the address space. +The behavior of SFENCE.VMA depends on _rs1_ and _rs2_ as follows: + + +* [#norm:sfence-vma_all_asid_va]#If __rs1__=`x0` and __rs2__=`x0`, the fence orders all reads and writes +made to any level of the page tables, for all address spaces. The fence +also invalidates all address-translation cache entries, for all address +spaces.# + +* [#norm:sfence-vma_asid_only]#If __rs1__=`x0` and __rs2__{ne}``x0``, the fence orders all +reads and writes made to any level of the page tables, but only for the +address space identified by integer register _rs2_. Accesses to _global_ +mappings (see <>) are not ordered. The +fence also invalidates all address-translation cache entries matching +the address space identified by integer register _rs2_, except for +entries containing global mappings.# + +* [#norm:sfence-vma_va_all_asid]#If __rs1__{ne}``x0`` and __rs2__=`x0`, the fence orders only +reads and writes made to leaf page table entries corresponding to the +virtual address in __rs1__, for all address spaces. The fence also +invalidates all address-translation cache entries that contain leaf page +table entries corresponding to the virtual address in _rs1_, for all +address spaces.# + +* [#norm:sfence-vma_va_asid]#If __rs1__{ne}``x0`` and __rs2__{ne}``x0``, the +fence orders only reads and writes made to leaf page table entries +corresponding to the virtual address in _rs1_, for the address space +identified by integer register _rs2_. Accesses to global mappings are +not ordered. The fence also invalidates all address-translation cache +entries that contain leaf page table entries corresponding to the +virtual address in _rs1_ and that match the address space identified by +integer register _rs2_, except for entries containing global mappings.# + +[[norm:sfence-vma_invalid_va]] +If the value held in _rs1_ is not a valid virtual address, then the +SFENCE.VMA instruction has no effect. No exception is raised in this +case. + +[NOTE] +==== +It is always legal to over-fence, e.g., by fencing only based on a +subset of the bits in _rs1_ and/or _rs2_, and/or by simply treating all +SFENCE.VMA instructions as having _rs1_=`x0` and/or _rs2_=`x0`. For +example, simpler implementations can ignore the virtual address in _rs1_ +and the ASID value in _rs2_ and always perform a global fence. The +choice not to raise an exception when an invalid virtual address is held +in _rs1_ facilitates this type of simplification. +==== + +[[norm:sfence-vma_rs2_bits]] +When __rs2__{ne}``x0``, bits SXLEN-1:ASIDMAX of the value held +in _rs2_ are reserved for future standard use. Until their use is +defined by a standard extension, they should be zeroed by software and +ignored by current implementations. Furthermore, if +ASIDLEN>), as pointer masking applies to the effective address only and +does not affect any memory-management data structures. + +[[sv32]] +=== Sv32: Page-Based 32-bit Virtual-Memory Systems + +When Sv32 is written to the MODE field in the `satp` register (see +<>), the supervisor operates in a 32-bit paged +virtual-memory system. In this mode, supervisor and user virtual +addresses are translated into supervisor physical addresses by +traversing a radix-tree page table. Sv32 is supported when SXLEN=32 and +is designed to include mechanisms sufficient for supporting modern +Unix-based operating systems. + +[NOTE] +==== +The initial RISC-V paged virtual-memory architectures have been designed +as straightforward implementations to support existing operating +systems. We have architected page table layouts to support a hardware +page-table walker. Software TLB refills are a performance bottleneck on +high-performance systems, and are especially troublesome with decoupled +specialized coprocessors. An implementation can choose to implement +software TLB refills using a machine-mode trap handler as an extension +to M-mode. + +*** + +Some ISAs architecturally expose _virtually indexed, physically tagged_ +caches, in that accesses to the same physical address via different +virtual addresses might not be coherent unless the virtual addresses lie +within the same cache set. Implicitly, this specification does not +permit such behavior to be architecturally exposed. +==== + +[[translation]] +==== Addressing and Memory Protection + +Sv32 implementations support a 32-bit virtual address space, divided +into pages. An Sv32 virtual address is partitioned into a virtual page +number (VPN) and page offset, as shown in <>. +When Sv32 virtual memory mode is selected in the MODE field of the +`satp` register, supervisor virtual addresses are translated into +supervisor physical addresses via a two-level page table. The 20-bit VPN +is translated into a [#norm:satp-ppn_sv32_sz]#22-bit physical page number (PPN)#, +while the 12-bit page offset is untranslated. The resulting supervisor-level physical +addresses are then checked using any physical memory protection +structures (<>), before being directly +converted to machine-level physical addresses. If necessary, +supervisor-level physical addresses are zero-extended to the number of +physical address bits found in the implementation. + +[NOTE] +==== +For example, consider an RV32 system supporting 34 bits of physical +address. When the value of `satp`.MODE is Sv32, a 34-bit physical +address is produced directly, and therefore no zero extension is needed. +When the value of `satp`.MODE is Bare, the 32-bit virtual address is +translated (unmodified) into a 32-bit physical address, and then that +physical address is zero-extended into a 34-bit machine-level physical +address. +==== +[[sv32va]] +.Sv32 virtual address. +include::images/bytefield/sv32va.edn[] + + +Sv32 page tables consist of 2^10^ page-table entries +(PTEs), each of four bytes. A page table is exactly the size of a page +and must always be aligned to a page boundary. The physical page number +of the root page table is stored in the `satp` register. + +[[sv32pa]] +.SV32 physical address. +include::images/bytefield/sv32pa.edn[] + +[[sv32pte]] +.Sv32 page table entry. +include::images/bytefield/sv32pte.edn[] + +The PTE format for Sv32 is shown in <>. +The V bit indicates whether the PTE is valid; if it is 0, all other bits +in the PTE are don’t-cares and may be used freely by software. The +permission bits, R, W, and X, indicate whether the page is readable, +writable, and executable, respectively. When all three are zero, the PTE +is a pointer to the next level of the page table; otherwise, it is a +leaf PTE. Writable pages must also be marked readable; the contrary +combinations are reserved for future use. <> +summarizes the encoding of the permission bits. + +[[pteperm]] +.Encoding of PTE R/W/X fields. +[%autowidth,float="center",align="center",cols="^,^,^,<",options="header"] +|=== +|X |W |R |Meaning +|0 + +0 + +0 + +0 + +1 + +1 + +1 + +1 +|0 + +0 + +1 + +1 + +0 + +0 + +1 + +1 +|0 + +1 + +0 + +1 + +0 + +1 + +0 + +1 +|Pointer to next level of page table. + +Read-only page. + +_Reserved for future use._ + +Read-write page. + +Execute-only page. + +Read-execute page. + +_Reserved for future use._ + +Read-write-execute page. +|=== + +[#norm:fetch_page_fault_no_x]#Attempting to fetch an instruction from a page that does not have +execute permissions raises a fetch page-fault exception.# +[#norm:load_page_fault_no_r]#Attempting to execute a load, load-reserved, or cache-block management +instruction whose effective address lies +within a page without read permissions raises a load page-fault exception.# +[#norm:store_page_fault_no_w]#Attempting to execute a store, store-conditional, AMO, or cache-block zero instruction +instruction whose effective address lies within a page without write +permissions raises a store page-fault exception.# + +[NOTE] +==== +AMOs never raise load page-fault exceptions. Since any unreadable page +is also unwritable, attempting to perform an AMO on an unreadable page +always raises a store page-fault exception. +==== + +The U bit indicates whether the page is accessible to user mode. U-mode +software may only access the page when U=1. If the SUM bit in the +`sstatus` register is set, supervisor mode software may also access +pages with U=1. However, supervisor code normally operates with the SUM +bit clear, in which case, supervisor code will fault on accesses to +user-mode pages. Irrespective of SUM, the supervisor may not execute +code on pages with U=1. + +[NOTE] +==== +An alternative PTE format would support different permissions for +supervisor and user. We omitted this feature because it would be largely +redundant with the SUM mechanism (see <>) and would require more encoding space in the PTE. +==== + +The G bit designates a _global_ mapping. Global mappings are those that +exist in all address spaces. For non-leaf PTEs, the global setting +implies that all mappings in the subsequent levels of the page table are +global. Note that failing to mark a global mapping as global merely +reduces performance, whereas marking a non-global mapping as global is a +software bug that, after switching to an address space with a different +non-global mapping for that address range, can unpredictably result in +either mapping being used. + +[NOTE] +==== +Global mappings need not be stored redundantly in address-translation +caches for multiple ASIDs. Additionally, they need not be flushed from +local address-translation caches when an SFENCE.VMA instruction is +executed with __rs2__{ne}``x0``. +==== + +The RSW field is reserved for use by supervisor software; the +implementation shall ignore this field. + +Each leaf PTE contains an accessed (A) and dirty (D) bit. The A bit +indicates the virtual page has been read, written, or fetched from since +the last time the A bit was cleared. The D bit indicates the virtual +page has been written since the last time the D bit was cleared. + +Two schemes to manage the A and D bits are defined: + +* The _Svade_ extension: when a virtual page is accessed and the A bit is + clear, or is written and the D bit is clear, a page-fault exception is + raised. + +* When the Svade extension is not implemented, the following scheme applies. + + + + When a virtual page is accessed and the A bit is clear, the PTE is + updated to set the A bit. When the virtual page is written and the D + bit is clear, the PTE is updated to set the D bit. When G-stage address + translation is in use and is not Bare, the G-stage virtual pages may be + accessed or written by implicit accesses to VS-level memory management + data structures, such as page tables. + + + + When two-stage address translation is in use, an explicit access may + cause both VS-stage and G-stage PTEs to be updated. The following rules + apply to all PTE updates caused by an explicit or an implicit memory + accesses. + + + + The PTE update must be atomic with respect to other accesses to the + PTE, and must atomically perform all page-table walk checks for that leaf + PTE as part of, and before, conditionally updating the PTE value. + Updates of the A bit may be performed as a result of speculation, even + if the associated memory access ultimately is not performed + architecturally. However, updates to the D bit, resulting from an + explicit store, must be exact (i.e., non-speculative), and observed in + program order by the local hart. When two-stage address translation is + active, updates to the D bit in G-stage PTEs may be performed by an + implicit access to a VS-stage PTE, if the G-stage PTE provides write + permission, before any speculative access to the VS-stage PTE. + + + + The PTE update must appear in the global memory order before the + memory access that caused the PTE update and before any subsequent + explicit memory access to that virtual page by the local hart. The + ordering on loads and stores provided by FENCE instructions and the + acquire/release bits on atomic instructions also orders the PTE updates + associated with those loads and stores as observed by remote harts. + + + + The PTE update is not required to be atomic with respect to the memory + access that caused the update and a trap may occur between the PTE + update and the memory access that caused the PTE update. If a trap + occurs then the A and/or D bit may be updated but the memory access + that caused the PTE update might not occur. The hart must not perform + the memory access that caused the PTE update before the PTE update is + globally visible. + + + + The page tables must be located in memory with hardware page-table + write access and _RsrvEventual_ PMA. + +All harts in a system must employ the same PTE-update scheme as each +other. + +[NOTE] +==== +The PTE updates due to memory accesses ordered-after a FENCE are not +themselves ordered by the FENCE. + +Simpler implementations may order the Page Table Entry (PTE) update +to precede all subsequent explicit memory accesses, as opposed to +ensuring that the PTE update is precisely sequenced before subsequent +explicit memory accesses to the associated virtual page. + +Prior versions of this specification required PTE A bit updates to be +exact, but allowing the A bit to be updated as a result of speculation +simplifies the implementation of address translation prefetchers. System +software typically uses the A bit as a page replacement policy hint, but +does not require exactness for functional correctness. On the other +hand, D bit updates are still required to be exact and performed in +program order, as the D bit affects the functional correctness of page +eviction. + +Implementations are of course still permitted to perform both A and D +bit updates only in an exact manner. + +In both cases, requiring atomicity ensures that the PTE update will not +be interrupted by other intervening writes to the page table, as such +interruptions could lead to A/D bits being set on PTEs that have been +reused for other purposes, on memory that has been reclaimed for other +purposes, and so on. Simple implementations may instead generate +page-fault exceptions. + +The A and D bits are never cleared by the implementation. If the +supervisor software does not rely on accessed and/or dirty bits, e.g. if +it does not swap memory pages to secondary storage or if the pages are +being used to map I/O space, it should always set them to 1 in the PTE +to improve performance. +==== + +Any level of PTE may be a leaf PTE, so in addition to 4 KiB pages, Sv32 +supports 4 MiB _megapages_. A megapage must be virtually and physically +aligned to a 4 MiB boundary; a page-fault exception is raised if the +physical address is insufficiently aligned. + +For non-leaf PTEs, the D, A, and U bits are reserved for future standard +use. Until their use is defined by a standard extension, they must be +cleared by software for forward compatibility. + +For implementations with both page-based virtual memory and the "A" +standard extension, the LR/SC reservation set must lie completely within +a single base physical page (i.e., a naturally aligned 4 KiB physical-memory +region). + +On some implementations, misaligned loads, stores, and instruction +fetches may also be decomposed into multiple accesses, some of which may +succeed before a page-fault exception occurs. In particular, a +portion of a misaligned store that passes the exception check may become +visible, even if another portion fails the exception check. The same behavior +may manifest for stores wider than XLEN bits (e.g., the FSD instruction +in RV32D), even when the store address is naturally aligned. + + +[[sv32algorithm]] +==== Virtual Address Translation Process + +A virtual address _va_ is translated into a physical address _pa_ as follows: + +. Let _a_ be ``satp``.__ppn__×PAGESIZE, and let __i__=LEVELS-1. (For Sv32, PAGESIZE=2^12^ and LEVELS=2.) The `satp` register must be +_active_, i.e., the effective privilege mode must be S-mode or U-mode. + +. Let _pte_ be the value of the PTE at address __a__+__va__.__vpn__[__i__]×PTESIZE. (For Sv32, PTESIZE=4.) If accessing _pte_ violates a PMA or PMP check, raise an access-fault exception corresponding to the original access type. + +. If _pte_._v_=0, or if _pte_._r_=0 and _pte_._w_=1, or if any bits or encodings that are reserved for future standard use are set within _pte_, stop and raise a page-fault exception corresponding to the original access type. + +. Otherwise, the PTE is valid. If __pte__.__r__=1 or __pte__.__x__=1, go to step 5. Otherwise, this PTE is a pointer to the next level of the page table. Let __i=i__-1. If __i__<0, stop and raise a page-fault exception corresponding to the original access type. Otherwise, let +__a__=__pte__.__ppn__×PAGESIZE and go to step 2. + +. A leaf PTE has been reached. If _i>0_ and _pte_._ppn_[__i__-1:0] ≠ 0, this is a misaligned superpage; stop and raise a page-fault exception corresponding to the original access type. + +. Determine if the requested memory access is allowed by the _pte_._u_ bit, given the current privilege mode and the value of the SUM and MXR fields of the *mstatus* register. If not, stop and raise a page-fault exception corresponding to the original access type. + +. Determine if the requested memory access is allowed by the _pte_._r_, _pte_._w_, and _pte_._x_ bits, given the Shadow Stack Memory Protection rules. If not, stop and raise an access-fault exception. + +. Determine if the requested memory access is allowed by the _pte_._r_, _pte_._w_, and _pte_._x_ bits. If not, stop and raise a page-fault exception corresponding to the original access type. + +. If _pte_._a_=0, or if the original memory access is a store and _pte_._d_=0: + +* If the Svade extension is implemented, stop and raise a page-fault exception corresponding to the original access type. +* If a store to the PTE at address __a__+__va.vpn__[__i__]×PTESIZE would violate a PMA or PMP check, +raise an access-fault exception corresponding to the original access +type. +* Perform the following steps atomically: +** Compare _pte_ to the value of the PTE at address __a__+__va.vpn__[__i__]×PTESIZE. +** If the values match, set _pte_._a_ to 1 and, if the +original memory access is a store, also set _pte_._d_ to 1. Then store _pte_ to the PTE at address __a__+__va.vpn__[__i__]×PTESIZE. +** If the comparison fails, return to step 2. + +. The translation is successful. The translated physical address is +given as follows: +* _pa.pgoff_ = _va.pgoff_. +* If _i_>0, then this is a superpage translation and __pa.ppn__[__i__-1:0] = __va.vpn__[__i__-1:0]. +* _pa.ppn_[LEVELS-1:__i__] = _pte_._ppn_[LEVELS-1:__i__]. + +All implicit accesses to the address-translation data structures in this +algorithm are performed using width PTESIZE. + +[NOTE] +==== +This implies, for example, that an Sv48 implementation may not use two +separate 4{nbsp}B reads to non-atomically access a single 8{nbsp}B PTE, and that A/D +bit updates performed by the implementation are treated as atomically +updating the entire PTE, rather than just the A and/or D bit alone (even +though the PTE value does not otherwise change). +==== + +The results of implicit address-translation reads in step 2 may be held +in a read-only, incoherent _address-translation cache_ but not shared +with other harts. The address-translation cache may hold an arbitrary +number of entries, including an arbitrary number of entries for the same +address and ASID. Entries in the address-translation cache may then +satisfy subsequent step 2 reads if the ASID associated with the entry +matches the ASID loaded in step 0 or if the entry is associated with a +_global_ mapping. To ensure that implicit reads observe writes to the +same memory locations, an SFENCE.VMA instruction must be executed after +the writes to flush the relevant cached translations. + +The address-translation cache cannot be used in step 9; accessed and +dirty bits may only be updated in memory directly. +[NOTE] +==== +It is permitted for multiple address-translation cache entries to +co-exist for the same address. This represents the fact that in a +conventional TLB hierarchy, it is possible for multiple entries to match +a single address if, for example, a page is upgraded to a superpage +without first clearing the original non-leaf PTE’s valid bit and +executing an SFENCE.VMA with _rs1_=`x0`, or if multiple TLBs exist in +parallel at a given level of the hierarchy. In this case, just as if an +SFENCE.VMA is not executed between a write to the memory-management +tables and subsequent implicit read of the same address: it is +unpredictable whether the old non-leaf PTE or the new leaf PTE is used, +but the behavior is otherwise well defined. +==== + +Implementations may also execute the address-translation algorithm +speculatively at any time, for any virtual address, as long as `satp` is +active (as defined in <>). Such speculative +executions have the effect of pre-populating the address-translation +cache. + +Speculative executions of the address-translation algorithm behave as +non-speculative executions of the algorithm do, except that they must +not set the dirty bit for a PTE, they must not trigger an exception, and +they must not create address-translation cache entries if those entries +would have been invalidated by any SFENCE.VMA instruction executed by +the hart since the speculative execution of the algorithm began. + +[NOTE] +==== +For instance, it is illegal for both non-speculative and speculative +executions of the translation algorithm to begin, read the level 2 page +table, pause while the hart executes an SFENCE.VMA with +_rs1_=_rs2_=`x0`, then resume using the now-stale level 2 PTE, as +subsequent implicit reads could populate the address-translation cache +with stale PTEs. + +In many implementations, an SFENCE.VMA instruction with _rs1_=`x0` will +therefore either terminate all previously-launched speculative +executions of the address-translation algorithm (for the specified ASID, +if applicable), or simply wait for them to complete (in which case any +address-translation cache entries created will be invalidated by the +SFENCE.VMA as appropriate). Likewise, an SFENCE.VMA instruction with +__rs1__≠``x0`` generally must either ensure that +previously-launched speculative executions of the address-translation +algorithm (for the specified ASID, if applicable) are prevented from +creating new address-translation cache entries mapping leaf PTEs, or +wait for them to complete. + +A consequence of implementations being permitted to read the translation +data structures arbitrarily early and speculatively is that at any time, +all page table entries reachable by executing the algorithm may be +loaded into the address-translation cache. + +Although it would be uncommon to place page tables in non-idempotent +memory, there is no explicit prohibition against doing so. Since the +algorithm may only touch page tables reachable from the root page table +indicated in `satp`, the range of addresses that an implementation's +page-table walker will touch is fully under supervisor control. + +*** + +The algorithm does not admit the possibility of ignoring high-order PPN +bits for implementations with narrower physical addresses. +==== + +[[sv39]] +=== Sv39: Page-Based 39-bit Virtual-Memory System + +This section describes a simple paged virtual-memory system for +SXLEN=64, which supports 39-bit virtual address spaces. The design of +Sv39 follows the overall scheme of Sv32, and this section details only +the differences between the schemes. + +[NOTE] +==== +We specified multiple virtual memory systems for RV64 to relieve the +tension between providing a large address space and minimizing +address-translation cost. For many systems, 39 bits of virtual-address space is +ample, and so Sv39 suffices. Sv48 increases the virtual address space to +48 bits, but increases the physical memory capacity dedicated to page tables, +the latency of page-table traversals, and the size of hardware +structures that store virtual addresses. Sv57 increases the virtual +address space, page table capacity requirement, and translation latency +even further. +==== + +[[addressing-and-memory-protection]] +==== Addressing and Memory Protection + +Sv39 implementations support a 39-bit virtual address space, divided +into pages. An Sv39 address is partitioned as shown in +<>. Instruction fetch addresses and load and +store effective addresses, which are 64 bits, must have bits 63–39 all +equal to bit 38, or else a page-fault exception will occur. The 27-bit +VPN is translated into a [#norm:satp-ppn_sv39_sv48_sv57_sz]#44-bit PPN# via a three-level page table, while +the 12-bit page offset is untranslated. + +[NOTE] +==== +When mapping between narrower and wider addresses, RISC-V zero-extends a +narrower physical address to a wider size. The mapping between 64-bit +virtual addresses and the 39-bit usable address space of Sv39 is not +based on zero extension but instead follows an entrenched convention +that allows an OS to use one or a few of the most-significant bits of a +full-size (64-bit) virtual address to quickly distinguish user and +supervisor address regions. +==== + +[[sv39va]] +.Sv39 virtual address. +include::images/bytefield/sv39va.edn[] + +[[sv39pa]] +.Sv39 physical address. +include::images/bytefield/sv39pa.edn[] + +[[sv39pte]] +.Sv39 page table entry. +include::images/bytefield/sv39pte.edn[] + +Sv39 page tables contain 2^9^ page table entries (PTEs), +eight bytes each. A page table is exactly the size of a page and must +always be aligned to a page boundary. The physical page number of the +root page table is stored in the `satp` register's PPN field. + +The PTE format for Sv39 is shown in <>. +Bits 9-0 have the same meaning as for Sv32. Bit 63 is reserved for use +by the Svnapot extension in <>. If Svnapot is not +implemented, bit 63 remains reserved and must be zeroed by software for +forward compatibility, or else a page-fault exception is raised. Bits +62-61 are reserved for use by the Svpbmt extension in +<>. If Svpbmt is not implemented, bits 62-61 remain +reserved and must be zeroed by software for forward compatibility, or +else a page-fault exception is raised. Bits 60-54 are reserved for +future standard use and, until their use is defined by some standard +extension, must be zeroed by software for forward compatibility. If any +of these bits are set, a page-fault exception is raised. + +[NOTE] +==== +We reserved several PTE bits for a possible extension that improves +support for sparse address spaces by allowing page-table levels to be +skipped, reducing memory usage and TLB refill latency. These reserved +bits may also be used to facilitate research experimentation. The cost +is reducing the physical address space, but is presently ample. When it +no longer suffices, the reserved bits that remain unallocated could be +used to expand the physical address space. +==== + +Any level of PTE may be a leaf PTE, so in addition to 4 KiB pages, Sv39 +supports 2 MiB _megapages_ and 1 GiB _gigapages_, each of which must be virtually and physically aligned to a boundary equal to its size. A page-fault exception is raised if the physical address is insufficiently aligned. + +The algorithm for virtual-to-physical address translation is the same as +in <>, except LEVELS equals 3 and PTESIZE equals 8. + +[[sv48]] +=== Sv48: Page-Based 48-bit Virtual-Memory System + +This section describes a simple paged virtual-memory system for +SXLEN=64, which supports 48-bit virtual address spaces. Sv48 is intended +for systems for which a 39-bit virtual address space is insufficient. It +closely follows the design of Sv39, simply adding an additional level of +page table, and so this chapter only details the differences between the +two schemes. + +Implementations that support Sv48 must also support Sv39. + +[NOTE] +==== +Systems that support Sv48 can also support Sv39 at essentially no cost, +and so should do so to maintain compatibility with supervisor software +that assumes Sv39. +==== + +[[addressing-and-memory-protection-1]] +==== Addressing and Memory Protection + +Sv48 implementations support a 48-bit virtual address space, divided +into pages. An Sv48 address is partitioned as shown in +<>. Instruction fetch addresses and load and +store effective addresses, which are 64 bits, must have bits 63–48 all +equal to bit 47, or else a page-fault exception will occur. The 36-bit +VPN is translated into a 44-bit PPN via a four-level page table, while +the 12-bit page offset is untranslated. + +[[sv48va]] +.Sv48 virtual address. +include::images/bytefield/sv48va.edn[] + +[[sv48pa]] +.Sv48 physical address. +include::images/bytefield/sv48pa.edn[] + +[[sv48pte]] +.Sv48 page table entry. +include::images/bytefield/sv48pte.edn[] + +The PTE format for Sv48 is shown in <>. +Bits 63-54 and 9-0 have the same meaning as for Sv39. Any level of PTE +may be a leaf PTE, so in addition to 4 KiB pages, Sv48 supports 2 MiB _megapages_, +1 GiB _gigapages_, and 512 GiB _terapages_, each of which must be virtually and +physically aligned to a boundary equal to its size. A page-fault +exception is raised if the physical address is insufficiently aligned. + +The algorithm for virtual-to-physical address translation is the same as +in <>, except LEVELS equals 4 and +PTESIZE equals 8. + +[[sv57]] +=== Sv57: Page-Based 57-bit Virtual-Memory System + +This section describes a simple paged virtual-memory system designed for +RV64 systems, which supports 57-bit virtual address spaces. Sv57 is +intended for systems for which a 48-bit virtual address space is +insufficient. It closely follows the design of Sv48, simply adding an +additional level of page table, and so this chapter only details the +differences between the two schemes. + +Implementations that support Sv57 must also support Sv48. + +[NOTE] +==== +Systems that support Sv57 can also support Sv48 at essentially no cost, +and so should do so to maintain compatibility with supervisor software +that assumes Sv48. +==== + +[[addressing-and-memory-protection-2]] +==== Addressing and Memory Protection + +Sv57 implementations support a 57-bit virtual address space, divided +into pages. An Sv57 address is partitioned as shown in +<>. Instruction fetch addresses and load and +store effective addresses, which are 64 bits, must have bits 63–57 all +equal to bit 56, or else a page-fault exception will occur. The 45-bit +VPN is translated into a 44-bit PPN via a five-level page table, while +the 12-bit page offset is untranslated. + +[[sv57va]] +.Sv57 virtual address. +include::images/bytefield/sv57va.edn[] + +[[sv57pa]] +.Sv57 physical address. +include::images/bytefield/sv57pa.edn[] + +[[sv57pte]] +.Sv57 page table entry. +include::images/bytefield/sv57pte.edn[] + +The PTE format for Sv57 is shown in <>. +Bits 63–54 and 9–0 have the same meaning as for Sv39. Any level of PTE +may be a leaf PTE, so in addition to 4 KiB pages, Sv57 supports 2 MiB _megapages_, +1 GiB _gigapages_, 512 GiB _terapages_, and 256 TiB _petapages_, each of which must be +virtually and physically aligned to a boundary equal to its size. A +page-fault exception is raised if the physical address is insufficiently +aligned. + +The algorithm for virtual-to-physical address translation is the same as +in <>, except LEVELS equals 5 and +PTESIZE equals 8. + +[[svnapot]] +== "Svnapot" Extension for NAPOT Translation Contiguity, Version 1.0 + +In Sv39, Sv48, and Sv57, when a PTE has N=1, the PTE represents a +translation that is part of a range of contiguous virtual-to-physical +translations with the same values for PTE bits 5–0. Such ranges must be +of a naturally aligned power-of-2 (NAPOT) granularity larger than the +base page size. + +The Svnapot extension depends on the Sv39 extension. + +[[ptenapot]] +.Page table entry encodings when __pte__.N=1 +[%autowidth,float="center",align="center",cols="^,^,<,^",options="header"] +|=== +|i |_pte_._ppn_[_i_] |Description |_pte_.__napot_bits__ +|0 + +0 + +0 + +0 + +0 + +{ge}1 +|`x xxxx xxx1` + +`x xxxx xx1x` + +`x xxxx x1xx` + +`x xxxx 1000` + +`x xxxx 0xxx` + +`x xxxx xxxx` +|_Reserved_ + +_Reserved_ + +_Reserved_ + +64 KiB contiguous region + +_Reserved_ + +_Reserved_ +| - + +- + +- + +4 + +- + +- +|=== + +NAPOT PTEs behave identically to non-NAPOT PTEs within the +address-translation algorithm in <>, +except that: + +* If the encoding in _pte_ is valid according to +<>, then instead of returning the original +value of _pte_, implicit reads of a NAPOT PTE return a copy +of _pte_ in which __pte__.__ppn__[__i__][__pte__.__napot_bits__-1:0] is replaced by +__vpn__[__i__][__pte__.__napot_bits__-1:0]. If the encoding in _pte_ is reserved according to +<>, then a page-fault exception must be raised. +* Implicit reads of NAPOT page table entries may create +address-translation cache entries mapping +_a_ + _j_×PTESIZE to a copy of _pte_ in which _pte_._ppn_[_i_][_pte_.__napot_bits__-1:0] +is replaced by _vpn[i][pte.napot_bits_-1:0], for any or all _j_ such that +__j__ >> __napot_bits__ = __vpn__[__i__] >> __napot_bits__, all for the address space identified in _satp_ as loaded by step 1. + +[NOTE] +==== +The motivation for a NAPOT PTE is that it can be cached in a TLB as one +or more entries representing the contiguous region as if it were a +single (large) page covered by a single translation. This compaction can +help relieve TLB pressure in some scenarios. The encoding is designed to +fit within the pre-existing Sv39, Sv48, and Sv57 PTE formats so as not +to disrupt existing implementations or designs that choose not to +implement the scheme. It is also designed so as not to complicate the +definition of the address-translation algorithm. + +The address translation cache abstraction captures the behavior that +would result from the creation of a single TLB entry covering the entire +NAPOT region. It is also designed to be consistent with implementations +that support NAPOT PTEs by splitting the NAPOT region into TLB entries +covering any smaller power-of-two region sizes. For example, a 64 KiB +NAPOT PTE might trigger the creation of 16 standard 4 KiB TLB entries, +all with contents generated from the NAPOT PTE (even if the PTEs for the +other 4 KiB regions have different contents). + +In typical usage scenarios, NAPOT PTEs in the same region will have the +same attributes, same PPNs, and same values for bits 5-0. RSW remains +reserved for supervisor software control. It is the responsibility of +the OS and/or hypervisor to configure the page tables in such a way that +there are no inconsistencies between NAPOT PTEs and other NAPOT or +non-NAPOT PTEs that overlap the same address range. If an update needs +to be made, the OS generally should first mark all of the PTEs invalid, +then issue SFENCE.VMA instruction(s) covering all 4 KiB regions within +the range (either via a single SFENCE.VMA with _rs1_=`x0`, or with +multiple SFENCE.VMA instructions with _rs1_≠`x0`), then update the PTE(s), as described in <>, unless any inconsistencies are known to be benign. If any inconsistencies do exist, then the effect is the same as when SFENCE.VMA +is used incorrectly: one of the translations will be chosen, but the +choice is unpredictable. + +If an implementation chooses to use a NAPOT PTE (or cached version +thereof), it might not consult the PTE directly specified by the +algorithm in <> at all. Therefore, the D +and A bits may not be identical across all mappings of the same address +range even in typical use cases The operating system must query all +NAPOT aliases of a page to determine whether that page has been accessed +and/or is dirty. If the OS manually sets the A and/or D bits for a page, +it is recommended that the OS also set the A and/or D bits for other +NAPOT aliases as appropriate in order to avoid unnecessary traps. + +Just as with normal PTEs, TLBs are permitted to cache NAPOT PTEs whose V +(Valid) bit is clear. + +Depending on need, the NAPOT scheme may be extended to other +intermediate page sizes and/or to other levels of the page table in the +future. The encoding is designed to accommodate other NAPOT sizes should +that need arise. For example: + +__ + +[%autowidth,float="center",align="center",cols="^,^,<,^",options="header"] +|=== +|i |_pte_._ppn_[_i_] |Description |_pte_.__napot_bits__ +|0 + +0 + +0 + +0 + +0 + +... + +1 + +1 + +... +|`x xxxx xxx1` + +`x xxxx xx10` + +`x xxxx x100` + +`x xxxx 1000` + +`x xxx1 0000` + +... + +`x xxxx xxx1` + +`x xxxx xx10` + +... +|8 KiB contiguous region + +16 KiB contiguous region + +32 KiB contiguous region + +64 KiB contiguous region + +128 KiB contiguous region + +... + +4 MiB contiguous region + +8 MiB contiguous region + +... +| 1 + +2 + +3 + +4 + +5 + +... + +1 + +2 + +... +|=== + +In such a case, an implementation may or may not support all options. +The discoverability mechanism for this extension would be extended to +allow system software to determine which sizes are supported. + +Other sizes may remain deliberately excluded, so that PPN bits not being +used to indicate a valid NAPOT region size (e.g., the least-significant +bit of _pte_._ppn_[_i_]) may be repurposed for other uses in the +future. + +However, in case finer-grained intermediate page size support proves not +to be useful, we have chosen to standardize only 64 KiB support as a +first step. +==== + +[[svpbmt]] +== "Svpbmt" Extension for Page-Based Memory Types, Version 1.0 + +In Sv39, Sv48, and Sv57, bits 62-61 of a leaf page table entry indicate +the use of page-based memory types that override the PMA(s) for the +associated memory pages. The encoding for the PBMT bits is captured in +<>. + +The Svpbmt extension depends on the Sv39 extension. + +[[pbmt]] +.Encodings for PBMT field in Sv39, Sv48, and Sv57 PTEs. +[%autowidth,float="center",align="center",cols="^,^,<",options="header"] +|=== +|Mode |Value |Requested Memory Attributes +|PMA + +NC + +IO + +- +|0 + +1 + +2 + +3 +|None + +Non-cacheable, idempotent, weakly-ordered (RVWMO), main memory + +Non-cacheable, non-idempotent, strongly-ordered (I/O ordering), I/O + +_Reserved for future standard use_ +|=== + +Implementations may override additional PMAs not explicitly listed in +<>. +For example, to be consistent with the characteristics of a typical I/O region, +a misaligned memory access to a page with PBMT=IO might raise an exception, +even if the underlying region were main memory and the same access would have +succeeded for PBMT=PMA. + +[NOTE] +==== +Future extensions may provide more and/or finer-grained control over +which PMAs can be overridden. +==== + +For non-leaf PTEs, bits 62-61 are reserved for future standard use. +Until their use is defined by a standard extension, they must be cleared +by software for forward compatibility, or else a page-fault exception is +raised. + +For leaf PTEs, setting bits 62-61 to the value 3 is reserved for future +standard use. Until this value is defined by a standard extension, using +this reserved value in a leaf PTE raises a page-fault exception. + +When PBMT settings override a main memory page into I/O or vice versa, +memory accesses to such pages obey the memory ordering rules of the +final effective attribute, as follows. + +If the underlying physical memory attribute for a page is I/O, and the +page has PBMT=NC, then accesses to that page obey RVWMO. However, +accesses to such pages are considered to be _both_ I/O and main memory +accesses for the purposes of FENCE, _.aq_, and _.rl_. + +If the underlying physical memory attribute for a page is main memory, +and the page has PBMT=IO, then accesses to that page obey strong channel +0 I/O ordering rules. +However, accesses to +such pages are considered to be _both_ I/O and main memory accesses for +the purposes of FENCE, _.aq_, and _.rl_. + +[NOTE] +==== +A device driver written to rely on I/O strong ordering rules will not +operate correctly if the address range is mapped with PBMT=NC. As such, +this configuration is discouraged. + +It will often still be useful to map physical I/O regions using PBMT=NC +so that write combining and speculative accesses can be performed. Such +optimizations will likely improve performance when applied with adequate +care. +==== + +When Svpbmt is used with non-zero PBMT encodings, it is possible for +multiple virtual aliases of the same physical page to exist +simultaneously with different memory attributes. It is also possible for +a U-mode or S-mode mapping through a PTE with Svpbmt enabled to observe +different memory attributes for a given region of physical memory than a +concurrent access to the same page performed by M-mode or when +MODE=Bare. In such cases, the behaviors dictated by the attributes +(including coherence, which is otherwise unaffected) may be violated. + +Accessing the same location using different attributes that are both +non-cacheable (e.g., NC and IO) does not cause loss of coherence, but +might result in weaker memory ordering than the stricter attribute +ordinarily guarantees. Executing a `fence iorw, iorw` instruction +between such accesses suffices to prevent loss of memory ordering. + +Accessing the same location using different cacheability attributes may +cause loss of coherence. Executing the following sequence between such +accesses prevents both loss of coherence and loss of memory ordering: +`fence iorw, iorw`, followed by `cbo.flush` to an address of that +location, followed by a `fence iorw, iorw`. + +[NOTE] +==== +It follows that, if the same location might later be referenced using +the original attributes, then this sequence must be repeated beforehand. + +*** + +In certain cases, a weaker sequence might suffice to prevent loss of +coherence. These situations will be detailed following the forthcoming +formalization of the interaction of the RVWMO memory model with the +instructions in the Zicbom extension. +==== + +When two-stage address translation is enabled within the H extension, +the page-based memory types are also applied in two stages. First, if +`hgatp`.MODE is not equal to zero, non-zero G-stage PTE PBMT bits +override the attributes in the PMA to produce an intermediate set of +attributes. Otherwise, the PMAs serve as the intermediate attributes. +Second, if `vsatp`.MODE is not equal to zero, non-zero VS-stage PTE PBMT +bits override the intermediate attributes to produce the final set of +attributes used by accesses to the page in question. Otherwise, the +intermediate attributes are used as the final set of attributes. + +NOTE: These final attributes apply to implicit and explicit accesses that +are subject to both stages of address translation. +For accesses that are not subject to the first stage of address translation, +e.g. VS-stage page-table accesses, the intermediate attributes apply instead. + +[[svinval]] +== "Svinval" Extension for Fine-Grained Address-Translation Cache Invalidation, Version 1.0 + +The Svinval extension splits SFENCE.VMA, HFENCE.VVMA, and HFENCE.GVMA +instructions into finer-grained invalidation and ordering operations +that can be more efficiently batched or pipelined on certain classes of +high-performance implementation. + +include::images/wavedrom/sinvalvma.edn[] + +The SINVAL.VMA instruction invalidates any address-translation cache +entries that an SFENCE.VMA instruction with the same values of _rs1_ and +_rs2_ would invalidate. However, unlike SFENCE.VMA, SINVAL.VMA +instructions are only ordered with respect to SFENCE.VMA, +SFENCE.W.INVAL, and SFENCE.INVAL.IR instructions as defined below. + +include::images/wavedrom/sfencewinval.edn[] + +include::images/wavedrom/sfenceinvalir.edn[] + +The SFENCE.W.INVAL instruction guarantees that any previous stores +already visible to the current RISC-V hart are ordered before subsequent +SINVAL.VMA instructions executed by the same hart. The SFENCE.INVAL.IR +instruction guarantees that any previous SINVAL.VMA instructions +executed by the current hart are ordered before subsequent implicit +references by that hart to the memory-management data structures. + +When executed in order (but not necessarily consecutively) by a single +hart, the sequence SFENCE.W.INVAL, SINVAL.VMA, and SFENCE.INVAL.IR has +the same effect as a hypothetical SFENCE.VMA instruction in which: + +* the values of _rs1_ and _rs2_ for the SFENCE.VMA are the same as those +used in the SINVAL.VMA, +* reads and writes prior to the SFENCE.W.INVAL are considered to be +those prior to the SFENCE.VMA, and +* reads and writes following the SFENCE.INVAL.IR are considered to be +those subsequent to the SFENCE.VMA. + +include::images/wavedrom/hinvalvvma.edn[] + +include::images/wavedrom/hinvalgvma.edn[] + +If the hypervisor extension is implemented, the Svinval extension also +provides two additional instructions: HINVAL.VVMA and HINVAL.GVMA. These +have the same semantics as SINVAL.VMA, except that they combine with +SFENCE.W.INVAL and SFENCE.INVAL.IR to replace HFENCE.VVMA and +HFENCE.GVMA, respectively, instead of SFENCE.VMA. In addition, +HINVAL.GVMA uses VMIDs instead of ASIDs. + +SINVAL.VMA, HINVAL.VVMA, and HINVAL.GVMA require the same permissions +and raise the same exceptions as SFENCE.VMA, HFENCE.VVMA, and +HFENCE.GVMA, respectively. In particular, an attempt to execute any of +these instructions in U-mode always raises an illegal-instruction +exception, and an attempt to execute SINVAL.VMA or HINVAL.GVMA in S-mode +or HS-mode when `mstatus`.TVM=1 also raises an illegal-instruction +exception. An attempt to execute HINVAL.VVMA or HINVAL.GVMA in VS-mode +or VU-mode, or to execute SINVAL.VMA in VU-mode, raises a +virtual-instruction exception. When `hstatus`.VTVM=1, an attempt to execute +SINVAL.VMA in VS-mode also raises a virtual-instruction exception. + +Attempting to execute SFENCE.W.INVAL or SFENCE.INVAL.IR in U-mode +raises an illegal-instruction exception. +Doing so in VU-mode raises a virtual-instruction exception. +SFENCE.W.INVAL and SFENCE.INVAL.IR are unaffected by the `mstatus`.TVM and +`hstatus`.VTVM fields and hence are always permitted in S-mode and VS-mode. + +[NOTE] +==== +SFENCE.W.INVAL and SFENCE.INVAL.IR instructions do not need to be +trapped when `mstatus`.TVM=1 or when `hstatus`.VTVM=1, as they only have +ordering effects but no visible side effects. Trapping of the SINVAL.VMA +instruction is sufficient to enable emulation of the intended overall +TLB maintenance functionality. + +In typical usage, software will invalidate a range of virtual addresses +in the address-translation caches by executing an SFENCE.W.INVAL +instruction, executing a series of SINVAL.VMA, HINVAL.VVMA, or +HINVAL.GVMA instructions to the addresses (and optionally ASIDs or +VMIDs) in question, and then executing an SFENCE.INVAL.IR instruction. + +High-performance implementations will be able to pipeline the +address-translation cache invalidation operations, and will defer any +pipeline stalls or other memory ordering enforcement until an +SFENCE.W.INVAL, SFENCE.INVAL.IR, SFENCE.VMA, HFENCE.GVMA, or HFENCE.VVMA +instruction is executed. + +Simpler implementations may implement SINVAL.VMA, HINVAL.VVMA, and +HINVAL.GVMA identically to SFENCE.VMA, HFENCE.VVMA, and HFENCE.GVMA, +respectively, while implementing SFENCE.W.INVAL and SFENCE.INVAL.IR +instructions as no-ops. +==== + +[[sec:svadu]] +== "Svadu" Extension for Hardware Updating of A/D Bits, Version 1.0 + +The Svadu extension adds support and CSR controls for hardware updating of PTE A/D bits. + +If the Svadu extension is implemented, the `menvcfg`.ADUE field is writable. +If the hypervisor extension is additionally implemented, the `henvcfg`.ADUE +field is also writable. +See <> and <> for the definitions of those fields. + +<> defines the semantics of hardware updating of A/D bits. When +hardware updating of A/D bits is disabled, the Svade extension, which mandates +exceptions when A/D bits need be set, instead takes effect. +The Svade extension is also defined in <>. + +[[sec:svvptc]] +== "Svvptc" Extension for Obviating Memory-Management Instructions after Marking PTEs Valid, Version 1.0 + +When the Svvptc extension is implemented, explicit stores by a hart that update +the Valid bit of leaf and/or non-leaf PTEs from 0 to 1 and are visible to a hart +will eventually become visible within a bounded timeframe to subsequent implicit +accesses by that hart to such PTEs. + +[NOTE] +==== +Svvptc relieves an operating system from executing certain memory-management +instructions, such as `SFENCE.VMA` or `SINVAL.VMA`, which would normally be used +to synchronize the hart's address-translation caches when a memory-resident PTE +is changed from Invalid to Valid. Synchronizing the hart's address-translation +caches with other forms of updates to a memory-resident PTE, including when a +PTE is changed from Valid to Invalid, requires the use of suitable +memory-management instructions. Svvptc guarantees that a change to a PTE from +Invalid to Valid is made visible within a bounded time, thereby making the +execution of these memory-management instructions redundant. The performance +benefit of eliding these instructions outweighs the cost of an occasional +gratuitous additional page fault that may occur. + +Depending on the microarchitecture, some possible ways to facilitate +implementation of Svvptc include: not having any address-translation caches, not +storing Invalid PTEs in the address-translation caches, automatically evicting +Invalid PTEs using a bounded timer, or making address-translation caches +coherent with store instructions that modify PTEs. +==== + +[[sec:svrsw60t59b]] +== "Svrsw60t59b" Extension for PTE Reserved-for-Software Bits 60-59, Version 1.0 + +If the Svrsw60t59b extension is implemented, then bits 60-59 of the page table +entries (PTEs) are reserved for use by supervisor software and are ignored by +the implementation. + +If the Hypervisor (H) extension is also implemented, then bits 60-59 of the +G-stage PTEs are reserved for use by supervisor software and are ignored by the +implementation. + +The Svrsw60t59b extension depends on Sv39. + +[NOTE] +==== +Operating systems frequently use reserved bits within PTEs to store metadata for +advanced memory management features. Embedding these metadata bits directly within +the PTEs allows for fast access with minimal overhead, avoiding costly lookups in +auxiliary data structures. By default, Sv39 and Sv39x4 require a page fault and +a guest-page fault exception, respectively, to be raised if bits 60–59 are not +zero. +==== + +[[ssqosid]] +== "Ssqosid" Extension for Quality-of-Service (QoS) Identifiers, Version 1.0 + +Quality of Service (QoS) is defined as the minimal end-to-end performance +guaranteed in advance by a service level agreement (SLA) to a workload. +Performance metrics might include measures such as instructions per cycle (IPC), +latency of service, etc. + +When multiple workloads execute concurrently on modern processors—equipped with +large core counts, multiple cache hierarchies, and multiple memory +controllers—the performance of any given workload becomes less deterministic, or +even non-deterministic, due to shared resource contention. + +To manage performance variability, system software needs resource allocation and +monitoring capabilities. These capabilities allow for the reservation of +resources like cache and bandwidth, thus meeting individual performance targets +while minimizing interference. For resource management, hardware should provide +monitoring features that allow system software to profile workload resource +consumption and allocate resources accordingly. + +To facilitate this, the QoS Identifiers extension (Ssqosid) introduces the +`srmcfg` register, which configures a hart with two identifiers: a Resource +Control ID (`RCID`) and a Monitoring Counter ID (`MCID`). These identifiers +accompany each request issued by the hart to shared resource controllers. + +Additional metadata, like the nature of the memory access and the ID of the +originating supervisor domain, can accompany `RCID` and `MCID`. Resource +controllers may use this metadata for differentiated service such as a different +capacity allocation for code storage vs. data storage. Resource controllers can +use this data for security policies such as not exposing statistics of one +security domain to another. + +These identifiers are crucial for the RISC-V Capacity and Bandwidth Controller +QoS Register Interface (CBQRI) specification, which provides methods for setting +resource usage limits and monitoring resource consumption. The `RCID` controls +resource allocations, while the `MCID` is used for tracking resource usage. + +NOTE: The Ssqosid extension does not require that S-mode mode be implemented. + +=== Supervisor Resource Management Configuration (`srmcfg`) register + +The `srmcfg` register is an SXLEN-bit read/write register used to configure a +Resource Control ID (`RCID`) and a Monitoring Counter ID (`MCID`). Both `RCID` +and `MCID` are WARL fields. The register is formatted as shown in <> +when SXLEN=64 and <> when SXLEN=32. + +The `RCID` and `MCID` accompany each request made by the hart to shared resource +controllers. The `RCID` is used to determine the resource allocations (e.g., +cache occupancy limits, memory bandwidth limits, etc.) to enforce. The `MCID` is +used to identify a counter to monitor resource usage. + +[[SRMCFG64]] +.Supervisor Resource Management Configuration (`srmcfg`) register for SXLEN=64 + +[wavedrom, , ] +.... +{reg: [ + {bits: 12, name: 'RCID'}, + {bits: 4, name: 'WPRI'}, + {bits: 12, name: 'MCID'}, + {bits: 36, name: 'WPRI'}, +], config:{lanes: 2, hspace:1024}} +.... + +[[SRMCFG32]] +.Supervisor Resource Management Configuration (`srmcfg`) register for SXLEN=32 + +[wavedrom, , ] +.... +{reg: [ + {bits: 12, name: 'RCID'}, + {bits: 4, name: 'WPRI'}, + {bits: 12, name: 'MCID'}, + {bits: 4, name: 'WPRI'}, +], config:{lanes: 1, hspace:1024}} +.... + +The `RCID` and `MCID` configured in the `srmcfg` CSR apply to all privilege +modes of software execution on that hart by default, but this behavior may be +overridden by future extensions. + +If extension Smstateen is implemented together with Ssqosid, then Ssqosid also +requires the SRMCFG bit in `mstateen0` to be implemented. +If `mstateen0`.SRMCFG is 0, attempts to access `srmcfg` in privilege modes +less privileged than M-mode raise an illegal-instruction exception. +If `mstateen0`.SRMCFG is 1 or if extension Smstateen is not implemented, +attempts to access `srmcfg` when `V=1` raise a virtual-instruction exception. + +[NOTE] +==== +A reset value of 0 is suggested for the `RCID` field matching resource +controllers' default behavior of associating all capacity with `RCID=0`. The +`MCID` reset value does not affect functionality and may be +implementation-defined. + +Typically, fewer bits are allocated for `RCID` (e.g., to support tens of RCIDs) +than for `MCID` (e.g., to support hundreds of MCIDs). A common `RCID` is usually +used to group apps or VMs, pooling resource allocations to meet collective SLAs. +If an SLA breach occurs, unique MCIDs enable granular monitoring, aiding +decisions on resource adjustment, associating a different `RCID` with a subset +of members, or migrating members to other machines. The larger pool of MCIDs +speeds up this analysis. + +The `RCID` and `MCID` in `srmcfg` apply across all privilege levels on the hart. +Typically, higher-privilege modes don't modify `srmcfg`, as they often serve +lower-privileged tasks. If differentiation is needed, higher privilege code can +update `srmcfg` and restore it before returning to a lower privilege level. + +In VM environments, hypervisors usually manage resource allocations, keeping +the Guest OS out of QoS flows. If needed, the hypervisor can virtualize +`srmcfg` CSR for a VM using the virtual-instruction exceptions triggered upon +Guest access. If the direct selection of `RCID` and `MCID` by the VM becomes +common and emulation overhead is an issue, future extensions may allow VS-mode +to use a selector for a hypervisor-configured set of CSRs holding `RCID` and +`MCID` values designated for that Guest OS use. + +During context switches, the supervisor may choose to execute with the `srmcfg` +of the outgoing context to attribute the execution to it. Prior to restoring +the new context, it switches to the new VM's `srmcfg`. The supervisor can also +use a separate configuration for execution not to be attributed to either +contexts. +==== diff --git a/param_extraction/chunks/chunk_054.txt.license b/param_extraction/chunks/chunk_054.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_054.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_055.txt b/param_extraction/chunks/chunk_055.txt new file mode 100644 index 0000000000..3fc024f9a8 --- /dev/null +++ b/param_extraction/chunks/chunk_055.txt @@ -0,0 +1,24 @@ +# Chunk: chunk_055 +# Source: symbols.adoc +# Lines: 1-17 (of 17) +# Content starts: line 1 +# Line count: 17 +# Sections: 0 +# +// Macros that can be used in place of unicode characters to make writing them +// easier, e.g. "X {ge} Y". +:le: ≤ +:ge: ≥ +:ne: ≠ +:approx: ≈ +:inf: ∞ +:circ: ○ +:bullet: ∙ +:times: × +:check: ✓ +:vertical-ellipsis: ⋮ +:ellipsis: ⋯ +:prime: ′ +:interpunct: · +:pm: ± +:rightarrow: → diff --git a/param_extraction/chunks/chunk_055.txt.license b/param_extraction/chunks/chunk_055.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_055.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_056.txt b/param_extraction/chunks/chunk_056.txt new file mode 100644 index 0000000000..6fc63c2a0a --- /dev/null +++ b/param_extraction/chunks/chunk_056.txt @@ -0,0 +1,911 @@ +# Chunk: chunk_056 +# Source: unpriv-cfi.adoc +# Lines: 1-894 (of 894) +# Content starts: line 1 +# Line count: 894 +# Sections: 10 +# == Control-flow Integrity (CFI) +# === Landing Pad (Zicfilp) +# ==== Landing Pad Enforcement +# ==== Landing Pad Instruction +# === Shadow Stack (Zicfiss) +# ==== Zicfiss Instructions Summary +# ==== Shadow Stack Pointer (`ssp`) +# ==== Zicfiss Instructions +# ==== Push to the Shadow Stack +# ==== Pop from the Shadow Stack +# +== Control-flow Integrity (CFI) + +Control-flow Integrity (CFI) capabilities help defend against Return-Oriented +Programming (ROP) and Call/Jump-Oriented Programming (COP/JOP) style +control-flow subversion attacks. These attack methodologies use code sequences +in authorized modules, with at least one instruction in the sequence being a +control transfer instruction that depends on attacker-controlled data either in +the return stack or in memory used to obtain the target address for a call or +jump. Attackers stitch these sequences together by diverting the control flow +instructions (e.g., `JALR`, `C.JR`, `C.JALR`), from their original target +address to a new target via modification in the return stack or in the memory +used to obtain the jump/call target address. + +RV32/RV64 provides two types of control transfer instructions - unconditional +jumps and conditional branches. Conditional branches encode an offset in the +immediate field of the instruction and are thus direct branches that are not +susceptible to control-flow subversion. Unconditional direct jumps using `JAL` +transfer control to a target that is in a +/- 1 MiB range from the current `pc`. +Unconditional indirect jumps using the `JALR` obtain their branch target by +adding the sign extended 12-bit immediate encoded in the instruction to the +`rs1` register. + +The RV32I/RV64I does not have a dedicated instruction for calling a procedure or +returning from a procedure. A `JAL` or `JALR` may be used to perform a procedure +call and `JALR` to return from a procedure. The RISC-V ABI however defines the +convention that a `JAL`/`JALR` where `rd` (i.e. the link register) is `x1` or +`x5` is a procedure call, and a `JALR` where `rs1` is the conventional +link register (i.e. `x1` or `x5`) is a return from procedure. The architecture +allows for using these hints and conventions to support return address +prediction (See <>). + +The RVC standard extension for compressed instructions provides unconditional +jump and conditional branch instructions. The `C.J` and `C.JAL` instructions +encode an offset in the immediate field of the instruction and thus are not +susceptible to control-flow subversion. The `C.JR` and `C.JALR` RVC instructions +perform an unconditional control transfer to the address in register `rs1`. The +`C.JALR` additionally writes the address of the instruction following the jump +(`pc+2`) to the link register `x1` and is a procedure call. The `C.JR` is a +return from procedure if `rs1` is a conventional link register (i.e. `x1` or +`x5`); else it is an indirect jump. + +[[norm:cfi_call_term]] +The term _call_ is used to refer to a `JAL` or `JALR` instruction with a link +register as destination, i.e., _rd_≠`x0`. Conventionally, the link register is +`x1` or `x5`. A _call_ using `JAL` or `C.JAL` is termed a direct call. A +`C.JALR` expands to `JALR x1, 0(rs1)` and is a _call_. A _call_ using `JALR` or +`C.JALR` is termed an _indirect-call_. + +[[norm:cfi_return_term]] +The term _return_ is used to refer to a `JALR` instruction with _rd_=`x0` and +with _rs1_=`x1` or _rs1_=`x5`. A `C.JR` instruction expands to +`JALR x0, 0(rs1)` and is a _return_ if _rs1_=`x1` or _rs1_=`x5`. + +[[norm:cfi_indirect-jump_term]] +The term _indirect-jump_ is used to refer to a `JALR` instruction with _rd_=`x0` +and where the _rs1_ is not `x1` or `x5` (i.e., not a return). A `C.JR` +instruction where _rs1_ is not `x1` or `x5` (i.e., not a return) is an +_indirect-jump_. + +The Zicfiss and Zicfilp extensions build on these conventions and hints and +provide backward-edge and forward-edge control flow integrity respectively. + +The Unprivileged ISA for Zicfilp extension is specified in <> +and for the Unprivileged ISA for Zicfiss extension is specified in +<>. The Privileged ISA for these extensions is specified in the +Privileged ISA specification. + +[[unpriv-forward]] +=== Landing Pad (Zicfilp) + +To enforce forward-edge control-flow integrity, the Zicfilp extension introduces +a landing pad (`LPAD`) instruction. The `LPAD` instruction must be placed at the +program locations that are valid targets of indirect jumps or calls. [#norm:zicflip_lpad_enc]#The `LPAD` +instruction (See <>) is encoded using the `AUIPC` major opcode with +_rd_=`x0`.# + +Compilers emit a landing pad instruction as the first instruction of an +address-taken function, as well as at any indirect jump targets. A landing pad +instruction is not required in functions that are only reached using a direct +call or direct jump. + +The landing pad is designed to provide integrity to control transfers performed +using indirect calls and jumps, and this is referred to as forward-edge +protection. When the Zicfilp is active, the hart tracks an expected landing pad +(`ELP`) state that is updated by an _indirect_call_ or _indirect_jump_ to +require a landing pad instruction at the target of the branch. If the +instruction at the target is not a landing pad, then a software-check exception +is raised. + +A landing pad may be optionally associated with a 20-bit label. With labeling +enabled, the number of landing pads that can be reached from an indirect call +or jump sites can be defined using programming language-based policies. Labeling +of the landing pads enables software to achieve greater precision in pairing up +indirect call/jump sites with valid targets. When labeling of landing pads +is used, indirect call or indirect jump site can specify the expected label of +the landing pad and thereby constrain the set of landing pads that may be +reached from each indirect call or indirect jump site in the program. + +In the simplest form, a program can be built with a single label value to +implement a coarse-grained version of forward-edge control-flow integrity. By +constraining gadgets to be preceded by a landing pad instruction that marks +the start of indirect callable functions, the program can significantly reduce +the available gadget space. A second form of label generation may generate a +signature, such as a MAC, using the prototype of the function. Programs that use +this approach would further constrain the gadgets accessible from a call site to +only indirectly callable functions that match the prototype of the called +functions. Another approach to label generation involves analyzing the +control-flow-graph (CFG) of the program, which can lead to even more stringent +constraints on the set of reachable gadgets. Such programs may further use +multiple labels per function, which means that if a function is called from two +or more call sites, the functions can be labeled as being reachable from each of +the call sites. For instance, consider two call sites A and B, where A calls the +functions X and Y, and B calls the functions Y and Z. In a single label scheme, +functions X, Y, and Z would need to be assigned the same label so that both call +sites A and B can invoke the common function Y. This scheme would allow call +site A to also call function Z and call site B to also call function X. However, +if function Y was assigned two labels - one corresponding to call site A and the +other to call site B, then Y can be invoked by both call sites, but X can only be +invoked by call site A and Z can only be invoked by call site B. To support +multiple labels, the compiler could generate a call-site-specific entry point +for shared functions, with each entry point having its own landing pad +instruction followed by a direct branch to the start of the function. This would +allow the function to be labeled with multiple labels, each corresponding to a +specific call site. A portion of the label space may be dedicated to labeled +landing pads that are only valid targets of an indirect jump (and not an +indirect call). + +The `LPAD` instruction uses the code points defined as HINTs for the `AUIPC` +opcode. When Zicfilp is not active at a privilege level or when the extension +is not implemented, the landing pad instruction executes as a no-op. A program +that is built with `LPAD` instructions can thus continue to operate correctly, +but without forward-edge control-flow integrity, on processors that do not +support the Zicfilp extension or if the Zicfilp extension is not active. + +Compilers and linkers should provide an attribute flag to indicate if the +program has been compiled with the Zicfilp extension and use that to determine +if the Zicfilp extension should be activated. The dynamic loader should activate +the use of Zicfilp extension for an application only if all executables (the +application and the dependent dynamically linked libraries) used by that +application use the Zicfilp extension. + +When Zicfilp extension is not active or not implemented, the hart does not +require landing pad instructions at the targets of indirect calls/jumps, and the +landing instructions revert to being no-ops. This allows a program compiled +with landing pad instructions to operate correctly but without forward-edge +control-flow integrity. + +The Zicfilp extensions may be activated for use individually and independently +for each privilege mode. + +The Zicfilp extension depends on the Zicsr extension. + +==== Landing Pad Enforcement + +To enforce that the target of an indirect call or indirect jump must be a valid +landing pad instruction, the hart maintains an expected landing pad (`ELP`) state +to determine if a landing pad instruction is required at the target of an +indirect call or an indirect jump. The `ELP` state can be one of: + +* 0 - `NO_LP_EXPECTED` +* 1 - `LP_EXPECTED` + +The `ELP` state is initialized to `NO_LP_EXPECTED` by the hart upon reset. + +[[norm:zicflip_lpad_expected]] +The Zicfilp extension, when enabled, determines if an indirect call or an +indirect jump must land on a landing pad, as specified in <>. If +`is_lp_expected` is 1, then the hart updates the `ELP` to `LP_EXPECTED`. + +[[IND_CALL_JMP]] +.Landing pad expected determination +[listing] +---- + + is_lp_expected = ( (JALR || C.JR || C.JALR) && + (rs1 != x1) && (rs1 != x5) && (rs1 != x7) ) ? 1 : 0; +---- + +[[norm:zicflip_indirect_branch_lpad]] +An indirect branch using `JALR`, `C.JALR`, or `C.JR` with `rs1` as `x7` is +termed a software guarded branch. Such branches do not need to land on a +`LPAD` instruction and thus do not set `ELP` to `LP_EXPECTED`. + +[NOTE] +==== +When the register source is a link register and the register destination is +`x0`, then it's a return from a procedure and does not require a landing pad at +the target. + +When the register source and register destination are both link registers, then +it is a semantically-direct-call. For example, the `call offset` +pseudoinstruction may expand to a two instruction sequence composed of a +`lui ra, imm20` or a `auipc ra, imm20` instruction followed by a +`jalr ra, imm12(ra)` instruction where `ra` is the link register (either `x1` or +`x5`). Since the address of the procedure was not explicitly taken and the +computed address is not obtained from mutable memory, such semantically-direct +calls do not require a landing pad to be placed at the target. Compilers and +JITers must use the semantically-direct calls only if the `rs1` was computed as +a PC-relative or an absolute offset to the symbol. + +The `tail offset` pseudoinstruction used to tail call a far-away procedure may +also be expanded to a two instruction sequence composed of a `lui x7, imm20` or +`auipc x7, imm20` followed by a `jalr x0, x7`. Since the address of the +procedure was not explicitly taken and the computed address is not obtained from +mutable memory, such semantically-direct tail-calls do not require a landing pad +to be placed at the target. + +Software guarded branches may also be used by compilers to generate code for +constructs like switch-cases. When using the software guarded branches, the +compiler is required to ensure it has full control on the possible jump +targets (e.g., by obtaining the targets from a read-only table in memory and +performing bounds checking on the index into the table, etc.). +==== + +The landing pad may be labeled. Zicfilp extension designates the register `x7` +for use as the landing pad label register. [#norm:zicflip_lpad_label]#To support labeled landing pads, the +indirect call/jump sites establish an expected landing pad label (e.g., using +the `LUI` instruction) in the bits 31:12 of the `x7` register.# [#norm:zicflip_lpad_imm_enc]#The `LPAD` +instruction is encoded with a 20-bit immediate value called the landing-pad-label +(`LPL`) that is matched to the expected landing pad label. When `LPL` is encoded +as zero, the `LPAD` instruction does not perform the label check and in programs +built with this single label mode of operation the indirect call/jump sites do +not need to establish an expected landing pad label value in `x7`.# + +[[norm:zicflip_elp_lpad_expected]] +When `ELP` is set to `LP_EXPECTED`, if the next instruction in the instruction +stream is not 4-byte aligned, or is not `LPAD`, or if the landing pad label +encoded in `LPAD` is not zero and does not match the expected landing pad label +in bits 31:12 of the `x7` register, then a software-check exception (cause=18) +with `__x__tval` set to "landing pad fault (code=2)" is raised else the `ELP` is +updated to `NO_LP_EXPECTED`. + +[NOTE] +==== +The tracking of `ELP` and the requirement for a landing pad instruction +at the target of indirect call and jump enables a processor implementation to +significantly reduce or to prevent speculation to non-landing-pad instructions. +Constraining speculation using this technique, greatly reduces the gadget space +and increases the difficulty of using techniques such as branch-target-injection, +also known as Spectre variant 2, which use speculative execution to leak data +through side channels. + +The `LPAD` requires a 4-byte alignment to address the concatenation of two +instructions `A` and `B` accidentally forming an unintended landing pad in the +program. For example, consider a 32-bit instruction where the bytes 3 and 2 have +a pattern of `?017h` (for example, the immediate fields of a `LUI`, `AUIPC`, or +a `JAL` instruction), followed by a 16-bit or a 32-bit instruction. When +patterns that can accidentally form a valid landing pad are detected, the +assembler or linker can force instruction `A` to be aligned to a 4-byte +boundary to force the unintended `LPAD` pattern to become misaligned, and thus +not a valid landing pad, or may use an alternate register allocation to prevent +the accidental landing pad. +==== + +<<< + +[[LP_INST]] +==== Landing Pad Instruction + +[#norm:zicflip_lpad_enabled_instr_allowed]#When Zicfilp is enabled, `LPAD` is the only instruction allowed to execute when +the `ELP` state is `LP_EXPECTED`. If Zicfilp is not enabled then the instruction +is a no-op.# [#norm:zicflip_lpad_enabled_exception]#If Zicfilp is enabled, the `LPAD` instruction causes a +software-check exception with `__x__tval` set to "landing pad fault (code=2)"# if +any of the following conditions are true: + +* [#norm:zicflip_lpad_alignment_exception]#The `pc` is not 4-byte aligned and `ELP` is `LP_EXPECTED`.# +* [#norm:zicflip_lpad_label_exception]#The `ELP` is `LP_EXPECTED` and the `LPL` is not zero and the `LPL` does not match the expected landing pad label in bits 31:12 of the `x7` register.# + +[[norm:zicflip_lpad_no_sw_exception]] +If a software-check exception is not caused then the `ELP` is updated to +`NO_LP_EXPECTED`. + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr:'AUIPC'}, + {bits: 5, name: 'rd', attr:'00000'}, + {bits: 20, name: 'LPL'}, +], config:{lanes: 1, hspace:1024}} +.... + +The operation of the `LPAD` instruction is as follows: + +.`LPAD` operation +[listing] +---- +if (xLPE == 1 && ELP == LP_EXPECTED) + // If PC not 4-byte aligned then software-check exception + if pc[1:0] != 0 + raise software-check exception + // If landing pad label not matched -> software-check exception + else if (inst.LPL != x7[31:12] && inst.LPL != 0) + raise software-check exception + else + ELP = NO_LP_EXPECTED +else + no-op +endif +---- +# +<<< + +[[unpriv-backward]] +=== Shadow Stack (Zicfiss) + +The Zicfiss extension introduces a shadow stack to enforce backward-edge +control-flow integrity. A shadow stack is a second stack used to store a +shadow copy of the return address in the link register if it needs to be +spilled. + +The shadow stack is designed to provide integrity to control transfers performed +using a _return_, where the return may be from a procedure invoked using an +indirect call or a direct call, and this is referred to as backward-edge +protection. + +A program using backward-edge control-flow integrity has two stacks: a regular +stack and a shadow stack. The shadow stack is used to spill the link register, +if required, by non-leaf functions. An additional register, shadow-stack-pointer +(`ssp`), is introduced in the architecture to hold the address of the top of the +active shadow stack. + +The shadow stack, similar to the regular stack, grows downwards, from +higher addresses to lower addresses. Each entry on the shadow stack is `XLEN` +wide and holds the link register value. The `ssp` points to the top of the +shadow stack, which is the address of the last element stored on the shadow +stack. + +The shadow stack is architecturally protected from inadvertent corruptions and +modifications, as detailed in the Privileged specification. + +The Zicfiss extension provides instructions to store and load the link register +to/from the shadow stack and to check the integrity of the return address. The +extension provides instructions to support common stack maintenance operations +such as stack unwinding and stack switching. + +[#norm:zicfiss_link_reg_func_enter]#When Zicfiss is enabled, each function that needs to spill the link register, +typically non-leaf functions, store the link register value to the regular stack +and a shadow copy of the link register value to the shadow stack when the +function is entered (the prologue).# [#norm:zicfiss_link_reg_func_return]#When such a function returns (the +epilogue), the function loads the link register from the regular stack and +the shadow copy of the link register from the shadow stack.# [#norm:zicfiss_stack_compare]#Then, the link +register value from the regular stack and the shadow link register value from +the shadow stack are compared. A mismatch of the two values is indicative of a +subversion of the return address control variable and causes a software-check +exception.# + +[#norm:zicfiss_enc]#The Zicfiss instructions, except `SSAMOSWAP.W/D`, are encoded using a subset of +May-Be-Operation instructions defined by the Zimop and Zcmop extensions.# +This subset of instructions revert to their Zimop/Zcmop defined behavior when +the Zicfiss extension is not implemented or if the extension has not been +activated. A program that is built with Zicfiss instructions can thus continue +to operate correctly, but without backward-edge control-flow integrity, on +processors that do not support the Zicfiss extension or if the Zicfiss extension +is not active. The Zicfiss extension may be activated for use individually and +independently for each privilege mode. + +Compilers should flag each object file (for example, using flags in the ELF +attributes) to indicate if the object file has been compiled with the Zicfiss +instructions. The linker should flag (for example, using flags in the ELF +attributes) the binary/executable generated by linking objects as being +compiled with the Zicfiss instructions only if all the object files that are +linked have the same Zicfiss attributes. + +The dynamic loader should activate the use of Zicfiss extension for an +application only if all executables (the application and the dependent +dynamically-linked libraries) used by that application use the Zicfiss +extension. + +<<< + +An application that has the Zicfiss extension active may request the dynamic +loader at runtime to load a new dynamic shared object (using dlopen() for +example). If the requested object does not have the Zicfiss attribute then +the dynamic loader, based on its policy (e.g., established by the operating +system or the administrator) configuration, could either deny the request or +deactivate the Zicfiss extension for the application. It is strongly recommended +that the policy enforces a strict security posture and denies the request. + +The Zicfiss extension depends on the Zicsr and Zimop extensions. Furthermore, +if the Zcmop extension is implemented, the Zicfiss extension also provides the +`C.SSPUSH` and `C.SSPOPCHK` instructions. Moreover, use of Zicfiss in U-mode +requires S-mode to be implemented. Use of Zicfiss in M-mode is not supported. + +==== Zicfiss Instructions Summary + +The Zicfiss extension introduces the following instructions: + +* Push to the shadow stack (See <>) +** [#norm:zicfiss_sspush_enc]#`SSPUSH x1` and `SSPUSH x5` - encoded using `MOP.RR.7`# +** [#norm:zicfiss_c-sspush_enc]#`C.SSPUSH x1` - encoded using `C.MOP.1`# + +* Pop from the shadow stack (See <>) +** [#norm:zicfiss_sspopchk_enc]#`SSPOPCHK x1` and `SSPOPCHK x5` - encoded using `MOP.R.28`# +** [#norm:zicfiss_c-sspopchk_enc]#`C.SSPOPCHK x5` - encoded using `C.MOP.5`# + +* Read the value of `ssp` into a register (See <>) +** [#norm:zicfiss_ssrdp_enc]#`SSRDP` - encoded using `MOP.R.28`# + +* [#norm:zicfiss_atomic_swap]#Perform an atomic swap from a shadow stack location (See <>)# +** `SSAMOSWAP.W` and `SSAMOSWAP.D` + +Zicfiss does not use all encodings of `MOP.RR.7` or `MOP.R.28`. When a +`MOP.RR.7` or `MOP.R.28` encoding is not used by the Zicfiss extension, the +corresponding instruction adheres to its Zimop-defined behavior, unless +redefined by another extension. + +==== Shadow Stack Pointer (`ssp`) + +[#norm:ssp_op]#The `ssp` CSR is an unprivileged read-write (URW) CSR that reads and writes +`XLEN` low order bits of the shadow stack pointer (`ssp`).# [#norm:ssp_addr]#The CSR address is +0x011.# [#norm:ssp_sz]#There is no high CSR defined as the `ssp` is always as wide as the `XLEN` +of the current privilege mode.# [#norm:ssp-field_1_0]#The bits 1:0 of `ssp` are read-only zero. If the +UXLEN or SXLEN may never be 32, then the bit 2 is also read-only zero.# + +<<< + +==== Zicfiss Instructions + +[[SS_PUSH]] +==== Push to the Shadow Stack +[[norm:ss_push]] +A shadow stack push operation is defined as decrement of the `ssp` by `XLEN/8` +followed by a store of the value in the link register to memory at the new top +of the shadow stack. + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr:'SYSTEM'}, + {bits: 5, name: 'rd', attr:['00000']}, + {bits: 3, name: 'funct3', attr:['100']}, + {bits: 5, name: 'rs1', attr:['00000']}, + {bits: 5, name: 'rs2', attr:['00001', '00101']}, + {bits: 7, name: '1100111', attr:['SSPUSH x1','SSPUSH x5']}, +], config:{lanes: 1, hspace:1024}} +.... + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 2, name: 'op', attr:'C1'}, + {bits: 5, name: '00000'}, + {bits: 1, name: '1'}, + {bits: 3, name: 'n[3:1]', attr:['000']}, + {bits: 1, name: '0'}, + {bits: 1, name: '0'}, + {bits: 3, name: '011', attr:['C.SSPUSH x1']}, +], config:{lanes: 1, hspace:1024}} +.... + +Only `x1` and `x5` registers are supported as `rs2` for `SSPUSH`. Zicfiss +provides a 16-bit version of the `SSPUSH x1` instruction using the Zcmop +defined `C.MOP.1` encoding. The `C.SSPUSH x1` expands to `SSPUSH x1`. + +[[norm:sspush_c-sspush_instr]] +The `SSPUSH` instruction and its compressed form `C.SSPUSH` can be used to push +a link register on the shadow stack. The `SSPUSH` and `C.SSPUSH` instructions +perform a store identically to the existing store instructions, with the +difference that the base is implicitly `ssp` and the width is implicitly `XLEN`. + +The operation of the `SSPUSH` and `C.SSPUSH` instructions is as follows: + +.`SSPUSH` and `C.SSPUSH` operation +[listing] +---- +if (xSSE == 1) + mem[ssp - (XLEN/8)] = X(src) # Store src value to ssp - XLEN/8 + ssp = ssp - (XLEN/8) # decrement ssp by XLEN/8 +endif +---- +[[norm:sspush_c-sspush_decrement]] +The `ssp` is decremented by `SSPUSH` and `C.SSPUSH` only if the store to the +shadow stack completes successfully. + +<<< + +[[SS_POP]] +==== Pop from the Shadow Stack +[[norm:ss_pop]] +A shadow stack pop operation is defined as an `XLEN` wide read from the +current top of the shadow stack followed by an increment of the `ssp` by +`XLEN/8`. + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr:'SYSTEM'}, + {bits: 5, name: 'rd', attr:['00000','00000']}, + {bits: 3, name: 'funct3', attr:['100']}, + {bits: 5, name: 'rs1', attr:['00001','00101']}, + {bits: 12, name: '110011011100', attr:['SSPOPCHK x1','SSPOPCHK x5']}, +], config:{lanes: 1, hspace:1024}} +.... + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 2, name: 'op', attr:'C1'}, + {bits: 5, name: '00000'}, + {bits: 1, name: '1'}, + {bits: 3, name: 'n[3:1]', attr:['010']}, + {bits: 1, name: '0'}, + {bits: 1, name: '0'}, + {bits: 3, name: '011', attr:['C.SSPOPCHK x5']}, +], config:{lanes: 1, hspace:1024}} +.... + +Only `x1` and `x5` registers are supported as `rs1` for `SSPOPCHK`. Zicfiss +provides a 16-bit version of the `SSPOPCHK x5` using the Zcmop defined `C.MOP.5` +encoding. The `C.SSPOPCHK x5` expands to `SSPOPCHK x5`. + +Programs with a shadow stack push the return address onto the regular stack as +well as the shadow stack in the prologue of non-leaf functions. When returning +from these non-leaf functions, such programs pop the link register from the +regular stack and pop a shadow copy of the link register from the shadow stack. +The two values are then compared. If the values do not match, it is indicative +of a corruption of the return address variable on the regular stack. + +[[norm:sspopchk_shadow_return_pop]] +The `SSPOPCHK` instruction, and its compressed form `C.SSPOPCHK`, can be used to +pop the shadow return address value from the shadow stack and check that the +value matches the contents of the link register, and if not cause a +software-check exception with `__x__tval` set to "shadow stack fault (code=3)". + +While any register may be used as link register, conventionally the `x1` or `x5` +registers are used. The shadow stack instructions are designed to be most +efficient when the `x1` and `x5` registers are used as the link register. + +[NOTE] +==== +Return-address prediction stacks are a common feature of high-performance +instruction-fetch units, but they require accurate detection of instructions +used for procedure calls and returns to be effective. For RISC-V, hints as to +the instructions' usage are encoded implicitly via the register numbers used. +The return-address stack (RAS) actions to pop and/or push onto the RAS are +specified in <>. + +Using `x1` or `x5` as the link register allows a program to benefit from the +return-address prediction stacks. Additionally, since the shadow stack +instructions are designed around the use of `x1` or `x5` as the link register, +using any other register as a link register would incur the cost of additional +register movements. + +Compilers, when generating code with backward-edge CFI, must protect the link +register, e.g., `x1` and/or `x5`, from arbitrary modification by not emitting +unsafe code sequences. +==== + +<<< + +[NOTE] +==== +Storing the return address on both stacks preserves the call stack layout and +the ABI, while also allowing for the detection of corruption of the return +address on the regular stack. The prologue and epilogue of a non-leaf function +that uses shadow stacks is as follows: + +[listing] +---- + function_entry: + addi sp,sp,-8 # push link register x1 + sd x1,(sp) # on regular stack + sspush x1 # push link register x1 on shadow stack + : + ld x1,(sp) # pop link register x1 from regular stack + addi sp,sp,8 + sspopchk x1 # fault if x1 not equal to shadow + # return address + ret +---- + +This example illustrates the use of `x1` register as the link register. +Alternatively, the `x5` register may also be used as the link register. + +A leaf function, a function that does not itself make function calls, does +not need to spill the link register. Consequently, the return value may be held +in the link register itself for the duration of the leaf function's execution. +==== + +[[norm:sspopchk-c_load_op]] +The `C.SSPOPCHK`, and `SSPOPCHK` instructions perform a load identically to the +existing load instructions, with the difference that the base is implicitly +`ssp` and the width is implicitly `XLEN`. + +The operation of the `SSPOPCHK` and `C.SSPOPCHK` instructions is as follows: + +.`SSPOPCHK` and `C.SSPOPCHK` operation +[listing] +---- +if (xSSE == 1) + temp = mem[ssp] # Load temp from address in ssp and + if temp != X(src) # Compare temp to value in src and + # cause an software-check exception + # if they are not bitwise equal. + # Only x1 and x5 may be used as src + raise software-check exception + else + ssp = ssp + (XLEN/8) # increment ssp by XLEN/8. + endif +endif +---- + +[[norm:sspop_exception]] +If the value loaded from the address in `ssp` does not match the value in `rs1`, +a software-check exception (cause=18) is raised with `__x__tval` set to "shadow +stack fault (code=3)". The software-check exception caused by `SSPOPCHK`/ +`C.SSPOPCHK` is lower in priority than a load/store/AMO access-fault exception. + +[[norm:sspop_increment]] +The `ssp` is incremented by `SSPOPCHK` and `C.SSPOPCHK` only if the load from +the shadow stack completes successfully and no software-check exception is +raised. + +<<< + +[NOTE] +==== +The use of the compressed instruction `C.SSPUSH x1` to push on the shadow stack +is most efficient when the ABI uses `x1` as the link register, as the link +register may then be pushed without needing a register-to-register move in the +function prologue. To use the compressed instruction `C.SSPOPCHK x5`, the +function should pop the return address from regular stack into the alternate +link register `x5` and use the `C.SSPOPCHK x5` to compare the return address to +the shadow copy stored on the shadow stack. The function then uses `C.JR x5` to +jump to the return address. + +[listing] +---- + function_entry: + c.addi sp,sp,-8 # push link register x1 + c.sd x1,(sp) # on regular stack + c.sspush x1 # push link register x1 on shadow stack + : + c.ld x5,(sp) # pop link register x5 from regular stack + c.addi sp,sp,8 + c.sspopchk x5 # fault if x5 not equal to shadow return address + c.jr x5 +---- + +==== + +[NOTE] +==== +Store-to-load forwarding is a common technique employed by high-performance +processor implementations. Zicfiss implementations may prevent forwarding from +a non-shadow-stack store to the `SSPOPCHK` or the `C.SSPOPCHK` instructions. A +non-shadow-stack store causes a fault if done to a page mapped as a shadow +stack. However, such determination may be delayed till the PTE has been examined +and thus may be used to transiently forward the data from such stores to +`SSPOPCHK` or to `C.SSPOPCHK`. +==== + +<<< + +[[SSP_READ]] +==== Read `ssp` into a Register + +[[norm:ssrdp_read]] +The `SSRDP` instruction is provided to move the contents of `ssp` to a destination +register. + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr:'SYSTEM'}, + {bits: 5, name: 'rd', attr:['dst']}, + {bits: 3, name: 'funct3', attr:['100']}, + {bits: 5, name: '00000'}, + {bits: 12, name: '110011011100', attr:['SSRDP']}, +], config:{lanes: 1, hspace:1024}} +.... + +Encoding _rd_ as `x0` is not supported for `SSRDP`. + +The operation of the `SSRDP` instructions is as follows: + +.`SSRDP` operation +[listing] +---- +if (xSSE == 1) + X(dst) = ssp +else + X(dst) = 0 +endif +---- + +[NOTE] +==== +The property of Zimop writing 0 to the `rd` when the extension using Zimop is +not implemented or not active may be used by to determine if Zicfiss extension +is active. For example, functions that unwind shadow stacks may skip over the +unwind actions by dynamically detecting if the Zicfiss extension is active. + +An example sequence such as the following may be used: + +[listing] + ssrdp t0 # mv ssp to t0 + beqz t0, zicfiss_not_active # zero is not a valid shadow stack + # pointer by convention + # Zicfiss is active + : + : +zicfiss_not_active: + +To assist with the use of such code sequences, operating systems and runtimes +must not locate shadow stacks at address 0. +==== + +<<< + +[NOTE] +==== +A common operation performed on stacks is to unwind them to support constructs +like `setjmp`/`longjmp`, C++ exception handling, etc. A program that uses shadow +stacks must unwind the shadow stack in addition to the stack used to store data. +The unwind function must verify that it does not accidentally unwind past the +bounds of the shadow stack. Shadow stacks are expected to be bounded on each end +using guard pages. A guard page for a stack is a page that is not accessible by +the process that owns the stack. To detect if the unwind occurs past the bounds +of the shadow stack, the unwind may be done in maximal increments of 4 KiB, +testing whether the `ssp` is still pointing to a shadow stack page or has +unwound into the guard page. The following examples illustrate the use of shadow +stack instructions to unwind a shadow stack. This example assumes that the +`setjmp` function itself does not push on to the shadow stack (being a leaf +function, it is not required to). + +[source,c] +---- +setjmp() { + : + : + // read and save the shadow stack pointer to jmp_buf + asm("ssrdp %0" : "=r"(cur_ssp):); + jmp_buf->saved_ssp = cur_ssp; + : + : +} +longjmp() { + : + // Read current shadow stack pointer and + // compute number of call frames to unwind + asm("ssrdp %0" : "=r"(cur_ssp):); + // Skip the unwind if backward-edge CFI not active + asm("beqz %0, back_cfi_not_active" : "=r"(cur_ssp):); + // Unwind the frames in a loop + while ( jmp_buf->saved_ssp > cur_ssp ) { + // advance by a maximum of 4K at a time to avoid + // unwinding past bounds of the shadow stack + cur_ssp = ( (jmp_buf->saved_ssp - cur_ssp) >= 4096 ) ? + (cur_ssp + 4096) : jmp_buf->saved_ssp; + asm("csrw ssp, %0" : : "r" (cur_ssp)); + // Test if unwound past the shadow stack bounds + asm("sspush x5"); + asm("sspopchk x5"); + } +back_cfi_not_active: + : +} +---- +==== + +<<< + +[[SSAMOSWAP]] +==== Atomic Swap from a Shadow Stack Location + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr:'AMO'}, + {bits: 5, name: 'rd', attr:'dest'}, + {bits: 3, name: 'funct3', attr:['010', '011']}, + {bits: 5, name: 'rs1', attr:'addr'}, + {bits: 5, name: 'rs2', attr:'src'}, + {bits: 1, name: 'rl'}, + {bits: 1, name: 'aq'}, + {bits: 5, name: '01001', attr:['SSAMOSWAP.W', 'SSAMOSWAP.D']}, +], config:{lanes: 1, hspace:1024}} +.... + +[[norm:rv32_ssamoswap-w_op]] +For RV32, `SSAMOSWAP.W` atomically loads a 32-bit data value from address of a +shadow stack location in `rs1`, puts the loaded value into register `rd`, and +stores the 32-bit value held in `rs2` to the original address in `rs1`. +`SSAMOSWAP.D` (RV64 only) is similar to `SSAMOSWAP.W` but operates on 64-bit +data values. + +.`SSAMOSWAP.W` for RV32 and `SSAMOSWAP.D` (RV64 only) operation +[listing] +---- + if privilege_mode != M && menvcfg.SSE == 0 + raise illegal-instruction exception + else if S-mode not implemented + raise illegal-instruction exception + else if privilege_mode == U && senvcfg.SSE == 0 + raise illegal-instruction exception + else if privilege_mode == VS && henvcfg.SSE == 0 + raise virtual-instruction exception + else if privilege_mode == VU && senvcfg.SSE == 0 + raise virtual-instruction exception + else + X(rd) = mem[X(rs1)] + mem[X(rs1)] = X(rs2) + endif +---- + +[[norm:rv64_ssamoswap-w_op]] +For RV64, `SSAMOSWAP.W` atomically loads a 32-bit data value from address of a +shadow stack location in `rs1`, sign-extends the loaded value and puts it in +`rd`, and stores the lower 32 bits of the value held in `rs2` to the original +address in `rs1`. + +.`SSAMOSWAP.W` for RV64 +[listing] +---- + if privilege_mode != M && menvcfg.SSE == 0 + raise illegal-instruction exception + else if S-mode not implemented + raise illegal-instruction exception + else if privilege_mode == U && senvcfg.SSE == 0 + raise illegal-instruction exception + else if privilege_mode == VS && henvcfg.SSE == 0 + raise virtual-instruction exception + else if privilege_mode == VU && senvcfg.SSE == 0 + raise virtual-instruction exception + else + temp[31:0] = mem[X(rs1)] + X(rd) = SignExtend(temp[31:0]) + mem[X(rs1)] = X(rs2)[31:0] + endif +---- + +[[norm:ssamoswap_address]] +Just as for AMOs in the A extension, `SSAMOSWAP.W/D` requires that the address +held in `rs1` be naturally aligned to the size of the operand (i.e., eight-byte +aligned for __doublewords__, and four-byte aligned for __words__). The same +exception options apply if the address is not naturally aligned. + +Just as for AMOs in the A extension, `SSAMOSWAP.W/D` optionally provides release +consistency semantics, using the `aq` and `rl` bits, to help implement +multiprocessor synchronization. An `SSAMOSWAP.W/D` operation has acquire +semantics if `aq=1` and release semantics if `rl=1`. + +[NOTE] +==== +Stack switching is a common operation in user programs as well as supervisor +programs. When a stack switch is performed the stack pointer of the currently +active stack is saved into a context data structure and the new stack is made +active by loading a new stack pointer from a context data structure. + +When shadow stacks are active for a program, the program needs to additionally +switch the shadow stack pointer. If the pointer to the top of the deactivated +shadow stack is held in a context data structure, then it may be susceptible to +memory corruption vulnerabilities. To protect the pointer value, the program may +store it at the top of the deactivated shadow stack itself and thereby create a +checkpoint. A legal checkpoint is defined as one that holds a value of `X`, +where `X` is the address at which the checkpoint is positioned on the shadow +stack. +==== + +[NOTE] +==== +An example sequence to restore the shadow stack pointer from the new shadow +stack and save the old shadow stack pointer on the old shadow stack is as +follows: + +[listing] +---- +# a0 hold pointer to top of new shadow stack to switch to +stack_switch: + ssrdp ra + beqz ra, 2f # skip if Zicfiss not active + ssamoswap.d ra, x0, (a0) # ra=*[a0] and *[a0]=0 + beq ra, a0, 1f # [a0] must be == [ra] + unimp # else crash +1: addi ra, ra, XLEN/8 # pop the checkpoint + csrrw ra, ssp, ra # swap ssp: ra=ssp, ssp=ra + addi ra, ra, -(XLEN/8) # checkpoint = "old ssp - XLEN/8" + ssamoswap.d x0, ra, (ra) # Save checkpoint at "old ssp - XLEN/8" +2: +---- + +This sequence uses the `ra` register. If the privilege mode at which this +sequence is executed can be interrupted, then the trap handler should save the +`ra` on the shadow stack itself. There it is guarded against tampering and +can be restored prior to returning from the trap. + +When a new shadow stack is created by the supervisor, it needs to store a +checkpoint at the highest address on that stack. This enables the shadow stack +pointer to be switched using the process outlined in this note. The +`SSAMOSWAP.W/D` instruction can be used to store this checkpoint. When the old +value at the memory location operated on by `SSAMOSWAP.W/D` is not required, +`rd` can be set to `x0`. +==== diff --git a/param_extraction/chunks/chunk_056.txt.license b/param_extraction/chunks/chunk_056.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_056.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_057.txt b/param_extraction/chunks/chunk_057.txt new file mode 100644 index 0000000000..1885f30cbb --- /dev/null +++ b/param_extraction/chunks/chunk_057.txt @@ -0,0 +1,3419 @@ +# Chunk: chunk_057 +# Source: v-st-ext.adoc +# Lines: 1-3393 (of 5396) +# Content starts: line 1 +# Line count: 3393 +# Sections: 20 +# == "V" Standard Extension for Vector Operations, Version 1.0 +# === Introduction +# === Implementation-defined Constant Parameters +# === Vector Extension Programmer's Model +# ==== Vector Registers +# ==== Vector Context Status in `mstatus` +# ==== Vector Context Status in `vsstatus` +# ==== Vector Type (`vtype`) Register +# ===== Vector Selected Element Width (`vsew[2:0]`) +# ===== Vector Register Grouping (`vlmul[2:0]`) +# ===== Vector Tail Agnostic and Vector Mask Agnostic `vta` and `vma` +# ===== Vector Type Illegal (`vill`) +# ==== Vector Length (`vl`) Register +# ==== Vector Byte Length (`vlenb`) Register +# ==== Vector Start Index (`vstart`) Register +# ==== Vector Fixed-Point Rounding Mode (`vxrm`) Register +# ==== Vector Fixed-Point Saturation Flag (`vxsat`) +# ==== Vector Control and Status (`vcsr`) Register +# ==== State of Vector Extension at Reset +# === Mapping of Vector Elements to Vector Register State +# +[[vector]] +== "V" Standard Extension for Vector Operations, Version 1.0 + +[NOTE] +==== +_The base vector extension is intended to provide general support for +data-parallel execution within the 32-bit instruction encoding space, +with later vector extensions supporting richer functionality for certain +domains._ +==== + +=== Introduction + +<> lists the standard +vector extensions and which instructions and element widths are +supported by each extension. + +=== Implementation-defined Constant Parameters + +Each hart supporting a vector extension defines two parameters: + +. [#norm:elen_param]#The maximum size in bits of a vector element that any operation can produce or consume, _ELEN_ {ge} 8, which +must be a power of 2.# +. [#norm:vlen_param]#The number of bits in a single vector register, _VLEN_ {ge} ELEN, which must be a power of 2, and must be no greater than 2^16^.# + +Standard vector extensions (<>) and +architecture profiles may set further constraints on _ELEN_ and _VLEN_. + +NOTE: Future extensions may allow ELEN {gt} VLEN by holding one +element using bits from multiple vector registers, but this +extension does not include this option. + +NOTE: The upper limit on VLEN allows software to know that indices +will fit into 16 bits (largest VLMAX of 65,536 occurs for LMUL=8 and +SEW=8 with VLEN=65,536). Any future extension beyond 64Kib per vector +register will require new configuration instructions such that +software using the old configuration instructions does not see greater +vector lengths. + +The vector extension supports writing binary code that under certain +constraints will execute portably on harts with different values for +the VLEN parameter, provided the harts support the required element +types and instructions. + +NOTE: Code can be written that will expose differences in +implementation parameters. + +NOTE: In general, thread contexts with active vector state cannot be +migrated during execution between harts that have any difference in +VLEN or ELEN parameters. + +=== Vector Extension Programmer's Model + +The vector extension adds 32 vector registers, and seven unprivileged +CSRs (`vstart`, `vxsat`, `vxrm`, `vcsr`, `vtype`, `vl`, `vlenb`) to a +base scalar RISC-V ISA. + +.New vector CSRs +[cols="2,2,2,10"] +[%autowidth,float="center",align="center",options="header"] +|=== +| Address | Privilege | Name | Description + +| 0x008 | URW | vstart | Vector start element index +| 0x009 | URW | vxsat | Fixed-Point Saturate Flag +| 0x00A | URW | vxrm | Fixed-Point Rounding Mode +| 0x00F | URW | vcsr | Vector control and status register +| 0xC20 | URO | vl | Vector length +| 0xC21 | URO | vtype | Vector data type register +| 0xC22 | URO | vlenb | VLEN/8 (vector register length in bytes) +|=== + +NOTE: The four CSR numbers `0x00B`-`0x00E` are tentatively reserved +for future vector CSRs, some of which may be mirrored into `vcsr`. + +==== Vector Registers + +[[norm:vreg_count]] +The vector extension adds 32 architectural vector registers, +`v0`-`v31` to the base scalar RISC-V ISA. + +Each vector register has a fixed VLEN bits of state. + +==== Vector Context Status in `mstatus` + +[[norm:mstatus-vs_sstatus-vs_op]] +A vector context status field, `VS`, is added to `mstatus[10:9]` and shadowed +in `sstatus[10:9]`. It is defined analogously to the floating-point context +status field, `FS`. + +[[norm:mstatus-vs_op_off]] +Attempts to execute any vector instruction, or to access the vector +CSRs, raise an illegal-instruction exception when `mstatus.VS` is +set to Off. + +[[norm:mstatus-vs_op_initial_clean]] +When `mstatus.VS` is set to Initial or Clean, executing any +instruction that changes vector state, including the vector CSRs, will +change `mstatus.VS` to Dirty. +Implementations may also change `mstatus.VS` from Initial or Clean to Dirty +at any time, even when there is no change in vector state. + +NOTE: Accurate setting of `mstatus.VS` is an optimization. Software +will typically use VS to reduce context-swap overhead. + +[[norm:mstatus-sd_op]] +If `mstatus.VS` is Dirty, `mstatus.SD` is 1; +otherwise, `mstatus.SD` is set in accordance with existing specifications. + +[#norm:mutable_misa_v_param]#Implementations may have a writable `misa.V` field.# [#norm:mstatus_vs_exists_param]#Analogous to the +way in which the floating-point unit is handled, the `mstatus.VS` +field may exist even if `misa.V` is clear.# + +NOTE: Allowing `mstatus.VS` to exist when `misa.V` is clear, enables +vector emulation and simplifies handling of `mstatus.VS` in systems +with writable `misa.V`. + +==== Vector Context Status in `vsstatus` + +[[norm:vsstatus-vs_sz_acc]] +When the hypervisor extension is present, a vector context status field, `VS`, +is added to `vsstatus[10:9]`. +It is defined analogously to the floating-point context status field, `FS`. + +[[norm:vsstatus-vs_mstatus-vs_op_off]] +When V=1, both `vsstatus.VS` and `mstatus.VS` are in effect: attempts to +execute any vector instruction, or to access the vector CSRs, raise an +illegal-instruction exception when either field is set to Off. + +[#norm:vsstatus-vs_mstatus-vs_op_active]#When V=1 and neither `vsstatus.VS` nor `mstatus.VS` is set to Off, executing +any instruction that changes vector state, including the vector CSRs, will +change both `mstatus.VS` and `vsstatus.VS` to Dirty.# +[#norm:hw_mstatus_vs_dirty_update_param]#Implementations may also change `mstatus.VS` or `vsstatus.VS` from Initial or +Clean to Dirty at any time, even when there is no change in vector state.# + +[[norm:vsstatus-sd_op_vs]] +If `vsstatus.VS` is Dirty, `vsstatus.SD` is 1; +otherwise, `vsstatus.SD` is set in accordance with existing specifications. + +[[norm:mstatus-sd_op_vs]] +If `mstatus.VS` is Dirty, `mstatus.SD` is 1; +otherwise, `mstatus.SD` is set in accordance with existing specifications. + +[[norm:vsstatus_vs_exists_param]] +For implementations with a writable `misa.V` field, +the `vsstatus.VS` field may exist even if `misa.V` is clear. + +==== Vector Type (`vtype`) Register + +[#norm:vtype_sz_acc_op]#The read-only XLEN-wide _vector_ _type_ CSR, `vtype` provides the +default type used to interpret the contents of the vector register +file, and can only be updated by `vset{i}vl{i}` instructions.# The +vector type determines the organization of elements in each +vector register, and how multiple vector registers are grouped. The +`vtype` register also indicates how masked-off elements and elements +past the current vector length in a vector result are handled. + +NOTE: Allowing updates only via the `vset{i}vl{i}` instructions +simplifies maintenance of the `vtype` register state. + +[[norm:vtype-fields_sz]] +The `vtype` register has five fields, `vill`, `vma`, `vta`, +`vsew[2:0]`, and `vlmul[2:0]`. Bits `vtype[XLEN-2:8]` should be +written with zero, and non-zero values in this field are reserved. + +include::images/wavedrom/vtype-format.edn[] + + +NOTE: [#norm:vill_implicit_encoding_param]#A small implementation supporting ELEN=32 requires only seven bits of state in `vtype`: two bits for `ma` and `ta`, two bits for `vsew[1:0]` and three bits for `vlmul[2:0]`. The illegal value represented by `vill` can be internally encoded using the illegal 64-bit combination in `vsew[1:0]` without requiring an additional storage +bit to hold `vill`.# + +NOTE: Further standard and custom vector extensions may extend these +fields to support a greater variety of data types. + +NOTE: The primary motivation for the `vtype` CSR is to allow the +vector instruction set to fit into a 32-bit instruction encoding +space. A separate `vset{i}vl{i}` instruction can be used to set `vl` +and/or `vtype` fields before execution of a vector instruction, and +implementations may choose to fuse these two instructions into a single +internal vector microop. In many cases, the `vl` and `vtype` values +can be reused across multiple instructions, reducing the static and +dynamic instruction overhead from the `vset{i}vl{i}` instructions. It +is anticipated that a future extended 64-bit instruction encoding +would allow these fields to be specified statically in the instruction +encoding. + +===== Vector Selected Element Width (`vsew[2:0]`) +[[norm:vtype-vsew_op]] +The value in `vsew` sets the dynamic _selected_ _element_ _width_ +(SEW). By default, a vector register is viewed as being divided into +VLEN/SEW elements. + +.vsew[2:0] (selected element width) encoding +[cols="1,1,1,1"] +[%autowidth,float="center",align="center",options="header"] +|=== +3+| vsew[2:0] | SEW + +| 0 | 0 | 0 | 8 +| 0 | 0 | 1 | 16 +| 0 | 1 | 0 | 32 +| 0 | 1 | 1 | 64 +| 1 | X | X | Reserved +|=== + +NOTE: [#norm:vtype-vsew_rsv]#While it is anticipated the larger `vsew[2:0]` encodings +(`100`-`111`) will be used to encode larger SEW, the encodings are +formally _reserved_ at this point.# + +.Example VLEN = 128 bits +[cols=">,>"] +[%autowidth,float="center",align="center",options="header"] +|=== +| SEW | Elements per vector register + +| 64 | 2 +| 32 | 4 +| 16 | 8 +| 8 | 16 +|=== + +The supported element width may vary with LMUL. + +NOTE: The current set of standard vector extensions do not vary +supported element width with LMUL. Some future extensions may support +larger SEWs only when bits from multiple vector registers are combined +using LMUL. In this case, software that relies on large SEW should +attempt to use the largest LMUL, and hence the fewest vector register +groups, to increase the number of implementations on which the code +will run. The `vill` bit in `vtype` should be checked after setting +`vtype` to see if the configuration is supported, and an alternate +code path should be provided if it is not. Alternatively, a profile +can mandate the minimum SEW at each LMUL setting. + +[[vector-register-grouping]] +===== Vector Register Grouping (`vlmul[2:0]`) + +Multiple vector registers can be grouped together, so that a single +vector instruction can operate on multiple vector registers. The term +_vector_ _register_ _group_ is used herein to refer to one or more +vector registers used as a single operand to a vector instruction. +Vector register groups can be used to provide greater execution +efficiency for longer application vectors, but the main reason for +their inclusion is to allow double-width or larger elements to be +operated on with the same vector length as single-width elements. The +vector length multiplier, _LMUL_, when greater than 1, represents the +default number of vector registers that are combined to form a vector +register group. [#norm:vtype-lmul_val]#Implementations must support LMUL integer values of +1, 2, 4, and 8.# + + +NOTE: The vector architecture includes instructions that take multiple +source and destination vector operands with different element widths, +but the same number of elements. The effective LMUL (EMUL) of each +vector operand is determined by the number of registers required to +hold the elements. For example, for a widening add operation, such as +add 32-bit values to produce 64-bit results, a double-width result +requires twice the LMUL of the single-width inputs. + +LMUL can also be a fractional value, reducing the number of bits used +in a single vector register. Fractional LMUL is used to increase the +number of effective usable vector register groups when operating on +mixed-width values. + +NOTE: With only integer LMUL values, a loop operating on a range of +sizes would have to allocate at least one whole vector register +(LMUL=1) for the narrowest data type and then would consume multiple +vector registers (LMUL>1) to form a vector register group for each +wider vector operand. This can limit the number of vector register groups +available. With fractional LMUL, the widest values need occupy only a +single vector register while narrower values can occupy a fraction of +a single vector register, allowing all 32 architectural vector +register names to be used for different values in a vector loop even +when handling mixed-width values. Fractional LMUL implies portions of +vector registers are unused, but in some cases, having more shorter +register-resident vectors improves efficiency relative to fewer longer +register-resident vectors. + +[[norm:vtype-lmul_fval]] +Implementations must provide fractional LMUL settings that allow the +narrowest supported type to occupy a fraction of a vector register +corresponding to the ratio of the narrowest supported type's width to +that of the largest supported type's width. In general, the +requirement is to support LMUL {ge} SEW~MIN~/ELEN, where SEW~MIN~ is +the narrowest supported SEW value and ELEN is the widest supported SEW +value. In the standard extensions, SEW~MIN~=8. For +standard vector extensions with ELEN=32, fractional LMULs of 1/2 and +1/4 must be supported. For standard vector extensions with ELEN=64, +fractional LMULs of 1/2, 1/4, and 1/8 must be supported. + +NOTE: When LMUL < SEW~MIN~/ELEN, there is no guarantee +an implementation would have enough bits in the fractional vector +register to store at least one element, as VLEN=ELEN is a +valid implementation choice. For example, with VLEN=ELEN=32, +and SEW~MIN~=8, an LMUL of 1/8 would only provide four bits of +storage in a vector register. + +[[norm:vtype-sew_val]] +For a given supported fractional LMUL setting, implementations must support +SEW settings between SEW~MIN~ and LMUL * ELEN, inclusive. + +[[norm:vtype-lmul_fval_rsv]] +The use of `vtype` encodings with LMUL < SEW~MIN~/ELEN is +__reserved__, but implementations can set `vill` if they do not +support these configurations. + +NOTE: Requiring all implementations to set `vill` in this case would +prohibit future use of this case in an extension, so to allow for a +future definition of LMUL>. + +[[norm:vtype-vta-vma_val]] +All systems must support all four options: + +[cols="1,1,3,3"] +[%autowidth,float="center",align="center",options="header"] +|=== +| `vta` | `vma` | Tail Elements | Inactive Elements + +| 0 | 0 | undisturbed | undisturbed +| 0 | 1 | undisturbed | agnostic +| 1 | 0 | agnostic | undisturbed +| 1 | 1 | agnostic | agnostic +|=== + +[[norm:vreg_mask_tail_agn]] +Mask destination tail elements are always treated as tail-agnostic, +regardless of the setting of `vta`. + +[[norm:vreg_mask_op]] +When a set is marked undisturbed, the corresponding set of destination +elements in a vector register group retain the value they previously +held. + +[[norm:vreg_agnostic_op]] +When a set is marked agnostic, the corresponding set of destination +elements in any vector destination operand can either retain the value +they previously held, or are overwritten with 1s. Within a single vector +instruction, each destination element can be either left undisturbed +or overwritten with 1s, in any combination, and the pattern of +undisturbed or overwritten with 1s is not required to be deterministic +when the instruction is executed with the same inputs. + +NOTE: The agnostic policy was added to accommodate machines with +vector register renaming. With an undisturbed policy, all elements +would have to be read from the old physical destination vector +register to be copied into the new physical destination vector +register. This causes an inefficiency when these inactive or tail +values are not required for subsequent calculations. + +NOTE: The value of all 1s instead of all 0s was chosen for the +overwrite value to discourage software developers from depending on +the value written. + +NOTE: A simple in-order implementation can ignore the settings and +simply execute all vector instructions using the undisturbed +policy. The `vta` and `vma` state bits must still be provided in +`vtype` for compatibility and to support thread migration. + +NOTE: An out-of-order implementation can choose to implement +tail-agnostic + mask-agnostic using tail-agnostic + mask-undisturbed +to reduce implementation complexity. + +NOTE: The definition of agnostic result policy is left loose to +accommodate migrating application threads between harts on a small +in-order core (which probably leaves agnostic regions undisturbed) and +harts on a larger out-of-order core with register renaming (which +probably overwrites agnostic elements with 1s). As it might be +necessary to restart in the middle, we allow arbitrary mixing of +agnostic policies within a single vector instruction. This allowed +mixing of policies also enables implementations that might change +policies for different granules of a vector register, for example, +using undisturbed within a granule that is actively operated on but +renaming to all 1s for granules in the tail. + +[[norm:vreg_mask_tail_op]] +In addition, except for mask load instructions, any element in the +tail of a mask result can also be written with the value the +mask-producing operation would have calculated with `vl`=VLMAX. +Furthermore, for mask-logical instructions and `vmsbf.m`, `vmsif.m`, +`vmsof.m` mask-manipulation instructions, any element in the tail of +the result can be written with the value the mask-producing operation +would have calculated with `vl`=VLEN, SEW=8, and LMUL=8 (i.e., all +bits of the mask register can be overwritten). + +NOTE: Mask tails are always treated as agnostic to reduce complexity +of managing mask data, which can be written at bit granularity. There +appears to be little software need to support tail-undisturbed for +mask register values. Allowing mask-generating instructions to write +back the result of the instruction avoids the need for logic to mask +out the tail, except mask loads cannot write memory values to +destination mask tails as this would imply accessing memory past +software intent. + +The assembly syntax adds two mandatory flags to the `vsetvli` instruction: + +---- + ta # Tail agnostic + tu # Tail undisturbed + ma # Mask agnostic + mu # Mask undisturbed + + vsetvli t0, a0, e32, m4, ta, ma # Tail agnostic, mask agnostic + vsetvli t0, a0, e32, m4, tu, ma # Tail undisturbed, mask agnostic + vsetvli t0, a0, e32, m4, ta, mu # Tail agnostic, mask undisturbed + vsetvli t0, a0, e32, m4, tu, mu # Tail undisturbed, mask undisturbed +---- + +NOTE: Prior to v0.9, when these flags were not specified on a +`vsetvli`, they defaulted to mask-undisturbed/tail-undisturbed. The +use of `vsetvli` without these flags is deprecated, however, and +specifying a flag setting is now mandatory. The default should +perhaps be tail-agnostic/mask-agnostic, so software has to specify +when it cares about the non-participating elements, but given the +historical meaning of the instruction prior to introduction of these +flags, it was decided to always require them in future assembly code. + +===== Vector Type Illegal (`vill`) + +The `vill` bit is used to encode that a previous `vset{i}vl{i}` +instruction attempted to write an unsupported value to `vtype`. + +NOTE: The `vill` bit is held in bit XLEN-1 of the CSR to support +checking for illegal values with a branch on the sign bit. + +[[norm:vtype-vill_op]] +If the `vill` bit is set, then any attempt to execute a vector instruction +that depends upon `vtype` will raise an illegal-instruction exception. + +NOTE: `vset{i}vl{i}` and whole register loads and stores do not depend +upon `vtype`. + +When the `vill` bit is set, the other XLEN-1 bits in `vtype` shall be +zero. + +==== Vector Length (`vl`) Register + +[[norm:vl_acc]] +The _XLEN_-bit-wide read-only `vl` CSR can only be updated by the +`vset{i}vl{i}` instructions, and the _fault-only-first_ vector load +instruction variants. + +[[norm:vl_op]] +The `vl` register holds an unsigned integer specifying the number of +elements to be updated with results from a vector instruction, as +further detailed in <>. + +NOTE: The number of bits implemented in `vl` depends on the +implementation's maximum vector length of the smallest supported +type. The smallest vector implementation with VLEN=32 and supporting +SEW=8 would need at least six bits in `vl` to hold the values 0-32 +(VLEN=32, with LMUL=8 and SEW=8, yields VLMAX=32). + +==== Vector Byte Length (`vlenb`) Register + +[[norm:vlenb_acc_op]] +The _XLEN_-bit-wide read-only CSR `vlenb` holds the value VLEN/8, +i.e., the vector register length in bytes. + +NOTE: The value in `vlenb` is a design-time constant in any +implementation. + +NOTE: Without this CSR, several instructions are needed to calculate +VLEN in bytes, and the code has to disturb current `vl` and `vtype` +settings which require them to be saved and restored. + +==== Vector Start Index (`vstart`) Register +[[norm:vstart_acc_sz]] +The _XLEN_-bit-wide read-write `vstart` CSR specifies the index of the +first element to be executed by a vector instruction, as described in +<>. + +Normally, `vstart` is only written by hardware on a trap on a vector +instruction, with the `vstart` value representing the element on which +the trap was taken (either a synchronous exception or an asynchronous +interrupt), and at which execution should resume after a resumable +trap is handled. + +[#norm:vstart_op]#All vector instructions are defined to begin execution with the +element number given in the `vstart` CSR, leaving earlier elements in +the destination vector undisturbed#, and to [#norm:vstart_update]#reset the `vstart` CSR to +zero at the end of execution.# + +NOTE: All vector instructions, including `vset{i}vl{i}`, reset the `vstart` +CSR to zero. + +[[norm:vstart_unmodified]] +`vstart` is not modified by vector instructions that raise illegal-instruction +exceptions. + +[[norm:vstart_sz_writable]] +The `vstart` CSR is defined to have only enough writable bits to hold +the largest element index (one less than the maximum VLMAX). + +NOTE: The maximum vector length is obtained with the largest LMUL +setting (8) and the smallest SEW setting (8), so VLMAX_max = 8*VLEN/8 = VLEN. For example, for VLEN=256, `vstart` would have 8 bits to +represent indices from 0 through 255. + +[[norm:vstart_val_rsv]] +The use of `vstart` values greater than the largest element index for +the current `vtype` setting is reserved. + +NOTE: It is recommended that implementations trap if `vstart` is out +of bounds. It is not required to trap, as a possible future use of +upper `vstart` bits is to store imprecise trap information. + +The `vstart` CSR is writable by unprivileged code, but non-zero +`vstart` values may cause vector instructions to run substantially +slower on some implementations, so `vstart` should not be used by +application programmers. A few vector instructions cannot be +executed with a non-zero `vstart` value and will raise an +illegal-instruction exception as defined below. + +NOTE: Making `vstart` visible to unprivileged code supports user-level +threading libraries. + +[[norm:vstart_vtype_dep]] +Implementations are permitted to raise illegal-instruction exceptions when +attempting to execute a vector instruction with a value of `vstart` that the +implementation can never produce when executing that same instruction with +the same `vtype` setting. + +NOTE: For example, some implementations will never take interrupts during +execution of a vector arithmetic instruction, instead waiting until the +instruction completes to take the interrupt. Such implementations are +permitted to raise an illegal-instruction exception when attempting to execute +a vector arithmetic instruction when `vstart` is nonzero. + +NOTE: When migrating a software thread between two harts with +different microarchitectures, the `vstart` value might not be +supported by the new hart microarchitecture. The runtime on the +receiving hart might then have to emulate instruction execution up to the +next supported `vstart` element position. Alternatively, migration events +can be constrained to only occur at mutually supported `vstart` +locations. + +==== Vector Fixed-Point Rounding Mode (`vxrm`) Register + +[[norm:vxrm_val_sz_acc]] +The vector fixed-point rounding-mode register holds a two-bit +read-write rounding-mode field in the least-significant bits +(`vxrm[1:0]`). The upper bits, `vxrm[XLEN-1:2]`, should be written as +zeros. + +[[norm:vcsr-vxrm_op]] +The vector fixed-point rounding-mode is given a separate CSR address +to allow independent access, but is also reflected as a field in +`vcsr`. + +NOTE: A new rounding mode can be set while saving the original +rounding mode using a single `csrwi` instruction. + +[[norm:vxrm_op]] +The fixed-point rounding algorithm is specified as follows. +Suppose the pre-rounding result is `v`, and `d` bits of that result are to be +rounded off. +Then the rounded result is `(v >> d) + r`, where `r` depends on the rounding +mode as specified in the following table. + +.vxrm encoding +//[cols="1,1,4,10,5"] +[%autowidth,float="center",align="center",cols="<,<,<,<,<",options="header"] +|=== +2+| `vxrm[1:0]` | Abbreviation | Rounding Mode | Rounding increment, `r` + +| 0 | 0 | rnu | round-to-nearest-up (add +0.5 LSB) | `v[d-1]` +| 0 | 1 | rne | round-to-nearest-even | `v[d-1] & (v[d-2:0]{ne}0 \| v[d])` +| 1 | 0 | rdn | round-down | `0` +| 1 | 1 | rod | round-to-odd (OR bits into LSB, aka "jam") | `!v[d] & v[d-1:0]{ne}0` +|=== + +The rounding functions: +---- +roundoff_unsigned(v, d) = (unsigned(v) >> d) + r +roundoff_signed(v, d) = (signed(v) >> d) + r +---- +are used to represent this operation in the instruction descriptions below. + +==== Vector Fixed-Point Saturation Flag (`vxsat`) + +[[norm:vxsat_op_acc_sz]] +The `vxsat` CSR has a single read-write least-significant bit +(`vxsat[0]`) that indicates if a fixed-point instruction has had to +saturate an output value to fit into a destination format. +Bits `vxsat[XLEN-1:1]` should be written as zeros. + +[[norm:vcsr-vxsat_op]] +The `vxsat` bit is mirrored in `vcsr`. + +==== Vector Control and Status (`vcsr`) Register + +[[norm:vcsr-vxrm-vxsat_acc]] +The `vxrm` and `vxsat` separate CSRs can also be accessed via fields +in the _XLEN_-bit-wide vector control and status CSR, `vcsr`. + +.vcsr layout +[cols=">2,4,10"] +[%autowidth,float="center",align="center",options="header"] +|=== +| Bits | Name | Description + +| XLEN-1:3 | | Reserved +| 2:1 | vxrm[1:0] | Fixed-point rounding mode +| 0 | vxsat | Fixed-point accrued saturation flag +|=== + +==== State of Vector Extension at Reset + +The vector extension must have a consistent state at reset. In +particular, `vtype` and `vl` must have values that can be read and +then restored with a single `vsetvl` instruction. + +NOTE: It is recommended that at reset, `vtype.vill` is set, the +remaining bits in `vtype` are zero, and `vl` is set to zero. + +The `vstart`, `vxrm`, `vxsat` CSRs can have arbitrary values at reset. + +NOTE: Most uses of the vector unit will require an initial `vset{i}vl{i}`, +which will reset `vstart`. The `vxrm` and `vxsat` fields should be +reset explicitly in software before use. + +The vector registers can have arbitrary values at reset. + +=== Mapping of Vector Elements to Vector Register State + +The following diagrams illustrate how different width elements are +packed into the bytes of a vector register depending on the current +SEW and LMUL settings, as well as implementation VLEN. Elements are +packed into each vector register with the least-significant byte in +the lowest-numbered bits. + +The mapping was chosen to provide the simplest and most portable model +for software, but might appear to incur large wiring cost for wider +vector datapaths on certain operations. The vector instruction set +was expressly designed to support implementations that internally +rearrange vector data for different SEW to reduce datapath wiring +costs, while externally preserving the simple software model. + +NOTE: For example, microarchitectures can track the EEW with which a +vector register was written, and then insert additional scrambling +operations to rearrange data if the register is accessed with a +different EEW. + +==== Mapping for LMUL = 1 + +[[norm:vreg_lmul1_op]] +When LMUL=1, elements are simply packed in order from the +least-significant to most-significant bits of the vector register. + +NOTE: To increase readability, vector register layouts are drawn with +bytes ordered from right to left with increasing byte address. Bits +within an element are numbered in a little-endian format with +increasing bit index from right to left corresponding to increasing +magnitude. + +---- +LMUL=1 examples. + +The element index is given in hexadecimal and is shown placed at the +least-significant byte of the stored element. + + + VLEN=32b + + Byte 3 2 1 0 + + SEW=8b 3 2 1 0 + SEW=16b 1 0 + SEW=32b 0 + + VLEN=64b + + Byte 7 6 5 4 3 2 1 0 + + SEW=8b 7 6 5 4 3 2 1 0 + SEW=16b 3 2 1 0 + SEW=32b 1 0 + SEW=64b 0 + + VLEN=128b + + Byte F E D C B A 9 8 7 6 5 4 3 2 1 0 + + SEW=8b F E D C B A 9 8 7 6 5 4 3 2 1 0 + SEW=16b 7 6 5 4 3 2 1 0 + SEW=32b 3 2 1 0 + SEW=64b 1 0 + + VLEN=256b + + Byte 1F1E1D1C1B1A19181716151413121110 F E D C B A 9 8 7 6 5 4 3 2 1 0 + + SEW=8b 1F1E1D1C1B1A19181716151413121110 F E D C B A 9 8 7 6 5 4 3 2 1 0 + SEW=16b F E D C B A 9 8 7 6 5 4 3 2 1 0 + SEW=32b 7 6 5 4 3 2 1 0 + SEW=64b 3 2 1 0 +---- + +==== Mapping for LMUL < 1 + +[[norm:vreg_flmul_op]] +When LMUL < 1, only the first LMUL*VLEN/SEW elements in the vector +register are used. The remaining space in the vector register is +treated as part of the tail, and hence must obey the vta setting. + +---- + Example, VLEN=128b, LMUL=1/4 + + Byte F E D C B A 9 8 7 6 5 4 3 2 1 0 + + SEW=8b - - - - - - - - - - - - 3 2 1 0 + SEW=16b - - - - - - 1 0 + SEW=32b - - - 0 +---- + +==== Mapping for LMUL > 1 + +[[norm:vreg_lmulge2_op]] +When vector registers are grouped, the elements of the vector register +group are packed contiguously in element order beginning with the +lowest-numbered vector register and moving to the +next-highest-numbered vector register in the group once each vector +register is filled. + +---- + LMUL > 1 examples + + VLEN=32b, SEW=8b, LMUL=2 + + Byte 3 2 1 0 + v2*n 3 2 1 0 + v2*n+1 7 6 5 4 + + VLEN=32b, SEW=16b, LMUL=2 + + Byte 3 2 1 0 + v2*n 1 0 + v2*n+1 3 2 + + VLEN=32b, SEW=16b, LMUL=4 + + Byte 3 2 1 0 + v4*n 1 0 + v4*n+1 3 2 + v4*n+2 5 4 + v4*n+3 7 6 + + VLEN=32b, SEW=32b, LMUL=4 + + Byte 3 2 1 0 + v4*n 0 + v4*n+1 1 + v4*n+2 2 + v4*n+3 3 + + VLEN=64b, SEW=32b, LMUL=2 + + Byte 7 6 5 4 3 2 1 0 + v2*n 1 0 + v2*n+1 3 2 + + VLEN=64b, SEW=32b, LMUL=4 + + Byte 7 6 5 4 3 2 1 0 + v4*n 1 0 + v4*n+1 3 2 + v4*n+2 5 4 + v4*n+3 7 6 + + VLEN=128b, SEW=32b, LMUL=2 + + Byte F E D C B A 9 8 7 6 5 4 3 2 1 0 + v2*n 3 2 1 0 + v2*n+1 7 6 5 4 + + VLEN=128b, SEW=32b, LMUL=4 + + Byte F E D C B A 9 8 7 6 5 4 3 2 1 0 + v4*n 3 2 1 0 + v4*n+1 7 6 5 4 + v4*n+2 B A 9 8 + v4*n+3 F E D C +---- + +[[sec-mapping-mixed]] +==== Mapping across Mixed-Width Operations + +The vector ISA is designed to support mixed-width operations without +requiring additional explicit rearrangement instructions. The +recommended software strategy when operating on multiple vectors with +different precision values is to modify `vtype` dynamically to keep +SEW/LMUL constant (and hence VLMAX constant). + +The following example shows four different packed element widths (8b, +16b, 32b, 64b) in a VLEN=128b implementation. The vector register +grouping factor (LMUL) is increased by the relative element size such +that each group can hold the same number of vector elements (VLMAX=8 +in this example) to simplify strip-mining code. + +---- +Example VLEN=128b, with SEW/LMUL=16 + +Byte F E D C B A 9 8 7 6 5 4 3 2 1 0 +vn - - - - - - - - 7 6 5 4 3 2 1 0 SEW=8b, LMUL=1/2 + +vn 7 6 5 4 3 2 1 0 SEW=16b, LMUL=1 + +v2*n 3 2 1 0 SEW=32b, LMUL=2 +v2*n+1 7 6 5 4 + +v4*n 1 0 SEW=64b, LMUL=4 +v4*n+1 3 2 +v4*n+2 5 4 +v4*n+3 7 6 +---- + +The following table shows each possible constant SEW/LMUL operating +point for loops with mixed-width operations. Each column represents a +constant SEW/LMUL operating point. Entries in table are the LMUL +values that yield that column's SEW/LMUL value for the data width on +that row. In each column, an LMUL setting for a data width indicates +that it can be aligned with the other data widths in the same column +that also have an LMUL setting, such that all have the same VLMAX. + +|=== +| 7+^| SEW/LMUL +| | 1 | 2 | 4 | 8 | 16 | 32 | 64 + +| SEW= 8 | 8 | 4 | 2 | 1 | 1/2 | 1/4 | 1/8 +| SEW= 16 | | 8 | 4 | 2 | 1 | 1/2 | 1/4 +| SEW= 32 | | | 8 | 4 | 2 | 1 | 1/2 +| SEW= 64 | | | | 8 | 4 | 2 | 1 +|=== + +Larger LMUL settings can also used to simply increase vector length to +reduce instruction fetch and dispatch overheads in cases where fewer +vector register groups are needed. + +[[sec-mask-register-layout]] +==== Mask Register Layout + +[[norm:vreg_mask_vtype_indp]] +A vector mask occupies only one vector register regardless of SEW and +LMUL. + +[[norm:vreg_mask_sz]] +Each element is allocated a single mask bit in a mask vector register. +The mask bit for element _i_ is located in bit _i_ of the mask +register, independent of SEW or LMUL. + +=== Vector Instruction Formats + +The instructions in the vector extension fit under two existing major +opcodes (LOAD-FP and STORE-FP) and one new major opcode (OP-V). + +Vector loads and stores are encoded within the scalar floating-point +load and store major opcodes (LOAD-FP/STORE-FP). The vector load and +store encodings repurpose a portion of the standard scalar +floating-point load/store 12-bit immediate field to provide further +vector instruction encoding, with bit 25 holding the standard vector +mask bit (see <>). + +include::images/wavedrom/vmem-format.edn[] + +include::images/wavedrom/valu-format.edn[] + +include::images/wavedrom/vcfg-format.edn[] + +Vector instructions can have scalar or vector source operands and +produce scalar or vector results, and most vector instructions can be +performed either unconditionally or conditionally under a mask. + +Vector loads and stores move bit patterns between vector register +elements and memory. Vector arithmetic instructions operate on values +held in vector register elements. + +==== Scalar Operands + +Scalar operands can be immediates, or taken from the `x` registers, +the `f` registers, or element 0 of a vector register. Scalar results +are written to an `x` or `f` register or to element 0 of a vector +register. [#norm:vreg_scalar_lmul_indp]#Any vector register can be used to hold a scalar regardless +of the current LMUL setting.# + +NOTE: Zfinx ("F in X") is a new ISA extension where +floating-point instructions take their arguments from the integer +register file. The vector extension is also compatible with Zfinx, +where the Zfinx vector extension has vector-scalar floating-point +instructions taking their scalar argument from the `x` registers. + +NOTE: We considered but did not pursue overlaying the `f` registers on +`v` registers. The adopted approach reduces vector register pressure, +avoids interactions with the standard calling convention, simplifies +high-performance scalar floating-point design, and provides +compatibility with the Zfinx ISA option. Overlaying `f` with `v` +would provide the advantage of lowering the number of state bits in +some implementations, but complicates high-performance designs and +would prevent compatibility with the Zfinx ISA option. + +[[sec-vec-operands]] +==== Vector Operands + +[[norm:eew_emul]] +Each vector operand has an _effective_ _element_ _width_ (EEW) and an +_effective_ LMUL (EMUL) that is used to determine the size and +location of all the elements within a vector register group. By +default, for most operands of most instructions, EEW=SEW and +EMUL=LMUL. + +Some vector instructions have source and destination vector operands +with the same number of elements but different widths, so that EEW and +EMUL differ from SEW and LMUL respectively but [#norm:eew_emul_sew_lmul_dep]#EEW/EMUL = SEW/LMUL.# +For example, most widening arithmetic instructions have a source group +with EEW=SEW and EMUL=LMUL but have a destination group with EEW=2*SEW and +EMUL=2*LMUL. [#norm:vnarrowing_eew_emul]#Narrowing instructions have a source operand that has +EEW=2*SEW and EMUL=2*LMUL but with a destination where EEW=SEW and EMUL=LMUL.# + +Vector operands or results may occupy one or more vector registers +depending on EMUL, but are always specified using the lowest-numbered +vector register in the group. [#norm:emul_offgroup_rsv]#Using other than the lowest-numbered +vector register to specify a vector register group is a reserved +encoding.# + +[[norm:vreg_source_eew_rsv]] +A vector register cannot be used to provide source operands with more +than one EEW for a single instruction. A mask register source is +considered to have EEW=1 for this constraint. An encoding that would +result in the same vector register being read with two or more +different EEWs, including when the vector register appears at +different positions within two or more vector register groups, is +reserved. + +NOTE: In practice, there is no software benefit to reading the same +register with different EEW in the same instruction, and this +constraint reduces complexity for implementations that internally +rearrange data dependent on EEW. + +[[norm:vreg_overlap_legal]] +A destination vector register group can overlap a source vector register +group only if one of the following holds: + +- The destination EEW equals the source EEW. +- The destination EEW is smaller than the source EEW, and the lowest-numbered + register in the destination vector register group is the same as the the + lowest-numbered register in the source vector register group. + (For example, when LMUL=1, + `vnsrl.wi v0, v0, 3` is legal, but a destination of `v1` is not). +- The destination EEW is greater than the source EEW, the source EMUL is + at least 1, and the highest-numbered register in the destination + vector register group is the same as the highest-numbered register in + the source vector register group. + (For example, when LMUL=8, `vzext.vf4 v0, v6` is legal, + but a source of `v0`, `v2`, or `v4` is not). + +[[norm:vreg_mask_overlap]] +For the purpose of determining register group overlap constraints, +mask elements have EEW=1. + +NOTE: The overlap constraints are designed to support resumable +exceptions in machines without register renaming. + +[[norm:vreg_overlap_rsv]] +Any instruction encoding that violates the overlap constraints is reserved. + +[[norm:vreg_overlap_agn]] +When source and destination registers overlap and have different EEW, the +instruction is mask- and tail-agnostic, regardless of the setting of the +`vta` and `vma` bits in `vtype`. + +[[norm:emul_rsv]] +The largest vector register group used by an instruction can not be +greater than 8 vector registers (i.e., EMUL{le}8), and if a vector +instruction would require greater than 8 vector registers in a group, +the instruction encoding is reserved. For example, a widening +operation that produces a widened vector register group result when +LMUL=8 is reserved as this would imply a result EMUL=16. + +[[norm:vreg_scalar_emul]] +Widened scalar values, e.g., input and output to a widening reduction +operation, are held in the first element of a vector register and +have EMUL=1. + +==== Vector Masking + +Masking is supported on many vector instructions. [#norm:vmask_inactive_op]#Element operations +that are masked off (inactive) never generate exceptions.# [#norm:vmask_agn_op]#The +destination vector register elements corresponding to masked-off +elements are handled with either a mask-undisturbed or mask-agnostic +policy depending on the setting of the `vma` bit in `vtype`# +(<>). + +[[norm:vreg_vmask]] +The mask value used to control execution of a masked vector +instruction is always supplied by vector register `v0`. + +NOTE: Masks are held in vector registers, rather than in a separate mask +register file, to reduce total architectural state and to simplify the ISA. + +NOTE: Future vector extensions may provide longer instruction +encodings with space for a full mask register specifier. + +[[norm:vreg_vmask_rsv]] +The destination vector register group for a masked vector instruction +cannot overlap the source mask register (`v0`), unless the destination +vector register is being written with a mask value (e.g., compares) +or the scalar result of a reduction. These instruction encodings are +reserved. + +NOTE: This constraint supports restart with a non-zero `vstart` value. + +Other vector registers can be used to hold working mask values, and +mask vector logical operations are provided to perform predicate +calculations. [[sec-mask-vector-logical]] + +As specified in <>, mask destination tail elements are +always treated as tail-agnostic, regardless of the setting of `vta`. + +[[sec-vector-mask-encoding]] +===== Mask Encoding + +[[norm:vmask_vm_enc]] +Where available, masking is encoded in a single-bit `vm` field in the + instruction (`inst[25]`). + +[cols="1,15"] +|=== +| vm | Description + +| 0 | vector result, only where v0.mask[i] = 1 +| 1 | unmasked +|=== + +Vector masking is represented in assembler code as another vector +operand, with `.t` indicating that the operation occurs when +`v0.mask[i]` is `1` (`t` for "true"). If no masking operand is +specified, unmasked vector execution (`vm=1`) is assumed. + +---- + vop.v* v1, v2, v3, v0.t # enabled where v0.mask[i]=1, vm=0 + vop.v* v1, v2, v3 # unmasked vector operation, vm=1 +---- + +NOTE: Even though the current vector extensions only support one vector +mask register `v0` and only the true form of predication, the assembly +syntax writes it out in full to be compatible with future extensions +that might add a mask register specifier and support both true and +complement mask values. The `.t` suffix on the masking operand also helps +to visually encode the use of a mask. + +NOTE: The `.mask` suffix is not part of the assembly syntax. +We only append it in contexts where a mask vector is subscripted, +e.g., `v0.mask[i]`. + +[[sec-inactive-defs]] +==== Prestart, Active, Inactive, Body, and Tail Element Definitions + +The destination element indices operated on during a vector +instruction's execution can be divided into three disjoint subsets. + +* The _prestart_ elements are those whose element index is less than the +initial value in the `vstart` register. [#norm:vector_prestart_element]#The prestart elements do not raise exceptions and do not update the destination vector register.# + +* The _body_ elements are those whose element index is greater than or equal +to the initial value in the `vstart` register, and less than the current +vector length setting in `vl`. The body can be split into two disjoint subsets: + +** The _active_ elements during a vector instruction's execution are the +elements within the body and where the current mask is enabled at that element +position. [#norm:vector_active_element]#The active elements can raise exceptions and update the destination vector register group.# + +** The _inactive_ elements are the elements within the body +but where the current mask is disabled at that element +position. [#norm:vector_inactive_element]#The inactive elements do not raise exceptions and do not update any destination vector register group unless masked agnostic is specified (`vtype.vma`=1), in which case inactive elements may be overwritten with 1s.# + +* The _tail_ elements during a vector instruction's execution are the +elements past the current vector length setting specified in `vl`. +[#norm:vector_tail_element]#The tail elements do not raise exceptions, and do not update any destination vector register group unless tail agnostic is specified (`vtype.vta`=1), in which case tail elements may be overwritten with 1s, or with the result of the instruction in the case of mask-producing instructions except for mask loads. When LMUL < 1, the tail includes the elements past VLMAX that are held in the same vector register.# + +---- + for element index x + prestart(x) = (0 <= x < vstart) + body(x) = (vstart <= x < vl) + tail(x) = (vl <= x < max(VLMAX,VLEN/SEW)) + mask(x) = unmasked || v0.mask[x] == 1 + active(x) = body(x) && mask(x) + inactive(x) = body(x) && !mask(x) +---- + +[[norm:vstart_vl_dep]] +When `vstart` {ge} `vl`, there are no body elements, and no elements +are updated in any destination vector register group, including that +no tail elements are updated with agnostic values. + +NOTE: As a consequence, when `vl`=0, no elements, including agnostic +elements, are updated in the destination vector register group +regardless of `vstart`. + +[[norm:vstart_vl_scalar_indp]] +Instructions that write an `x` register or `f` register +do so even when `vstart` {ge} `vl`, including when `vl`=0. + +NOTE: Some instructions such as `vslidedown` and `vrgather` may read +indices past `vl` or even VLMAX in source vector register groups. The +general policy is to return the value 0 when the index is greater than +VLMAX in the source vector register group. + +[[sec-vector-config]] +=== Configuration-Setting Instructions (`vsetvli`/`vsetivli`/`vsetvl`) + +One of the common approaches to handling a large number of elements is +"strip mining" where each iteration of a loop handles some number of elements, +and the iterations continue until all elements have been processed. The RISC-V +vector specification provides direct, portable support for this approach. +The application specifies the total number of elements to be processed (the application vector length or AVL) as a +candidate value for `vl`, and the hardware responds via a general-purpose +register with the (frequently smaller) number of elements that the hardware +will handle per iteration (stored in `vl`), based on the microarchitectural +implementation and the `vtype` setting. A straightforward loop structure, +shown in <>, depicts the ease with which the code keeps +track of the remaining number of elements and the amount per iteration handled +by hardware. + +A set of instructions is provided to allow rapid configuration of the +values in `vl` and `vtype` to match application needs. [#norm:vset_op]#The +`vset{i}vl{i}` instructions set the `vtype` and `vl` CSRs based on +their arguments, and write the new value of `vl` into `rd`.# + +---- + vsetvli rd, rs1, vtypei # rd = new vl, rs1 = AVL, vtypei = new vtype setting + vsetivli rd, uimm, vtypei # rd = new vl, uimm = AVL, vtypei = new vtype setting + vsetvl rd, rs1, rs2 # rd = new vl, rs1 = AVL, rs2 = new vtype value +---- + +include::images/wavedrom/vcfg-format.edn[] + +==== `vtype` encoding + +include::images/wavedrom/vtype-format.edn[] + +[[norm:vtype_acc]] +The new `vtype` value is encoded in the immediate fields of `vsetvli` +and `vsetivli`, and in the `rs2` register for `vsetvl`. + +---- + Suggested assembler names used for vset{i}vli vtypei immediate + + e8 # SEW=8b + e16 # SEW=16b + e32 # SEW=32b + e64 # SEW=64b + + mf8 # LMUL=1/8 + mf4 # LMUL=1/4 + mf2 # LMUL=1/2 + m1 # LMUL=1 + m2 # LMUL=2 + m4 # LMUL=4 + m8 # LMUL=8 + +Examples: + vsetvli t0, a0, e8, m1, ta, ma # SEW= 8, LMUL=1 + vsetvli t0, a0, e8, m2, ta, ma # SEW= 8, LMUL=2 + vsetvli t0, a0, e32, mf2, ta, ma # SEW=32, LMUL=1/2 +---- + +The `vsetvl` variant operates similarly to `vsetvli` except that it +takes a `vtype` value from `rs2` and can be used for context restore. + +===== Unsupported `vtype` Values + +[#norm:vtype-vill_val]#If the `vtype` value is not supported by the implementation, then +the `vill` bit is set in `vtype`, the remaining bits in `vtype` are +set to zero#, and [#norm:vtype-vstart_op]#the `vl` register is also set to zero.# + +NOTE: Earlier drafts required a trap when setting `vtype` to an +illegal value. However, this would have added the first +data-dependent trap on a CSR write to the ISA. Implementations could +choose to trap when illegal values are written to `vtype` instead of +setting `vill`, to allow emulation to support new configurations for +forward-compatibility. The current scheme supports light-weight +runtime interrogation of the supported vector unit configurations by +checking if `vill` is clear for a given setting. + +[[norm:vtype-vill_val_vill]] +A `vtype` value with `vill` set is treated as an unsupported +configuration. + +[[norm:vtype-vill_all_bits]] +Implementations must consider all bits of the `vtype` value to +determine if the configuration is supported. An unsupported value in +any location within the `vtype` value must result in `vill` being set. + +NOTE: In particular, all XLEN bits of the register `vtype` argument to +the `vsetvl` instruction must be checked. Implementations cannot +ignore fields they do not implement. All bits must be checked to +ensure that new code assuming unsupported vector features in `vtype` +traps instead of executing incorrectly on an older implementation. + +==== AVL encoding + +The new vector +length setting is based on AVL, which for `vsetvli` and `vsetvl` is encoded in the `rs1` and `rd` +fields as follows: + +.AVL used in `vsetvli` and `vsetvl` instructions +[cols="2,2,10,10"] +[%autowidth,float="center",align="center",options="header"] +|=== +| `rd` | `rs1` | AVL value | Effect on `vl` +| - | !x0 | Value in `x[rs1]` | Normal strip mining +| !x0 | x0 | ~0 | Set `vl` to VLMAX +| x0 | x0 | Value in `vl` register | Keep existing `vl` (of course, `vtype` may change) +|=== + +[[norm:vsetvl_op]] +When _rs1_ is not `x0`, the AVL is an unsigned integer held in the `x` +register specified by _rs1_, and the new `vl` value is also written to +the `x` register specified by _rd_. + +[[norm:vsetvl_op_rs1_x0_rd_nx0]] +When _rs1_=`x0` but _rd_≠`x0`, the maximum unsigned integer value (`~0`) +is used as the AVL, and the resulting VLMAX is written to `vl` and +also to the `x` register specified by `rd`. + +[#norm:vsetvl_op_rs1_x0_rd_x0]#When _rs1_=`x0` and _rd_=`x0`, the instructions operate as if the current vector length in `vl` is used as the AVL, and the resulting value is written to `vl`, but not to a destination register. This form can only be used when VLMAX and hence `vl` is not actually changed by the new SEW/LMUL ratio.# [#norm:vtype_vset_rsv]#Use of the instructions with a new SEW/LMUL ratio that would result in a change of VLMAX is reserved. Use of the instructions is also reserved if `vill` was 1 beforehand.# [#norm:reserved_vill_set_param]#Implementations may set `vill` in either case.# + +NOTE: This last form of the instructions allows the `vtype` register to +be changed while maintaining the current `vl`, provided VLMAX is not +reduced. This design was chosen to ensure `vl` would always hold a +legal value for current `vtype` setting. The current `vl` value can +be read from the `vl` CSR. The `vl` value could be reduced by these +instructions if the new SEW/LMUL ratio causes VLMAX to shrink, and so +this case has been reserved as it is not clear this is a generally +useful operation, and implementations can otherwise assume `vl` is not +changed by these instructions to optimize their microarchitecture. + +[[norm:vsetivli_op]] +For the `vsetivli` instruction, the AVL is encoded as a 5-bit +zero-extended immediate (0--31) in the `rs1` field. + +NOTE: The encoding of AVL for `vsetivli` is the same as for regular +CSR immediate values. + +NOTE: The `vsetivli` instruction provides more compact code when the +dimensions of vectors are small and known to fit inside the vector +registers, in which case there is no strip-mining overhead. + +[[constraints-on-setting-vl]] +==== Constraints on Setting `vl` + +[[norm:vl_val_lead-in]] +The `vset{i}vl{i}` instructions first set VLMAX according to their `vtype` +argument, then set `vl` obeying the following constraints: + +[[norm:vl_val_list]] +. `vl = AVL` if `AVL {le} VLMAX` +. `ceil(AVL / 2) {le} vl {le} VLMAX` if `AVL < (2 * VLMAX)` +. `vl = VLMAX` if `AVL {ge} (2 * VLMAX)` +. Deterministic on any given implementation for same input AVL and VLMAX values +. These specific properties follow from the prior rules: +.. `vl = 0` if `AVL = 0` +.. `vl > 0` if `AVL > 0` +.. `vl {le} VLMAX` +.. `vl {le} AVL` +.. a value read from `vl` when used as the AVL argument to `vset{i}vl{i}` results in the same +value in `vl`, provided the resultant VLMAX equals the value of VLMAX at the time that `vl` was read + +[NOTE] +-- +The `vl` setting rules are designed to be sufficiently strict to +preserve `vl` behavior across register spills and context swaps for +`AVL {le} VLMAX`, yet flexible enough to enable implementations to improve +vector lane utilization for `AVL > VLMAX`. + +For example, this permits an implementation to set `vl = ceil(AVL / 2)` +for `VLMAX < AVL < 2*VLMAX` in order to evenly distribute work over the +last two iterations of a strip-mine loop. +Requirement 2 ensures that the first strip-mine iteration of reduction +loops uses the largest vector length of all iterations, even in the case +of `AVL < 2*VLMAX`. +This allows software to avoid needing to explicitly calculate a running +maximum of vector lengths observed during a strip-mined loop. +Requirement 2 also allows an implementation to set vl to VLMAX for `VLMAX < AVL < 2*VLMAX` +-- + +[[example-stripmine-sew]] +==== Example of strip mining and changes to SEW + +The SEW and LMUL settings can be changed dynamically to provide high +throughput on mixed-width operations in a single loop. +---- +# Example: Load 16-bit values, widen multiply to 32b, shift 32b result +# right by 3, store 32b values. +# On entry: +# a0 holds the total number of elements to process +# a1 holds the address of the source array +# a2 holds the address of the destination array + +loop: + vsetvli a3, a0, e16, m4, ta, ma # vtype = 16-bit integer vectors; + # also update a3 with vl (# of elements this iteration) + vle16.v v4, (a1) # Get 16b vector + slli t1, a3, 1 # Multiply # elements this iteration by 2 bytes/source element + add a1, a1, t1 # Bump pointer + vwmul.vx v8, v4, x10 # Widening multiply into 32b in + + vsetvli x0, x0, e32, m8, ta, ma # Operate on 32b values + vsrl.vi v8, v8, 3 + vse32.v v8, (a2) # Store vector of 32b elements + slli t1, a3, 2 # Multiply # elements this iteration by 4 bytes/destination element + add a2, a2, t1 # Bump pointer + sub a0, a0, a3 # Decrement count by vl + bnez a0, loop # Any more? +---- + +[[sec-vector-memory]] +=== Vector Loads and Stores + +Vector loads and stores move values between vector registers and +memory. +Vector loads and stores can be masked, and they only access memory or raise +exceptions for active elements. +Masked vector loads do not update inactive elements in the destination vector +register group, unless masked agnostic is specified (`vtype.vma`=1). +[[norm:vector_ls_vstart_param]] +All vector loads and stores may +generate and accept a non-zero `vstart` value. + +==== Vector Load/Store Instruction Encoding + +Vector loads and stores are encoded within the scalar floating-point +load and store major opcodes (LOAD-FP/STORE-FP). The vector load and +store encodings repurpose a portion of the standard scalar +floating-point load/store 12-bit immediate field to provide further +vector instruction encoding, with bit 25 holding the standard vector +mask bit (see <>). + +include::images/wavedrom/vmem-format.edn[] + +[cols="4,12"] +|=== +| Field | Description + +| rs1[4:0] | specifies x register holding base address +| rs2[4:0] | specifies x register holding stride +| vs2[4:0] | specifies v register holding address offsets +| vs3[4:0] | specifies v register holding store data +| vd[4:0] | specifies v register destination of load +| vm | specifies whether vector masking is enabled (0 = mask enabled, 1 = mask disabled) +| width[2:0] | specifies size of memory elements, and distinguishes from FP scalar +| mew | extended memory element width. See <> +| mop[1:0] | specifies memory addressing mode +| nf[2:0] | specifies the number of fields in each segment, for segment load/stores +| lumop[4:0]/sumop[4:0] | are additional fields encoding variants of unit-stride instructions +|=== + +[#norm:vector_ls_strided_eew]#Vector memory unit-stride and constant-stride operations directly encode EEW of the data to be transferred statically in the instruction to reduce the number of `vtype` changes when accessing memory in a mixed-width routine.# [#norm:vector_ls_indexed_eew]#Indexed operations use the explicit EEW encoding in the instruction to set the size of the indices used, and use SEW/LMUL to specify the data width.# + +==== Vector Load/Store Addressing Modes + +The vector extension supports unit-stride, constant-stride, and +indexed (scatter/gather) addressing modes. [#norm:vector_ls_base_stride_regtype]#Vector load/store base +registers and strides are taken from the GPR `x` registers.# + +[[norm:vector_ls_base]] +The base effective address for all vector accesses is given by the +contents of the `x` register named in `rs1`. + +[[norm:vector_ls_unit-stride_op]] +Vector unit-stride operations access elements stored contiguously in +memory starting from the base effective address. + +[[norm:vector_ls_constant-stride_op]] +Vector constant-stride operations access the first memory element at the base +effective address, and then access subsequent elements at address +increments given by the byte offset contained in the `x` register +specified by `rs2`. + +[[norm:vector_ls_indexed_op]] +Vector indexed operations add the contents of each element of the +vector offset operand specified by `vs2` to the base effective address +to give the effective address of each element. The data vector +register group has EEW=SEW, EMUL=LMUL, while the offset vector +register group has EEW encoded in the instruction and +EMUL=(EEW/SEW)*LMUL. + +[[norm:vector_ls_bytewise]] +The vector offset operand is treated as a vector of byte-address +offsets. + +NOTE: The indexed operations can also be used to access fields within +a vector of objects, where the `vs2` vector holds pointers to the base +of the objects and the scalar `x` register holds the offset of the +member field in each object. Supporting this case is why the indexed +operations were not defined to scale the element indices by the data +EEW. + +[[norm:vector_ls_xlen_dep]] +If the vector offset elements are narrower than XLEN, they are +zero-extended to XLEN before adding to the base effective address. If +the vector offset elements are wider than XLEN, the least-significant +XLEN bits are used in the address calculation. +[[norm:vector_ls_eew_rsv]] +If the implementation does not support the EEW of the offset elements, +the instruction is reserved. + +NOTE: A profile may place an upper limit on the maximum supported index +EEW (e.g., only up to XLEN) smaller than ELEN. + +The vector addressing modes are encoded using the 2-bit `mop[1:0]` +field. + +.encoding for loads +[cols="1,1,7,6"] +|=== +2+| mop [1:0] | Description | Opcodes + +| 0 | 0 | unit-stride | VLE +| 0 | 1 | indexed-unordered | VLUXEI +| 1 | 0 | constant-stride | VLSE +| 1 | 1 | indexed-ordered | VLOXEI +|=== + +.encoding for stores +[cols="1,1,7,6"] +|=== +2+| mop [1:0] | Description | Opcodes + +| 0 | 0 | unit-stride | VSE +| 0 | 1 | indexed-unordered | VSUXEI +| 1 | 0 | constant-stride | VSSE +| 1 | 1 | indexed-ordered | VSOXEI +|=== + +[[norm:vector_ls_stride_ordered_op]] +Vector unit-stride and constant-stride memory accesses do not +guarantee ordering between individual element accesses. The vector +indexed load and store memory operations have two forms, ordered and +unordered. The indexed-ordered variants preserve element ordering on +memory accesses. + +[[norm:vector_ls_stride_unordered_op]] +For unordered instructions (`mop[1:0]`!=11) there is no guarantee on +element access order. If the accesses are to a strongly ordered IO +region, the element accesses can be initiated in any order. + +NOTE: To provide ordered vector accesses to a strongly ordered IO +region, the ordered indexed instructions should be used. + +[[norm:vector_ls_stride_unordered_precise]] +For implementations with precise vector traps, exceptions on +indexed-unordered stores must also be precise. + +Additional unit-stride vector addressing modes are encoded using the +5-bit `lumop` and `sumop` fields in the unit-stride load and store +instruction encodings respectively. + +.lumop +[cols="1,1,1,1,1,11"] +|=== +5+| lumop[4:0] | Description + +| 0 | 0 | 0 | 0 | 0 | unit-stride load +| 0 | 1 | 0 | 0 | 0 | unit-stride, whole register load +| 0 | 1 | 0 | 1 | 1 | unit-stride, mask load, EEW=8 +| 1 | 0 | 0 | 0 | 0 | unit-stride fault-only-first +| x | x | x | x | x | other encodings reserved +|=== + +.sumop +[cols="1,1,1,1,1,11"] +|=== +5+| sumop[4:0] | Description + +| 0 | 0 | 0 | 0 | 0 | unit-stride store +| 0 | 1 | 0 | 0 | 0 | unit-stride, whole register store +| 0 | 1 | 0 | 1 | 1 | unit-stride, mask store, EEW=8 +| x | x | x | x | x | other encodings reserved +|=== + +[[norm:vector_ls_nf_op]] +The `nf[2:0]` field encodes the number of fields in each segment. For +regular vector loads and stores, `nf`=0, indicating that a single +value is moved between a vector register group and memory at each +element position. Larger values in the `nf` field are used to access +multiple contiguous fields within a segment as described below in +<>. + +[[norm:vector_wholels_nf_op]] +The `nf[2:0]` field also encodes the number of whole vector registers +to transfer for the whole vector register load/store instructions. + +[[sec-vector-loadstore-width-encoding]] +==== Vector Load/Store Width Encoding + +[#norm:vector_ls_eew_emul]#Vector loads and stores have an EEW encoded directly in the +instruction. The corresponding EMUL is calculated as EMUL = +(EEW/SEW)*LMUL.# [#norm:vector_ls_emul_rsv]#If the EMUL would be out of range (EMUL>8 or +EMUL<1/8), the instruction encoding is reserved.# [#norm:vector_ls_emul_offgroup_rsv]#The vector register +groups must have legal register specifiers for the selected EMUL, +otherwise the instruction encoding is reserved.# + +[[norm:vector_ls_indexed_eew_emul]] +Vector unit-stride and constant-stride use the EEW/EMUL encoded in the +instruction for the data values, while vector indexed loads and stores +use the EEW/EMUL encoded in the instruction for the index values and +the SEW/LMUL encoded in `vtype` for the data values. + +Vector loads and stores are encoded using width values that are not +claimed by the standard scalar floating-point loads and stores. + +[#norm:vector_ls_ins_req]#Implementations must provide vector loads and stores with EEWs corresponding to all supported SEW settings.# [#norm:vector_ls_ins_rsv]#Vector load/store encodings for unsupported EEW widths are reserved.# + +.Width encoding for vector loads and stores. +[cols="5,1,1,1,1,>3,>3,>3,3"] +|=== +| | mew 3+| width [2:0] | Mem bits | Data Reg bits | Index bits | Opcodes + +| Standard scalar FP | x | 0 | 0 | 1 | 16| FLEN | - | FLH/FSH +| Standard scalar FP | x | 0 | 1 | 0 | 32| FLEN | - | FLW/FSW +| Standard scalar FP | x | 0 | 1 | 1 | 64| FLEN | - | FLD/FSD +| Standard scalar FP | x | 1 | 0 | 0 | 128| FLEN | - | FLQ/FSQ +| Vector 8b element | 0 | 0 | 0 | 0 | 8| 8 | - | VLxE8/VSxE8 +| Vector 16b element | 0 | 1 | 0 | 1 | 16| 16 | - | VLxE16/VSxE16 +| Vector 32b element | 0 | 1 | 1 | 0 | 32| 32 | - | VLxE32/VSxE32 +| Vector 64b element | 0 | 1 | 1 | 1 | 64| 64 | - | VLxE64/VSxE64 +| Vector 8b index | 0 | 0 | 0 | 0 | SEW | SEW | 8 | VLxEI8/VSxEI8 +| Vector 16b index | 0 | 1 | 0 | 1 | SEW | SEW | 16 | VLxEI16/VSxEI16 +| Vector 32b index | 0 | 1 | 1 | 0 | SEW | SEW | 32 | VLxEI32/VSxEI32 +| Vector 64b index | 0 | 1 | 1 | 1 | SEW | SEW | 64 | VLxEI64/VSxEI64 +| Reserved | 1 | X | X | X | - | - | - | +|=== + +Mem bits is the size of each element accessed in memory. + +Data reg bits is the size of each data element accessed in register. + +Index bits is the size of each index accessed in register. + +[[norm:vector_ls_mew_rsv]] +The `mew` bit (`inst[28]`) when set is expected to be used to encode +expanded memory sizes of 128 bits and above, but these encodings are +currently reserved. + +==== Vector Unit-Stride Instructions + +---- +# Vector unit-stride loads and stores + +# vd destination, rs1 base address, vm is mask encoding (v0.t or ) +vle8.v vd, (rs1), vm # 8-bit unit-stride load +vle16.v vd, (rs1), vm # 16-bit unit-stride load +vle32.v vd, (rs1), vm # 32-bit unit-stride load +vle64.v vd, (rs1), vm # 64-bit unit-stride load + +# vs3 store data, rs1 base address, vm is mask encoding (v0.t or ) +vse8.v vs3, (rs1), vm # 8-bit unit-stride store +vse16.v vs3, (rs1), vm # 16-bit unit-stride store +vse32.v vs3, (rs1), vm # 32-bit unit-stride store +vse64.v vs3, (rs1), vm # 64-bit unit-stride store +---- + +[[norm:vector_ls_unit-stride_mask]] +Additional unit-stride mask load and store instructions are +provided to transfer mask values to/from memory. These +operate similarly to unmasked byte loads or stores (EEW=8), except that +the effective vector length is ``evl``=ceil(``vl``/8) (i.e. EMUL=1), +and the destination register is always written with a tail-agnostic +policy. + +---- +# Vector unit-stride mask load +vlm.v vd, (rs1) # Load byte vector of length ceil(vl/8) + +# Vector unit-stride mask store +vsm.v vs3, (rs1) # Store byte vector of length ceil(vl/8) +---- + +`vlm.v` and `vsm.v` are encoded with the same `width[2:0]`=0 encoding as +`vle8.v` and `vse8.v`, but are distinguished by different +`lumop` and `sumop` encodings. Since `vlm.v` and `vsm.v` operate as byte loads and stores, +`vstart` is in units of bytes for these instructions. + +NOTE: `vlm.v` and `vsm.v` respect the `vill` field in `vtype`, as +they depend on `vtype` indirectly through its constraints on `vl`. + +NOTE: The previous assembler mnemonics `vle1.v` and `vse1.v` were +confusing as length was handled differently for these instructions +versus other element load/store instructions. To avoid software +churn, these older assembly mnemonics are being retained as aliases. + +NOTE: The primary motivation to provide mask load and store is to +support machines that internally rearrange data to reduce +cross-datapath wiring. However, these instructions also provide a convenient +mechanism to use packed bit vectors in memory as mask values, +and also reduce the cost of mask spill/fill by reducing need to change +`vl`. + +==== Vector Constant-Stride Instructions + +---- +# Vector constant-stride loads and stores + +# vd destination, rs1 base address, rs2 byte constant-stride +vlse8.v vd, (rs1), rs2, vm # 8-bit constant-stride load +vlse16.v vd, (rs1), rs2, vm # 16-bit constant-stride load +vlse32.v vd, (rs1), rs2, vm # 32-bit constant-stride load +vlse64.v vd, (rs1), rs2, vm # 64-bit constant-stride load + +# vs3 store data, rs1 base address, rs2 byte constant-stride +vsse8.v vs3, (rs1), rs2, vm # 8-bit constant-stride store +vsse16.v vs3, (rs1), rs2, vm # 16-bit constant-stride store +vsse32.v vs3, (rs1), rs2, vm # 32-bit constant-stride store +vsse64.v vs3, (rs1), rs2, vm # 64-bit constant-stride store +---- + +[[norm:vector_ls_neg_zero_stride]] +Negative and zero strides are supported. + +[[norm:vector_ls_constant-stride_unordered]] +Element accesses within a constant-stride instruction are unordered with +respect to each other. + +[[norm:vector_ls_constant-stride_x0]] +When `rs2`=`x0`, then an implementation is allowed, but not required, +to perform fewer memory operations than the number of active elements, +and may perform different numbers of memory operations across +different dynamic executions of the same static instruction. + +NOTE: Compilers must be aware to not use the `x0` form for rs2 when +the immediate stride is `0` if the intent is to require all memory +accesses are performed. + +When `rs2!=x0` and the value of `x[rs2]=0`, the implementation must +perform one memory access for each active element (but these accesses +will not be ordered). + +NOTE: As with other architectural mandates, implementations must +_appear_ to perform each memory access. Microarchitectures are +free to optimize away accesses that would not be observed by another +agent, for example, in idempotent memory regions obeying RVWMO. For +non-idempotent memory regions, where by definition each access can be +observed by a device, the optimization would not be possible. + +NOTE: When repeating ordered vector accesses to the same memory +address are required, then an ordered indexed operation can be used. + +==== Vector Indexed Instructions + +---- +# Vector indexed loads and stores + +# Vector indexed-unordered load instructions +# vd destination, rs1 base address, vs2 byte offsets +vluxei8.v vd, (rs1), vs2, vm # unordered 8-bit indexed load of SEW data +vluxei16.v vd, (rs1), vs2, vm # unordered 16-bit indexed load of SEW data +vluxei32.v vd, (rs1), vs2, vm # unordered 32-bit indexed load of SEW data +vluxei64.v vd, (rs1), vs2, vm # unordered 64-bit indexed load of SEW data + +# Vector indexed-ordered load instructions +# vd destination, rs1 base address, vs2 byte offsets +vloxei8.v vd, (rs1), vs2, vm # ordered 8-bit indexed load of SEW data +vloxei16.v vd, (rs1), vs2, vm # ordered 16-bit indexed load of SEW data +vloxei32.v vd, (rs1), vs2, vm # ordered 32-bit indexed load of SEW data +vloxei64.v vd, (rs1), vs2, vm # ordered 64-bit indexed load of SEW data + +# Vector indexed-unordered store instructions +# vs3 store data, rs1 base address, vs2 byte offsets +vsuxei8.v vs3, (rs1), vs2, vm # unordered 8-bit indexed store of SEW data +vsuxei16.v vs3, (rs1), vs2, vm # unordered 16-bit indexed store of SEW data +vsuxei32.v vs3, (rs1), vs2, vm # unordered 32-bit indexed store of SEW data +vsuxei64.v vs3, (rs1), vs2, vm # unordered 64-bit indexed store of SEW data + +# Vector indexed-ordered store instructions +# vs3 store data, rs1 base address, vs2 byte offsets +vsoxei8.v vs3, (rs1), vs2, vm # ordered 8-bit indexed store of SEW data +vsoxei16.v vs3, (rs1), vs2, vm # ordered 16-bit indexed store of SEW data +vsoxei32.v vs3, (rs1), vs2, vm # ordered 32-bit indexed store of SEW data +vsoxei64.v vs3, (rs1), vs2, vm # ordered 64-bit indexed store of SEW data +---- + +NOTE: The assembler syntax for indexed loads and stores uses +``ei``__x__ instead of ``e``__x__ to indicate the statically encoded EEW +is of the index not the data. + +NOTE: The indexed operations mnemonics have a "U" or "O" to +distinguish between unordered and ordered, while the other vector +addressing modes have no character. While this is perhaps a little +less consistent, this approach minimizes disruption to existing +software, as VSXEI previously meant "ordered" - and the opcode can be +retained as an alias during transition to help reduce software churn. + +==== Unit-stride Fault-Only-First Loads + +[#norm:vector_ff_trigger]#The unit-stride fault-only-first load instructions are used to +vectorize loops with data-dependent exit conditions ("while" loops). +These instructions execute as a regular load except that they will +only take a trap caused by a synchronous exception on element 0.# [#norm:vector_ff_op]#If element 0 raises an exception, `vl` is not modified, and the trap is taken. If an element > 0 raises an exception, the corresponding trap is not taken, and the vector length `vl` is reduced to the index of the element that would have raised an exception.# + +[#norm:vector_ls_overwrite_past_trap_param]#Load instructions may overwrite active destination vector register +group elements past the element index at which the trap is reported.# +[#norm:vector_ff_past_trap_param]#Similarly, fault-only-first load instructions may update active destination elements past the element that causes trimming of the vector length (but not past the original vector length). The values of these spurious updates do not have to correspond to the values in memory at the addressed memory locations. Non-idempotent memory locations can only be accessed when it is known the corresponding element load operation will not be restarted due to a trap or vector-length trimming.# + +---- +# Vector unit-stride fault-only-first loads + +# vd destination, rs1 base address, vm is mask encoding (v0.t or ) +vle8ff.v vd, (rs1), vm # 8-bit unit-stride fault-only-first load +vle16ff.v vd, (rs1), vm # 16-bit unit-stride fault-only-first load +vle32ff.v vd, (rs1), vm # 32-bit unit-stride fault-only-first load +vle64ff.v vd, (rs1), vm # 64-bit unit-stride fault-only-first load +---- + +---- +strlen example using unit-stride fault-only-first instruction + +include::example/strlen.s[lines=4..-1] +---- + +NOTE: There is a security concern with fault-on-first loads, as they +can be used to probe for valid effective addresses. The unit-stride +versions only allow probing a region immediately contiguous to a known +region, and so reduce the security impact when used in unprivileged +code. However, code running in S-mode can establish arbitrary page +translations that allow probing of random guest physical addresses +provided by a hypervisor. Constant-stride and scatter/gather fault-only-first +instructions are not provided due to lack of encoding space, but they +can also represent a larger security hole, allowing even unprivileged +software to easily check multiple random pages for accessibility +without experiencing a trap. This standard does not address possible +security mitigations for fault-only-first instructions. + +[[norm:vector_ff_no_exception]] +Even when an exception is not raised, implementations are permitted to process +fewer than `vl` elements and reduce `vl` accordingly, but if `vstart`=0 and +`vl`>0, then at least one element must be processed. + +[[norm:vector_ff_interrupt_behavior]] +When the fault-only-first instruction takes a trap due to an +interrupt, implementations should not reduce `vl` and should instead +set a `vstart` value. + +NOTE: When the fault-only-first instruction would trigger a debug +data-watchpoint trap on an element after the first, implementations +should not reduce `vl` but instead should trigger the debug trap as +otherwise the event might be lost. + +[[sec-aos]] +==== Vector Load/Store Segment Instructions + +The vector load/store segment instructions move multiple contiguous +fields in memory to and from consecutively numbered vector registers. + +NOTE: The name "segment" reflects that the items moved are subarrays +with homogeneous elements. These operations can be used to transpose +arrays between memory and registers, and can support operations on +"array-of-structures" datatypes by unpacking each field in a structure +into a separate vector register. + +[[norm:nfields]] +The three-bit `nf` field in the vector instruction encoding is an +unsigned integer that contains one less than the number of fields per +segment, _NFIELDS_. + +[[fig-nf]] +.NFIELDS Encoding +[cols="1,1,1,13"] +|=== +3+| nf[2:0] | NFIELDS + +| 0 | 0 | 0 | 1 +| 0 | 0 | 1 | 2 +| 0 | 1 | 0 | 3 +| 0 | 1 | 1 | 4 +| 1 | 0 | 0 | 5 +| 1 | 0 | 1 | 6 +| 1 | 1 | 0 | 7 +| 1 | 1 | 1 | 8 +|=== + +[[norm:emul_nfields_rsv]] +The EMUL setting must be such that EMUL * NFIELDS {le} 8, otherwise +the instruction encoding is reserved. + +NOTE: The product ceil(EMUL) * NFIELDS represents the number of underlying +vector registers that will be touched by a segmented load or store +instruction. This constraint makes this total no larger than 1/4 of +the architectural register file, and the same as for regular +operations with EMUL=8. + +[[norm:nfields_op]] +Each field will be held in successively numbered vector register +groups. When EMUL>1, each field will occupy a vector register group +held in multiple successively numbered vector registers, and the +vector register group for each field must follow the usual vector +register alignment constraints (e.g., when EMUL=2 and NFIELDS=4, each +field's vector register group must start at an even vector register, +but does not have to start at a multiple of 8 vector register number). + +[[norm:vector_ls_seg_rsv]] +If the vector register numbers accessed by the segment load or store +would increment past 31, then the instruction encoding is reserved. + +NOTE: This constraint is to help allow for forward-compatibility with +a possible future longer instruction encoding that has more +addressable vector registers. + +[[norm:vector_ls_seg_op]] +The `vl` register gives the number of segments to move, which is +equal to the number of elements transferred to each vector register +group. Masking is also applied at the level of whole segments. + +[[norm:vector_ls_seg_unordered]] +For segment loads and stores, the individual memory accesses used to +access fields within each segment are unordered with respect to each +other even for ordered indexed segment loads and stores. + +[#norm:vector_ls_seg_vstart_dep]#The `vstart` value is in units of whole segments.# [#norm:vector_ls_seg_partial_access_param]#If a trap occurs during +access to a segment, it is implementation-defined whether a subset +of the faulting segment's accesses are performed before the trap is taken.# + +===== Vector Unit-Stride Segment Loads and Stores + +[[norm:vector_ls_seg_unit-stride_op]] +The vector unit-stride load and store segment instructions move packed +contiguous segments into multiple destination vector register groups. + +NOTE: Where the segments hold structures with heterogeneous-sized +fields, software can later unpack individual structure fields using +additional instructions after the segment load brings data into the +vector registers. + +The assembler prefixes `vlseg`/`vsseg` are used for unit-stride +segment loads and stores respectively. + +---- +# Format +# In this syntax, equals NFIELDS and is an integer in the range [2, 8]. +vlsege.v vd, (rs1), vm # Unit-stride segment load template +vssege.v vs3, (rs1), vm # Unit-stride segment store template + +# Examples +vlseg8e8.v vd, (rs1), vm # Load eight vector registers with eight byte fields. + +vsseg3e32.v vs3, (rs1), vm # Store packed vector of 3*4-byte segments from vs3,vs3+1,vs3+2 to memory +---- + +[[norm:vector_ls_seg_unit-stride_vd_vs3]] +For loads, the `vd` register will hold the first field loaded from the +segment. For stores, the `vs3` register is read to provide the first +field to be stored to each segment. + +---- +# Example 1 +# Memory structure holds packed RGB pixels (24-bit data structure, 8bpp) +vsetvli a1, t0, e8, m1, ta, ma +vlseg3e8.v v8, (a0), vm +# v8 holds the red pixels +# v9 holds the green pixels +# v10 holds the blue pixels + +# Example 2 +# Memory structure holds complex values, 32b for real and 32b for imaginary +vsetvli a1, t0, e32, m1, ta, ma +vlseg2e32.v v8, (a0), vm +# v8 holds real +# v9 holds imaginary +---- + +There are also fault-only-first versions of the unit-stride instructions. + +---- +# Template for vector fault-only-first unit-stride segment loads. +vlsegeff.v vd, (rs1), vm # Unit-stride fault-only-first segment loads +---- + +[[norm:vector_ls__seg_ff_unit-stride_op]] +For fault-only-first segment loads, if an exception is detected partway +through accessing the zeroth segment, the trap is taken. +If an exception is detected partway through accessing a subsequent segment, +`vl` is reduced to the index of that segment. +[[norm:vector_ff_seg_partial_access_param]] +In both cases, it is implementation-defined whether a subset of the segment is +loaded. + +[[norm:vector_ls_seg_ff_overload_param]] +These instructions may overwrite destination vector register group +elements past the point at which a trap is reported or past the point +at which vector length is trimmed. + +===== Vector Constant-Stride Segment Loads and Stores + +[[norm:vector_ls_seg_constant-stride_op]] +Vector constant-stride segment loads and stores move contiguous segments where +each segment is separated by the byte-stride offset given in the `rs2` +GPR argument. + +NOTE: Negative and zero strides are supported. + +---- +# Format +vlssege.v vd, (rs1), rs2, vm # Constant-stride segment loads +vsssege.v vs3, (rs1), rs2, vm # Constant-stride segment stores + +# Examples +vsetvli a1, t0, e8, m1, ta, ma +vlsseg3e8.v v4, (x5), x6 # Load bytes at addresses x5+i*x6 into v4[i], + # and bytes at addresses x5+i*x6+1 into v5[i], + # and bytes at addresses x5+i*x6+2 into v6[i]. + +# Examples +vsetvli a1, t0, e32, m1, ta, ma +vssseg2e32.v v2, (x5), x6 # Store words from v2[i] to address x5+i*x6 + # and words from v3[i] to address x5+i*x6+4 +---- + +[[norm:vector_ls_seg_constant-stride_unordered]] +Accesses to the fields within each segment can occur in any order, +including the case where the byte stride is such that segments overlap +in memory. + +===== Vector Indexed Segment Loads and Stores + +[#norm:vector_ls_seg_indexed_op]#Vector indexed segment loads and stores move contiguous segments where each segment is located at an address given by adding the scalar base address in the `rs1` field to byte offsets in vector register `vs2`.# Both ordered and unordered forms are provided, where the ordered forms access segments in element order. [#norm:vector_ls_seg_indexed_unordered]#However, even for the ordered form, accesses to the fields within an individual segment are not ordered with respect to each other.# + +[[norm:vector_ls_seg_indexed_eew_emul_op]] +The data vector register group has EEW=SEW, EMUL=LMUL, while the index +vector register group has EEW encoded in the instruction with +EMUL=(EEW/SEW)*LMUL. +[[norm:vector_ls_seg_indexed_emul_nfields_val]] +The EMUL * NFIELDS {le} 8 constraint applies to the data vector register group. + +---- +# Format +vluxsegei.v vd, (rs1), vs2, vm # Indexed-unordered segment loads +vloxsegei.v vd, (rs1), vs2, vm # Indexed-ordered segment loads +vsuxsegei.v vs3, (rs1), vs2, vm # Indexed-unordered segment stores +vsoxsegei.v vs3, (rs1), vs2, vm # Indexed-ordered segment stores + +# Examples +vsetvli a1, t0, e8, m1, ta, ma +vluxseg3ei8.v v4, (x5), v3 # Load bytes at addresses x5+v3[i] into v4[i], + # and bytes at addresses x5+v3[i]+1 into v5[i], + # and bytes at addresses x5+v3[i]+2 into v6[i]. + +# Examples +vsetvli a1, t0, e32, m1, ta, ma +vsuxseg2ei32.v v2, (x5), v5 # Store words from v2[i] to address x5+v5[i] + # and words from v3[i] to address x5+v5[i]+4 +---- + +[[norm:vector_ls_seg_indexed_vreg_rsv]] +For vector indexed segment loads, the destination vector register +groups cannot overlap the source vector register group (specified by +`vs2`), else the instruction encoding is reserved. + +NOTE: This constraint supports restart of indexed segment loads +that raise exceptions partway through loading a structure. + +==== Vector Load/Store Whole Register Instructions + +Format for Vector Load Whole Register Instructions under LOAD-FP major opcode + +//// +31 29 28 27 26 25 24 20 19 15 14 12 11 7 6 0 + nf | mew| 00 | 1| 01000 | rs1 | width | vd |0000111| VLR +//// + +[wavedrom,,svg] +.... +{reg: [ + {bits: 7, name: 0x07, attr: 'VL*R*'}, + {bits: 5, name: 'vd', attr: 'destination of load', type: 2}, + {bits: 3, name: 'width'}, + {bits: 5, name: 'rs1', attr: 'base address', type: 4}, + {bits: 5, name: 8, attr: 'lumop'}, + {bits: 1, name: 1, attr: 'vm'}, + {bits: 2, name: 0x10000, attr: 'mop'}, + {bits: 1, name: 'mew'}, + {bits: 3, name: 'nf'}, +]} +.... + +Format for Vector Store Whole Register Instructions under STORE-FP major opcode + +//// +31 29 28 27 26 25 24 20 19 15 14 12 11 7 6 0 + nf | 0 | 00 | 1| 01000 | rs1 | 000 | vs3 |0100111| VSR +//// + +[wavedrom,,svg] +.... +{reg: [ + {bits: 7, name: 0x27, attr: 'VS*R*'}, + {bits: 5, name: 'vs3', attr: 'store data', type: 2}, + {bits: 3, name: 0x1000}, + {bits: 5, name: 'rs1', attr: 'base address', type: 4}, + {bits: 5, name: 8, attr: 'sumop'}, + {bits: 1, name: 1, attr: 'vm'}, + {bits: 2, name: 0x100, attr: 'mop'}, + {bits: 1, name: 0x100, attr: 'mew'}, + {bits: 3, name: 'nf'}, +]} +.... + + +These instructions load and store whole vector register groups. + +NOTE: These instructions are intended to be used to save and restore +vector registers when the type or length of the current contents of +the vector register is not known, or where modifying `vl` and `vtype` +would be costly. Examples include compiler register spills, vector +function calls where values are passed in vector registers, interrupt +handlers, and OS context switches. Software can determine the number +of bytes transferred by reading the `vlenb` register. + +[[norm:vector_ls_seg_wholereg_eew]] +The load instructions have an EEW encoded in the `mew` and `width` +fields following the pattern of regular unit-stride loads. + +NOTE: Because in-register byte layouts are identical to in-memory byte +layouts, the same data is written to the destination register group +regardless of EEW. +Hence, it would have sufficed to provide only EEW=8 variants. +The full set of EEW variants is provided so that the encoded EEW can be used +as a hint to indicate the destination register group will next be accessed +with this EEW, which aids implementations that rearrange data internally. + +The vector whole register store instructions are encoded similar to +unmasked unit-stride store of elements with EEW=8. + +The `nf` field encodes how many vector registers to load and store using the NFIELDS encoding (Figure <>). +The encoded number of registers must be a power of 2 and the vector +register numbers must be aligned as with a vector register group, +otherwise the instruction encoding is reserved. [#norm:vector_ls_seg_wholereg_op]#NFIELDS +indicates the number of vector registers to transfer, numbered +successively after the base.# [#norm:vector_ls_seg_wholereg_nf_rsv]#Only NFIELDS values of 1, 2, 4, 8 are +supported, with other values reserved.# [#norm:vector_ls_seg_wholereg_op_cont]#When multiple registers are +transferred, the lowest-numbered vector register is held in the +lowest-numbered memory addresses and successive vector register +numbers are placed contiguously in memory.# + +[[norm:vector_ls_seg_wholereg_evl]] +The instructions operate with an effective vector length, +`evl`=NFIELDS*VLEN/EEW, regardless of current settings in `vtype` and +`vl`. The usual property that no elements are written if `vstart` +{ge} `vl` does not apply to these instructions. +Similarly, the property that the instructions are reserved if `vstart` +exceeds the largest element index for the current `vtype` setting +does not apply. +Instead, the instructions are reserved if `vstart` {ge} `evl`. + +The instructions operate similarly to unmasked unit-stride load and +store instructions, with the base address passed in the scalar `x` +register specified by `rs1`. + +[[norm:vector_ls_wholereg_missaligned_exception_param]] +Implementations are allowed to raise a misaligned address exception on +whole register loads and stores if the base address is not naturally +aligned to the larger of the size of the encoded EEW in bytes (EEW/8) +or the implementation's smallest supported SEW size in bytes +(SEW~MIN~/8). + +NOTE: Allowing misaligned exceptions to be raised based on +non-alignment to the encoded EEW simplifies the implementation of these +instructions. Some subset implementations might not support smaller +SEW widths, so are allowed to report misaligned exceptions for the +smallest supported SEW even if larger than encoded EEW. An extreme +non-standard implementation might have SEW~MIN~>XLEN for example. Software +environments can mandate the minimum alignment requirements to support +an ABI. + +---- +# Format of whole register load and store instructions. +vl1r.v v3, (a0) # Pseudoinstruction equal to vl1re8.v + +vl1re8.v v3, (a0) # Load v3 with VLEN/8 bytes held at address in a0 +vl1re16.v v3, (a0) # Load v3 with VLEN/16 halfwords held at address in a0 +vl1re32.v v3, (a0) # Load v3 with VLEN/32 words held at address in a0 +vl1re64.v v3, (a0) # Load v3 with VLEN/64 doublewords held at address in a0 + +vl2r.v v2, (a0) # Pseudoinstruction equal to vl2re8.v + +vl2re8.v v2, (a0) # Load v2-v3 with 2*VLEN/8 bytes from address in a0 +vl2re16.v v2, (a0) # Load v2-v3 with 2*VLEN/16 halfwords held at address in a0 +vl2re32.v v2, (a0) # Load v2-v3 with 2*VLEN/32 words held at address in a0 +vl2re64.v v2, (a0) # Load v2-v3 with 2*VLEN/64 doublewords held at address in a0 + +vl4r.v v4, (a0) # Pseudoinstruction equal to vl4re8.v + +vl4re8.v v4, (a0) # Load v4-v7 with 4*VLEN/8 bytes from address in a0 +vl4re16.v v4, (a0) +vl4re32.v v4, (a0) +vl4re64.v v4, (a0) + +vl8r.v v8, (a0) # Pseudoinstruction equal to vl8re8.v + +vl8re8.v v8, (a0) # Load v8-v15 with 8*VLEN/8 bytes from address in a0 +vl8re16.v v8, (a0) +vl8re32.v v8, (a0) +vl8re64.v v8, (a0) + +vs1r.v v3, (a1) # Store v3 to address in a1 +vs2r.v v2, (a1) # Store v2-v3 to address in a1 +vs4r.v v4, (a1) # Store v4-v7 to address in a1 +vs8r.v v8, (a1) # Store v8-v15 to address in a1 +---- + +NOTE: We have considered adding a whole register mask load instruction +(`vl1rm.v`) but have decided to omit from initial extension. The +primary purpose would be to inform the microarchitecture that the data +will be used as a mask. The same effect can be achieved with the +following code sequence, whose cost is at most four instructions. Of +these, the first could likely be removed as `vl` is often already +in a scalar register, and the last might already be present if the +following vector instruction needs a new SEW/LMUL. So, in best case +only two instructions (of which only one performs vector operations) are needed to synthesize the effect of the +dedicated instruction: +---- +csrr t0, vl # Save current vl (potentially not needed) +vsetvli t1, x0, e8, m8, ta, ma # Maximum VLMAX +vlm.v v0, (a0) # Load mask register +vsetvli x0, t0, # Restore vl (potentially already present) +---- + +=== Vector Memory Alignment Constraints + +[[norm:vector_ls_missaligned_exception_param]] +If an element accessed by a vector memory instruction is not naturally +aligned to the size of the element, either the element is transferred +successfully or an address-misaligned exception is raised on that +element. + +[[norm:vector_ls_scalar_missaligned_independence]] +Support for misaligned vector memory accesses is independent of an +implementation's support for misaligned scalar memory accesses. + +NOTE: An implementation may have neither, one, or both scalar and +vector memory accesses support some or all misaligned accesses in +hardware. A separate PMA should be defined to determine if vector +misaligned accesses are supported in the associated address range. + +[[norm:vector_ls_scalar_missaligned_dependence]] +Vector misaligned memory accesses follow the same rules for atomicity +as scalar misaligned memory accesses. + +=== Vector Memory Consistency Model + +[[norm:vector_ls_program_order]] +Vector memory instructions appear to execute in program order on the +local hart. + +[#norm:vector_ls_rvwmo]#Vector memory instructions follow RVWMO at the instruction level.# +[#norm:vector_ls_rvtso]#If the Ztso extension is implemented, vector memory instructions additionally follow RVTSO at the instruction level.# + +[[norm:vector_ls_indexed-ordered_ordered]] +Except for vector indexed-ordered loads and stores, element operations +are unordered within the instruction. + +[[norm:vector_ls_indexed-ordered_rvwmo]] +Vector indexed-ordered loads and stores read and write elements +from/to memory in element order respectively, +obeying RVWMO at the element level. + +NOTE: Ztso only imposes RVTSO at the instruction level; intra-instruction +ordering follows RVWMO regardless of whether Ztso is implemented. + +NOTE: More formal definitions required. + +[[norm:vl_control_dependency]] +Instructions affected by the vector length register `vl` have a control +dependency on `vl`, rather than a data dependency. +[[norm:vmask_control_dependency]] +Similarly, masked vector instructions have a control dependency on the source +mask register, rather than a data dependency. + +NOTE: Treating the vector length and mask as control rather than data +typically matches the semantics of the corresponding scalar code, where branch +instructions ordinarily would have been used. +Treating the mask as control allows masked vector load instructions to access +memory before the mask value is known, without the need for +a misspeculation-recovery mechanism. + +=== Vector Arithmetic Instruction Formats + +The vector arithmetic instructions use a new major opcode (OP-V = +1010111~2~) which neighbors OP-FP. The three-bit `funct3` field is +used to define sub-categories of vector instructions. + +include::images/wavedrom/valu-format.edn[] + +[[sec-arithmetic-encoding]] +==== Vector Arithmetic Instruction encoding + +The `funct3` field encodes the operand type and source locations. + +.funct3 +[cols="1,1,1,3,5,5"] +|=== +3+| funct3[2:0] | Category | Operands | Type of scalar operand + +| 0 | 0 | 0 | OPIVV | vector-vector | N/A +| 0 | 0 | 1 | OPFVV | vector-vector | N/A +| 0 | 1 | 0 | OPMVV | vector-vector | N/A +| 0 | 1 | 1 | OPIVI | vector-immediate | `imm[4:0]` +| 1 | 0 | 0 | OPIVX | vector-scalar | GPR `x` register `rs1` +| 1 | 0 | 1 | OPFVF | vector-scalar | FP `f` register `rs1` +| 1 | 1 | 0 | OPMVX | vector-scalar | GPR `x` register `rs1` +| 1 | 1 | 1 | OPCFG | scalars-imms | GPR `x` register `rs1` & `rs2`/`imm` +|=== + +Integer operations are performed using unsigned or two's-complement +signed integer arithmetic depending on the opcode. + +NOTE: In this discussion, fixed-point operations are +considered to be integer operations. + +All standard vector floating-point arithmetic operations follow the +IEEE-754/2008 standard. [#norm:V_fp_frm]#All vector floating-point operations use the dynamic rounding mode in the `frm` register.# [#norm:V_inv_frm_rsv]#Use of the `frm` field +when it contains an invalid rounding mode by any vector floating-point +instruction--even those that do not depend on the rounding mode, or +when `vl`=0, or when `vstart` {ge} `vl`--is reserved.# + +NOTE: All vector floating-point code will rely on a valid value in +`frm`. Implementations can make all vector FP instructions report +exceptions when the rounding mode is invalid to simplify control +logic. + +[[norm:vop-vv_vreg_vs2_vs1]] +Vector-vector operations take two vectors of operands from vector +register groups specified by `vs2` and `vs1` respectively. + +Vector-scalar operations can have three possible forms. In all three forms, +[#norm:vop-vx_vop-vi_vreg_vs2]#the vector register group operand is specified by `vs2`.# The second +scalar source operand comes from one of three alternative sources: + +. [#norm:vop-vi_imm_5bit]#For integer operations, the scalar can be a 5-bit immediate, `imm[4:0]`, encoded +in the `rs1` field. The value is sign-extended to SEW bits, unless otherwise specified.# + +. [#norm:vop-vx_xreg_rs1]#For integer operations, the scalar can be taken from the scalar `x` +register specified by `rs1`.# [#norm:vop-vx_rs1_trunc_lsb_sewbits]#If XLEN>SEW, the least-significant SEW bits of the `x` register are used, unless otherwise specified.# [#norm:vop-vx_rs1_sext_sewbits]#If XLEN SEW, the value in the `f` registers is +checked for a valid NaN-boxed value, in which case the +least-significant SEW bits of the `f` register are used, else the +canonical NaN value is used.# [#norm:V_fp_eew_rsv]#Vector instructions where any +floating-point vector operand's EEW is not a supported floating-point +type width (which includes when FLEN < SEW) are reserved.# + +NOTE: Some instructions _zero_-extend the 5-bit immediate, and denote this +by naming the immediate `uimm` in the assembly syntax. + +NOTE: [#norm:V_Zinx_fp_scalar]#When adding a vector extension to the Zfinx/Zdinx/Zhinx +extensions, floating-point scalar arguments are taken from the `x` registers. +NaN-boxing is not supported in these extensions, and so operands narrower +than XLEN bits are not checked for a NaN box; bits XLEN-1:EEW are ignored. +For RV32_Zdinx, EEW=64 scalar arguments are supplied by an `x`-register pair.# + +[#norm:V_masked]#Vector arithmetic instructions are masked under control of the `vm` +field.# + +---- +# Assembly syntax pattern for vector binary arithmetic instructions + +# Operations returning vector results, masked by vm (v0.t, ) +vop.vv vd, vs2, vs1, vm # integer vector-vector vd[i] = vs2[i] op vs1[i] +vop.vx vd, vs2, rs1, vm # integer vector-scalar vd[i] = vs2[i] op x[rs1] +vop.vi vd, vs2, imm, vm # integer vector-immediate vd[i] = vs2[i] op imm + +vfop.vv vd, vs2, vs1, vm # FP vector-vector operation vd[i] = vs2[i] fop vs1[i] +vfop.vf vd, vs2, rs1, vm # FP vector-scalar operation vd[i] = vs2[i] fop f[rs1] +---- + +NOTE: In the encoding, `vs2` is the first operand, while `rs1/imm` +is the second operand. This is the opposite to the standard scalar +ordering. This arrangement retains the existing encoding conventions +that instructions that read only one scalar register, read it from +`rs1`, and that 5-bit immediates are sourced from the `rs1` field. + +---- +# Assembly syntax pattern for vector ternary arithmetic instructions (multiply-add) + +# Integer operations overwriting sum input +vop.vv vd, vs1, vs2, vm # vd[i] = vs1[i] * vs2[i] + vd[i] +vop.vx vd, rs1, vs2, vm # vd[i] = x[rs1] * vs2[i] + vd[i] + +# Integer operations overwriting product input +vop.vv vd, vs1, vs2, vm # vd[i] = vs1[i] * vd[i] + vs2[i] +vop.vx vd, rs1, vs2, vm # vd[i] = x[rs1] * vd[i] + vs2[i] + +# Floating-point operations overwriting sum input +vfop.vv vd, vs1, vs2, vm # vd[i] = vs1[i] * vs2[i] + vd[i] +vfop.vf vd, rs1, vs2, vm # vd[i] = f[rs1] * vs2[i] + vd[i] + +# Floating-point operations overwriting product input +vfop.vv vd, vs1, vs2, vm # vd[i] = vs1[i] * vd[i] + vs2[i] +vfop.vf vd, rs1, vs2, vm # vd[i] = f[rs1] * vd[i] + vs2[i] +---- + +NOTE: For ternary multiply-add operations, the assembler syntax always +places the destination vector register first, followed by either `rs1` +or `vs1`, then `vs2`. This ordering provides a more natural reading +of the assembler for these ternary operations, as the multiply +operands are always next to each other. + +[[sec-widening]] +==== Widening Vector Arithmetic Instructions + +[#norm:vwop_vd_eew_emul]#A few vector arithmetic instructions are defined to be __widening__ +operations where the destination vector register group has EEW=2*SEW +and EMUL=2*LMUL.# These are generally given a `vw*` prefix on the +opcode, or `vfw*` for vector floating-point instructions. + +The first vector register group operand can be either single or +double-width. + +---- +# Assembly syntax pattern for vector widening arithmetic instructions + +# Double-width result, two single-width sources: 2*SEW = SEW op SEW +vwop.vv vd, vs2, vs1, vm # integer vector-vector vd[i] = vs2[i] op vs1[i] +vwop.vx vd, vs2, rs1, vm # integer vector-scalar vd[i] = vs2[i] op x[rs1] + +# Double-width result, first source double-width, second source single-width: 2*SEW = 2*SEW op SEW +vwop.wv vd, vs2, vs1, vm # integer vector-vector vd[i] = vs2[i] op vs1[i] +vwop.wx vd, vs2, rs1, vm # integer vector-scalar vd[i] = vs2[i] op x[rs1] +---- + +NOTE: Originally, a `w` suffix was used on opcode, but this could be +confused with the use of a `w` suffix to mean word-sized operations in +doubleword integers, so the `w` was moved to prefix. + +NOTE: The floating-point widening operations were changed to `vfw*` +from `vwf*` to be more consistent with any scalar widening +floating-point operations that will be written as `fw*`. + +Widening instruction encodings must follow the constraints in +<>. + +[[sec-narrowing]] +==== Narrowing Vector Arithmetic Instructions + +[#norm:vnop_vd_vs2_eew_emul]#A few instructions are provided to convert double-width source vectors +into single-width destination vectors. These instructions convert a +vector register group specified by `vs2` with EEW/EMUL=2*SEW/2*LMUL to a vector register +group with the current SEW/LMUL setting.# [#norm:vnop_vs1_eew_emul]#Where there is a second +source vector register group (specified by `vs1`), this has the same +(narrower) width as the result (i.e., EEW=SEW).# + +NOTE: An alternative design decision would have been to treat SEW/LMUL +as defining the size of the source vector register group. The choice +here is motivated by the belief the chosen approach will require fewer +`vtype` changes. + +NOTE: Compare operations that set a mask register are also +implicitly a narrowing operation. + +A `vn*` prefix on the opcode is used to distinguish these instructions +in the assembler, or a `vfn*` prefix for narrowing floating-point +opcodes. The double-width source vector register group is signified +by a `w` in the source operand suffix (e.g., `vnsra.wv`) + +---- +Assembly syntax pattern for vector narrowing arithmetic instructions + +# Single-width result vd, double-width source vs2, single-width source vs1/rs1 +# SEW = 2*SEW op SEW +vnop.wv vd, vs2, vs1, vm # integer vector-vector vd[i] = vs2[i] op vs1[i] +vnop.wx vd, vs2, rs1, vm # integer vector-scalar vd[i] = vs2[i] op x[rs1] +---- + +Narrowing instruction encodings must follow the constraints in +<>. + +[[sec-vector-integer]] +=== Vector Integer Arithmetic Instructions + +A set of vector integer arithmetic instructions is provided. Unless +otherwise stated, integer operations wrap around on overflow. + +==== Vector Single-Width Integer Add and Subtract + +[#norm:vadd_vsub_op]#Vector integer add and subtract are provided.# [#norm:vrsub_op]#Reverse-subtract +instructions are also provided for the vector-scalar forms.# + +---- +# Integer adds. +vadd.vv vd, vs2, vs1, vm # Vector-vector +vadd.vx vd, vs2, rs1, vm # vector-scalar +vadd.vi vd, vs2, imm, vm # vector-immediate + +# Integer subtract +vsub.vv vd, vs2, vs1, vm # Vector-vector +vsub.vx vd, vs2, rs1, vm # vector-scalar + +# Integer reverse subtract +vrsub.vx vd, vs2, rs1, vm # vd[i] = x[rs1] - vs2[i] +vrsub.vi vd, vs2, imm, vm # vd[i] = imm - vs2[i] +---- + +NOTE: A vector of integer values can be negated using a +reverse-subtract instruction with a scalar operand of `x0`. An +assembly pseudoinstruction `vneg.v vd,vs` = `vrsub.vx vd,vs,x0` is provided. + +==== Vector Widening Integer Add/Subtract + +[#norm:vwaddu_vwadd_vwsubu_vwsub_op]#The widening add/subtract instructions are provided in both signed and +unsigned variants, depending on whether the narrower source operands +are first sign- or zero-extended before forming the double-width sum.# + +---- +# Widening unsigned integer add/subtract, 2*SEW = SEW +/- SEW +vwaddu.vv vd, vs2, vs1, vm # vector-vector +vwaddu.vx vd, vs2, rs1, vm # vector-scalar +vwsubu.vv vd, vs2, vs1, vm # vector-vector +vwsubu.vx vd, vs2, rs1, vm # vector-scalar + +# Widening signed integer add/subtract, 2*SEW = SEW +/- SEW +vwadd.vv vd, vs2, vs1, vm # vector-vector +vwadd.vx vd, vs2, rs1, vm # vector-scalar +vwsub.vv vd, vs2, vs1, vm # vector-vector +vwsub.vx vd, vs2, rs1, vm # vector-scalar + +# Widening unsigned integer add/subtract, 2*SEW = 2*SEW +/- SEW +vwaddu.wv vd, vs2, vs1, vm # vector-vector +vwaddu.wx vd, vs2, rs1, vm # vector-scalar +vwsubu.wv vd, vs2, vs1, vm # vector-vector +vwsubu.wx vd, vs2, rs1, vm # vector-scalar + +# Widening signed integer add/subtract, 2*SEW = 2*SEW +/- SEW +vwadd.wv vd, vs2, vs1, vm # vector-vector +vwadd.wx vd, vs2, rs1, vm # vector-scalar +vwsub.wv vd, vs2, vs1, vm # vector-vector +vwsub.wx vd, vs2, rs1, vm # vector-scalar +---- + +NOTE: An integer value can be doubled in width using the widening add +instructions with a scalar operand of `x0`. Assembly +pseudoinstructions `vwcvt.x.x.v vd,vs,vm` = `vwadd.vx vd,vs,x0,vm` and +`vwcvtu.x.x.v vd,vs,vm` = `vwaddu.vx vd,vs,x0,vm` are provided. + +==== Vector Integer Extension + +[#norm:vsext_vzext_op]#The vector integer extension instructions zero- or sign-extend a +source vector integer operand with EEW less than SEW to fill SEW-sized +elements in the destination.# [#norm:vsext_vzext_vs_eew_emul]#The EEW of the source is 1/2, 1/4, or +1/8 of SEW, while EMUL of the source is (EEW/SEW)*LMUL.# [#norm:vsext_vzext_vd_eew_emul]#The +destination has EEW equal to SEW and EMUL equal to LMUL.# + +---- +vzext.vf2 vd, vs2, vm # Zero-extend SEW/2 source to SEW destination +vsext.vf2 vd, vs2, vm # Sign-extend SEW/2 source to SEW destination +vzext.vf4 vd, vs2, vm # Zero-extend SEW/4 source to SEW destination +vsext.vf4 vd, vs2, vm # Sign-extend SEW/4 source to SEW destination +vzext.vf8 vd, vs2, vm # Zero-extend SEW/8 source to SEW destination +vsext.vf8 vd, vs2, vm # Sign-extend SEW/8 source to SEW destination +---- + +[#norm:vsext_vzext_ill_eew_emul_rsv]#If the source EEW is not a supported width, or source EMUL would be +below the minimum legal LMUL, the instruction encoding is reserved.# + +NOTE: Standard vector load instructions access memory values that are +the same size as the destination register elements. Some application +code needs to operate on a range of operand widths in a wider element, +for example, loading a byte from memory and adding to an eight-byte +element. To avoid having to provide the cross-product of the number +of vector load instructions by the number of data types (byte, word, +halfword, and also signed/unsigned variants), we instead add explicit +extension instructions that can be used if an appropriate widening +arithmetic instruction is not available. + +==== Vector Integer Add-with-Carry / Subtract-with-Borrow Instructions + +To support multi-word integer arithmetic, instructions that operate on +a carry bit are provided. For each operation (add or subtract), two +instructions are provided: one to provide the result (SEW width), and +the second to generate the carry output (single bit encoded as a mask +boolean). + +[#norm:vmadc_vmsbc_vadc_vsbc_carry_v0]#The carry inputs and outputs are represented using the mask register +layout as described in <>. Due to +encoding constraints, the carry input must come from the implicit `v0` +register,# but carry outputs can be written to any vector register that +respects the source/destination overlap restrictions. + +[#norm:vadc_vsbc_op]#`vadc` and `vsbc` add or subtract the source operands and the carry-in or +borrow-in, and write the result to vector register `vd`.# +[#norm:vadc_vsbc_masked_write_all_elem]#These instructions are encoded as masked instructions (`vm=0`), but they operate +on and write back all body elements.# +[#norm:vadc_vsbc_unmasked_rsv]#Encodings corresponding to the unmasked versions (`vm=1`) are reserved.# + +[#norm:vmadc_vmsbc_op_masked]#`vmadc` and `vmsbc` add or subtract the source operands, optionally +add the carry-in or subtract the borrow-in if masked (`vm=0`), and +write the resulting carry-out or borrow-out back to mask register `vd`.# +[#norm:vmadc_vmsbc_op_unmasked]#If unmasked (`vm=1`), there is no carry-in or borrow-in.# [#norm:vmadc_vmsbc_masked_write_all_elem]#These instructions +operate on and write back all body elements, even if masked.# [#norm:vmadc_vmsbc_tail_agnostic]#Because these +instructions produce a mask value, they always operate with a +tail-agnostic policy.# + +---- + # Produce sum with carry. + + # vd[i] = vs2[i] + vs1[i] + v0.mask[i] + vadc.vvm vd, vs2, vs1, v0 # Vector-vector + + # vd[i] = vs2[i] + x[rs1] + v0.mask[i] + vadc.vxm vd, vs2, rs1, v0 # Vector-scalar + + # vd[i] = vs2[i] + imm + v0.mask[i] + vadc.vim vd, vs2, imm, v0 # Vector-immediate + + # Produce carry out in mask register format + + # vd.mask[i] = carry_out(vs2[i] + vs1[i] + v0.mask[i]) + vmadc.vvm vd, vs2, vs1, v0 # Vector-vector + + # vd.mask[i] = carry_out(vs2[i] + x[rs1] + v0.mask[i]) + vmadc.vxm vd, vs2, rs1, v0 # Vector-scalar + + # vd.mask[i] = carry_out(vs2[i] + imm + v0.mask[i]) + vmadc.vim vd, vs2, imm, v0 # Vector-immediate + + # vd.mask[i] = carry_out(vs2[i] + vs1[i]) + vmadc.vv vd, vs2, vs1 # Vector-vector, no carry-in + + # vd.mask[i] = carry_out(vs2[i] + x[rs1]) + vmadc.vx vd, vs2, rs1 # Vector-scalar, no carry-in + + # vd.mask[i] = carry_out(vs2[i] + imm) + vmadc.vi vd, vs2, imm # Vector-immediate, no carry-in +---- + +Because implementing a carry propagation requires executing two +instructions with unchanged inputs, destructive accumulations will +require an additional move to obtain correct results. + +---- +# Example multi-word arithmetic sequence, accumulating into v4 +vmadc.vvm v1, v4, v8, v0 # Get carry into temp register v1 +vadc.vvm v4, v4, v8, v0 # Calc new sum +vmmv.m v0, v1 # Move temp carry into v0 for next word +---- + +The subtract with borrow instruction `vsbc` performs the equivalent +function to support long word arithmetic for subtraction. There are +no subtract with immediate instructions. + +---- +# Produce difference with borrow. + +# vd[i] = vs2[i] - vs1[i] - v0.mask[i] +vsbc.vvm vd, vs2, vs1, v0 # Vector-vector + +# vd[i] = vs2[i] - x[rs1] - v0.mask[i] +vsbc.vxm vd, vs2, rs1, v0 # Vector-scalar + +# Produce borrow out in mask register format + +# vd.mask[i] = borrow_out(vs2[i] - vs1[i] - v0.mask[i]) +vmsbc.vvm vd, vs2, vs1, v0 # Vector-vector + +# vd.mask[i] = borrow_out(vs2[i] - x[rs1] - v0.mask[i]) +vmsbc.vxm vd, vs2, rs1, v0 # Vector-scalar + +# vd.mask[i] = borrow_out(vs2[i] - vs1[i]) +vmsbc.vv vd, vs2, vs1 # Vector-vector, no borrow-in + +# vd.mask[i] = borrow_out(vs2[i] - x[rs1]) +vmsbc.vx vd, vs2, rs1 # Vector-scalar, no borrow-in +---- + +[#norm:vmsbc_borrow_neg]#For `vmsbc`, the borrow is defined to be 1 iff the difference, prior to +truncation, is negative.# + +[#norm:vadc_vsbc_vd_v0_rsv]#For `vadc` and `vsbc`, the instruction encoding is reserved if the +destination vector register is `v0`.# + +NOTE: This constraint corresponds to the constraint on masked vector +operations that overwrite the mask register. + +==== Vector Bitwise Logical Instructions + +[#norm:vand_vor_vxor_op] +---- +# Bitwise logical operations. +vand.vv vd, vs2, vs1, vm # Vector-vector +vand.vx vd, vs2, rs1, vm # vector-scalar +vand.vi vd, vs2, imm, vm # vector-immediate + +vor.vv vd, vs2, vs1, vm # Vector-vector +vor.vx vd, vs2, rs1, vm # vector-scalar +vor.vi vd, vs2, imm, vm # vector-immediate + +vxor.vv vd, vs2, vs1, vm # Vector-vector +vxor.vx vd, vs2, rs1, vm # vector-scalar +vxor.vi vd, vs2, imm, vm # vector-immediate +---- + +NOTE: With an immediate of -1, scalar-immediate forms of the `vxor` +instruction provide a bitwise NOT operation. This is provided as +an assembler pseudoinstruction `vnot.v vd,vs,vm` = `vxor.vi vd,vs,-1,vm`. + +==== Vector Single-Width Shift Instructions + +[#norm:vsll_vsrl_vsra_op]#A full set of vector shift instructions are provided, including +logical shift left (`sll`), and logical (zero-extending `srl`) and +arithmetic (sign-extending `sra`) shift right. The data to be shifted +is in the vector register group specified by `vs2` and the shift +amount value can come from a vector register group `vs1`, a scalar +integer register `rs1`, or a zero-extended 5-bit immediate.# [#norm:vsll_vsrl_vsra_shamt]#Only the low +lg2(SEW) bits of the shift-amount value are used to control the shift +amount.# + +---- +# Bit shift operations +vsll.vv vd, vs2, vs1, vm # Vector-vector +vsll.vx vd, vs2, rs1, vm # vector-scalar +vsll.vi vd, vs2, uimm, vm # vector-immediate + +vsrl.vv vd, vs2, vs1, vm # Vector-vector +vsrl.vx vd, vs2, rs1, vm # vector-scalar +vsrl.vi vd, vs2, uimm, vm # vector-immediate + +vsra.vv vd, vs2, vs1, vm # Vector-vector +vsra.vx vd, vs2, rs1, vm # vector-scalar +vsra.vi vd, vs2, uimm, vm # vector-immediate +---- + +==== Vector Narrowing Integer Right Shift Instructions + +[#norm:vnsrl_vnsra_op]#The narrowing right shifts extract a smaller field from a wider +operand and have both zero-extending (`srl`) and sign-extending +(`sra`) forms. The shift amount can come from a vector register +group, or a scalar `x` register, or a zero-extended 5-bit immediate.# +[#norm:vnsrl_vnsra_shamt]#The low lg2(2*SEW) bits of the shift-amount value are +used (e.g., the low 6 bits for a SEW=64-bit to SEW=32-bit narrowing +operation).# + +---- + # Narrowing shift right logical, SEW = (2*SEW) >> SEW + vnsrl.wv vd, vs2, vs1, vm # vector-vector + vnsrl.wx vd, vs2, rs1, vm # vector-scalar + vnsrl.wi vd, vs2, uimm, vm # vector-immediate + + # Narrowing shift right arithmetic, SEW = (2*SEW) >> SEW + vnsra.wv vd, vs2, vs1, vm # vector-vector + vnsra.wx vd, vs2, rs1, vm # vector-scalar + vnsra.wi vd, vs2, uimm, vm # vector-immediate +---- + +NOTE: Future extensions might add support for versions that narrow to +a destination that is 1/4 the width of the source. + +NOTE: An integer value can be halved in width using the narrowing integer +shift instructions with a scalar operand of `x0`. An assembly +pseudoinstruction is provided `vncvt.x.x.w vd,vs,vm` = `vnsrl.wx vd,vs,x0,vm`. + +==== Vector Integer Compare Instructions + +[#norm:vmseq_vmsne_vmsltu_vmslt_vmsleu_vmsle_vmsgtu_vmsgt_op]#The following integer compare instructions write 1 to the destination +mask register element if the comparison evaluates to true, and 0 +otherwise. The destination mask vector is always held in a single +vector register, with a layout of elements as described in +<>.# [#norm:vmseq_vmsne_vmsltu_vmslt_vmsleu_vmsle_vmsgtu_vmsgt_vd_v0_legal]#The destination mask vector register +may be the same as the source vector mask register (`v0`).# + +---- +# Set if equal +vmseq.vv vd, vs2, vs1, vm # Vector-vector +vmseq.vx vd, vs2, rs1, vm # vector-scalar +vmseq.vi vd, vs2, imm, vm # vector-immediate + +# Set if not equal +vmsne.vv vd, vs2, vs1, vm # Vector-vector +vmsne.vx vd, vs2, rs1, vm # vector-scalar +vmsne.vi vd, vs2, imm, vm # vector-immediate + +# Set if less than, unsigned +vmsltu.vv vd, vs2, vs1, vm # Vector-vector +vmsltu.vx vd, vs2, rs1, vm # Vector-scalar + +# Set if less than, signed +vmslt.vv vd, vs2, vs1, vm # Vector-vector +vmslt.vx vd, vs2, rs1, vm # vector-scalar + +# Set if less than or equal, unsigned +vmsleu.vv vd, vs2, vs1, vm # Vector-vector +vmsleu.vx vd, vs2, rs1, vm # vector-scalar +vmsleu.vi vd, vs2, imm, vm # Vector-immediate + +# Set if less than or equal, signed +vmsle.vv vd, vs2, vs1, vm # Vector-vector +vmsle.vx vd, vs2, rs1, vm # vector-scalar +vmsle.vi vd, vs2, imm, vm # vector-immediate + +# Set if greater than, unsigned +vmsgtu.vx vd, vs2, rs1, vm # Vector-scalar +vmsgtu.vi vd, vs2, imm, vm # Vector-immediate + +# Set if greater than, signed +vmsgt.vx vd, vs2, rs1, vm # Vector-scalar +vmsgt.vi vd, vs2, imm, vm # Vector-immediate + +# Following two instructions are not provided directly +# Set if greater than or equal, unsigned +# vmsgeu.vx vd, vs2, rs1, vm # Vector-scalar +# Set if greater than or equal, signed +# vmsge.vx vd, vs2, rs1, vm # Vector-scalar +---- + +The following table indicates how all comparisons are implemented in +native machine code. + +---- +Comparison Assembler Mapping Assembler Pseudoinstruction + +va < vb vmslt{u}.vv vd, va, vb, vm +va <= vb vmsle{u}.vv vd, va, vb, vm +va > vb vmslt{u}.vv vd, vb, va, vm vmsgt{u}.vv vd, va, vb, vm +va >= vb vmsle{u}.vv vd, vb, va, vm vmsge{u}.vv vd, va, vb, vm + +va < x vmslt{u}.vx vd, va, x, vm +va <= x vmsle{u}.vx vd, va, x, vm +va > x vmsgt{u}.vx vd, va, x, vm +va >= x see below + +va < i vmsle{u}.vi vd, va, i-1, vm vmslt{u}.vi vd, va, i, vm +va <= i vmsle{u}.vi vd, va, i, vm +va > i vmsgt{u}.vi vd, va, i, vm +va >= i vmsgt{u}.vi vd, va, i-1, vm vmsge{u}.vi vd, va, i, vm + +va, vb vector register groups +x scalar integer register +i immediate +---- + +NOTE: The immediate forms of `vmslt{u}.vi` are not provided as the +immediate value can be decreased by 1 and the `vmsle{u}.vi` variants +used instead. The `vmsle.vi` range is -16 to 15, resulting in an +effective `vmslt.vi` range of -15 to 16. The `vmsleu.vi` range is 0 +to 15 giving an effective `vmsltu.vi` range of 1 to 16 (Note, +`vmsltu.vi` with immediate 0 is not useful as it is always +false). + +NOTE: Because the 5-bit vector immediates are always sign-extended, +when the high bit of the `simm5` immediate is set, `vmsleu.vi` also +supports unsigned immediate values in the range `2^SEW^-16` to +`2^SEW^-1`, allowing corresponding `vmsltu.vi` compares against +unsigned immediates in the range `2^SEW^-15` to `2^SEW^`. Note that +`vmsltu.vi` with immediate `2^SEW^` is not useful as it is always +true. + +Similarly, `vmsge{u}.vi` is not provided and the compare is +implemented using `vmsgt{u}.vi` with the immediate decremented by one. +The resulting effective `vmsge.vi` range is -15 to 16, and the +resulting effective `vmsgeu.vi` range is 1 to 16 (Note, `vmsgeu.vi` with +immediate 0 is not useful as it is always true). + +NOTE: The `vmsgt` forms for register scalar and immediates are provided +to allow a single compare instruction to provide the correct +polarity of mask value without using additional mask logical +instructions. + +To reduce encoding space, the `vmsge{u}.vx` form is not directly +provided, and so the `va {ge} x` case requires special treatment. + +NOTE: The `vmsge{u}.vx` could potentially be encoded in a +non-orthogonal way under the unused OPIVI variant of `vmslt{u}`. These +would be the only instructions in OPIVI that use a scalar `x` register +however. Alternatively, a further two funct6 encodings could be used, +but these would have a different operand format (writes to mask +register) than others in the same group of 8 funct6 encodings. The +current PoR is to omit these instructions and to synthesize where +needed as described below. + +The `vmsge{u}.vx` operation can be synthesized by reducing the +value of `x` by 1 and using the `vmsgt{u}.vx` instruction, when it is +known that this will not underflow the representation in `x`. + +---- +Sequences to synthesize vmsge{u}.vx instruction + +va >= x, x > minimum + + addi t0, x, -1; vmsgt{u}.vx vd, va, t0, vm +---- + +The above sequence will usually be the most efficient implementation, +but assembler pseudoinstructions can be provided for cases where the +range of `x` is unknown. + +---- +unmasked va >= x + + pseudoinstruction: vmsge{u}.vx vd, va, x + expansion: vmslt{u}.vx vd, va, x; vmnand.mm vd, vd, vd + +masked va >= x, vd != v0 + + pseudoinstruction: vmsge{u}.vx vd, va, x, v0.t + expansion: vmslt{u}.vx vd, va, x, v0.t; vmxor.mm vd, vd, v0 + +masked va >= x, vd == v0 + + pseudoinstruction: vmsge{u}.vx vd, va, x, v0.t, vt + expansion: vmslt{u}.vx vt, va, x; vmandn.mm vd, vd, vt + +masked va >= x, any vd + + pseudoinstruction: vmsge{u}.vx vd, va, x, v0.t, vt + expansion: vmslt{u}.vx vt, va, x; vmandn.mm vt, v0, vt; vmandn.mm vd, vd, v0; vmor.mm vd, vt, vd + + The vt argument to the pseudoinstruction must name a temporary vector register that is + not same as vd and which will be clobbered by the pseudoinstruction +---- + +[#norm:vmseq_vmsne_vmsltu_vmslt_vmsleu_vmsle_vmsgtu_vmsgt_maskundisturbed]#Compares effectively AND in the mask under a mask-undisturbed policy if the destination register is `v0`,# e.g., + +---- +# (a < b) && (b < c) in two instructions when mask-undisturbed +vmslt.vv v0, va, vb # All body elements written +vmslt.vv v0, vb, vc, v0.t # Only update at set mask +---- + +[#norm:vmseq_vmsne_vmsltu_vmslt_vmsleu_vmsle_vmsgtu_vmsgt_tail_agnostic]#Compares write mask registers, and so always operate under a +tail-agnostic policy.# + +==== Vector Integer Min/Max Instructions + +[#norm:vminu_vmin_vmaxu_vmax_op]#Signed and unsigned integer minimum and maximum instructions are +supported.# + +---- +# Unsigned minimum +vminu.vv vd, vs2, vs1, vm # Vector-vector +vminu.vx vd, vs2, rs1, vm # vector-scalar + +# Signed minimum +vmin.vv vd, vs2, vs1, vm # Vector-vector +vmin.vx vd, vs2, rs1, vm # vector-scalar + +# Unsigned maximum +vmaxu.vv vd, vs2, vs1, vm # Vector-vector +vmaxu.vx vd, vs2, rs1, vm # vector-scalar + +# Signed maximum +vmax.vv vd, vs2, vs1, vm # Vector-vector +vmax.vx vd, vs2, rs1, vm # vector-scalar +---- + +==== Vector Single-Width Integer Multiply Instructions + +[#norm:vmul_vmulh_vmulhu_vmulhsu_op]#The single-width multiply instructions perform a SEW-bit*SEW-bit +multiply to generate a 2*SEW-bit product, then return one half of the +product in the SEW-bit-wide destination. The `*mul*` versions write +the low word of the product to the destination register, while the +`*mulh*` versions write the high word of the product to the +destination register.# + +---- +# Signed multiply, returning low bits of product +vmul.vv vd, vs2, vs1, vm # Vector-vector +vmul.vx vd, vs2, rs1, vm # vector-scalar + +# Signed multiply, returning high bits of product +vmulh.vv vd, vs2, vs1, vm # Vector-vector +vmulh.vx vd, vs2, rs1, vm # vector-scalar + +# Unsigned multiply, returning high bits of product +vmulhu.vv vd, vs2, vs1, vm # Vector-vector +vmulhu.vx vd, vs2, rs1, vm # vector-scalar + +# Signed(vs2)-Unsigned multiply, returning high bits of product +vmulhsu.vv vd, vs2, vs1, vm # Vector-vector +vmulhsu.vx vd, vs2, rs1, vm # vector-scalar +---- + +NOTE: There is no `vmulhus.vx` opcode to return high half of +unsigned-vector * signed-scalar product. The scalar can be splatted +to a vector, then a `vmulhsu.vv` used. + +NOTE: The current `vmulh*` opcodes perform simple fractional +multiplies, but with no option to scale, round, and/or saturate the +result. A possible future extension can consider variants of `vmulh`, +`vmulhu`, `vmulhsu` that use the `vxrm` rounding mode when discarding +low half of product. There is no possibility of overflow in these +cases. + +==== Vector Integer Divide Instructions + +[#norm:vdivu_vdiv_vremu_vrem_op]#The divide and remainder instructions are equivalent to the RISC-V +standard scalar integer multiply/divides, with the same results for +extreme inputs.# + +---- +# Unsigned divide. +vdivu.vv vd, vs2, vs1, vm # Vector-vector +vdivu.vx vd, vs2, rs1, vm # vector-scalar + +# Signed divide +vdiv.vv vd, vs2, vs1, vm # Vector-vector +vdiv.vx vd, vs2, rs1, vm # vector-scalar + +# Unsigned remainder +vremu.vv vd, vs2, vs1, vm # Vector-vector +vremu.vx vd, vs2, rs1, vm # vector-scalar + +# Signed remainder +vrem.vv vd, vs2, vs1, vm # Vector-vector +vrem.vx vd, vs2, rs1, vm # vector-scalar +---- + +NOTE: The decision to include integer divide and remainder was +contentious. The argument in favor is that without a standard +instruction, software would have to pick some algorithm to perform the +operation, which would likely perform poorly on some +microarchitectures versus others. + +NOTE: There is no instruction to perform a "scalar divide by vector" +operation. + +==== Vector Widening Integer Multiply Instructions + +[#norm:vwmul_wmulu_vwmulsu_op]#The widening integer multiply instructions return the full 2*SEW-bit +product from an SEW-bit*SEW-bit multiply.# + +---- +# Widening signed-integer multiply +vwmul.vv vd, vs2, vs1, vm # vector-vector +vwmul.vx vd, vs2, rs1, vm # vector-scalar + +# Widening unsigned-integer multiply +vwmulu.vv vd, vs2, vs1, vm # vector-vector +vwmulu.vx vd, vs2, rs1, vm # vector-scalar + +# Widening signed(vs2)-unsigned integer multiply +vwmulsu.vv vd, vs2, vs1, vm # vector-vector +vwmulsu.vx vd, vs2, rs1, vm # vector-scalar +---- + +==== Vector Single-Width Integer Multiply-Add Instructions + +[#norm:vmacc_vnmsac_vmadd_vnmsub_op]#The integer multiply-add instructions are destructive and are provided +in two forms, one that overwrites the addend or minuend +(`vmacc`, `vnmsac`) and one that overwrites the first multiplicand +(`vmadd`, `vnmsub`).# + +[#norm:vmacc_vnmsac_vmadd_vnmsub_op_lowhalf]#The low half of the product is added or subtracted from the third operand.# + +NOTE: `sac` is intended to be read as "subtract from accumulator". The +opcode is `vnmsac` to match the (unfortunately counterintuitive) +floating-point `fnmsub` instruction definition. Similarly for the +`vnmsub` opcode. + +---- +# Integer multiply-add, overwrite addend +vmacc.vv vd, vs1, vs2, vm # vd[i] = (vs1[i] * vs2[i]) + vd[i] +vmacc.vx vd, rs1, vs2, vm # vd[i] = (x[rs1] * vs2[i]) + vd[i] + +# Integer multiply-sub, overwrite minuend +vnmsac.vv vd, vs1, vs2, vm # vd[i] = -(vs1[i] * vs2[i]) + vd[i] +vnmsac.vx vd, rs1, vs2, vm # vd[i] = -(x[rs1] * vs2[i]) + vd[i] + +# Integer multiply-add, overwrite multiplicand +vmadd.vv vd, vs1, vs2, vm # vd[i] = (vs1[i] * vd[i]) + vs2[i] +vmadd.vx vd, rs1, vs2, vm # vd[i] = (x[rs1] * vd[i]) + vs2[i] + +# Integer multiply-sub, overwrite multiplicand +vnmsub.vv vd, vs1, vs2, vm # vd[i] = -(vs1[i] * vd[i]) + vs2[i] +vnmsub.vx vd, rs1, vs2, vm # vd[i] = -(x[rs1] * vd[i]) + vs2[i] +---- + +==== Vector Widening Integer Multiply-Add Instructions + +[#norm:vwmaccu_vwmacc_vwmaccsu_vwmaccus_op]#The widening integer multiply-add instructions add the full 2*SEW-bit +product from a SEW-bit*SEW-bit multiply to a 2*SEW-bit value and +produce a 2*SEW-bit result.# All combinations of signed and unsigned +multiply operands are supported. + +---- +# Widening unsigned-integer multiply-add, overwrite addend +vwmaccu.vv vd, vs1, vs2, vm # vd[i] = (vs1[i] * vs2[i]) + vd[i] +vwmaccu.vx vd, rs1, vs2, vm # vd[i] = (x[rs1] * vs2[i]) + vd[i] + +# Widening signed-integer multiply-add, overwrite addend +vwmacc.vv vd, vs1, vs2, vm # vd[i] = (vs1[i] * vs2[i]) + vd[i] +vwmacc.vx vd, rs1, vs2, vm # vd[i] = (x[rs1] * vs2[i]) + vd[i] + +# Widening signed-unsigned-integer multiply-add, overwrite addend +vwmaccsu.vv vd, vs1, vs2, vm # vd[i] = (signed(vs1[i]) * unsigned(vs2[i])) + vd[i] +vwmaccsu.vx vd, rs1, vs2, vm # vd[i] = (signed(x[rs1]) * unsigned(vs2[i])) + vd[i] + +# Widening unsigned-signed-integer multiply-add, overwrite addend +vwmaccus.vx vd, rs1, vs2, vm # vd[i] = (unsigned(x[rs1]) * signed(vs2[i])) + vd[i] +---- + +==== Vector Integer Merge Instructions + +[#norm:vmerge_op]#The vector integer merge instructions combine two source operands +based on a mask.# [#norm:vmerge_all_elem]#Unlike regular arithmetic instructions, the +merge operates on all body elements (i.e., the set of elements from +`vstart` up to the current vector length in `vl`).# + +[#norm:vmerge_op_mask]#The `vmerge` instructions are encoded as masked instructions (`vm=0`). +The instructions combine two +sources as follows. At elements where the mask value is zero, the +first operand is copied to the destination element, otherwise the +second operand is copied to the destination element. The first +operand is always a vector register group specified by `vs2`. The +second operand is a vector register group specified by `vs1` or a +scalar `x` register specified by `rs1` or a 5-bit sign-extended +immediate.# + +---- +vmerge.vvm vd, vs2, vs1, v0 # vd[i] = v0.mask[i] ? vs1[i] : vs2[i] +vmerge.vxm vd, vs2, rs1, v0 # vd[i] = v0.mask[i] ? x[rs1] : vs2[i] +vmerge.vim vd, vs2, imm, v0 # vd[i] = v0.mask[i] ? imm : vs2[i] +---- + +==== Vector Integer Move Instructions + +[#norm:vmv_op]#The vector integer move instructions copy a source operand to a vector +register group. +The `vmv.v.v` variant copies a vector register group, whereas the `vmv.v.x` +and `vmv.v.i` variants __splat__ a scalar register or immediate to all active +elements of the destination vector register group.# +These instructions are encoded as unmasked instructions (`vm=1`). +[#norm:vmv_vs2_nv0_rsv]#The first operand specifier (`vs2`) must contain `v0`, and any other vector +register number in `vs2` is _reserved_.# + +---- +vmv.v.v vd, vs1 # vd[i] = vs1[i] +vmv.v.x vd, rs1 # vd[i] = x[rs1] +vmv.v.i vd, imm # vd[i] = imm +---- + +NOTE: Mask values can be widened into SEW-width elements using a +sequence `vmv.v.i vd, 0; vmerge.vim vd, vd, 1, v0`. + +NOTE: The vector integer move instructions share the encoding with the vector +merge instructions, but with `vm=1` and `vs2=v0`. + +The form `vmv.v.v vd, vd`, which leaves body elements unchanged, +can be used to indicate that the register will next be used +with an EEW equal to SEW. + +NOTE: Implementations that internally reorganize data according to EEW +can shuffle the internal representation according to SEW. +Implementations that do not internally reorganize data can dynamically +elide this instruction (aside from resetting `vstart` to 0). + +NOTE: The `vmv.v.v vd, vd` instruction is not a RISC-V HINT as a +tail-agnostic setting may cause an architectural state change on some +implementations. + +[[sec-vector-fixed-point]] +=== Vector Fixed-Point Arithmetic Instructions + +The preceding set of integer arithmetic instructions is extended to support +fixed-point arithmetic. + +A fixed-point number is a two's-complement signed or unsigned integer +interpreted as the numerator in a fraction with an implicit denominator. +The fixed-point instructions are intended to be applied to the numerators; +it is the responsibility of software to manage the denominators. +An N-bit element can hold two's-complement signed integers in the +range -2^N-1^...+2^N-1^-1, and unsigned integers in the range 0 +... +2^N^-1. The fixed-point instructions help preserve precision in +narrow operands by supporting scaling and rounding, and can handle +overflow by saturating results into the destination format range. + +NOTE: The widening integer operations described above can also be used +to avoid overflow. + +==== Vector Single-Width Saturating Add and Subtract + +[#norm:vsaddu_vsadd_vssubu_vssub_op]#Saturating forms of integer add and subtract are provided, for both +signed and unsigned integers.# [#norm:vsaddu_vsadd_vssubu_vssub_op_overflow_vxsat_op_vsaddsub]#If the result would overflow the +destination, the result is replaced with the closest representable +value, and the `vxsat` bit is set.# + +---- +# Saturating adds of unsigned integers. +vsaddu.vv vd, vs2, vs1, vm # Vector-vector +vsaddu.vx vd, vs2, rs1, vm # vector-scalar +vsaddu.vi vd, vs2, imm, vm # vector-immediate + +# Saturating adds of signed integers. +vsadd.vv vd, vs2, vs1, vm # Vector-vector +vsadd.vx vd, vs2, rs1, vm # vector-scalar +vsadd.vi vd, vs2, imm, vm # vector-immediate + +# Saturating subtract of unsigned integers. +vssubu.vv vd, vs2, vs1, vm # Vector-vector +vssubu.vx vd, vs2, rs1, vm # vector-scalar + +# Saturating subtract of signed integers. +vssub.vv vd, vs2, vs1, vm # Vector-vector +vssub.vx vd, vs2, rs1, vm # vector-scalar +---- + +==== Vector Single-Width Averaging Add and Subtract + +[#norm:vaaddu_vaadd_vasubu_vasub_op]#The averaging add and subtract instructions right shift the result by +one bit and round off the result according to the setting in `vxrm`. +Computation is performed in infinite precision before rounding and truncating.# +Both unsigned and signed versions are provided. +For `vaaddu` and `vaadd` there can be no overflow in the result. +[#norm:vasub_vasubu_op_overflow]#For `vasub` and `vasubu`, overflow is ignored and the result wraps around.# + +NOTE: For `vasub`, overflow occurs only when subtracting the smallest number +from the largest number under `rnu` or `rne` rounding. + +---- +# Averaging add + +# Averaging adds of unsigned integers. +vaaddu.vv vd, vs2, vs1, vm # roundoff_unsigned(vs2[i] + vs1[i], 1) +vaaddu.vx vd, vs2, rs1, vm # roundoff_unsigned(vs2[i] + x[rs1], 1) + +# Averaging adds of signed integers. +vaadd.vv vd, vs2, vs1, vm # roundoff_signed(vs2[i] + vs1[i], 1) +vaadd.vx vd, vs2, rs1, vm # roundoff_signed(vs2[i] + x[rs1], 1) + +# Averaging subtract + +# Averaging subtract of unsigned integers. +vasubu.vv vd, vs2, vs1, vm # roundoff_unsigned(vs2[i] - vs1[i], 1) +vasubu.vx vd, vs2, rs1, vm # roundoff_unsigned(vs2[i] - x[rs1], 1) + +# Averaging subtract of signed integers. +vasub.vv vd, vs2, vs1, vm # roundoff_signed(vs2[i] - vs1[i], 1) +vasub.vx vd, vs2, rs1, vm # roundoff_signed(vs2[i] - x[rs1], 1) +---- + +==== Vector Single-Width Fractional Multiply with Rounding and Saturation + +[#norm:vsmul_op]#The signed fractional multiply instruction produces a 2*SEW product of +the two SEW inputs, then shifts the result right by SEW-1 bits, +rounding these bits according to `vxrm`, then saturates the result to +fit into SEW bits.# [#norm:vxsat_op_vsmul]#If the result causes saturation, the `vxsat` bit +is set.# + +---- +# Signed saturating and rounding fractional multiply +# See vxrm description for rounding calculation +vsmul.vv vd, vs2, vs1, vm # vd[i] = clip(roundoff_signed(vs2[i]*vs1[i], SEW-1)) +vsmul.vx vd, vs2, rs1, vm # vd[i] = clip(roundoff_signed(vs2[i]*x[rs1], SEW-1)) +---- + +NOTE: When multiplying two N-bit signed numbers, the largest magnitude +is obtained for -2^N-1^ * -2^N-1^ producing a result +2^2N-2^, which +has a single (zero) sign bit when held in 2N bits. All other products +have two sign bits in 2N bits. To retain greater precision in N +result bits, the product is shifted right by one bit less than N, +saturating the largest magnitude result but increasing result +precision by one bit for all other products. + +NOTE: We do not provide an equivalent fractional multiply where one +input is unsigned, as these would retain all upper SEW bits and would +not need to saturate. This operation is partly covered by the +`vmulhu` and `vmulhsu` instructions, for the case where rounding is +simply truncation (`rdn`). + +==== Vector Single-Width Scaling Shift Instructions + +[#norm:vssrl_vssra_op]#These instructions shift the input value right, and round off the +shifted out bits according to `vxrm`. The scaling right shifts have +both zero-extending (`vssrl`) and sign-extending (`vssra`) forms. The +data to be shifted is in the vector register group specified by `vs2` +and the shift amount value can come from a vector register group +`vs1`, a scalar integer register `rs1`, or a zero-extended 5-bit +immediate.# [#norm:vssrl_vssra_shamt]#Only the low lg2(SEW) bits of the shift-amount value are used to control the shift amount.# + +---- + # Scaling shift right logical + vssrl.vv vd, vs2, vs1, vm # vd[i] = roundoff_unsigned(vs2[i], vs1[i]) + vssrl.vx vd, vs2, rs1, vm # vd[i] = roundoff_unsigned(vs2[i], x[rs1]) + vssrl.vi vd, vs2, uimm, vm # vd[i] = roundoff_unsigned(vs2[i], uimm) + + # Scaling shift right arithmetic + vssra.vv vd, vs2, vs1, vm # vd[i] = roundoff_signed(vs2[i],vs1[i]) + vssra.vx vd, vs2, rs1, vm # vd[i] = roundoff_signed(vs2[i], x[rs1]) + vssra.vi vd, vs2, uimm, vm # vd[i] = roundoff_signed(vs2[i], uimm) +---- + +==== Vector Narrowing Fixed-Point Clip Instructions + +[#norm:vnclipu_vnclip_op]#The `vnclip` instructions are used to pack a fixed-point value into a +narrower destination. The instructions support rounding, scaling, and +saturation into the final destination format. The source data is in +the vector register group specified by `vs2`. The scaling shift amount +value can come from a vector register group `vs1`, a scalar integer +register `rs1`, or a zero-extended 5-bit immediate.# [#norm:vnclipu_vnclip_shamt]#The low +lg2(2*SEW) bits of the vector or scalar shift-amount value (e.g., the +low 6 bits for a SEW=64-bit to SEW=32-bit narrowing operation) are +used to control the right shift amount, which provides the scaling.# +---- +# Narrowing unsigned clip +# SEW 2*SEW SEW +vnclipu.wv vd, vs2, vs1, vm # vd[i] = clip(roundoff_unsigned(vs2[i], vs1[i])) +vnclipu.wx vd, vs2, rs1, vm # vd[i] = clip(roundoff_unsigned(vs2[i], x[rs1])) +vnclipu.wi vd, vs2, uimm, vm # vd[i] = clip(roundoff_unsigned(vs2[i], uimm)) + +# Narrowing signed clip +vnclip.wv vd, vs2, vs1, vm # vd[i] = clip(roundoff_signed(vs2[i], vs1[i])) +vnclip.wx vd, vs2, rs1, vm # vd[i] = clip(roundoff_signed(vs2[i], x[rs1])) +vnclip.wi vd, vs2, uimm, vm # vd[i] = clip(roundoff_signed(vs2[i], uimm)) +---- + +[#norm:vnclipu_vnclip_rounding]#For `vnclipu`/`vnclip`, the rounding mode is specified in the `vxrm` +CSR. Rounding occurs around the least-significant bit of the +destination and before saturation.# + +[#norm:vnclipu_overflow]#For `vnclipu`, the shifted rounded source value is treated as an +unsigned integer and saturates if the result would overflow the +destination viewed as an unsigned integer.# + +NOTE: There is no single instruction that can saturate a signed value +into an unsigned destination. A sequence of two vector instructions +that first removes negative numbers by performing a max against 0 +using `vmax` then clips the resulting unsigned value into the +destination using `vnclipu` can be used if setting `vxsat` value for +negative numbers is not required. A `vsetvli` is required between +these two instructions to change SEW. + +[#norm:vnclip_overflow]#For `vnclip`, the shifted rounded source value is treated as a signed +integer and saturates if the result would overflow the destination viewed +as a signed integer.# + +[#norm:vxsat_op_vnclip_u]#If any destination element is saturated, the `vxsat` bit is set in the +`vxsat` register.# + +[[sec-vector-float]] +=== Vector Floating-Point Instructions + +The standard vector floating-point instructions treat elements as +IEEE-754/2008-compatible values. [#norm:V_fp_EEW_IEEE_nsupported_rsv]#If the EEW of a vector +floating-point operand does not correspond to a supported IEEE +floating-point type, the instruction encoding is reserved.# + +NOTE: Whether floating-point is supported, and for which element +widths, is determined by the specific vector extension. The current +set of extensions include support for 32-bit and 64-bit floating-point +values. When 16-bit and 128-bit element widths are added, they will be +also be treated as IEEE-754/2008-compatible values. Other +floating-point formats may be supported in future extensions. + +[#norm:Vf_requrires_Vx]#Vector floating-point instructions require the presence of base scalar +floating-point extensions corresponding to the supported vector +floating-point element widths.# + +NOTE: In particular, future vector extensions supporting 16-bit +half-precision floating-point values will also require some scalar +half-precision floating-point support. + +[#norm:mstatus-FS_off_V_fp_ill]#If the floating-point unit status field `mstatus.FS` is `Off` then any +attempt to execute a vector floating-point instruction will raise an +illegal-instruction exception.# [#norm:mstatus-FS_dirty_V_fp]#Any vector floating-point instruction +that modifies any floating-point extension state (i.e., floating-point +CSRs or `f` registers) must set `mstatus.FS` to `Dirty`.# + +[#norm:vsstatus_mstatus-FS_off_hypervisor_V_fp_ill]#If the hypervisor extension is implemented and V=1, the `vsstatus.FS` field is +additionally in effect for vector floating-point instructions. If +`vsstatus.FS` or `mstatus.FS` is `Off` then any +attempt to execute a vector floating-point instruction will raise an +illegal-instruction exception.# [#norm:vsstatus_mstatus-FS_dirty_hypervisor_V_fp]#Any vector floating-point instruction +that modifies any floating-point extension state (i.e., floating-point +CSRs or `f` registers) must set both `mstatus.FS` and `vsstatus.FS` to `Dirty`.# + +The vector floating-point instructions have the same behavior as the +scalar floating-point instructions with regard to NaNs. + +Scalar values for floating-point vector-scalar operations are sourced +as described in <>. + +==== Vector Floating-Point Exception Flags + +[#norm:fflags_op_V_fp]#A vector floating-point exception at any active floating-point element +sets the standard FP exception flags in the `fflags` register. Inactive +elements do not set FP exception flags.# + +==== Vector Single-Width Floating-Point Add/Subtract Instructions + +[#norm:vfadd_vfsub_vfrsub_op] +---- +# Floating-point add +vfadd.vv vd, vs2, vs1, vm # Vector-vector +vfadd.vf vd, vs2, rs1, vm # vector-scalar + +# Floating-point subtract +vfsub.vv vd, vs2, vs1, vm # Vector-vector +vfsub.vf vd, vs2, rs1, vm # Vector-scalar vd[i] = vs2[i] - f[rs1] +vfrsub.vf vd, vs2, rs1, vm # Scalar-vector vd[i] = f[rs1] - vs2[i] +---- + +==== Vector Widening Floating-Point Add/Subtract Instructions + +[#norm:vfwadd_op] +---- +# Widening FP add/subtract, 2*SEW = SEW +/- SEW +vfwadd.vv vd, vs2, vs1, vm # vector-vector +vfwadd.vf vd, vs2, rs1, vm # vector-scalar +vfwsub.vv vd, vs2, vs1, vm # vector-vector +vfwsub.vf vd, vs2, rs1, vm # vector-scalar + +# Widening FP add/subtract, 2*SEW = 2*SEW +/- SEW +vfwadd.wv vd, vs2, vs1, vm # vector-vector +vfwadd.wf vd, vs2, rs1, vm # vector-scalar +vfwsub.wv vd, vs2, vs1, vm # vector-vector +vfwsub.wf vd, vs2, rs1, vm # vector-scalar +---- + +==== Vector Single-Width Floating-Point Multiply/Divide Instructions + +[#norm:vfmul_vfdiv_vfrdiv_op] +---- +# Floating-point multiply +vfmul.vv vd, vs2, vs1, vm # Vector-vector +vfmul.vf vd, vs2, rs1, vm # vector-scalar + +# Floating-point divide +vfdiv.vv vd, vs2, vs1, vm # Vector-vector +vfdiv.vf vd, vs2, rs1, vm # vector-scalar + +# Reverse floating-point divide vector = scalar / vector +vfrdiv.vf vd, vs2, rs1, vm # scalar-vector, vd[i] = f[rs1]/vs2[i] +---- + +==== Vector Widening Floating-Point Multiply +[#norm:vfwmul_op] +---- +# Widening floating-point multiply +vfwmul.vv vd, vs2, vs1, vm # vector-vector +vfwmul.vf vd, vs2, rs1, vm # vector-scalar +---- diff --git a/param_extraction/chunks/chunk_057.txt.license b/param_extraction/chunks/chunk_057.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_057.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_058.txt b/param_extraction/chunks/chunk_058.txt new file mode 100644 index 0000000000..7aaa7de0bb --- /dev/null +++ b/param_extraction/chunks/chunk_058.txt @@ -0,0 +1,2039 @@ +# Chunk: chunk_058 +# Source: v-st-ext.adoc +# Lines: 3386-5396 (of 5396) +# Content starts: line 3394 +# Line count: 2011 +# Overlap from line: 3386 +# Sections: 20 +# ==== Vector Single-Width Floating-Point Fused Multiply-Add Instructions +# ==== Vector Widening Floating-Point Fused Multiply-Add Instructions +# ==== Vector Floating-Point Square-Root Instruction +# ==== Vector Floating-Point Reciprocal Square-Root Estimate Instruction +# ==== Vector Floating-Point Reciprocal Estimate Instruction +# ==== Vector Floating-Point MIN/MAX Instructions +# ==== Vector Floating-Point Sign-Injection Instructions +# ==== Vector Floating-Point Compare Instructions +# ==== Vector Floating-Point Classify Instruction +# ==== Vector Floating-Point Merge Instruction +# ==== Vector Floating-Point Move Instruction +# ==== Single-Width Floating-Point/Integer Type-Convert Instructions +# ==== Widening Floating-Point/Integer Type-Convert Instructions +# ==== Narrowing Floating-Point/Integer Type-Convert Instructions +# === Vector Reduction Operations +# ==== Vector Single-Width Integer Reduction Instructions +# ==== Vector Widening Integer Reduction Instructions +# ==== Vector Single-Width Floating-Point Reduction Instructions +# ===== Vector Ordered Single-Width Floating-Point Sum Reduction +# ===== Vector Unordered Single-Width Floating-Point Sum Reduction +# +==== Vector Widening Floating-Point Multiply +[#norm:vfwmul_op] +---- +# Widening floating-point multiply +vfwmul.vv vd, vs2, vs1, vm # vector-vector +vfwmul.vf vd, vs2, rs1, vm # vector-scalar +---- + +==== Vector Single-Width Floating-Point Fused Multiply-Add Instructions + +[#norm:vfmacc_vfnmacc_vfmsac_vfnmsac_vfmadd_vfnmadd_vfmsub_vfnmsub_op]#All four varieties of fused multiply-add are provided, and in two +destructive forms that overwrite one of the operands, either the +addend or the first multiplicand.# + +---- +# FP multiply-accumulate, overwrites addend +vfmacc.vv vd, vs1, vs2, vm # vd[i] = (vs1[i] * vs2[i]) + vd[i] +vfmacc.vf vd, rs1, vs2, vm # vd[i] = (f[rs1] * vs2[i]) + vd[i] + +# FP negate-(multiply-accumulate), overwrites subtrahend +vfnmacc.vv vd, vs1, vs2, vm # vd[i] = -(vs1[i] * vs2[i]) - vd[i] +vfnmacc.vf vd, rs1, vs2, vm # vd[i] = -(f[rs1] * vs2[i]) - vd[i] + +# FP multiply-subtract-accumulator, overwrites subtrahend +vfmsac.vv vd, vs1, vs2, vm # vd[i] = (vs1[i] * vs2[i]) - vd[i] +vfmsac.vf vd, rs1, vs2, vm # vd[i] = (f[rs1] * vs2[i]) - vd[i] + +# FP negate-(multiply-subtract-accumulator), overwrites minuend +vfnmsac.vv vd, vs1, vs2, vm # vd[i] = -(vs1[i] * vs2[i]) + vd[i] +vfnmsac.vf vd, rs1, vs2, vm # vd[i] = -(f[rs1] * vs2[i]) + vd[i] + +# FP multiply-add, overwrites multiplicand +vfmadd.vv vd, vs1, vs2, vm # vd[i] = (vs1[i] * vd[i]) + vs2[i] +vfmadd.vf vd, rs1, vs2, vm # vd[i] = (f[rs1] * vd[i]) + vs2[i] + +# FP negate-(multiply-add), overwrites multiplicand +vfnmadd.vv vd, vs1, vs2, vm # vd[i] = -(vs1[i] * vd[i]) - vs2[i] +vfnmadd.vf vd, rs1, vs2, vm # vd[i] = -(f[rs1] * vd[i]) - vs2[i] + +# FP multiply-sub, overwrites multiplicand +vfmsub.vv vd, vs1, vs2, vm # vd[i] = (vs1[i] * vd[i]) - vs2[i] +vfmsub.vf vd, rs1, vs2, vm # vd[i] = (f[rs1] * vd[i]) - vs2[i] + +# FP negate-(multiply-sub), overwrites multiplicand +vfnmsub.vv vd, vs1, vs2, vm # vd[i] = -(vs1[i] * vd[i]) + vs2[i] +vfnmsub.vf vd, rs1, vs2, vm # vd[i] = -(f[rs1] * vd[i]) + vs2[i] +---- + +NOTE: While we considered using the two unused rounding modes +in the scalar FP FMA encoding to provide a few non-destructive FMAs, +these would complicate microarchitectures by being the only maskable +operation with three inputs and separate output. + +==== Vector Widening Floating-Point Fused Multiply-Add Instructions + +[#norm:vfwmacc_vfwnmacc_vfwmsac_vfwnmsac_op]#The widening floating-point fused multiply-add instructions all +overwrite the wide addend with the result. The multiplier inputs are +all SEW wide, while the addend and destination is 2*SEW bits wide.# + +---- +# FP widening multiply-accumulate, overwrites addend +vfwmacc.vv vd, vs1, vs2, vm # vd[i] = (vs1[i] * vs2[i]) + vd[i] +vfwmacc.vf vd, rs1, vs2, vm # vd[i] = (f[rs1] * vs2[i]) + vd[i] + +# FP widening negate-(multiply-accumulate), overwrites addend +vfwnmacc.vv vd, vs1, vs2, vm # vd[i] = -(vs1[i] * vs2[i]) - vd[i] +vfwnmacc.vf vd, rs1, vs2, vm # vd[i] = -(f[rs1] * vs2[i]) - vd[i] + +# FP widening multiply-subtract-accumulator, overwrites addend +vfwmsac.vv vd, vs1, vs2, vm # vd[i] = (vs1[i] * vs2[i]) - vd[i] +vfwmsac.vf vd, rs1, vs2, vm # vd[i] = (f[rs1] * vs2[i]) - vd[i] + +# FP widening negate-(multiply-subtract-accumulator), overwrites addend +vfwnmsac.vv vd, vs1, vs2, vm # vd[i] = -(vs1[i] * vs2[i]) + vd[i] +vfwnmsac.vf vd, rs1, vs2, vm # vd[i] = -(f[rs1] * vs2[i]) + vd[i] +---- + +==== Vector Floating-Point Square-Root Instruction + +This is a unary vector-vector instruction. +[#norm:vfsqrt_op] + +---- +# Floating-point square root +vfsqrt.v vd, vs2, vm # Vector-vector square root +---- + +==== Vector Floating-Point Reciprocal Square-Root Estimate Instruction + +---- +# Floating-point reciprocal square-root estimate to 7 bits. +vfrsqrt7.v vd, vs2, vm +---- + +[#norm:vfrsqrt7_op]#This is a unary vector-vector instruction that returns an estimate of +1/sqrt(x) accurate to 7 bits.# + +NOTE: An earlier draft version had used the assembler name `vfrsqrte7` +but this was deemed to cause confusion with the ``e``__x__ notation for element +width. The earlier name can be retained as alias in tool chains for +backward compatibility. + +The following table describes the instruction's behavior for all +classes of floating-point inputs: + +[cols="1,1,1"] +[%autowidth,float="center",align="center",options="header"] +|=== +| Input | Output | Exceptions raised + +| -{inf} {le} _x_ < -0.0 | canonical NaN | NV +| -0.0 | -{inf} | DZ +| +0.0 | +{inf} | DZ +| +0.0 < _x_ < +{inf} | _estimate of 1/sqrt(x)_ | +| +{inf} | +0.0 | +| qNaN | canonical NaN | +| sNaN | canonical NaN | NV +|=== + +NOTE: All positive normal and subnormal inputs produce normal outputs. + +NOTE: The output value is independent of the dynamic rounding mode. + +[#norm:vfrsqrt7_op_unex]#For the non-exceptional cases, the low bit of the exponent and the six high +bits of significand (after the leading one) are concatenated and used to +address the following table. +The output of the table becomes the seven high bits of the result significand +(after the leading one); the remainder of the result significand is zero. +Subnormal inputs are normalized and the exponent adjusted appropriately before +the lookup. +The output exponent is chosen to make the result approximate the reciprocal of +the square root of the argument.# + +[#norm:vfrsqrt7_op_precise]#More precisely, the result is computed as follows. +Let the normalized input exponent be equal to the input exponent if the input +is normal, or 0 minus the number of leading zeros in the significand +otherwise. +If the input is subnormal, the normalized input significand is given by +shifting the input significand left by 1 minus the normalized input exponent, +discarding the leading 1 bit. +The output exponent equals floor((3*B - 1 - the normalized input exponent) / 2), +where B is the exponent bias. The output sign equals the input sign.# + +The following table gives the seven MSBs of the output significand as a +function of the LSB of the normalized input exponent and the six MSBs of the +normalized input significand; the other bits of the output significand are zero. + +include::images/wavedrom/vfrsqrt7.edn[] + +NOTE: For example, when SEW=32, vfrsqrt7(0x00718abc ({approx} 1.043e-38)) = 0x5f080000 ({approx} 9.800e18), and vfrsqrt7(0x7f765432 ({approx} 3.274e38)) = 0x1f820000 ({approx} 5.506e-20). + +NOTE: The 7 bit accuracy was chosen as it requires 0,1,2,3 +Newton-Raphson iterations to converge to close to bfloat16, FP16, +FP32, FP64 accuracy respectively. Future instructions can be defined +with greater estimate accuracy. + +==== Vector Floating-Point Reciprocal Estimate Instruction + +---- +# Floating-point reciprocal estimate to 7 bits. +vfrec7.v vd, vs2, vm +---- + +NOTE: An earlier draft version had used the assembler name `vfrece7` +but this was deemed to cause confusion with ``e``__x__ notation for element +width. The earlier name can be retained as alias in tool chains for +backward compatibility. + +[#norm:vfrec7_op]#This is a unary vector-vector instruction that returns an estimate of +1/x accurate to 7 bits.# + +The following table describes the instruction's behavior for all +classes of floating-point inputs, where _B_ is the exponent bias: + +[cols="1,1,1,1"] +[%autowidth,float="center",align="center",options="header"] +|=== +| Input (_x_) | Rounding Mode | Output (_y_ {approx} _1/x_) | Exceptions raised + +| -{inf} | _any_ | -0.0 | +| -2^B+1^ < _x_ {le} -2^B^ (normal) | _any_ | -2^-(B+1)^ {ge} _y_ > -2^-B^ (subnormal, sig=01...) | +| -2^B^ < _x_ {le} -2^B-1^ (normal) | _any_ | -2^-B^ {ge} _y_ > -2^-B+1^ (subnormal, sig=1...) | +| -2^B-1^ < _x_ {le} -2^-B+1^ (normal) | _any_ | -2^-B+1^ {ge} _y_ > -2^B-1^ (normal) | +| -2^-B+1^ < _x_ {le} -2^-B^ (subnormal, sig=1...) | _any_ | -2^B-1^ {ge} _y_ > -2^B^ (normal) | +| -2^-B^ < _x_ {le} -2^-(B+1)^ (subnormal, sig=01...) | _any_ | -2^B^ {ge} _y_ > -2^B+1^ (normal) | +| -2^-(B+1)^ < _x_ < -0.0 (subnormal, sig=00...) | RUP, RTZ | greatest-mag. negative finite value | NX, OF +| -2^-(B+1)^ < _x_ < -0.0 (subnormal, sig=00...) | RDN, RNE, RMM | -{inf} | NX, OF +| -0.0 | _any_ | -{inf} | DZ +| +0.0 | _any_ | +{inf} | DZ +| +0.0 < _x_ < 2^-(B+1)^ (subnormal, sig=00...) | RUP, RNE, RMM | +{inf} | NX, OF +| +0.0 < _x_ < 2^-(B+1)^ (subnormal, sig=00...) | RDN, RTZ | greatest finite value | NX, OF +| 2^-(B+1)^ {le} _x_ < 2^-B^ (subnormal, sig=01...) | _any_ | 2^B+1^ > _y_ {ge} 2^B^ (normal) | +| 2^-B^ {le} _x_ < 2^-B+1^ (subnormal, sig=1...) | _any_ | 2^B^ > _y_ {ge} 2^B-1^ (normal) | +| 2^-B+1^ {le} _x_ < 2^B-1^ (normal) | _any_ | 2^B-1^ > _y_ {ge} 2^-B+1^ (normal) | +| 2^B-1^ {le} _x_ < 2^B^ (normal) | _any_ | 2^-B+1^ > _y_ {ge} 2^-B^ (subnormal, sig=1...) | +| 2^B^ {le} _x_ < 2^B+1^ (normal) | _any_ | 2^-B^ > _y_ {ge} 2^-(B+1)^ (subnormal, sig=01...) | +| +{inf} | _any_ | +0.0 | +| qNaN | _any_ | canonical NaN | +| sNaN | _any_ | canonical NaN | NV +|=== + +NOTE: Subnormal inputs with magnitude at least 2^-(B+1)^ produce normal outputs; +other subnormal inputs produce infinite outputs. +Normal inputs with magnitude at least 2^B-1^ produce subnormal outputs; +other normal inputs produce normal outputs. + +NOTE: The output value depends on the dynamic rounding mode when +the overflow exception is raised. + +[#norm:vfrec7_op_unex]#For the non-exceptional cases, the seven high bits of significand (after the +leading one) are used to address the following table. +The output of the table becomes the seven high bits of the result significand +(after the leading one); the remainder of the result significand is zero. +Subnormal inputs are normalized and the exponent adjusted appropriately before +the lookup. +The output exponent is chosen to make the result approximate the reciprocal of +the argument, and subnormal outputs are denormalized accordingly.# + +[#norm:vfrec7_op_precise]#More precisely, the result is computed as follows. +Let the normalized input exponent be equal to the input exponent if the input +is normal, or 0 minus the number of leading zeros in the significand +otherwise. +The normalized output exponent equals (2*B - 1 - the normalized input exponent). +If the normalized output exponent is outside the range [-1, 2*B], the result +corresponds to one of the exceptional cases in the table above.# + +[#norm:vfrec7_op_subnorm]#If the input is subnormal, the normalized input significand is given by +shifting the input significand left by 1 minus the normalized input exponent, +discarding the leading 1 bit. +Otherwise, the normalized input significand equals the input significand. +The following table gives the seven MSBs of the normalized output significand +as a function of the seven MSBs of the normalized input significand; the other +bits of the normalized output significand are zero.# + +include::images/wavedrom/vfrec7.edn[] + +[#norm:vfrec7_op_output]#If the normalized output exponent is 0 or -1, the result is subnormal: the +output exponent is 0, and the output significand is given by concatenating +a 1 bit to the left of the normalized output significand, then shifting that +quantity right by 1 minus the normalized output exponent. +Otherwise, the output exponent equals the normalized output exponent, and the +output significand equals the normalized output significand. +The output sign equals the input sign.# + +NOTE: For example, when SEW=32, vfrec7(0x00718abc ({approx} 1.043e-38)) = 0x7e900000 ({approx} 9.570e37), and vfrec7(0x7f765432 ({approx} 3.274e38)) = 0x00214000 ({approx} 3.053e-39). + +NOTE: The 7 bit accuracy was chosen as it requires 0,1,2,3 +Newton-Raphson iterations to converge to close to bfloat16, FP16, +FP32, FP64 accuracy respectively. Future instructions can be defined +with greater estimate accuracy. + +==== Vector Floating-Point MIN/MAX Instructions + +[#norm:vfmin_vfmax_op]#The vector floating-point `vfmin` and `vfmax` instructions have the +same behavior as the corresponding scalar floating-point instructions +in version 2.2 of the RISC-V F/D/Q extension: they perform the `minimumNumber` +or `maximumNumber` operation on active elements.# + +---- +# Floating-point minimum +vfmin.vv vd, vs2, vs1, vm # Vector-vector +vfmin.vf vd, vs2, rs1, vm # vector-scalar + +# Floating-point maximum +vfmax.vv vd, vs2, vs1, vm # Vector-vector +vfmax.vf vd, vs2, rs1, vm # vector-scalar +---- + +==== Vector Floating-Point Sign-Injection Instructions + +[#norm:vfsgnj_vfsgnjn_vfsgnjx_op]#Vector versions of the scalar sign-injection instructions. The result +takes all bits except the sign bit from the vector `vs2` operands.# + +---- +vfsgnj.vv vd, vs2, vs1, vm # Vector-vector +vfsgnj.vf vd, vs2, rs1, vm # vector-scalar + +vfsgnjn.vv vd, vs2, vs1, vm # Vector-vector +vfsgnjn.vf vd, vs2, rs1, vm # vector-scalar + +vfsgnjx.vv vd, vs2, vs1, vm # Vector-vector +vfsgnjx.vf vd, vs2, rs1, vm # vector-scalar +---- + +NOTE: A vector of floating-point values can be negated using a +sign-injection instruction with both source operands set to the same +vector operand. An assembly pseudoinstruction is provided: `vfneg.v vd,vs` = `vfsgnjn.vv vd,vs,vs`. + +NOTE: The absolute value of a vector of floating-point elements can be +calculated using a sign-injection instruction with both source +operands set to the same vector operand. An assembly +pseudoinstruction is provided: `vfabs.v vd,vs` = `vfsgnjx.vv vd,vs,vs`. + +==== Vector Floating-Point Compare Instructions + +[#norm:vmfeq_vmfne_vmflt_vmfle_vmfgt_vmfge_op]#These vector FP compare instructions compare two source operands and +write the comparison result to a mask register.# [#norm:vmfeq_vmfne_vmflt_vmfle_vmfgt_vmfge_vd_single_vreg]#The destination mask +vector is always held in a single vector register, with a layout of +elements as described in <>.# [#norm:vmfeq_vmfne_vmflt_vmfle_vmfgt_vmfge_vd_eq_v0]#The +destination mask vector register may be the same as the source vector +mask register (`v0`).# [#norm:vmfeq_vmfne_vmflt_vmfle_vmfgt_vmfge_tail_agnostic]#Compares write mask registers, and so always +operate under a tail-agnostic policy.# + +The compare instructions follow the semantics of the scalar +floating-point compare instructions. [#norm:vmfeq_vmfne_sNaN_invalid]#`vmfeq` and `vmfne` raise the invalid +operation exception only on signaling NaN inputs.# [#norm:vmflt_vmfle_vmfgt_vmfge_sqNaN_invalid]#`vmflt`, `vmfle`, `vmfgt`, +and `vmfge` raise the invalid operation exception on both signaling and +quiet NaN inputs.# +[#norm:vmfne_vdval1_NaN]#`vmfne` writes 1 to the destination element when either +operand is NaN,# [#norm:vmfeq_vmflt_vmfle_vmfgt_vmfge_vdval0_NaN]#whereas the other compares write 0 when either operand +is NaN.# + +---- +# Compare equal +vmfeq.vv vd, vs2, vs1, vm # Vector-vector +vmfeq.vf vd, vs2, rs1, vm # vector-scalar + +# Compare not equal +vmfne.vv vd, vs2, vs1, vm # Vector-vector +vmfne.vf vd, vs2, rs1, vm # vector-scalar + +# Compare less than +vmflt.vv vd, vs2, vs1, vm # Vector-vector +vmflt.vf vd, vs2, rs1, vm # vector-scalar + +# Compare less than or equal +vmfle.vv vd, vs2, vs1, vm # Vector-vector +vmfle.vf vd, vs2, rs1, vm # vector-scalar + +# Compare greater than +vmfgt.vf vd, vs2, rs1, vm # vector-scalar + +# Compare greater than or equal +vmfge.vf vd, vs2, rs1, vm # vector-scalar +---- + +---- +Comparison Assembler Mapping Assembler pseudoinstruction + +va < vb vmflt.vv vd, va, vb, vm +va <= vb vmfle.vv vd, va, vb, vm +va > vb vmflt.vv vd, vb, va, vm vmfgt.vv vd, va, vb, vm +va >= vb vmfle.vv vd, vb, va, vm vmfge.vv vd, va, vb, vm + +va < f vmflt.vf vd, va, f, vm +va <= f vmfle.vf vd, va, f, vm +va > f vmfgt.vf vd, va, f, vm +va >= f vmfge.vf vd, va, f, vm + +va, vb vector register groups +f scalar floating-point register +---- + +NOTE: Providing all forms is necessary to correctly handle unordered +compares for NaNs. + +NOTE: C99 floating-point quiet compares can be implemented by masking +the signaling compares when either input is NaN, as follows. When +the comparand is a non-NaN constant, the middle two instructions can be +omitted. + +---- +# Example of implementing isgreater() +vmfeq.vv v0, va, va # Only set where A is not NaN. +vmfeq.vv v1, vb, vb # Only set where B is not NaN. +vmand.mm v0, v0, v1 # Only set where A and B are ordered, +vmfgt.vv v0, va, vb, v0.t # so only set flags on ordered values. +---- + +NOTE: In the above sequence, it is tempting to mask the second `vmfeq` +instruction and remove the `vmand` instruction, but this more efficient +sequence incorrectly fails to raise the invalid exception when an +element of `va` contains a quiet NaN and the corresponding element in +`vb` contains a signaling NaN. + +==== Vector Floating-Point Classify Instruction + +[#norm:vfclass_op]#This is a unary vector-vector instruction that operates in the same +way as the scalar classify instruction.# + +---- +vfclass.v vd, vs2, vm # Vector-vector +---- + +[#norm:vfclass_op_result]#The 10-bit mask produced by this instruction is placed in the +least-significant bits of the result elements. The upper (SEW-10) +bits of the result are filled with zeros.# [#norm:vfclass_SEWge16]#The instruction is only +defined for SEW=16b and above, so the result will always fit in the +destination elements.# + +==== Vector Floating-Point Merge Instruction + +[#norm:vfmerge_op]#A vector-scalar floating-point merge instruction is provided,# which +[#norm:vfmerge_all_elem]#operates on all body elements from `vstart` up to the current vector +length in `vl` regardless of mask value.# + +The `vfmerge.vfm` instruction is encoded as a masked instruction (`vm=0`). +[#norm:vfmerge_op_mask]#At elements where the mask value is zero, the first vector operand is +copied to the destination element, otherwise a scalar floating-point +register value is copied to the destination element.# + +---- +vfmerge.vfm vd, vs2, rs1, v0 # vd[i] = v0.mask[i] ? f[rs1] : vs2[i] +---- + +==== Vector Floating-Point Move Instruction + +[#norm:vfmv_op]#The vector floating-point move instruction __splats__ a floating-point +scalar operand to a vector register group. The instruction copies a +scalar `f` register value to all active elements of a vector register +group.# This instruction is encoded as an unmasked instruction (`vm=1`). +[#norm:vfmv_vs2_nv0_rsv]#The instruction must have the `vs2` field set to `v0`, with all other +values for `vs2` reserved.# + +---- +vfmv.v.f vd, rs1 # vd[i] = f[rs1] +---- + +NOTE: The `vfmv.v.f` instruction shares the encoding with the `vfmerge.vfm` +instruction, but with `vm=1` and `vs2=v0`. + +==== Single-Width Floating-Point/Integer Type-Convert Instructions + +[#norm:vfcvt_op]#Conversion operations are provided to convert to and from +floating-point values and unsigned and signed integers, where both +source and destination are SEW wide.# + +---- +vfcvt.xu.f.v vd, vs2, vm # Convert float to unsigned integer. +vfcvt.x.f.v vd, vs2, vm # Convert float to signed integer. + +vfcvt.rtz.xu.f.v vd, vs2, vm # Convert float to unsigned integer, truncating. +vfcvt.rtz.x.f.v vd, vs2, vm # Convert float to signed integer, truncating. + +vfcvt.f.xu.v vd, vs2, vm # Convert unsigned integer to float. +vfcvt.f.x.v vd, vs2, vm # Convert signed integer to float. +---- + +[#norm:vfcvt_op_exceptions]#The conversions follow the same rules on exceptional conditions as the +scalar conversion instructions.# +[#norm:vfcvt_op_frm]#The conversions use the dynamic rounding mode in `frm`, except for the `rtz` +variants, which round towards zero.# + +NOTE: The `rtz` variants are provided to accelerate truncating conversions +from floating-point to integer, as is common in languages like C and Java. + +==== Widening Floating-Point/Integer Type-Convert Instructions + +[#norm:vfwcvt_op]#A set of conversion instructions is provided to convert between +narrower integer and floating-point datatypes to a type of twice the +width.# + +---- +vfwcvt.xu.f.v vd, vs2, vm # Convert float to double-width unsigned integer. +vfwcvt.x.f.v vd, vs2, vm # Convert float to double-width signed integer. + +vfwcvt.rtz.xu.f.v vd, vs2, vm # Convert float to double-width unsigned integer, truncating. +vfwcvt.rtz.x.f.v vd, vs2, vm # Convert float to double-width signed integer, truncating. + +vfwcvt.f.xu.v vd, vs2, vm # Convert unsigned integer to double-width float. +vfwcvt.f.x.v vd, vs2, vm # Convert signed integer to double-width float. + +vfwcvt.f.f.v vd, vs2, vm # Convert single-width float to double-width float. +---- + +[#norm:vfwcvt_vreg_constr]#These instructions have the same constraints on vector register overlap +as other widening instructions (see <>).# + +NOTE: A double-width IEEE floating-point value can always represent a +single-width integer exactly. + +NOTE: A double-width IEEE floating-point value can always represent a +single-width IEEE floating-point value exactly. + +NOTE: A full set of floating-point widening conversions is not +supported as single instructions, but any widening conversion can be +implemented as several doubling steps with equivalent results and no +additional exception flags raised. + +==== Narrowing Floating-Point/Integer Type-Convert Instructions + +[#norm:vfncvt_op]#A set of conversion instructions is provided to convert wider integer +and floating-point datatypes to a type of half the width.# + +---- +vfncvt.xu.f.w vd, vs2, vm # Convert double-width float to unsigned integer. +vfncvt.x.f.w vd, vs2, vm # Convert double-width float to signed integer. + +vfncvt.rtz.xu.f.w vd, vs2, vm # Convert double-width float to unsigned integer, truncating. +vfncvt.rtz.x.f.w vd, vs2, vm # Convert double-width float to signed integer, truncating. + +vfncvt.f.xu.w vd, vs2, vm # Convert double-width unsigned integer to float. +vfncvt.f.x.w vd, vs2, vm # Convert double-width signed integer to float. + +vfncvt.f.f.w vd, vs2, vm # Convert double-width float to single-width float. +vfncvt.rod.f.f.w vd, vs2, vm # Convert double-width float to single-width float, + # rounding towards odd. +---- + +[#norm:vfncvt_vreg_constr]#These instructions have the same constraints on vector register overlap +as other narrowing instructions (see <>).# + +NOTE: A full set of floating-point narrowing conversions is not +supported as single instructions. Conversions can be implemented in +a sequence of halving steps. Results are equivalently rounded and +the same exception flags are raised if all but the last halving step +use round-towards-odd (`vfncvt.rod.f.f.w`). Only the final step +should use the desired rounding mode. + +NOTE: For `vfncvt.rod.f.f.w`, a finite value that exceeds the range of the +destination format is converted to the destination format's largest finite value with the same sign. + +=== Vector Reduction Operations + +[#norm:vreduction_scalar_def]#Vector reduction operations take a vector register group of elements +and a scalar held in element 0 of a vector register, and perform a +reduction using some binary operator, to produce a scalar result in +element 0 of a vector register.# [#norm:vreduction_scalar_disregard_LMUL]#The scalar input and output operands +are held in element 0 of a single vector register, not a vector +register group, so any vector register can be the scalar source or +destination of a vector reduction regardless of LMUL setting.# + +[#norm:vreduction_vd_overlap_vs]#The destination vector register can overlap the source operands, +including the mask register.# + +NOTE: Vector reductions read and write the scalar operand and result +into element 0 of a vector register instead of a scalar register to +avoid a loss of decoupling with the scalar processor, and to support +future polymorphic use with future types not supported in the scalar +unit. + +[#norm:vreduction_scalar_disregard_maskval]#Inactive elements from the source vector register group are excluded +from the reduction, but the scalar operand is always included +regardless of the mask values.# + +[#norm:vreduction_tail_policy]#The other elements in the destination vector register ( 0 < index < +VLEN/SEW) are considered the tail and are managed with the current +tail agnostic/undisturbed policy.# + +[#norm:vreduction_vl_0]#If `vl`=0, no operation is performed and the destination register is +not updated.# + +NOTE: This choice of behavior for `vl`=0 reduces implementation +complexity as it is consistent with other operations on vector +register state. For the common case that the source and destination +scalar operand are the same vector register, this behavior also +produces the expected result. For the uncommon case that the source +and destination scalar operand are in different vector registers, this +instruction will not copy the source into the destination when `vl`=0. +However, it is expected that in most of these cases it will be +statically known that `vl` is not zero. In other cases, a check for +`vl`=0 will have to be added to ensure that the source scalar is +copied to the destination (e.g., by explicitly setting `vl`=1 and +performing a register-register copy). + +[#norm:vreduction_trap]#Traps on vector reduction instructions are always reported with a +`vstart` of 0.# [#norm:vreduction_vstart_n0_ill]#Vector reduction operations raise an +illegal-instruction exception if `vstart` is non-zero.# + +The assembler syntax for a reduction operation is `vredop.vs`, where +the `.vs` suffix denotes the first operand is a vector register group +and the second operand is a scalar stored in element 0 of a vector +register. + +[[sec-vector-integer-reduce]] +==== Vector Single-Width Integer Reduction Instructions + +[#norm:vredsum_vredmaxu_vredmax_vredminu_vredmin_vredand_vredor_vredxor_op]#All operands and results of single-width reduction instructions have +the same SEW width.# [#norm:vredsum_vredmaxu_vredmax_vredminu_vredmin_vredand_vredor_vredxor_overflow]#Overflows wrap around on arithmetic sums.# + +---- +# Simple reductions, where [*] denotes all active elements: +vredsum.vs vd, vs2, vs1, vm # vd[0] = sum( vs1[0] , vs2[*] ) +vredmaxu.vs vd, vs2, vs1, vm # vd[0] = maxu( vs1[0] , vs2[*] ) +vredmax.vs vd, vs2, vs1, vm # vd[0] = max( vs1[0] , vs2[*] ) +vredminu.vs vd, vs2, vs1, vm # vd[0] = minu( vs1[0] , vs2[*] ) +vredmin.vs vd, vs2, vs1, vm # vd[0] = min( vs1[0] , vs2[*] ) +vredand.vs vd, vs2, vs1, vm # vd[0] = and( vs1[0] , vs2[*] ) +vredor.vs vd, vs2, vs1, vm # vd[0] = or( vs1[0] , vs2[*] ) +vredxor.vs vd, vs2, vs1, vm # vd[0] = xor( vs1[0] , vs2[*] ) +---- + +[[sec-vector-integer-reduce-widen]] +==== Vector Widening Integer Reduction Instructions + +[#norm:vwredsumu_op]#The unsigned `vwredsumu.vs` instruction zero-extends the SEW-wide +vector elements before summing them, then adds the 2*SEW-width scalar +element, and stores the result in a 2*SEW-width scalar element.# + +[#norm:vwredsum_op]#The `vwredsum.vs` instruction sign-extends the SEW-wide vector +elements before summing them.# + +[#norm:vwredsumu_vwredsum_op_overflow]#For both `vwredsumu.vs` and `vwredsum.vs`, overflows wrap around.# + +---- +# Unsigned sum reduction into double-width accumulator +vwredsumu.vs vd, vs2, vs1, vm # 2*SEW = 2*SEW + sum(zero-extend(SEW)) + +# Signed sum reduction into double-width accumulator +vwredsum.vs vd, vs2, vs1, vm # 2*SEW = 2*SEW + sum(sign-extend(SEW)) +---- + +[[sec-vector-float-reduce]] +==== Vector Single-Width Floating-Point Reduction Instructions + +---- +# Simple reductions. +vfredosum.vs vd, vs2, vs1, vm # Ordered sum +vfredusum.vs vd, vs2, vs1, vm # Unordered sum +vfredmax.vs vd, vs2, vs1, vm # Maximum value +vfredmin.vs vd, vs2, vs1, vm # Minimum value +---- + +NOTE: Older assembler mnemonic `vfredsum` is retained as alias for `vfredusum`. + +===== Vector Ordered Single-Width Floating-Point Sum Reduction + +[#norm:vfredosum_op]#The `vfredosum` instruction must sum the floating-point values in +element order, starting with the scalar in `vs1[0]`#--that is, it +performs the computation: + +---- + vd[0] = (((vs1[0] + vs2[0]) + vs2[1]) + ...) + vs2[vl-1] +---- +[#norm:vfredosum_op_exceptions]#where each addition operates identically to the scalar floating-point +instructions in terms of raising exception flags and generating or +propagating special values.# + +NOTE: The ordered reduction supports compiler auto-vectorization, while +the unordered FP sum allows for faster implementations. + +[#norm:vfredosum_maskoff]#When the operation is masked (`vm=0`), the masked-off elements do not +affect the result or the exception flags.# + +NOTE: If no elements are active, no additions are performed, so the scalar in +`vs1[0]` is simply copied to the destination register, without canonicalizing +NaN values and without setting any exception flags. This behavior preserves +the handling of NaNs, exceptions, and rounding when auto-vectorizing a scalar +summation loop. + +===== Vector Unordered Single-Width Floating-Point Sum Reduction + +The unordered sum reduction instruction, `vfredusum`, provides an +implementation more freedom in performing the reduction. + +[#norm:vfredusum_op]#The implementation must produce a result equivalent to a reduction tree +composed of binary operator nodes, with the inputs being elements from +the source vector register group (`vs2`) and the source scalar value +(`vs1[0]`). Each operator in the tree accepts two inputs and produces +one result. +Each operator first computes an exact sum as a RISC-V scalar floating-point +addition with infinite exponent range and precision, then converts this exact +sum to a floating-point format with range and precision each at least as great +as the element floating-point format indicated by SEW, rounding using the +currently active floating-point dynamic rounding mode and raising exception +flags as necessary. +A different floating-point range and precision may be chosen for the result of +each operator. +A node where one input is derived only from elements masked-off or beyond the +active vector length may either treat that input as the additive identity of the +appropriate EEW or simply copy the other input to its output. +The rounded result from the root node in the tree is converted (rounded again, +using the dynamic rounding mode) to the standard floating-point format +indicated by SEW.# +An implementation +is allowed to add an additional additive identity to the final result. + +[#norm:vfredusum_additive_impl]#The additive identity is +0.0 when rounding down (towards -{inf}) or +-0.0 for all other rounding modes.# + +[#norm:vfredusum_redtree]#The reduction tree structure must be deterministic for a given value +in `vtype` and `vl`.# + +NOTE: As a consequence of this definition, implementations need not propagate +NaN payloads through the reduction tree when no elements are active. In +particular, if no elements are active and the scalar input is NaN, +implementations are permitted to canonicalize the NaN and, if the NaN is +signaling, set the invalid exception flag. Implementations are alternatively +permitted to pass through the original NaN and set no exception flags, as with +`vfredosum`. + +NOTE: The `vfredosum` instruction is a valid implementation of the +`vfredusum` instruction. + +===== Vector Single-Width Floating-Point Max and Min Reductions + +[#norm:vfredmin_vfredmax_op]#The `vfredmin` and `vfredmax` instructions reduce the scalar argument in +`vs1[0]` and active elements in `vs2` using the `minimumNumber` and +`maximumNumber` operations, respectively.# + +NOTE: Floating-point max and min reductions should return the same +final value and raise the same exception flags regardless of operation +order. + +NOTE: If no elements are active, the scalar in `vs1[0]` is simply copied to +the destination register, without canonicalizing NaN values and without +setting any exception flags. + +[[sec-vector-float-reduce-widen]] +==== Vector Widening Floating-Point Reduction Instructions + +[#norm:vfwredosum_vfwredusum_op]#Widening forms of the sum reductions are provided that +read and write a double-width reduction result.# + +---- + # Simple reductions. + vfwredosum.vs vd, vs2, vs1, vm # Ordered sum + vfwredusum.vs vd, vs2, vs1, vm # Unordered sum +---- + +NOTE: Older assembler mnemonic `vfwredsum` is retained as alias for `vfwredusum`. + +[#norm:vfwredosum_vfwredusum_op_reduction]#The reduction of the SEW-width elements is performed as in the +single-width reduction case, with the elements in `vs2` promoted +to 2*SEW bits before adding to the 2*SEW-bit accumulator.# + +NOTE: `vfwredosum.vs` handles inactive elements and NaN payloads analogously +to `vfredosum.vs`; `vfwredusum.vs` does so analogously to `vfredusum.vs`. + +[[sec-vector-mask]] +=== Vector Mask Instructions + +Several instructions are provided to help operate on mask values held in +a vector register. + +[[sec-mask-register-logical]] +==== Vector Mask-Register Logical Instructions + +[#norm:vmask_maskreg_def]#Vector mask-register logical operations operate on mask registers. +Each element in a mask register is a single bit,# [#norm:instrgrp_vmask_disregard_vlmul]#so these instructions +all operate on single vector registers regardless of the setting of +the `vlmul` field in `vtype`. They do not change the value of +`vlmul`.# [#norm:vmask_vd_overlap_vs]#The destination vector register may be the same as either +source vector register.# + +[#norm:vmask_vstart]#As with other vector instructions, the elements with indices less than +`vstart` are unchanged, and `vstart` is reset to zero after execution.# +[#norm:vmasklogical_unmasked]#Vector mask logical instructions are always unmasked,# [#norm:vmasklogical_masked_rsv]#so there are no +inactive elements, and the encodings with `vm=0` are reserved.# +[#norm:vmasklogical_tail_agnostic]#Mask elements past `vl`, the tail elements, are +always updated with a tail-agnostic policy.# + +[#norm:vmand_vmnand_vmandn_vmxor_vmor_vmnor_vmorn_vmxnor_op] +---- +vmand.mm vd, vs2, vs1 # vd.mask[i] = vs2.mask[i] && vs1.mask[i] +vmnand.mm vd, vs2, vs1 # vd.mask[i] = !(vs2.mask[i] && vs1.mask[i]) +vmandn.mm vd, vs2, vs1 # vd.mask[i] = vs2.mask[i] && !vs1.mask[i] +vmxor.mm vd, vs2, vs1 # vd.mask[i] = vs2.mask[i] ^^ vs1.mask[i] +vmor.mm vd, vs2, vs1 # vd.mask[i] = vs2.mask[i] || vs1.mask[i] +vmnor.mm vd, vs2, vs1 # vd.mask[i] = !(vs2.mask[i] || vs1.mask[i]) +vmorn.mm vd, vs2, vs1 # vd.mask[i] = vs2.mask[i] || !vs1.mask[i] +vmxnor.mm vd, vs2, vs1 # vd.mask[i] = !(vs2.mask[i] ^^ vs1.mask[i]) +---- + +NOTE: The previous assembler mnemonics `vmandnot` and `vmornot` have +been changed to `vmandn` and `vmorn` to be consistent with the +equivalent scalar instructions. The old `vmandnot` and `vmornot` +mnemonics can be retained as assembler aliases for compatibility. + +Several assembler pseudoinstructions are defined as shorthand for +common uses of mask logical operations: +---- +vmmv.m vd, vs => vmand.mm vd, vs, vs # Copy mask register +vmclr.m vd => vmxor.mm vd, vd, vd # Clear mask register +vmset.m vd => vmxnor.mm vd, vd, vd # Set mask register +vmnot.m vd, vs => vmnand.mm vd, vs, vs # Invert bits +---- + +NOTE: The `vmmv.m` instruction was previously called `vmcpy.m`, but +with new layout it is more consistent to name as a "mv" because bits +are copied without interpretation. The `vmcpy.m` assembler +pseudoinstruction can be retained for compatibility. For +implementations that internally rearrange bits according to EEW, a +`vmmv.m` instruction with same source and destination can be used as +idiom to force an internal reformat into a mask vector. + +The set of eight mask logical instructions can generate any of the 16 +possibly binary logical functions of the two input masks: + +[cols="1,1,1,1,12"] +|=== +4+| inputs | + +| 0 | 0 | 1 | 1 | src1 +| 0 | 1 | 0 | 1 | src2 +|=== + +[cols="1,1,1,1,6,6"] +|=== +4+| output | instruction | pseudoinstruction + +| 0 | 0 | 0 | 0 | vmxor.mm vd, vd, vd | vmclr.m vd +| 1 | 0 | 0 | 0 | vmnor.mm vd, src1, src2 | +| 0 | 1 | 0 | 0 | vmandn.mm vd, src2, src1 | +| 1 | 1 | 0 | 0 | vmnand.mm vd, src1, src1 | vmnot.m vd, src1 +| 0 | 0 | 1 | 0 | vmandn.mm vd, src1, src2 | +| 1 | 0 | 1 | 0 | vmnand.mm vd, src2, src2 | vmnot.m vd, src2 +| 0 | 1 | 1 | 0 | vmxor.mm vd, src1, src2 | +| 1 | 1 | 1 | 0 | vmnand.mm vd, src1, src2 | +| 0 | 0 | 0 | 1 | vmand.mm vd, src1, src2 | +| 1 | 0 | 0 | 1 | vmxnor.mm vd, src1, src2 | +| 0 | 1 | 0 | 1 | vmand.mm vd, src2, src2 | vmmv.m vd, src2 +| 1 | 1 | 0 | 1 | vmorn.mm vd, src2, src1 | +| 0 | 0 | 1 | 1 | vmand.mm vd, src1, src1 | vmmv.m vd, src1 +| 1 | 0 | 1 | 1 | vmorn.mm vd, src1, src2 | +| 0 | 1 | 1 | 1 | vmor.mm vd, src1, src2 | +| 1 | 1 | 1 | 1 | vmxnor.mm vd, vd, vd | vmset.m vd +|=== + +NOTE: The vector mask logical instructions are designed to be easily +fused with a following masked vector operation to effectively expand +the number of predicate registers by moving values into `v0` before +use. + + +==== Vector count population in mask `vcpop.m` + +---- +vcpop.m rd, vs2, vm +---- + +NOTE: This instruction previously had the assembler mnemonic `vpopc.m` +but was renamed to be consistent with the scalar instruction. The +assembler instruction alias `vpopc.m` is being retained for software +compatibility. + +[#norm:vcpop_vs_single_vreg]#The source operand is a single vector register holding mask register +values as described in <>.# + +[#norm:vcpop_op]#The `vcpop.m` instruction counts the number of mask elements of the +active elements of the vector source mask register that have the value +1 and writes the result to a scalar `x` register.# + +[#norm:vcpop_op_mask]#The operation can be performed under a mask, in which case only the +masked elements are counted.# + +---- +vcpop.m rd, vs2, v0.t # x[rd] = sum_i ( vs2.mask[i] && v0.mask[i] ) +---- + +[#norm:vcpop_vl0]#The `vcpop.m` instruction writes `x[rd]` even if `vl`=0 (with the +value 0, since no mask elements are active).# + +[#norm:vcpop_trap]#Traps on `vcpop.m` are always reported with a `vstart` of 0.# [#norm:vcpop_vstart_n0_ill]#The +`vcpop.m` instruction will raise an illegal-instruction exception if +`vstart` is non-zero.# + +==== `vfirst` find-first-set mask bit + +---- +vfirst.m rd, vs2, vm +---- + +[#norm:vfirst_op]#The `vfirst` instruction finds the lowest-numbered active element of +the source mask vector that has the value 1 and writes that element's +index to a GPR. If no active element has the value 1, -1 is written +to the GPR.# + +NOTE: Software can assume that any negative value (highest bit set) +corresponds to no element found, as vector lengths will never reach +2^(XLEN-1)^ on any implementation. + +[#norm:vfirst_vl0]#The `vfirst.m` instruction writes `x[rd]` even if `vl`=0 (with the +value -1, since no mask elements are active).# + +[#norm:vfirst_trap]#Traps on `vfirst` are always reported with a `vstart` of 0.# [#norm:vfirst_vstart_n0_ill]#The +`vfirst` instruction will raise an illegal-instruction exception if +`vstart` is non-zero.# + +==== `vmsbf.m` set-before-first mask bit + +---- + vmsbf.m vd, vs2, vm + + # Example + + 7 6 5 4 3 2 1 0 Element number + + 1 0 0 1 0 1 0 0 v3 contents + vmsbf.m v2, v3 + 0 0 0 0 0 0 1 1 v2 contents + + 1 0 0 1 0 1 0 1 v3 contents + vmsbf.m v2, v3 + 0 0 0 0 0 0 0 0 v2 + + 0 0 0 0 0 0 0 0 v3 contents + vmsbf.m v2, v3 + 1 1 1 1 1 1 1 1 v2 + + 1 1 0 0 0 0 1 1 v0 vcontents + 1 0 0 1 0 1 0 0 v3 contents + vmsbf.m v2, v3, v0.t + 0 1 x x x x 1 1 v2 contents +---- + +[#norm:vmsbf_op]#The `vmsbf.m` instruction takes a mask register as input and writes +results to a mask register. The instruction writes a 1 to all active +mask elements before the first active source element that is a 1, then +writes a 0 to that element and all following active elements. If +there is no set bit in the active elements of the source vector, then +all active elements in the destination are written with a 1.# + +[#norm:vmsbf_tail_agnostic]#The tail elements in the destination mask register are updated under a +tail-agnostic policy.# + +[#norm:vmsbf_trap]#Traps on `vmsbf.m` are always reported with a `vstart` of 0.# [#norm:vmsbf_vstart_n0_ill]#The +`vmsbf` instruction will raise an illegal-instruction exception if +`vstart` is non-zero.# + +[#norm:vmsbf_vreg_constr]#The destination register cannot overlap the source register +and, if masked, cannot overlap the mask register ('v0').# + +==== `vmsif.m` set-including-first mask bit + +[#norm:vmsif_op]#The vector mask set-including-first instruction is similar to +set-before-first, except it also includes the element with a set bit.# + +---- + vmsif.m vd, vs2, vm + + # Example + + 7 6 5 4 3 2 1 0 Element number + + 1 0 0 1 0 1 0 0 v3 contents + vmsif.m v2, v3 + 0 0 0 0 0 1 1 1 v2 contents + + 1 0 0 1 0 1 0 1 v3 contents + vmsif.m v2, v3 + 0 0 0 0 0 0 0 1 v2 + + 1 1 0 0 0 0 1 1 v0 vcontents + 1 0 0 1 0 1 0 0 v3 contents + vmsif.m v2, v3, v0.t + 1 1 x x x x 1 1 v2 contents +---- + +[#norm:vmsif_tail_agnostic]#The tail elements in the destination mask register are updated under a +tail-agnostic policy.# + +[#norm:vmsif_trap]#Traps on `vmsif.m` are always reported with a `vstart` of 0.# [#norm:vmsif_vstart_n0_ill]#The +`vmsif` instruction will raise an illegal-instruction exception if +`vstart` is non-zero.# + +[#norm:vmsif_vreg_constr]#The destination register cannot overlap the source register +and, if masked, cannot overlap the mask register ('v0').# + +==== `vmsof.m` set-only-first mask bit + +[#norm:vmsof_op]#The vector mask set-only-first instruction is similar to +set-before-first, except it only sets the first element with a bit +set, if any.# + +---- + vmsof.m vd, vs2, vm + + # Example + + 7 6 5 4 3 2 1 0 Element number + + 1 0 0 1 0 1 0 0 v3 contents + vmsof.m v2, v3 + 0 0 0 0 0 1 0 0 v2 contents + + 1 0 0 1 0 1 0 1 v3 contents + vmsof.m v2, v3 + 0 0 0 0 0 0 0 1 v2 + + 1 1 0 0 0 0 1 1 v0 vcontents + 1 1 0 1 0 1 0 0 v3 contents + vmsof.m v2, v3, v0.t + 0 1 x x x x 0 0 v2 contents +---- + +[#norm:vmsof_tail_agnostic]#The tail elements in the destination mask register are updated under a +tail-agnostic policy.# + +[#norm:vmsof_trap]#Traps on `vmsof.m` are always reported with a `vstart` of 0.# [#norm:vmsof_vstart_n0_ill]#The +`vmsof` instruction will raise an illegal-instruction exception if +`vstart` is non-zero.# + +[#norm:vmsof_vreg_constr]#The destination register cannot overlap the source register +and, if masked, cannot overlap the mask register ('v0').# + +==== Example using vector mask instructions + +The following is an example of vectorizing a data-dependent exit loop. + +---- +include::example/strcpy.s[lines=4..-1] +---- +---- +include::example/strncpy.s[lines=4..-1] +---- + +==== Vector Iota Instruction + +[#norm:viota_op]#The `viota.m` instruction reads a source vector mask register and +writes to each element of the destination vector register group the +sum of all the bits of elements in the mask register +whose index is less than the element, e.g., a parallel prefix sum of +the mask values.# + +[#norm:viota_op_masked]#This instruction can be masked, in which case only the enabled +elements contribute to the sum.# + +---- + viota.m vd, vs2, vm + + # Example + + 7 6 5 4 3 2 1 0 Element number + + 1 0 0 1 0 0 0 1 v2 contents + viota.m v4, v2 # Unmasked + 2 2 2 1 1 1 1 0 v4 result + + 1 1 1 0 1 0 1 1 v0 contents + 1 0 0 1 0 0 0 1 v2 contents + 2 3 4 5 6 7 8 9 v4 contents + viota.m v4, v2, v0.t # Masked, vtype.vma=0 + 1 1 1 5 1 7 1 0 v4 results +---- + +[#norm:viota_op_zext]#The result value is zero-extended to fill the destination element if +SEW is wider than the result.# [#norm:viota_op_overflow]#If the result value would overflow the +destination SEW, the least-significant SEW bits are retained.# + +[#norm:viota_trap]#Traps on `viota.m` are always reported with a `vstart` of 0,# and +[#norm:viota_restart]#execution is always restarted from the beginning when resuming after a +trap handler.# [#norm:viota_vstart_n0_ill]#An illegal-instruction exception is raised if `vstart` +is non-zero.# + +[#norm:viota_vreg_constr]#The destination register group cannot overlap the source register +and, if masked, cannot overlap the mask register (`v0`).# + +The `viota.m` instruction can be combined with memory scatter +instructions (indexed stores) to perform vector compress functions. + +---- +# Compact non-zero elements from input memory array to output memory array +# +# size_t compact_non_zero(size_t n, const int* in, int* out) +# { +# size_t i; +# int *p = out; +# +# for (i=0; i XLEN, the +least-significant XLEN bits are transferred and the upper SEW-XLEN bits are +ignored. If SEW < XLEN, the value is sign-extended to XLEN bits.# + +NOTE: [#norm:vmv-x-s_vstartgevl_vl0]#`vmv.x.s` performs its operation even if `vstart` {ge} `vl` or `vl`=0.# + +[#norm:vmv-s-x_op]#The `vmv.s.x` instruction copies the scalar integer register to element 0 of +the destination vector register. If SEW < XLEN, the least-significant bits +are copied and the upper XLEN-SEW bits are ignored. If SEW > XLEN, the value +is sign-extended to SEW bits. The other elements in the destination vector +register ( 0 < index < VLEN/SEW) are treated as tail elements using the current tail agnostic/undisturbed policy.# [#norm:vmv-s-x_vstart_ge_vl]#If `vstart` {ge} `vl`, no +operation is performed and the destination register is not updated.# + +NOTE: As a consequence, when `vl`=0, no elements are updated in the +destination vector register group, regardless of `vstart`. + +[#norm:vmv-s-x_vmv-x-s_masked_rsv]#The encodings corresponding to the masked versions (`vm=0`) of `vmv.x.s` +and `vmv.s.x` are reserved.# + +[[sec-vector-float-move]] +==== Floating-Point Scalar Move Instructions + +The floating-point scalar read/write instructions transfer a single +value between a scalar `f` register and element 0 of a vector +register. [#norm:vfmv-f-s_vfmv-s-f_ignoreLMUL]#The instructions ignore LMUL and vector register groups.# + +---- +vfmv.f.s rd, vs2 # f[rd] = vs2[0] (rs1=0) +vfmv.s.f vd, rs1 # vd[0] = f[rs1] (vs2=0) +---- + +[#norm:vfmv-f-s_op]#The `vfmv.f.s` instruction copies a single SEW-wide element from index +0 of the source vector register to a destination scalar floating-point +register.# + +NOTE: `vfmv.f.s` performs its operation even if `vstart` {ge} `vl` or `vl`=0. + +[#norm:vfmv-s-f_op]#The `vfmv.s.f` instruction copies the scalar floating-point register +to element 0 of the destination vector register. The other elements +in the destination vector register ( 0 < index < VLEN/SEW) are treated +as tail elements using the current tail agnostic/undisturbed policy.# +[#norm:vfmv-s-f_vstart_ge_vl]#If `vstart` {ge} `vl`, no operation is performed and the destination +register is not updated.# + +NOTE: As a consequence, when `vl`=0, no elements are updated in the +destination vector register group, regardless of `vstart`. + +[#norm:vfmv-s-f_masked_rsv]#The encodings corresponding to the masked versions (`vm=0`) of `vfmv.f.s` +and `vfmv.s.f` are reserved.# + +==== Vector Slide Instructions + +The slide instructions move elements up and down a vector register +group. + +NOTE: The slide operations can be implemented much more efficiently +than using the arbitrary register gather instruction. Implementations +may optimize certain OFFSET values for `vslideup` and `vslidedown`. +In particular, power-of-2 offsets may operate substantially faster +than other offsets. + +[#norm:vslide_vstart_ge_vl]#For all of the `vslideup`, `vslidedown`, `v[f]slide1up`, and +`v[f]slide1down` instructions, if `vstart` {ge} `vl`, the instruction performs no +operation and leaves the destination vector register unchanged.# + +NOTE: As a consequence, when `vl`=0, no elements are updated in the +destination vector register group, regardless of `vstart`. + +The tail agnostic/undisturbed policy is followed for tail elements. + +[#norm:vslide_mask]#The slide instructions may be masked, with mask element _i_ +controlling whether _destination_ element _i_ is written. The mask +undisturbed/agnostic policy is followed for inactive elements.# + +===== Vector Slide-up Instructions + +---- +vslideup.vx vd, vs2, rs1, vm # vd[i+x[rs1]] = vs2[i] +vslideup.vi vd, vs2, uimm, vm # vd[i+uimm] = vs2[i] +---- + +[#norm:vslideup_op]#For `vslideup`, the value in `vl` specifies the maximum number of destination +elements that are written. The start index (_OFFSET_) for the +destination can be either specified using an unsigned integer in the +`x` register specified by `rs1`, or a 5-bit immediate, zero-extended to XLEN bits. +If XLEN > SEW, _OFFSET_ is _not_ truncated to SEW bits. +Destination elements _OFFSET_ through `vl`-1 are written if unmasked and +if _OFFSET_ < `vl`.# + +---- +vslideup behavior for destination elements (vstart < vl) + +OFFSET is amount to slideup, either from x register or a 5-bit immediate + + 0 <= i < min(vl, max(vstart, OFFSET)) Unchanged +max(vstart, OFFSET) <= i < vl vd[i] = vs2[i-OFFSET] if v0.mask[i] enabled + vl <= i < VLMAX Follow tail policy +---- + +[#norm:vslideup_vreg_constr]#The destination vector register group for `vslideup` cannot overlap +the source vector register group, otherwise the instruction encoding +is reserved.# + +NOTE: The non-overlap constraint avoids WAR hazards on the +input vectors during execution, and enables restart with non-zero +`vstart`. + +===== Vector Slide-down Instructions + +---- +vslidedown.vx vd, vs2, rs1, vm # vd[i] = vs2[i+x[rs1]] +vslidedown.vi vd, vs2, uimm, vm # vd[i] = vs2[i+uimm] +---- + +[#norm:vslidedown_op]#For `vslidedown`, the value in `vl` specifies the maximum number of +destination elements that are written. The remaining elements past +`vl` are handled according to the current tail policy +(<>).# + +[#norm:vslidedown_op_src]#The start index (_OFFSET_) for the source can be either specified +using an unsigned integer in the `x` register specified by `rs1`, or a +5-bit immediate, zero-extended to XLEN bits. +If XLEN > SEW, _OFFSET_ is _not_ truncated to SEW bits.# + +---- +vslidedown behavior for source elements for element i in slide (vstart < vl) + 0 <= i+OFFSET < VLMAX src[i] = vs2[i+OFFSET] + VLMAX <= i+OFFSET src[i] = 0 + +vslidedown behavior for destination element i in slide (vstart < vl) + 0 <= i < vstart Unchanged + vstart <= i < vl vd[i] = src[i] if v0.mask[i] enabled + vl <= i < VLMAX Follow tail policy +---- + +===== Vector Slide-1-up + +Variants of slide are provided that only move by one element but which +also allow a scalar integer value to be inserted at the vacated +element position. + +---- +vslide1up.vx vd, vs2, rs1, vm # vd[0]=x[rs1], vd[i+1] = vs2[i] +---- + +[#norm:vslide1up-vx_op]#The `vslide1up` instruction places the `x` register argument at +location 0 of the destination vector register group, provided that +element 0 is active, otherwise the destination element update follows the +current mask agnostic/undisturbed policy. If XLEN < SEW, the value is +sign-extended to SEW bits. If XLEN > SEW, the least-significant bits +are copied over and the high XLEN-SEW bits are ignored.# + +[#norm:vslide1up-vx_op_rem_elem]#The remaining active `vl`-1 elements are copied over from index _i_ in +the source vector register group to index _i_+1 in the destination +vector register group.# + +[#norm:vslide1up-vx_op_vl]#The `vl` register specifies the maximum number of destination vector +register elements updated with source values, and remaining elements +past `vl` are handled according to the current tail policy +(<>).# + + +---- +vslide1up behavior when vl > 0 + + i < vstart unchanged + 0 = i = vstart vd[i] = x[rs1] if v0.mask[i] enabled +max(vstart, 1) <= i < vl vd[i] = vs2[i-1] if v0.mask[i] enabled + vl <= i < VLMAX Follow tail policy +---- + +[#norm:vslide1up-vx_vreg_constr]#The `vslide1up` instruction requires that the destination vector +register group does not overlap the source vector register group. +Otherwise, the instruction encoding is reserved.# + +[[sec-vfslide1up]] +===== Vector Floating-Point Slide-1-up Instruction + +---- +vfslide1up.vf vd, vs2, rs1, vm # vd[0]=f[rs1], vd[i+1] = vs2[i] +---- + +[#norm:vslide1up-vf_op]#The `vfslide1up` instruction is defined analogously to `vslide1up`, +but sources its scalar argument from an `f` register.# + +===== Vector Slide-1-down Instruction + +[#norm:vslide1down-vx_op]#The `vslide1down` instruction copies the first `vl`-1 active elements +values from index _i_+1 in the source vector register group to index +_i_ in the destination vector register group.# + +[#norm:vslide1down-vx_op_vl]#The `vl` register specifies the maximum number of destination vector +register elements written with source values, and remaining elements +past `vl` are handled according to the current tail policy +(<>).# + +---- +vslide1down.vx vd, vs2, rs1, vm # vd[i] = vs2[i+1], vd[vl-1]=x[rs1] +---- + +[#norm:vslide1down-vx_op_details]#The `vslide1down` instruction places the `x` register argument at +location `vl`-1 in the destination vector register, provided that +element `vl-1` is active, otherwise the destination element update +follows the current mask agnostic/undisturbed policy. +If XLEN < SEW, the value is sign-extended to SEW bits. If +XLEN > SEW, the least-significant bits are copied over and the high +SEW-XLEN bits are ignored.# + +---- +vslide1down behavior + + i < vstart unchanged +vstart <= i < vl-1 vd[i] = vs2[i+1] if v0.mask[i] enabled +vstart <= i = vl-1 vd[vl-1] = x[rs1] if v0.mask[i] enabled + vl <= i < VLMAX Follow tail policy +---- + +NOTE: The `vslide1down` instruction can be used to load values into a +vector register without using memory and without disturbing other +vector registers. This provides a path for debuggers to modify the +contents of a vector register, albeit slowly, with multiple repeated +`vslide1down` invocations. + +[[sec-vfslide1down]] +===== Vector Floating-Point Slide-1-down Instruction + +---- +vfslide1down.vf vd, vs2, rs1, vm # vd[i] = vs2[i+1], vd[vl-1]=f[rs1] +---- + +[#norm:vslide1down-vf_op]#The `vfslide1down` instruction is defined analogously to `vslide1down`, +but sources its scalar argument from an `f` register.# + +==== Vector Register Gather Instructions + +The vector register gather instructions read elements from a first +source vector register group at locations given by a second source +vector register group. [#norm:vrgather_vrgatherei16_vs2_uint]#The index values in the second vector are +treated as unsigned integers.# [#norm:vrgather_vrgatherei16_vs_ignore_vl]#The source vector can be read at any +index < VLMAX regardless of `vl`.# [#norm:vrgather_vrgatherei16_vl]#The maximum number of elements to write to +the destination register is given by `vl`,# [#norm:vrgather_vrgatherei16_tail]#and the remaining elements +past `vl` are handled according to the current tail policy +(<>).# [#norm:vrgather_vrgatherei16_mask]#The operation can be masked, and the mask +undisturbed/agnostic policy is followed for inactive elements.# + +[#norm:vrgather-vv_op_vrgatherei16-vv_op] +---- +vrgather.vv vd, vs2, vs1, vm # vd[i] = (vs1[i] >= VLMAX) ? 0 : vs2[vs1[i]]; +vrgatherei16.vv vd, vs2, vs1, vm # vd[i] = (vs1[i] >= VLMAX) ? 0 : vs2[vs1[i]]; +---- + +[#norm:vrgather-vv_sew_lmul]#The `vrgather.vv` form uses SEW/LMUL for both the data and +indices.# [#norm:vrgatherei16-vv_sew_lmul]#The `vrgatherei16.vv` form uses SEW/LMUL for the data in +`vs2` but EEW=16 and EMUL = (16/SEW)*LMUL for the indices in `vs1`.# + +NOTE: When SEW=8, `vrgather.vv` can only reference vector elements +0-255. The `vrgatherei16` form can index 64K elements, and can also +be used to reduce the register capacity needed to hold indices when +SEW > 16. + +[#norm:vrgather_vrgatherei16_id_ge_VLMAX]#If an element index is out of range ( `vs1[i]` {ge} VLMAX ) +then zero is returned for the element value.# + +[#norm:vrgather-vx_vrgather-vi_op]#Vector-scalar and vector-immediate forms of the register gather are +also provided. These read one element from the source vector at the +given index, and write this value to the active elements +of the destination vector register. The index value in the scalar +register and the immediate, zero-extended to XLEN bits, are treated as +unsigned integers. If XLEN > SEW, the index value is _not_ truncated +to SEW bits.# + +NOTE: These forms allow any vector element to be "splatted" to an entire vector. + +---- +vrgather.vx vd, vs2, rs1, vm # vd[i] = (x[rs1] >= VLMAX) ? 0 : vs2[x[rs1]] +vrgather.vi vd, vs2, uimm, vm # vd[i] = (uimm >= VLMAX) ? 0 : vs2[uimm] +---- + +[#norm:vrgather_vrgatherei16_vreg_constr]#For any `vrgather` instruction, the destination vector register group +cannot overlap with the source vector register groups, otherwise the +instruction encoding is reserved.# + +==== Vector Compress Instruction + +The vector compress instruction allows elements selected by a vector +mask register from a source vector register group to be packed into +contiguous elements at the start of the destination vector register +group. + +---- +vcompress.vm vd, vs2, vs1 # Compress into vd elements of vs2 where vs1 is enabled +---- + +[#norm:vcompress_op]#The vector mask register specified by `vs1` indicates which of the +first `vl` elements of vector register group `vs2` should be extracted +and packed into contiguous elements at the beginning of vector +register `vd`. The remaining elements of `vd` are treated as tail +elements according to the current tail policy +(<>).# + +---- +Example use of vcompress instruction + +8 7 6 5 4 3 2 1 0 Element number + +1 1 0 1 0 0 1 0 1 v0 +8 7 6 5 4 3 2 1 0 v1 +1 2 3 4 5 6 7 8 9 v2 + vsetivli t0, 9, e8, m1, tu, ma + vcompress.vm v2, v1, v0 +1 2 3 4 8 7 5 2 0 v2 +---- + +[#norm:vcompress_enc]#T`vcompress` is encoded as an unmasked instruction (`vm=1`).# [#norm:vcompress_masked_rsv]#The equivalent +masked instruction (`vm=0`) is reserved.# + +[#norm:vcompress_vreg_constr]#The destination vector register group cannot overlap the source vector +register group or the source mask register, otherwise the instruction +encoding is reserved.# + +[#norm:vcompress_trap]#A trap on a `vcompress` instruction is always reported with a +`vstart` of 0.# [#norm:vcompress_vstart_n0_ill]#Executing a `vcompress` instruction with a non-zero +`vstart` raises an illegal-instruction exception.# + +NOTE: Although possible, `vcompress` is one of the more difficult +instructions to restart with a non-zero `vstart`, so assumption is +implementations will choose not do that but will instead restart from +element 0. This does mean elements in destination register after +`vstart` will already have been updated. + +===== Synthesizing `vdecompress` + +There is no inverse `vdecompress` provided, as this operation can be +readily synthesized using iota and a masked vrgather: + +---- +Desired functionality of 'vdecompress' +7 6 5 4 3 2 1 0 # vid + + e d c b a # packed vector of 5 elements +1 0 0 1 1 1 0 1 # mask vector of 8 elements +p q r s t u v w # destination register before vdecompress + +e q r d c b v a # result of vdecompress +---- + +---- +# v0 holds mask +# v1 holds packed data +# v11 holds input expanded vector and result +viota.m v10, v0 # Calc iota from mask in v0 +vrgather.vv v11, v1, v10, v0.t # Expand into destination +---- +---- +p q r s t u v w # v11 destination register + e d c b a # v1 source vector +1 0 0 1 1 1 0 1 # v0 mask vector + +4 4 4 3 2 1 1 0 # v10 result of viota.m +e q r d c b v a # v11 destination after vrgather using viota.m under mask +---- + +==== Whole Vector Register Move + +[#norm:vmv-nr-r_op]#The `vmvr.v` instructions copy whole vector registers (i.e., all +VLEN bits) and can copy whole vector register groups. The `nr` value +in the opcode is the number of individual vector registers, NREG, to +copy. The instructions operate as if EEW=SEW, EMUL = NREG, effective +length `evl`= EMUL * VLEN/SEW.# + +NOTE: These instructions are intended to aid compilers to shuffle +vector registers without needing to know or change `vl`. + +The usual property that no elements are written if `vstart` {ge} `vl` +does not apply to these instructions. +Similarly, the property that the instructions are reserved if `vstart` +exceeds the largest element index for the current `vtype` setting +does not apply. +Instead, the instructions are reserved if `vstart` {ge} `evl`. + +NOTE: If `vd` is equal to `vs2`, the instruction does not change any +vector register state. +Implementations that rearrange data internally can treat this instruction +as a hint that the register group will next be accessed with an EEW +equal to SEW. + +[#norm:vmv-nr-r_enc]#The instruction is encoded as an OPIVI instruction. The number of +vector registers to copy is encoded in the low three bits of the +`simm` field (`simm[2:0]`) using the same encoding as the `nf[2:0]` field for memory +instructions (Figure <>), i.e., `simm[2:0]` = NREG-1.# + +[#norm:vmv-nr-r_nreg_rsv]#The value of NREG must be 1, 2, 4, or 8, and values of `simm[4:0]` +other than 0, 1, 3, and 7 are reserved.# + +NOTE: A future extension may support other numbers of registers to be moved. + +NOTE: The instruction uses the same funct6 encoding as the `vsmul` +instruction but with an immediate operand, and only the unmasked +version (`vm=1`). This encoding is chosen as it is close to the +related `vmerge` encoding, and it is unlikely the `vsmul` instruction +would benefit from an immediate form. + +---- +vmvr.v vd, vs2 # General form + +vmv1r.v v1, v2 # Copy v1=v2 +vmv2r.v v10, v12 # Copy v10=v12; v11=v13 +vmv4r.v v4, v8 # Copy v4=v8; v5=v9; v6=v10; v7=v11 +vmv8r.v v0, v8 # Copy v0=v8; v1=v9; ...; v7=v15 +---- + +[#norm:vmv-nr-r_vreg_constr]#The source and destination vector register numbers must be aligned +appropriately for the vector register group size,# and [#norm:vmv-nr-r_unaligned_rsv]#encodings with +other vector register numbers are reserved.# + +NOTE: A future extension may relax the vector register alignment +restrictions. + +=== Exception Handling + +[#norm:epc_vstart_op_V_trap]#On a trap during a vector instruction (caused by either a synchronous +exception or an asynchronous interrupt), the existing `*epc` CSR is +written with a pointer to the trapping vector instruction, while the +`vstart` CSR contains the element index on which the trap was +taken.# + +NOTE: We chose to add a `vstart` CSR to allow resumption of a +partially executed vector instruction to reduce interrupt latencies +and to simplify forward-progress guarantees. This is similar to the +scheme in the IBM 3090 vector facility. To ensure forward progress +without the `vstart` CSR, implementations would have to guarantee an +entire vector instruction can always complete atomically without +generating a trap. This is particularly difficult to ensure in the +presence of constant-stride or scatter/gather operations and demand-paged +virtual memory. + +==== Precise vector traps + +NOTE: We assume most supervisor-mode environments with demand-paging +will require precise vector traps. + +Precise vector traps require that: + +. all instructions older than the trapping vector instruction have committed their results +. no instructions newer than the trapping vector instruction have altered architectural state +. any operations within the trapping vector instruction affecting result elements preceding the index in the `vstart` CSR have committed their results +. no operations within the trapping vector instruction affecting elements at or following the `vstart` CSR have altered architectural state except if restarting and completing the affected vector instruction will nevertheless produce the correct final state. + +We relax the last requirement to allow elements following `vstart` to +have been updated at the time the trap is reported, provided that +re-executing the instruction from the given `vstart` will correctly +overwrite those elements. + +In idempotent memory regions, vector store instructions may have +updated elements in memory past the element causing a synchronous +trap. Non-idempotent memory regions must not have been updated for +indices equal to or greater than the element that caused a synchronous +trap during a vector store instruction. + +Except where noted above, vector instructions are allowed to overwrite +their inputs, and so in most cases, the vector instruction restart +must be from the `vstart` element index. However, there are a number of +cases where this overwrite is prohibited to enable execution of the +vector instructions to be idempotent and hence restartable from an +earlier index location. + +Implementations must ensure forward progress can be eventually +guaranteed for the element or segment reported by `vstart`. + +==== Imprecise vector traps + +Imprecise vector traps are traps that are not precise. In particular, +instructions newer than `*epc` may have committed results, and +instructions older than `*epc` may have not completed execution. +Imprecise traps are primarily intended to be used in situations where +reporting an error and terminating execution is the appropriate +response. + +NOTE: A profile might specify that interrupts are precise while other +traps are imprecise. We assume many embedded implementations will +generate only imprecise traps for vector instructions on fatal errors, +as they will not require resumable traps. + +Imprecise traps shall report the faulting element in `vstart` for +traps caused by synchronous vector exceptions. + +There is no support for imprecise traps in the current standard extensions. + +==== Selectable precise/imprecise traps + +Some profiles may choose to provide a privileged mode bit to select +between precise and imprecise vector traps. Imprecise mode would run +at high-performance but possibly make it difficult to discern error +causes, while precise mode would run more slowly, but support +debugging of errors albeit with a possibility of not experiencing the +same errors as in imprecise mode. + +This mechanism is not defined in the current standard extensions. + +==== Swappable traps + +Another trap mode can support swappable state in the vector unit, +where on a trap, special instructions can save and restore the vector +unit microarchitectural state, to allow execution to continue +correctly around imprecise traps. + +This mechanism is not defined in the current standard extensions. + +NOTE: A future extension might define a standard way of saving and +restoring opaque microarchitectural state from a vector unit +implementation to support context switching with imprecise traps. + +[[sec-vector-extensions]] +=== Standard Vector Extensions + +This section describes the standard vector extensions. +A set of smaller extensions intended for embedded +use are named with a "Zve" prefix, while a larger vector extension +designed for application processors is named as a single-letter V +extension. A set of vector length extension names with prefix "Zvl" +are also provided. + +The initial vector extensions are designed to act as a base for +additional vector extensions in various domains, including +cryptography and machine learning. + +==== Zvl*: Minimum Vector Length Standard Extensions + +All standard vector extensions have a minimum required VLEN as +described below. A set of vector length extensions are provided to +increase the minimum vector length of a vector extension. + +NOTE: The vector length extensions can be used to either specify +additional software or architecture profile requirements, or to +advertise hardware capabilities. + +.Vector length extensions +[cols="1,1"] +[%autowidth,float="center",align="center",options="header"] +|=== +| Extension | Minimum VLEN + +| Zvl32b | 32 +| Zvl64b | 64 +| Zvl128b | 128 +| Zvl256b | 256 +| Zvl512b | 512 +| Zvl1024b | 1024 +|=== + +NOTE: Longer vector length extensions should follow the same pattern. + +NOTE: Every vector length extension effectively includes all shorter +vector length extensions. + +NOTE: Explicit use of the Zvl32b extension string is not required for +any standard vector extension as they all effectively mandate at least +this minimum, but the string can be useful when stating hardware +capabilities. + +==== Zve*: Vector Extensions for Embedded Processors + +The following five standard extensions are defined to provide varying +degrees of vector support and are intended for use with embedded +processors. [#norm:Zve_XLEN]#Any of these extensions can be added to base ISAs with +XLEN=32 or XLEN=64.# The table lists the minimum VLEN and supported +EEWs for each extension as well as what floating-point types are +supported. + +.Embedded vector extensions +[cols="1,1,2,1,1"] +[%autowidth,float="center",align="center",options="header"] +|=== +| Extension | Minimum VLEN | Supported EEW | FP32 | FP64 + +| Zve32x | 32 | 8, 16, 32 | N | N +| Zve32f | 32 | 8, 16, 32 | Y | N +| Zve64x | 64 | 8, 16, 32, 64 | N | N +| Zve64f | 64 | 8, 16, 32, 64 | Y | N +| Zve64d | 64 | 8, 16, 32, 64 | Y | Y +|=== + +[#norm:Zve32f_Zve64x_dependent_Zve32x]#The Zve32f and Zve64x extensions depend on the Zve32x extension.# +[#norm:Zve64f_dependent_Zve32f_Zve64x]#The Zve64f extension depends on the Zve32f and Zve64x extensions.# +[#norm:Zve64d_dependent_Zve64f]#The Zve64d extension depends on the Zve64f extension.# + +[#norm:Zve_precise_traps]#All Zve* extensions have precise traps.# + +NOTE: There is currently no standard support for handling imprecise +traps, so standard extensions have to provide precise traps. + +[#norm:Zve_eew]#All Zve* extensions provide support for EEW of 8, 16, and 32, and +Zve64* extensions also support EEW of 64.# + +All Zve* extensions support the vector configuration instructions +(<>). + +[#norm:Zve_nsupport_eew64_xlen32]#All Zve* extensions support all vector load and store instructions +(<>), except Zve64* extensions do not +support EEW=64 for index values when XLEN=32.# + +[#norm:Zve64_eew64_nsupport_vmulh]#All Zve* extensions support all vector integer instructions +(<>), except that the `vmulh` integer multiply +variants that return the high word of the product (`vmulh.vv`, +`vmulh.vx`, `vmulhu.vv`, `vmulhu.vx`, `vmulhsu.vv`, `vmulhsu.vx`) are +not included for EEW=64 in Zve64*.# + +NOTE: Producing the high-word of a product can take substantial +additional gates for large EEW. + +[#norm:Zve64_eew64_nsupport_vsmul]#All Zve* extensions support all vector fixed-point arithmetic +instructions (<>), except that `vsmul.vv` and +`vsmul.vx` are not included in EEW=64 in Zve64*.# + +NOTE: As with `vmulh`, `vsmul` requires a large amount of additional +logic, and 64-bit fixed-point multiplies are relatively rare. + +All Zve* extensions support all vector integer single-width and +widening reduction operations (<>, +<>). + +All Zve* extensions support all vector mask instructions +(<>). + +[#norm:Zve32x_Zve64x_nsupport_freg]#All Zve* extensions support all vector permutation instructions +(<>), except that Zve32x and Zve64x +do not include those with floating-point operands, and Zve64f does not include those +with EEW=64 floating-point operands.# + +[#norm:Zve32x_dependent_Zicsr]#The Zve32x extension depends on the Zicsr extension.# +[#norm:Zve32f_Zve64f_dependent_F]#The Zve32f and Zve64f extensions depend upon the F extension, +and implement all +vector floating-point instructions (<>) for +floating-point operands with EEW=32. Vector single-width floating-point reduction +operations (<>) for EEW=32 are supported.# + +The Zve64d extension depends upon the D extension, +and implements all vector +floating-point instructions (<>) for +floating-point operands with EEW=32 or EEW=64 (including widening +instructions and conversions between FP32 and FP64). Vector +single-width floating-point reductions (<>) +for EEW=32 and EEW=64 are supported as well as widening reductions +from FP32 to FP64. + +==== V: Vector Extension for Application Processors + +The single-letter V extension is intended for use in application +processor profiles. + +[#norm:misa-V_op]#The `misa.v` bit is set for implementations providing `misa` and +supporting V.# + +[#norm:V_precise_traps]#The V vector extension has precise traps.# + +[#norm:V_dependent_Zvl128b_Zve64d]#The V vector extension depends upon the Zvl128b and Zve64d extensions.# + +NOTE: The value of 128 was chosen as a compromise for application +processors. Providing a larger VLEN allows strip-mining code to be +elided in some cases for short vectors, but also increases the size of +the minimum implementation. Note that larger LMUL can be used to +avoid strip mining for longer known-size application vectors at the +cost of having fewer available vector register groups. For example, an +LMUL of 8 allows vectors of up to sixteen 64-bit elements to be +processed without strip mining using four vector register groups. + +[#norm:V_supported_eew]#The V extension supports EEW of 8, 16, and 32, and 64.# + +[#norm:V_instr_config]#The V extension supports the vector configuration instructions +(<>).# + +[#norm:V_instr_ls_eew64_nsupported_xlen32]#The V extension supports all vector load and store instructions +(<>), except the V extension does not +support EEW=64 for index values when XLEN=32.# + +[#norm:V_instr_int]#The V extension supports all vector integer instructions +(<>).# + +[#norm:V_instr_fixedpt]#The V extension supports all vector fixed-point arithmetic +instructions (<>).# + +[#norm:V_instr_red]#The V extension supports all vector integer single-width and +widening reduction operations (<>, +<>).# + +[#norm:V_instr_mask]#The V extension supports all vector mask instructions +(<>).# + +[#norm:V_instr_perm]#The V extension supports all vector permutation instructions +(<>).# + +[#norm:V_dependent_F_D]#The V extension depends upon the F and D +extensions, and implements all vector floating-point instructions +(<>) for floating-point operands with EEW=32 +or EEW=64 (including widening instructions and conversions between +FP32 and FP64). Vector single-width floating-point reductions +(<>) for EEW=32 and EEW=64 are supported as +well as widening reductions from FP32 to FP64.# + +[NOTE] +==== +As is the case with other RISC-V extensions, it is valid to +include overlapping extensions in the same ISA string. For example, +RV64GCV and RV64GCV_Zve64f are both valid and equivalent ISA strings, +as is RV64GCV_Zve64f_Zve32x_Zvl128b. +==== + +==== Zvfhmin: Vector Extension for Minimal Half-Precision Floating-Point + +The Zvfhmin extension provides minimal support for vectors of IEEE 754-2008 +binary16 values, adding conversions to and from binary32. +When the Zvfhmin extension is implemented, the `vfwcvt.f.f.v` and +`vfncvt.f.f.w` instructions become defined when SEW=16. +The EEW=16 floating-point operands of these instructions use the binary16 +format. + +[#norm:Zvfhmin_dependent_Zve32f]#The Zvfhmin extension depends on the Zve32f extension.# + +==== Zvfh: Vector Extension for Half-Precision Floating-Point + +The Zvfh extension provides support for vectors of IEEE 754-2008 +binary16 values. +[#norm:Zvfh_instr]#When the Zvfh extension is implemented, all instructions in +<>, <>, +<>, <>, +<>, and <> +become defined when SEW=16.# +[#norm:Zvfh_eew16]#The EEW=16 floating-point operands of these instructions use the binary16 +format.# + +[#norm:Zvfh_instr_cvt]#Additionally, conversions between 8-bit integers and binary16 values are +provided. The floating-point-to-integer narrowing conversions +(`vfncvt[.rtz].x[u].f.w`) and integer-to-floating-point +widening conversions (`vfwcvt.f.x[u].v`) become defined when SEW=8.# + +[#norm:Zvfh_dependent_Zve32f_Zfhmin]#The Zvfh extension depends on the Zve32f and Zfhmin extensions.# + +NOTE: Requiring basic scalar half-precision support makes Zvfh's +vector-scalar instructions substantially more useful. +We considered requiring more complete scalar half-precision support, but we +reasoned that, for many half-precision vector workloads, performing the scalar +computation in single-precision will suffice. + +[[vector-element-groups]] +=== Vector Element Groups + +Some vector instructions treat operands as a vector of one or more +_element_ _groups_, where each element group is a fixed number of +elements. For example, complex numbers can be viewed as a two-element +group (one real element and one imaginary element). +As another example, the SHA-256 cryptographic instructions in the Zvknha +extension operate on 128-bit values represented as a 4-element group of 32-bit +elements. + +This section describes recommendations and terminology for generic +instruction set design for vector instructions that operate on element +groups. + +==== Element Group Size + +The _element_ _group_ _size_ (EGS) is the number of elements in one +group, and must be a power-of-two (POT). + +NOTE: Support for non-POT EGS was considered but causes many practical +complications and so has been dropped. Error checking for `vl` is a +little more difficult. For LMUL>1, non-POT EGSs will result in groups +straddling the individual vector registers in a vector register +group. Non-POT EGS can also cause large increases in the +lowest-common-multiple of element group sizes, which adds constraints +to `vl` setting in order to avoid splitting an element group across +strip-mine iterations in vector-length-agnostic code. + +The element group size is statically encoded in the instruction, often +implicitly as part of the opcode. + +[#norm:egs_ge_vlmax_rsv]#Vector instructions with EGS > VLMAX are reserved.# + +NOTE: The vector instructions in the base V vector ISA can be viewed +as all having an element group size of 1 for all operands statically +encoded in the instruction. + +NOTE: Many operations only make sense with a certain number of +elements per group (e.g., complex operations require a element group +size of 2 and SHA-256 requires an element group size of 4). + +==== Setting `vl` + +Each source and destination operand to a vector instruction might be +defined as either a single element group or a vector of element +groups. [#norm:egs_vl_rsv]#When an operand is a vector of element groups, the `vl` +setting must correspond to an integer multiple of the element group +size, with other values of `vl` reserved.# + +NOTE: For example, a SHA-256 instruction would require that `vl` is a +multiple of 4. + +[#norm:egs_vl_avl]#When element group instructions are present, an additional constraint +is placed on the setting of `vl` based on an AVL value +(augmenting <>). +EGSMAX is the largest EGS supported by the +implementation. When AVL > VLMAX, the value of `vl` must be set to +either VLMAX or a positive integer multiple of EGSMAX.# + +NOTE: As the base vector extension only has element group size of 1, +this constraint is backwards-compatible. + +NOTE: This constraint prevents element groups being broken across +strip-mining iterations in vector-length-agnostic code when a +VLMAX-size vector would otherwise be able to accommodate a whole number +of element groups. + +NOTE: If EEW is encoded statically in the instruction, or if an +instruction has multiple operands containing vectors of element groups +with different EEW, an appropriate SEW must be chosen for `vsetvl` +instructions. + +NOTE: Additional constraints may be required for some element group +instructions to ensure legal length values for all operands. + +==== Determining EEW + +[#norm:egs_sew_eew]#The `vtype` SEW can be used to indicate or calculate the effective +element size (EEW) of one or more operands of an element group +instruction. Where the operand is an element group, SEW and EEW refer +to the number of bits in each individual element within a group not +the number of bits in the group as a whole.# + +Alternatively, the opcode might encode EEW of all operands statically +and ignore the value of SEW when the operation only makes sense for a +single size on each operand. + +NOTE: Many operations are only defined for one EEW, e.g., SHA-256 +requires EEW=32. Encoding EEWs statically in the instruction removes +a dynamic dependency on the SEW value and the need to check for errors +in SEW values. However, ignoring SEW also prevents reuse of the +static opcode with a different dynamic SEW, and in many cases, the SEW +setting will be needed for regular vector instructions used to process +the individual elements in the vector. + +==== Determining EMUL + +[#norm:egs_lmul_emul]#The `vtype` LMUL setting can be used to indicate or calculate the +effective length multiplier (EMUL) for one or more operands. Element +group instructions tend to exhibit a much wider range of relationships +between various operand EEW/EMUL values. For example, an instruction +might take a vector of length N of 4-element groups with EEW=8b and +reduce each group to produce a vector length N of 1-element groups +with EEW=32b. In this case, the input and output EMUL values are equal +even though the EEW settings differ by a factor of 4.# + +Each source and destination operand to a vector instruction may have a +different element group size, different EMUL, and/or different EEW. + +==== Element Group Width + +[#norm:egs_egw]#The _element_ _group_ _width_ (EGW) is the number of bits in the +element group as a whole. +For example, the SHA-256 instructions in the Zvknha extension operate on an +EGW of 128, with EGS=4 and EEW=32. +It is possible to use LMUL to concatenate multiple vector registers together +to support larger EGW>VLEN.# + +NOTE: If software using large-EGW instructions need be portable +across a range of implementations, some of which may have VLEN1, then software can only use a subset of the +architectural registers. Profiles can set minimum VLEN requirements +to inform authors of such software. + +NOTE: Element group operations by their nature will gather data from +across a wider portion of a vector datapath than regular vector +instructions. Some element group instructions might allow temporal +execution of individual element operations in a larger group, while +others will require all EGW bits of a group to be presented to a +functional unit at the same time. + +==== Masking + +No ratified extensions include masked element-group instructions. +Future extensions might extend the element-group scheme to support +element-level masking, or might define the concept of a _mask element group_ +(which might, e.g., update the destination element group if any mask bit in +the mask element group is set). + +=== Vector Instruction Listing + +include::images/wavedrom/v-inst-table.edn[] diff --git a/param_extraction/chunks/chunk_058.txt.license b/param_extraction/chunks/chunk_058.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_058.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_059.txt b/param_extraction/chunks/chunk_059.txt new file mode 100644 index 0000000000..ff587a8144 --- /dev/null +++ b/param_extraction/chunks/chunk_059.txt @@ -0,0 +1,3367 @@ +# Chunk: chunk_059 +# Source: vector-crypto.adoc +# Lines: 1-3340 (of 4966) +# Content starts: line 1 +# Line count: 3340 +# Sections: 20 +# == Cryptography Extensions: Vector Instructions, Version 1.0 +# === Introduction +# ==== Intended Audience +# ==== Sail Specifications +# ==== Policies +# ==== Element Groups +# ==== Instruction Constraints +# ==== Vector-Scalar Instructions +# ==== Software Portability +# === Extensions Overview +# ==== `Zvbb` - Vector Basic Bit-manipulation +# ==== `Zvbc` - Vector Carry-less Multiplication +# ==== `Zvkb` - Vector Cryptography Bit-manipulation +# ==== `Zvkg` - Vector GCM/GMAC +# ==== `Zvkned` - NIST Suite: Vector AES Block Cipher +# ==== `Zvknh[ab]` - NIST Suite: Vector SHA-2 Secure Hash +# ==== `Zvksed` - ShangMi Suite: SM4 Block Cipher +# ==== `Zvksh` - ShangMi Suite: SM3 Secure Hash +# ==== `Zvkn` - NIST Algorithm Suite +# ==== `Zvknc` - NIST Algorithm Suite with carry-less multiply +# +== Cryptography Extensions: Vector Instructions, Version 1.0 + +This document describes the Vector Cryptography extensions to the +RISC-V Instruction Set Architecture. + +[[crypto_vector_introduction]] +=== Introduction + +This document describes the RISC-V _vector_ cryptography extensions. +All instructions described here are based on the Vector registers. +The instructions are designed to be highly performant, with large +application and server-class cores being the main target. +A companion chapter _Volume I: Scalar & Entropy Source Instructions_, +describes +cryptographic instructions for smaller cores which do not +implement the vector extension. + +[[crypto_vector_audience]] +==== Intended Audience + +Cryptography is a specialized subject, requiring people with many different +backgrounds to cooperate in its secure and efficient implementation. +Where possible, we have written this specification to be understandable by +all, though we recognize that the motivations and references to +algorithms or other specifications and standards may be unfamiliar to those +who are not domain experts. + +This specification anticipates being read and acted on by various people +with different backgrounds. +We have tried to capture these backgrounds +here, with a brief explanation of what we expect them to know, and how +it relates to the specification. +We hope this aids people's understanding of which aspects of the specification +are particularly relevant to them, and which they may (safely!) ignore or +pass to a colleague. + +Cryptographers and cryptographic software developers:: +These are the people we expect to write code using the instructions +in this specification. +They should understand the motivations for the +instructions we include, and be familiar with most of the algorithms +and outside standards to which we refer. + +Computer architects:: +We do not expect architects to have a cryptography background. +We nonetheless expect architects to be able to examine our instructions +for implementation issues, understand how the instructions will be used +in context, and advise on how best to fit the functionality the +cryptographers want. + +Digital design engineers & micro-architects:: +These are the people who will implement the specification inside a +core. Again, no cryptography expertise is assumed, but we expect them to +interpret the specification and anticipate any hardware implementation +issues, e.g., where high-frequency design considerations apply, or where +latency/area tradeoffs exist etc. +In particular, they should be aware of the literature around efficiently +implementing AES and SM4 SBoxes in hardware. + +Verification engineers:: +These people are responsible for ensuring the correct implementation of the +extensions in hardware. +No cryptography background is assumed. +We expect them to identify interesting test cases from the +specification. An understanding of their real-world usage will help with this. + +These are by no means the only people concerned with the specification, +but they are the ones we considered most while writing it. + +[[crypto_vector_sail_specifications]] +==== Sail Specifications + +RISC-V maintains a +link:https://github.com/riscv/sail-riscv[formal model] +of the ISA specification, +implemented in the Sail ISA specification language +cite:[sail]. +Note that _Sail_ refers to the specification language itself, +and that there is a _model of RISC-V_, written using Sail. + +It was our intention to include actual Sail code in this specification. +However, the Vector Crypto Sail model needs the Vector Sail model as a +basis on which to build. This Vector Cryptography extensions specification +was completed before there was an approved RISC-V Vector Sail Model. +Therefore, we don't have any Sail code to include in the instruction +descriptions. Instead we have included Sail-like pseudocode. While we have +endeavored to adhere to Sail syntax, we have taken some liberties for the +sake of simplicity where we believe that that our intent is clear to the +reader. + +[NOTE] +==== +Where variables are concatenated, the order shown is how they would appear +in a vector register from left to right. +For example, an element group specified as `{a, b, e, f}` would appear in a vector +register with `a` having the highest element index of the group and `f` having the +lowest index of the group. +==== + +For the sake of brevity, our pseudocode does not include the handling of +masks or tail elements. We follow the _undisturbed_ and _agnostic_ policies +for masks and tails as described in the *RISC-V "V" Vector Extension* +specification. Furthermore, the code does not explicitly handle overlap and SEW +constraints; these are, however, explicitly stated in the text. + +In many cases the pseudocode includes +calls to supporting functions which are too verbose to include directly +in the specification. +This supporting code is listed in +<>. + + +The +link:https://alasdair.github.io/manual.html[Sail Manual] +is recommended reading in order to best understand the code snippets. +Also, the +link:https://github.com/billmcspadden-riscv/sail/blob/cookbook_br/cookbook/doc/TheSailCookbook_Complete.pdf[The Sail Programming Language: A Sail Cookbook] +is a good reference. + +For the latest RISC-V Sail model, refer to +the formal model GitHub +link:https://github.com/riscv/sail-riscv[repository]. + +[[crypto_vector_policies]] +==== Policies + +In creating this extension, we tried to adhere to the following +policies: + +* Where there is a choice between: + 1) supporting diverse implementation strategies for an algorithm + or + 2) supporting a single implementation style which is more performant / + less expensive; + the vector crypto extensions will pick the more constrained but performant + option. + This fits a common pattern in other parts of the RISC-V specifications, + where recommended (but not required) instruction sequences for performing + particular tasks are given as an example, such that both hardware and + software implementers can optimize for only a single use-case. + +* The extensions will be designed to support _existing_ standardized + cryptographic constructs well. + It will not try to support proposed standards, or cryptographic + constructs which exist only in academia. + Cryptographic standards which are settled upon concurrently with or after + the RISC-V vector cryptographic extensions standardization will be dealt with + by future RISC-V vector cryptographic + standard extensions. + +* Historically, there has been some discussion + cite:[LSYRR:04] + on how newly supported operations in general-purpose computing might + enable new bases for cryptographic algorithms. + The standard will not try to anticipate new useful low-level + operations which _may_ be useful as building blocks for + future cryptographic constructs. + +* Regarding side-channel countermeasures: + Where relevant, proposed instructions must aim to remove the + possibility of any timing side-channels. All instructions + shall be implemented with data-independent timing. That is, the latency of + the execution of these instructions shall not vary with different input values. + +[[crypto-vector-element-groups]] +==== Element Groups + +Many vector crypto instructions operate on operands that are wider than elements (which are currently limited +to 64 bits wide). +Typically, these operands are 128- and 256-bits wide. In many cases, these operands are comprised of smaller +operands that are combined (for example, each SHA-2 operand is comprised of 4 words). However, in other cases +these operands are a single value (for example, in the AES round instructions, each operand is 128-bit block +or round key). + +We treat these operands as a vector of one or more _element groups_ as defined in <>. + +Each vector crypto instruction that operates on element groups explicitly specifies their three defining +parameters: EGW, EGS, and EEW. + +[%autowidth] +[%header,cols="4,4,4,4,4"] +|=== +| Instruction Group +| Extension +| EGW +| EEW +| EGS + +| AES | <> | 128 | 32 | 4 +| SHA256 | <> | 128 | 32 | 4 +| SHA512 | <> | 256 | 64 | 4 +| GCM | <> | 128 | 32 | 4 +| SM4 | <> | 128 | 32 | 4 +| SM3 | <> | 256 | 32 | 8 +|=== + +[NOTE] +==== +- Element Group Width (`EGW`) - total number of bits in an element group +- Effective Element Width (`EEW`) - number of bits in each element +- Element Group Size (`EGS`) - number of elements in an element group +==== + +[[norm:veccrypto_eeweqsew]] +For all of the vector crypto instructions in this specification, `EEW`=`SEW`. + +[NOTE] +==== +The required `SEW` for each cryptographic instruction was chosen to match what is +typically needed for other instructions when implementing the targeted algorithm. +==== + +- A *Vector Element Group* is a vector of one or more element groups. +- A *Scalar Element Group* is a single element group. + +Element groups can be formed across registers in implementations where +`VLEN`< `EGW` by using an `LMUL`>1. + +[NOTE] +==== +Since the *vector extension for application processors* requires a minimum of VLEN of 128, +at most such implementations would require LMUL=2 to form the largest element groups in this specification. + +However, implementations with a smaller VLEN, such as embedded designs, will requires a larger `LMUL` +to form the necessary element groups. +It is important to keep in mind that this reduces the number of register groups available such +that it may be difficult or impossible to write efficient code for the intended cryptographic algorithms. + +For example, an implementation with `VLEN`=32 would need to set `LMUL`=8 to create a +256-bit element group for `SM3`. This would mean that there would only be 4 register groups, +3 of which would be consumed by a single `SM3` message-expansion instruction. +==== + +As with all vector instructions, the number of elements processed is specified by the +vector length `vl`. The number of element groups operated upon is then `vl`/`EGS`. +Likewise the starting element group is `vstart`/`EGS`. +See <> for limitations on `vl` and `vstart` +for vector crypto instructions. + +// If this ratio is not an integer for a vector crypto instruction, an illegal-instruction exception is raised. + +// Since `vstart` is expressed in elements, the starting element group is `vstart`/`EGS`. +// If this ratio is not an integer for a vector crypto instruction, an illegal-instruction exception is raised. + +[[crypto-vector-instruction-constraints]] +==== Instruction Constraints + +All standard vector instruction constraints specified by RVV 1.0 apply to Vector Crypto instructions. +In addition to those constraints a few additional specific constraints are introduced. + +The following is a quick reference for the various constraints of specific Vector Crypto instructions. + + +vl and vstart constraints:: +[#norm:veccrypto_vl_vstart_egsconstr]#Since `vl` and `vstart` refer to elements, Vector Crypto instructions that use elements groups +(See <>) require that these values are an integer multiple of the +Element Group Size (`EGS`).# + +- [#norm:veccrypto_vl_vstart_rsv]#Instructions that violate the `vl` or `vstart` requirements are _reserved_.# + +[%autowidth] +[%header,cols="4,4"] +|=== +| Instructions +| EGS + +| vaes* | 4 +| vsha2* | 4 +| vg* | 4 +| vsm3* | 8 +| vsm4* | 4 + +|=== + +LMUL constraints:: +[#norm:veccrypto_lmul_egwconstr]#For element-group instructions, `LMUL`*`VLEN` must always be at least as large as `EGW`, otherwise an +_illegal-instruction exception_ is raised, even if `vl`=0.# + +[%autowidth] +[%header,cols="4,2,2"] +|=== +| Instructions +| SEW +| EGW + +| vaes* | 32 | 128 +| vsha2* | 32 | 128 +| vsha2* | 64 | 256 +| vg* | 32 | 128 +| vsm3* | 32 | 256 +| vsm4* | 32 | 128 + +|=== + + +SEW constraints:: +[#norm:veccrypto_sew_rsv]#Some Vector Crypto instructions are only defined for a specific `SEW`. In such a case +all other `SEW` values are _reserved_.# + +[%autowidth] +[%header,cols="4,4"] +|=== +| Instructions +| Required SEW + +| vaes* | 32 +| Zvknha: vsha2* | 32 +| Zvknhb: vsha2* | 32 or 64 +| vclmul[h] | 64 +| vg* | 32 +| vsm3* | 32 +| vsm4* | 32 + + +|=== + +Vector/Scalar constraints:: +This specification defines new vector/scalar (.vs) instructions that uses *Scalar Element Groups*. The *Scalar Element Group* operand has `EMUL = ceil(EGW / VLEN)`. + +[NOTE] +==== +Scalar element group operands do not need to be aligned to LMUL for any implementation with VLEN >= EGW. +==== + +[#norm:veccrypto_vsins_vs2]#In the case of the `.vs` instructions defined in this specification, `vs2` holds a 128-bit scalar element group.# +[#norm:veccrypto_vsins_vdvs2overlap]#For implementations with `VLEN` ≥ 128, `vs2` refers to a single register. Thus, the `vd` register group must not +overlap the `vs2` register. +However, in implementations where `VLEN` < 128, `vs2` refers to a register group comprised of the number +of registers needed to hold the 128-bit scalar element group. In this case, the `vd` register group must not +overlap this `vs2` register group.# + +[%autowidth] +[%header,cols="4,4,4"] +|=== +| Instruction +| Register +| Cannot Overlap + +| vaes*.vs | vs2 | vd +| vsm4r.vs | vs2 | vd +| vsha2c[hl] | vs1, vs2 | vd +| vsha2ms | vs1, vs2 | vd +| vsm3me | vs2 | vd +| vsm3c | vs2 | vd + + +|=== + +[[crypto-vector-scalar-instructions]] +==== Vector-Scalar Instructions + +The RISC-V Vector Extension defines three encodings for Vector-Scalar operations which get their scalar operand from a GPR or FP register: + +- OPIVX: Scalar GPR _x_ register +- OPFVF: Scalar FP _f_ register +- OPMVX: Scalar GPR _x_ register + +However, the Vector Extensions include Vector Reduction Operations which can also be considered +Vector-Scalar operations because a scalar operand is provided from element 0 of +vector register `vs1`. The vector operand is provided in vector register group `vs2`. +These reduction operations all use the `.vs` suffix in their mnemonics. Additionally, the reduction operations all produce a scalar result in element 0 of the destination register, `vd`. + +The Vector Crypto Extensions define Vector-Scalar instructions that are similar to these +Vector Reduction Operations in that they get a scalar operand from a vector register. However, they differ +in that they get a scalar element group +(see <>) +from `vs2` and [#norm:veccrypto_vsins_vd]#they return _vector_ results to `vd`, which is also a source vector operand.# +These Vector-Scalar crypto instructions also use the `.vs` suffix in their mnemonics. + +[NOTE] +==== +We chose to use `vs2` as the scalar operand, and `vd` as the vector operand, so that we could use the `vs1` +specifier as additional encoding bits for these instructions. This allows these instructions to have a +much smaller encoding footprint, leaving more rooms for other instructions in the future. +==== + +[#norm:veccrypto_vsins_vs2function]#These instructions enable a single key, specified as a scalar element group in `vs2`, to be +applied to each element group of register group `vd`.# + +[NOTE] +==== +Scalar element groups will occupy at most a single register in application processors. However, in implementations where +VLEN<128, they will occupy 2 (VLEN=64) or 4 (VLEN=32) registers. +==== + + +[NOTE] +==== +It is common for multiple AES encryption rounds (for example) to be performed in parallel with the same +round key (e.g. in counter modes). +Rather than having to first splat the common key across the whole vector group, these vector-scalar +crypto instructions allow the round key to be specified as a scalar element group. +==== + +// In the case of AES256 all-rounds instructions we need to provide two 128-bit keys; one is held in `vs1` and +// the other is held in `vs2`. The 128-bit data to be processed is held in `vd`. +// A vector-scalar form of this instruction looks different from the existing vector-scalar instructions in that +// both `vs1` and `vs2` are treated as scalar operands that apply to the vector operands of `vd`. + +// [NOTE] +// ==== +// Previously, the AES and SM4 instructions that performed rounds operations (including AES all-rounds instructions) +// were defined to be destructive operations where the data source was provided in `vd` and the key was provided in +// `vs2`. With the advent of the new crypto vector-scalar instructions, we are changing these instructions +// to use `vs1` for the key and `vs2` for the data. +// In the case of vector-scalar instructions, the scalar key will be held in +// element group 0 of `vs1` . This is done to remain consistent with the use of `vs1` for the scalar element in +// all of the existing vector-scalar operations as well as the vector reduction operations. +// ==== + +[[crypto-vector-software-portability]] +==== Software Portability +The following contains some guidelines that enable the portability of vector-crypto-based code +to implementations with different values for `VLEN` + +Application Processors:: +Application processors are expected to follow the V-extension and will therefore have `VLEN` {ge} 128. + + + +// [NOTE] +// ==== +Since most of the _cryptography-specific_ instructions have an `EGW`=128, nothing special needs to be done +for these instructions to support implementations with `VLEN`=128. + +However, the SHA-512 and SM3 instructions have an `EGW`=256. Implementations with `VLEN` = 128, require that +`LMUL` is doubled for these instructions in order to create 256-bit elements across a pair of registers. +Code written with this doubling of `LMUL` will not affect the results returned by implementations with `VLEN` {ge} 256 +because `vl` controls how many element groups are processed. Therefore, we recommend that libraries that implement +SHA-512 and SM3 employ this doubling of `LMUL` to ensure that the software can run on all implementation +with `VLEN` {ge} 128. + +While the doubling of `LMUL` for these instructions is _safe_ for implementations with `VLEN` {ge} 256, it may be less +optimal as it will result in unnecessary register pressure and might exact a performance penalty in +some microarchitectures. Therefore, we suggest that in addition to providing portable code for SHA-512 and SM3, +libraries should also include more optimal code for these instructions when `VLEN` {ge} 256. +// ==== + +[%autowidth] +[%header,cols="4,4,4,4"] +|=== +| Algorithm +| Instructions +| VLEN +| LMUL + +| SHA-512 | vsha2* | 64 | vl/2 +| SM3 | vsm3* | 32 | vl/4 +|=== + +// [NOTE] +// ==== +// We recommend that all library code for application processors be written so that it can be run on any +// implementation with `VLEN` {ge} 128. Such libraries are also encouraged to have versions of code for +// SHA-512 and SM3 optimized for implementations with `VLEN` {ge} 256. +// ==== + +Embedded Processors:: + +Embedded processors will typically have implementations with `VLEN` < 128. This will require code to be written with +larger `LMUL` values to enable the element groups to be formed. + +The `.vs` instructions require scalar element groups of `EGW`=128. On implementations with `VLEN` < 128, these scalar +element groups will necessarily be formed across registers. This is different from most scalars in vector instructions +that typically consume part of a single register. + + +// [NOTE] +// ==== +We recommend that different code be available for `VLEN`=32 and `VLEN`=64, as code written for `VLEN`=32 will +likely be too burdensome for `VLEN`=64 implementations. +// ==== + +[[crypto_vector_extensions]] +=== Extensions Overview + +The section introduces all of the extensions in the Vector Cryptography +Instruction Set Extension Specification. + +[#norm:Zvknhb_Zvbc_Zvkn_Zvknc_Zvkng_depZve64x]#The <> and <> Vector Crypto Extensions +--and accordingly the composite extensions <>, <>, <>, and <>-- +depend on Zve64x.# + +[#norm:Zvbb_Zvkb_Zvkg_Zvkned_Zvknha_Zvksed_Zvksh_Zvks_Zvksc_Zvksg_Zvkt_depZve32x]#All of the other Vector Crypto Extensions depend on `Zve32x`.# + +Note: If `Zve32x` is supported then `Zvkb` or `Zvbb` provide support for EEW of 8, 16, and 32. If `Zve64x` is supported then `Zvkb` or `Zvbb` also add support for EEW 64. + + +// See <> for more details on vector element groups and the drawbacks of +// small `VLEN` values. + + +All _cryptography-specific_ instructions defined in this Vector Crypto specification (i.e., those +in <>, <>, <>, <> and <> but _not_ <>,<>, or <>) shall +be executed with data-independent execution latency as defined in the +<<#crypto_scalar_instructions,RISC-V Scalar Cryptography Extensions specification>>. +[#norm:veccrypto_indepZkt]#It is important to note that the Vector Crypto instructions are independent of the +implementation of the `Zkt` extension and do not require that `Zkt` is implemented.# + +This specification includes a <> extension that, when implemented, requires certain vector instructions +(including <>, <>, and <>) to be executed with data-independent execution latency. + +Detection of individual cryptography extensions uses the +unified software-based RISC-V discovery method. + +[NOTE] +==== +At the time of writing, these discovery mechanisms are still a work in +progress. +==== + +[[zvbb,Zvbb]] +==== `Zvbb` - Vector Basic Bit-manipulation + +Vector basic bit-manipulation instructions. + +[NOTE] +==== +This extension is a superset of the <> extension. +==== + +[%autowidth] +[%header,cols="2,4"] +|=== +|Mnemonic +|Instruction + +| vandn.[vv,vx] | <> +| vbrev.v | <> +| vbrev8.v | <> +| vrev8.v | <> +| vclz.v | <> +| vctz.v | <> +| vcpop.v | <> +| vrol.[vv,vx] | <> +| vror.[vv,vx,vi] | <> +| vwsll.[vv,vx,vi] | <> + +|=== + +<<< + +[[zvbc,Zvbc]] +==== `Zvbc` - Vector Carry-less Multiplication + +General purpose carry-less multiplication instructions which are commonly used in cryptography +and hashing (e.g., Elliptic curve cryptography, GHASH, CRC). + +[#norm:Zvbc_sew64only]#These instructions are only defined for `SEW`=64.# + +[%autowidth] +[%header,cols="^2,4"] +|=== +|Mnemonic +|Instruction +| vclmul.[vv,vx] | <> +| vclmulh.[vv,vx] | <> + +|=== + +<<< + +[[zvkb,Zvkb]] +==== `Zvkb` - Vector Cryptography Bit-manipulation + +Vector bit-manipulation instructions that are essential +for implementing common cryptographic workloads securely & +efficiently. + +[NOTE] +==== +This Zvkb extension is a proper subset of the Zvbb extension. +Zvkb allows for vector crypto implementations without incurring +the cost of implementing the additional bitmanip instructions +in the Zvbb extension: vbrev.v, vclz.v, vctz.v, vcpop.v, and vwsll.[vv,vx,vi]. +==== + +[%autowidth] +[%header,cols="2,4"] +|=== +|Mnemonic +|Instruction + +| vandn.[vv,vx] | <> +// | vbrev.v | <> +| vbrev8.v | <> +| vrev8.v | <> +// | vclz.v | <> +// | vctz.v | <> +// | vcpop.v | <> +| vrol.[vv,vx] | <> +| vror.[vv,vx,vi] | <> +// | vwsll.[vv,vx,vi] | <> +|=== + +<<< + +[[zvkg,Zvkg]] +==== `Zvkg` - Vector GCM/GMAC + +Instructions to enable the efficient implementation of GHASH~H~ which is used in Galois/Counter Mode (GCM) and +Galois Message Authentication Code (GMAC). + +[#norm:Zvkg_egw128b_elem32b]#All of these instructions work on 128-bit element groups comprised of four 32-bit elements.# + +GHASH~H~ is defined in the +// link:https://csrc.nist.gov/publications/detail/sp/800-38d/final[NIST Special Publication 800-38D] + "Recommendation for Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC" + cite:[nist:gcm] +(NIST Specification). + +[NOTE] +==== +GCM is used in conjunction with block ciphers (e.g., AES and SM4) to encrypt a message and +provide authentication. +GMAC is used to provide authentication of a message without encryption. +==== + +[#norm:Zvkg_dataindeptiming]#To help avoid side-channel timing attacks, these instructions shall be implemented with data-independent timing.# + +[#norm:Zvkg_vl]#The number of element groups to be processed is `vl`/`EGS`. +`vl` must be set to the number of `SEW=32` elements to be processed and +therefore must be a multiple of `EGS=4`.# + +[#norm:Zvkg_vstart]#Likewise, `vstart` must be a multiple of `EGS=4`.# + +[%autowidth] +[%header,cols="^2,4,4,4"] +|=== + +|SEW +|EGW +|Mnemonic +|Instruction +| 32 | 128 | vghsh.vv | <> +| 32 | 128 | vgmul.vv | <> + +|=== + +<<< + +[[zvkned,Zvkned]] +==== `Zvkned` - NIST Suite: Vector AES Block Cipher + +Instructions for accelerating +encryption, decryption and key-schedule +functions of the AES block cipher as defined in +Federal Information Processing Standards Publication 197 +cite:[nist:fips:197] + +[#norm:Zvkned_egw128b_elem32b]#All of these instructions work on 128-bit element groups comprised of four +32-bit elements.# + +For the best performance, it is suggested that these instruction be implemented on systems with `VLEN`>=128. +On systems with `VLEN`<128, element groups may be formed by concatenating 32-bit elements +from two or four registers by using an LMUL =2 and LMUL=4 respectively. + +// Implementations with `VLEN<128` should consider the existing +// Scalar Cryptography Extensions, specifically <> and <> +// for accelerated cryptographic operations. + +[#norm:Zvkned_dataindeptiming]#To help avoid side-channel timing attacks, these instructions shall be implemented with data-independent timing.# + +[#norm:Zvkned_vl]#The number of element groups to be processed is `vl`/`EGS`. +`vl` must be set to the number of `SEW=32` elements to be processed and +therefore must be a multiple of `EGS=4`.# + +[#norm:Zvkned_vstart]#Likewise, `vstart` must be a multiple of `EGS=4`.# + +[%autowidth] +[%header,cols="^2,4,4,4"] +|=== +|SEW +|EGW +|Mnemonic +|Instruction + +| 32| 128 | vaesef.[vv,vs] | <> +| 32| 128 | vaesem.[vv,vs] | <> +| 32| 128 | vaesdf.[vv,vs] | <> +| 32| 128 | vaesdm.[vv,vs] | <> +| 32| 128 | vaeskf1.vi | <> +| 32| 128 | vaeskf2.vi | <> +| 32| 128 | vaesz.vs | <> +|=== + +<<< + +[[zvknh, zvknh[ab]]] +==== `Zvknh[ab]` - NIST Suite: Vector SHA-2 Secure Hash + +Instructions for accelerating SHA-2 as defined in FIPS PUB 180-4 Secure Hash Standard (SHS) +cite:[nist:fips:180:4] + +`SEW` differentiates between SHA-256 (`SEW`=32) and SHA-512 (`SEW`=64). + +- [#norm:Zvknha_Zvknhb_sha256_egw128b_elem32b]#SHA-256: these instructions work on 128-bit element groups comprised of four 32-bit elements.# +- [#norm:Zvknhb_sha512_egw256b_elem64b]#SHA-512: these instructions work on 256-bit element groups comprised of four 64-bit elements.# + +[%autowidth] +[%header,cols="^2,^2,^2,2"] +|=== +|SEW +|EGW +|SHA-2 +|Extension + +|32 | 128 | SHA-256 | Zvknha, Zvknhb +|64 | 256 | SHA-512 | Zvknhb +|=== + +// link:https://doi.org/10.6028/NIST.FIPS.180-4[FIPS PUB 180-4 Secure Hash Standard (SHS)]) + +- [#norm:Zvknhb_sha256_sha512]#Zvknhb supports SHA-256 and SHA-512.# +- [#norm:Zvknha_sha256]#Zvknha supports only SHA-256.# + +// [NOTE] +// ==== +// Zvknhb is implemented, `SEW` is used to differentiate between SHA-256 (SEW=32) and SHA-512 (SEW=64). +// If Zvknha is implemented, only SHA-256 is supported, and SEW must be 32. +// ==== + +SHA-256 implementations with VLEN < 128 require LMUL>1 to combine +32-bit elements from register groups to provide all four elements of the element group. + +SHA-512 implementations with VLEN < 256 require LMUL>1 to combine +64-bit elements from register groups to provide all four elements of the element group. + +// SHA-2 is defined in +// link:https://doi.org/10.6028/NIST.FIPS.180-4[FIPS PUB 180-4 Secure Hash Standard (SHS)]. + +[#norm:Zvknha_Zvknhb_dataindeptiming]#To help avoid side-channel timing attacks, these instructions shall be implemented with data-independent timing.# + +// [NOTE] +// ==== +// It is recommended that implementations have VLEN{ge}128 for these instructions. +// // Furthermore, for the best performance in SHA512, it is recommended that implementations have VLEN{ge}256. +// When VLEN> +// | 128 +| vsha2c[hl].vv | <> +|=== + +<<< + +[[zvksed,Zvksed]] +==== `Zvksed` - ShangMi Suite: SM4 Block Cipher + +Instructions for accelerating +encryption, decryption, and key-schedule +functions of the SM4 block cipher. + +The SM4 block cipher is specified in _32907-2016: \{SM4} Block Cipher Algorithm_ +cite:[gbt:sm4] + +There are other various sources available that describe the SM4 block cipher. +While not the final version of the standard, +link:https://www.rfc-editor.org/rfc/rfc8998.html[RFC 8998 ShangMi (SM) Cipher Suites for TLS 1.3] +is useful and easy to access. + +// https://datatracker.ietf.org/doc/id/draft-crypto-sm4-00 + +[#norm:Zvksed_egw128b_elem32b]#All of these instructions work on 128-bit element groups comprised of four +32-bit elements.# + +// Systems which implement `VLEN<128` should consider the existing +// Scalar Cryptography Extensions, specifically <> and <> +// for accelerated cryptographic operations. + +[#norm:Zvksed_dataindeptiming]#To help avoid side-channel timing attacks, these instructions shall be implemented with data-independent timing.# + +[#norm:Zvksed_vl]#The number of element groups to be processed is `vl`/`EGS`. +`vl` must be set to the number of `SEW=32` elements to be processed and +therefore must be a multiple of `EGS=4`.# + +[#norm:Zvksed_vstart]#Likewise, `vstart` must be a multiple of `EGS=4`.# + +[%autowidth] +[%header,cols="^2,4,4,4"] +|=== +|SEW +|EGW +|Mnemonic +|Instruction + +| 32 | 128 | vsm4k.vi | <> +| 32 | 128 | vsm4r.[vv,vs] | <> +|=== + +<<< + +[[zvksh,Zvksh]] +==== `Zvksh` - ShangMi Suite: SM3 Secure Hash + +Instructions for accelerating +functions of the SM3 Hash Function. + +The SM3 secure hash algorithm is specified in _32905-2016: SM3 Cryptographic Hash Algorithm_ +cite:[gbt:sm3] + +There are other various sources available that describe the SM3 secure hash. +While not the final version of the standard, +link:https://www.rfc-editor.org/rfc/rfc8998.html[RFC 8998 ShangMi (SM) Cipher Suites for TLS 1.3] +is useful and easy to access. + +// https://datatracker.ietf.org/doc/id/draft-crypto-sm4-00 + +[#norm:Zvksh_egw256b_elem32b]#All of these instructions work on 256-bit element groups comprised of +eight 32-bit elements.# + +Implementations with VLEN < 256 require LMUL>1 to combine 32-bit elements from register groups +to provide all eight elements of the element group. + +// The instructions will be most efficient on implementations where `VLEN`{ge}256. +// They will also provide substantial benefit on implementations where +// `VLEN`=128, but will require an `LMUL`>1 in order to combine elements +// within a register group to form the full element group. +// Implementations with `VLEN`<128 might not be as efficient and should +// consider the existing +// Scalar Cryptography Extensions, specifically `Zkne` and `Zknd`, +// for accelerated cryptographic operations. + +[#norm:Zvksh_dataindeptiming]#To help avoid side-channel timing attacks, these instructions shall be implemented with data-independent timing.# + +[#norm:Zvksh_vl]#The number of element groups to be processed is `vl`/`EGS`. +`vl` must be set to the number of `SEW=32` elements to be processed and +therefore must be a multiple of `EGS=8`.# + +[#norm:Zvksh_vstart]#Likewise, `vstart` must be a multiple of `EGS=8`.# + +[%autowidth] +[%header,cols="2,4,4,4"] +|=== +| SEW +| EGW +| Mnemonic +| Instruction + +| 32 | 256 | vsm3me.vv | <> +| 32 | 256 | vsm3c.vi | <> +|=== + +<<< + +[[zvkn,Zvkn]] +==== `Zvkn` - NIST Algorithm Suite + +This extension is shorthand for the following set of other extensions: + +[%autowidth] +[%header,cols="^2,4"] +|=== +|Included Extension +|Description + + +| Zvkned | <> +| Zvknhb | <> +// | Zvbb | <> +| Zvkb | <> +// | Zvbc | <> +| Zvkt | <> +|=== + +[NOTE] +==== +While Zvkg and Zvbc are not part of this extension, it is recommended that at least one of them is implemented with this extension to enable efficient AES-GCM. +==== + +<<< + +[[zvknc,Zvknc]] +==== `Zvknc` - NIST Algorithm Suite with carry-less multiply + +This extension is shorthand for the following set of other extensions: + +[%autowidth] +[%header,cols="^2,4"] +|=== +|Included Extension +|Description + + +| Zvkn | <> +| Zvbc | <> +|=== + +[NOTE] +==== +This extension combines the NIST Algorithm Suite with the +vector carry-less multiply extension to enable AES-GCM. +==== + +<<< + +[[zvkng,Zvkng]] +==== `Zvkng` - NIST Algorithm Suite with GCM + +This extension is shorthand for the following set of other extensions: + +[%autowidth] +[%header,cols="^2,4"] +|=== +|Included Extension +|Description + + +| Zvkn | <> +| Zvkg | <> +|=== + +[NOTE] +==== +This extension combines the NIST Algorithm Suite with the +GCM/GMAC extension to enable high-performance AES-GCM. +==== + +<<< + +[[zvks,Zvks]] +==== `Zvks` - ShangMi Algorithm Suite + +This extension is shorthand for the following set of other extensions: + +[%autowidth] +[%header,cols="^2,4"] +|=== +|Included Extension +|Description + + +| Zvksed | <> +| Zvksh | <> +// | Zvbb | <> +| Zvkb | <> +// | Zvbc | <> +| Zvkt | <> +|=== + +[NOTE] +==== +While Zvkg and Zvbc are not part of this extension, it is recommended that at least one of them is implemented with this extension to enable efficient SM4-GCM. +==== + +<<< + +[[zvksc,Zvksc]] +==== `Zvksc` - ShangMi Algorithm Suite with carry-less multiplication + +This extension is shorthand for the following set of other extensions: + +[%autowidth] +[%header,cols="^2,4"] +|=== +|Included Extension +|Description + + +| Zvks | <> +| Zvbc | <> +|=== + +[NOTE] +==== +This extension combines the ShangMi Algorithm Suite with the +vector carry-less multiply extension to enable SM4-GCM. +==== + +<<< + +[[zvksg,Zvksg]] +==== `Zvksg` - ShangMi Algorithm Suite with GCM + +This extension is shorthand for the following set of other extensions: + +[%autowidth] +[%header,cols="^2,4"] +|=== +|Included Extension +|Description + + +| Zvks | <> +| Zvkg | <> +|=== + +[NOTE] +==== +This extension combines the ShangMi Algorithm Suite with the +GCM/GMAC extension to enable high-performance SM4-GCM. +==== + +<<< + +[[zvkt,Zvkt]] +==== `Zvkt` - Vector Data-Independent Execution Latency + +The Zvkt extension requires all implemented instructions from the following list to be +executed with data-independent execution latency as defined in the +<<#crypto_scalar_instructions,RISC-V Scalar Cryptography Extensions specification>>. + +Data-independent execution latency (DIEL) applies to all _data operands_ of an instruction, even those that are not a +part of the body or that are inactive. However, DIEL does not apply +to other values such as vl, vtype, and the mask (when used to control +execution of a masked vector instruction). +Also, DIEL does not apply to constant values specified in the +instruction encoding such as the use of the zero register (`x0`), and, in the +case of immediate forms of an instruction, the values in the immediate +fields (i.e., imm, and uimm). + +In some cases --- which are explicitly specified in the lists below +--- operands that are used as control rather than data +are exempt from DIEL. + +[NOTE] +==== +DIEL helps protect against side-channel timing attacks that are used +to determine data values that are intended to be kept secret. Such +values include cryptographic keys, plain text, and partially encrypted +text. DIEL is not intended to keep software (and cryptographic +algorithms contained therein) secret as it is assumed that an adversary +would already know these. This is why DIEL doesn't apply to constants +embedded in instruction encodings. + +It is important that the _values_ of elements that are not in the body or that are masked off do not affect the execution +latency of the instruction. Sometimes such elements contain data that +also needs to be kept secret. +==== + +===== All <> instructions +- vandn.v[vx] +- vclz.v +- vcpop.v +- vctz.v +- vbrev.v +- vbrev8.v +- vrev8.v +- vrol.v[vx] +- vror.v[vxi] +- vwsll.[vv,vx,vi] + +[NOTE] +==== +All <> instructions are also covered by DIEL as they are a +proper subset of <> +==== + +===== All <> instructions +- vclmul[h].v[vx] + +===== add/sub +- v[r]sub.v[vx] +- vadd.v[ivx] +- vsub.v[vx] +- vwadd[u].[vw][vx] +- vwsub[u].[vw][vx] + +===== add/sub with carry +- vadc.v[ivx]m +- vmadc.v[ivx][m] +- vmsbc.v[vx]m +- vsbc.v[vx]m + +===== compare and set +- vmseq.v[vxi] +- vmsgt[u].v[xi] +- vmsle[u].v[xi] +- vmslt[u].v[xi] +- vmsne.v[ivx] + +===== copy +- vmv.s.x +- vmv.v.[ivxs] +- vmv[1248]r.v + +===== extend +- vsext.vf[248] +- vzext.vf[248] + +===== logical +- vand.v[ivx] +- vm[n]or.mm +- vmand[n].mm +- vmnand.mm +- vmorn.mm +- vmx[n]or.mm +- vor.v[ivx] +- vxor.v[ivx] + +===== multiply +- vmul[h].v[vx] +- vmulh[s]u.v[vx] +- vwmul.v[vx] +- vwmul[s]u.v[vx] + +===== multiply-add +- vmacc.v[vx] +- vmadd.v[vx] +- vnmsac.v[vx] +- vnmsub.v[vx] +- vwmacc.v[vx] +- vwmacc[s]u.v[vx] +- vwmaccus.vx + +===== Integer Merge +- vmerge.v[ivx]m + +===== permute +In the `.vv` and `.xv` forms of the `vrgather[ei16]` instructions, +the values in `vs1` and `rs1` are used for control and therefore are exempt from DIEL. + +- vrgather.v[ivx] +- vrgatherei16.vv + +===== shift +// The values in `vs1`, `rs1`, `imm` are used for control (i.e., shift amount) and are exempt from DIEL. + +- vnsr[al].w[ivx] +- vsll.v[ivx] +- vsr[al].v[ivx] + +===== slide +- vslide1[up|down].vx +- vfslide1[up|down].vf + +In the vslide[up|down].vx instructions, the value in `rs1` +is used for control (i.e., slide amount) and therefore is exempt +from DIEL. + +- vslide[up|down].v[ix] + +[NOTE] +==== +The following instructions are not affected by Zvkt: + +- *All storage operations* +- *All floating-point operations* +- add/sub saturate +* vsadd[u].v[ivx] +* vssub[u].v[vx] +- clip +* vnclip[u].w[ivx] +- compress +* vcompress.vm +- divide +* vdiv[u].v[vx] +* vrem[u].v[vx] +- average +* vaadd[u].v[vx] +* vasub[u].v[vx] +- mask Op +* vcpop.m +* vfirst.m +* vid.v +* viota.m +* vms[bio]f.m +- min/max +* vmax[u].v[vx] +* vmin[u].v[vx] +- Multiply-saturate +* vsmul.v[vx] +- reduce +* vredsum.vs +* vwredsum[u].vs +* vred[and|or|xor].vs +* vred[min|max][u].vs +- shift round +* vssra.v[ivx] +* vssrl.v[ivx] +- vset +* vsetivli +* vsetvl[i] +==== + +[[crypto_vector_insns, reftext="Vector Cryptography Instructions"]] +=== Instructions + +[[insns-vaesdf, Vector AES decrypt final round]] +==== vaesdf.[vv,vs] + +Synopsis:: +Vector AES final-round decryption + +Mnemonic:: +vaesdf.vv vd, vs2 + +vaesdf.vs vd, vs2 + +Encoding (Vector-Vector):: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-VE'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPMVV'}, +{bits: 5, name: '00001'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: '1'}, +{bits: 6, name: '101000'}, +]} +.... + +Encoding (Vector-Scalar):: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-VE'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPMVV'}, +{bits: 5, name: '00001'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: '1'}, +{bits: 6, name: '101001'}, +]} +.... +Reserved Encodings:: +* `SEW` is any value other than 32 +* Only for the `.vs` form: the `vd` register group overlaps the `vs2` scalar element group + +Arguments:: + +[%autowidth] +[%header,cols="4,2,2,2,2,2"] +|=== +|Register +|Direction +|EGW +|EGS +|EEW +|Definition + +| Vd | input | 128 | 4 | 32 | round state +| Vs2 | input | 128 | 4 | 32 | round key +| Vd | output | 128 | 4 | 32 | new round state +|=== + +Description:: +[[norm:vaesdf_final]] A final-round AES block cipher decryption is performed. + +[#norm:vaesdf_ops]#The InvShiftRows and InvSubBytes steps are applied to each round state element group from `vd`.# +[#norm:vaesdf_xor_form]#This is then XORed with the round key in either the corresponding element group in `vs2` (vector-vector +form) or scalar element group in `vs2` (vector-scalar form).# + +This instruction must always be implemented such that its execution latency does not depend +on the data being operated upon. + +// if( ((vl%EGS)<>0) | ((vstart%EGS)<>0) | (LMUL*VLEN < EGW)) then { + +Operation:: +[source,sail] +-- +function clause execute (VAESDF(vs2, vd, suffix)) = { + if(LMUL*VLEN < EGW) then { + handle_illegal(); // illegal-instruction exception + RETIRE_FAIL + } else { + + eg_len = (vl/EGS) + eg_start = (vstart/EGS) + + foreach (i from eg_start to eg_len-1) { + let keyelem = if suffix == "vv" then i else 0; + let state : bits(128) = get_velem(vd, EGW=128, i); + let rkey : bits(128) = get_velem(vs2, EGW=128, keyelem); + let sr : bits(128) = aes_shift_rows_inv(state); + let sb : bits(128) = aes_subbytes_inv(sr); + let ark : bits(128) = sb ^ rkey; + set_velem(vd, EGW=128, i, ark); + } + RETIRE_SUCCESS + } +} +-- + +Included in:: +<>, <>, <>, <> + +<<< + +[[insns-vaesdm, Vector AES decrypt middle round]] +==== vaesdm.[vv,vs] + +Synopsis:: +Vector AES middle-round decryption + +Mnemonic:: +vaesdm.vv vd, vs2 + +vaesdm.vs vd, vs2 + +Encoding (Vector-Vector):: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-VE'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPMVV'}, +{bits: 5, name: '00000'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: '1'}, +{bits: 6, name: '101000'}, +]} +.... + +Encoding (Vector-Scalar):: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-VE'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPMVV'}, +{bits: 5, name: '00000'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: '1'}, +{bits: 6, name: '101001'}, +]} +.... +Reserved Encodings:: +* `SEW` is any value other than 32 +* Only for the `.vs` form: the `vd` register group overlaps the `vs2` scalar element group + +Arguments:: + +[%autowidth] +[%header,cols="4,2,2,2,2,2"] +|=== +|Register +|Direction +|EGW +|EGS +|EEW +|Definition + +| Vd | input | 128 | 4 | 32 | round state +| Vs2 | input | 128 | 4 | 32 | round key +| Vd | output | 128 | 4 | 32 | new round state +|=== + +Description:: +[[norm:vaesdm_mid]] A middle-round AES block cipher decryption is performed. + +[#norm:vaesdm_ops]#The InvShiftRows and InvSubBytes steps are applied to each round state element group from `vd`.# +[#norm:vaesdm_xor_form]#This is then XORed with the round key in either the corresponding element group in `vs2` (vector-vector +form) or the scalar element group in `vs2` (vector-scalar form).# The result is then applied to the +[#norm:vaesdm_invmix]#InvMixColumns step.# + +This instruction must always be implemented such that its execution latency does not depend +on the data being operated upon. +// +// The number of element groups to be processed is `vl`/`EGS`. +// `vl` must be set to the number of `SEW=32` elements to be processed and +// therefore must be a multiple of `EGS=4`. + +// Likewise, `vstart` must be a multiple of `EGS=4`. + +Operation:: +[source,sail] +-- +function clause execute (VAESDM(vs2, vd, suffix)) = { + if(LMUL*VLEN < EGW) then { + handle_illegal(); // illegal-instruction exception + RETIRE_FAIL + } else { + + eg_len = (vl/EGS) + eg_start = (vstart/EGS) + + foreach (i from eg_start to eg_len-1) { + let keyelem = if suffix == "vv" then i else 0; + let state : bits(128) = get_velem(vd, EGW=128, i); + let rkey : bits(128) = get_velem(vs2, EGW=128, keyelem); + let sr : bits(128) = aes_shift_rows_inv(state); + let sb : bits(128) = aes_subbytes_inv(sr); + let ark : bits(128) = sb ^ rkey; + let mix : bits(128) = aes_mixcolumns_inv(ark); + set_velem(vd, EGW=128, i, mix); + } + RETIRE_SUCCESS + } +} +-- + +Included in:: +<>, <>, <>, <> + +<<< + +[[insns-vaesef, Vector AES encrypt final round]] +==== vaesef.[vv,vs] + +Synopsis:: +Vector AES final-round encryption + +Mnemonic:: +vaesef.vv vd, vs2 + +vaesef.vs vd, vs2 + +Encoding (Vector-Vector):: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-VE'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPMVV'}, +{bits: 5, name: '00011'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: '1'}, +{bits: 6, name: '101000'}, +]} +.... + +Encoding (Vector-Scalar):: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-VE'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPMVV'}, +{bits: 5, name: '00011'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: '1'}, +{bits: 6, name: '101001'}, +]} +.... +Reserved Encodings:: +* `SEW` is any value other than 32 +* Only for the `.vs` form: the `vd` register group overlaps the `vs2` scalar element group + +Arguments:: + +[%autowidth] +[%header,cols="4,2,2,2,2,2"] +|=== +|Register +|Direction +|EGW +|EGS +|EEW +|Definition + +| vd | input | 128 | 4 | 32 | round state +| vs2 | input | 128 | 4 | 32 | round key +| vd | output | 128 | 4 | 32 | new round state +|=== + +Description:: +[[norm:vaesef_final]] A final-round encryption function of the AES block cipher is performed. + +[#norm:vaesef_ops]#The SubBytes and ShiftRows steps are applied to each round state element group from `vd`.# +[#norm:vaesef_xor_form]#This is then XORed with the round key in either the corresponding element group in `vs2` (vector-vector +form) or the scalar element group in `vs2` (vector-scalar form).# + +This instruction must always be implemented such that its execution latency does not depend +on the data being operated upon. +// +// The number of element groups to be processed is `vl`/`EGS`. +// `vl` must be set to the number of `SEW=32` elements to be processed and +// therefore must be a multiple of `EGS=4`. + +// Likewise, `vstart` must be a multiple of `EGS=4`. + + +Operation:: +[source,sail] +-- +function clause execute (VAESEF(vs2, vd, suffix) = { + if(LMUL*VLEN < EGW) then { + handle_illegal(); // illegal-instruction exception + RETIRE_FAIL + } else { + + eg_len = (vl/EGS) + eg_start = (vstart/EGS) + + foreach (i from eg_start to eg_len-1) { + let keyelem = if suffix == "vv" then i else 0; + let state : bits(128) = get_velem(vd, EGW=128, i); + let rkey : bits(128) = get_velem(vs2, EGW=128, keyelem); + let sb : bits(128) = aes_subbytes_fwd(state); + let sr : bits(128) = aes_shift_rows_fwd(sb); + let ark : bits(128) = sr ^ rkey; + set_velem(vd, EGW=128, i, ark); + } + RETIRE_SUCCESS + } +} +-- + +Included in:: +<>, <>, <>, <> + +<<< + +[[insns-vaesem, Vector AES encrypt middle round]] +==== vaesem.[vv,vs] + +Synopsis:: +Vector AES middle-round encryption + +Mnemonic:: +vaesem.vv vd, vs2 + +vaesem.vs vd, vs2 + +Encoding (Vector-Vector):: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-VE'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPMVV'}, +{bits: 5, name: '00010'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: '1'}, +{bits: 6, name: '101000'}, +]} +.... + +Encoding (Vector-Scalar):: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-VE'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPMVV'}, +{bits: 5, name: '00010'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: '1'}, +{bits: 6, name: '101001'}, +]} +.... +Reserved Encodings:: +* `SEW` is any value other than 32 +* Only for the `.vs` form: the `vd` register group overlaps the `vs2` scalar element group + + +Arguments:: + +[%autowidth] +[%header,cols="4,2,2,2,2,2"] +|=== +|Register +|Direction +|EGW +|EGS +|EEW +|Definition + +| Vd | input | 128 | 4 | 32 | round state +| Vs2 | input | 128 | 4 | 32 | Round key +| Vd | output | 128 | 4 | 32 | new round state +|=== + +Description:: +[[norm:vaesem_mid]] A middle-round encryption function of the AES block cipher is performed. + +[#norm:vaesem_ops]#The SubBytes, ShiftRows, and MixColumns steps are applied to each round state element group from `vd`.# +[#norm:vaesem_xor_form]#This is then XORed with the round key in either the corresponding element group in `vs2` (vector-vector +form) or the scalar element group in `vs2` (vector-scalar form).# + +This instruction must always be implemented such that its execution latency does not depend +on the data being operated upon. +// +// The number of element groups to be processed is `vl`/`EGS`. +// `vl` must be set to the number of `SEW=32` elements to be processed and +// therefore must be a multiple of `EGS=4`. + +// Likewise, `vstart` must be a multiple of `EGS=4`. + +Operation:: +[source,sail] +-- +function clause execute (VAESEM(vs2, vd, suffix)) = { + if(LMUL*VLEN < EGW) then { + handle_illegal(); // illegal-instruction exception + RETIRE_FAIL + } else { + + eg_len = (vl/EGS) + eg_start = (vstart/EGS) + + foreach (i from eg_start to eg_len-1) { + let keyelem = if suffix == "vv" then i else 0; + let state : bits(128) = get_velem(vd, EGW=128, i); + let rkey : bits(128) = get_velem(vs2, EGW=128, keyelem); + let sb : bits(128) = aes_subbytes_fwd(state); + let sr : bits(128) = aes_shift_rows_fwd(sb); + let mix : bits(128) = aes_mixcolumns_fwd(sr); + let ark : bits(128) = mix ^ rkey; + set_velem(vd, EGW=128, i, ark); + } + RETIRE_SUCCESS + } +} +-- + +Included in:: +<>, <>, <>, <> + +<<< + +[[insns-vaeskf1, Vector AES-128 Forward KeySchedule]] +==== vaeskf1.vi + +Synopsis:: +Vector AES-128 Forward KeySchedule generation + +Mnemonic:: +vaeskf1.vi vd, vs2, uimm + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-VE'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPMVV'}, +{bits: 5, name: 'uimm'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: '1'}, +{bits: 6, name: '100010'}, +]} +.... +Reserved Encodings:: +* `SEW` is any value other than 32 + +Arguments:: + +[%autowidth] +[%header,cols="4,2,2,2,2,2"] +|=== +|Register +|Direction +|EGW +|EGS +|EEW +|Definition + +| uimm | input | - | - | - | Round Number (rnd) +| Vs2 | input | 128 | 4 | 32 | Current round key +| Vd | output | 128 | 4 | 32 | Next round key +|=== + +Description:: +[#norm:vaeskf1_round]#A single round of the forward AES-128 KeySchedule is performed.# + +// Within each element group, +[#norm:vaeskf1_wordgen]#The next round key is generated word by word from the +current round key element group in `vs2` and the immediately previous word of the +round key.# The least significant word is generated using the most significant +word of the current round key as well as a round constant which is selected by +the round number. + +The round number, which [#norm:vaeskf1_uimm_src]#ranges from 1 to 10, comes from `uimm[3:0]`; +`uimm[4]` is ignored.# +[#norm:vaeskf1_uimm_map]#The out-of-range `uimm[3:0]` values of 0 and 11-15 are mapped to in-range +values by inverting `uimm[3]`.# Thus, 0 maps to 8, and 11-15 maps to 3-7. +The round number is used to specify a round constant which is used in generating +the first round key word. + +This instruction must always be implemented such that its execution latency does not depend +on the data being operated upon. + +[NOTE] +==== +We chose to map out-of-range round numbers to in-range values as this allows the instruction's +behavior to be fully defined for all values of `uimm[4:0]` with minimal extra logic. +==== + +// Each `EGW=128` element group next-round-key output is produced and is written to each `EGW=128` +// element group of `vd`. + + +// +// The number of element groups to be processed is `vl`/`EGS`. +// `vl` must be set to the number of `SEW=32` elements to be processed and +// therefore must be a multiple of `EGS=4`. + +// Likewise, `vstart` must be a multiple of `EGS=4`. + + +Operation:: +[source,Sail] +-- +function clause execute (VAESKF1(rnd, vd, vs2)) = { + if(LMUL*VLEN < EGW) then { + handle_illegal(); // illegal-instruction exception + RETIRE_FAIL + } else { + + // project out-of-range immediates onto in-range values + if( (unsigned(rnd[3:0]) > 10) | (rnd[3:0] = 0)) then rnd[3] = ~rnd[3] + + eg_len = (vl/EGS) + eg_start = (vstart/EGS) + + let r : bits(4) = rnd-1; + + foreach (i from eg_start to eg_len-1) { + let CurrentRoundKey[3:0] : bits(128) = get_velem(vs2, EGW=128, i); + let w[0] : bits(32) = aes_subword_fwd(aes_rotword(CurrentRoundKey[3])) XOR + aes_decode_rcon(r) XOR CurrentRoundKey[0] + let w[1] : bits(32) = w[0] XOR CurrentRoundKey[1] + let w[2] : bits(32) = w[1] XOR CurrentRoundKey[2] + let w[3] : bits(32) = w[2] XOR CurrentRoundKey[3] + set_velem(vd, EGW=128, i, w[3:0]); + } + RETIRE_SUCCESS + } +} + +-- + +Included in:: +<>, <>, <>, <> + +<<< + +[[insns-vaeskf2, Vector AES-256 Forward KeySchedule]] +==== vaeskf2.vi + +Synopsis:: +Vector AES-256 Forward KeySchedule generation + +Mnemonic:: +vaeskf2.vi vd, vs2, uimm + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-VE'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPMVV'}, +{bits: 5, name: 'uimm'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: '1'}, +{bits: 6, name: '101010'}, +]} +.... +Reserved Encodings:: +* `SEW` is any value other than 32 + +Arguments:: + +[%autowidth] +[%header,cols="4,2,2,2,2,2"] +|=== +|Register +|Direction +|EGW +|EGS +|EEW +|Definition + +| Vd | input | 128 | 4 | 32 | Previous Round key +| uimm | input | - | - | - | Round Number (rnd) +| Vs2 | input | 128 | 4 | 32 | Current Round key +| Vd | output | 128 | 4 | 32 | Next round key +|=== + +Description:: +[#norm:vaeskf2_round]#A single round of the forward AES-256 KeySchedule is performed.# + +// Within each element group, +[#norm:vaeskf2_wordgen]#The next round key is generated word by word from the +previous round key element group in `vd` and the immediately previous word of the +round key.# The [#norm:vaeskf2_rcon_lsw]#least significant word of the next round key is generated by +applying a function to the most significant word of the current round key and +then XORing the result with the round constant.# +[#norm:vaeskf2_rcon_func]#The round number is used to select the round constant as well as the function.# + +The round number, which [#norm:vaeskf2_uimm_src]#ranges from 2 to 14, comes from `uimm[3:0]`; +`uimm[4]` is ignored.# +[#norm:vaeskf2_uimm_map]#The out-of-range `uimm[3:0]` values of 0-1 and 15 are mapped to in-range +values by inverting `uimm[3]`.# Thus, 0-1 maps to 8-9, and 15 maps to 7. + +This instruction must always be implemented such that its execution latency does not depend +on the data being operated upon. + +[NOTE] +==== +We chose to map out-of-range round numbers to in-range values as this allows the instruction's +behavior to be fully defined for all values of `uimm[4:0]` with minimal extra logic. +==== + +// + +// The number of element groups to be processed is `vl`/`EGS`. +// `vl` must be set to the number of `SEW=32` elements to be processed and +// therefore must be a multiple of `EGS=4`. + +// Likewise, `vstart` must be a multiple of `EGS=4`. + +Operation:: +[source,Sail] +-- +function clause execute (VAESKF2(rnd, vd, vs2)) = { + if(LMUL*VLEN < EGW) then { + handle_illegal(); // illegal-instruction exception + RETIRE_FAIL + } else { + + // project out-of-range immediates into in-range values + if((unsigned(rnd[3:0]) < 2) | (unsigned(rnd[3:0]) > 14)) then rnd[3] = ~rnd[3] + + eg_len = (vl/EGS) + eg_start = (vstart/EGS) + + foreach (i from eg_start to eg_len-1) { + let CurrentRoundKey[3:0] : bits(128) = get_velem(vs2, EGW=128, i); + let RoundKeyB[3:0] : bits(128) = get_velem(vd, EGW=128, i); // Previous round key + + let w[0] : bits(32) = if (rnd[0]==1) then + aes_subword_fwd(CurrentRoundKey[3]) XOR RoundKeyB[0]; + else + aes_subword_fwd(aes_rotword(CurrentRoundKey[3])) XOR aes_decode_rcon((rnd>>1) - 1) XOR RoundKeyB[0]; + w[1] : bits(32) = w[0] XOR RoundKeyB[1] + w[2] : bits(32) = w[1] XOR RoundKeyB[2] + w[3] : bits(32) = w[2] XOR RoundKeyB[3] + set_velem(vd, EGW=128, i, w[3:0]); + } + RETIRE_SUCCESS + } +} +-- + +Included in:: +<>, <>, <>, <> + +<<< + +[[insns-vaesz, Vector AES round zero]] +==== vaesz.vs + +Synopsis:: +Vector AES round zero encryption/decryption + +Mnemonic:: +vaesz.vs vd, vs2 + +Encoding (Vector-Scalar):: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-VE'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPMVV'}, +{bits: 5, name: '00111'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: '1'}, +{bits: 6, name: '101001'}, +]} +.... +Reserved Encodings:: +* `SEW` is any value other than 32 +* The `vd` register group overlaps the `vs2` register + +Arguments:: + +[%autowidth] +[%header,cols="4,2,2,2,2,2"] +|=== +|Register +|Direction +|EGW +|EGS +|EEW +|Definition + +| vd | input | 128 | 4 | 32 | round state +| vs2 | input | 128 | 4 | 32 | round key +| vd | output | 128 | 4 | 32 | new round state +|=== + +Description:: +[#norm:vaesz_round0]#A round-0 AES block cipher operation is performed.# This operation is used for both encryption and decryption. + +[#norm:vaesz_vs_only]#There is only a `.vs` form of the instruction.# +[#norm:vaesz_vs2_rk]#`Vs2` holds a +scalar element group that is used +as the round key for all of the round state element groups.# +The new round state output of each element group is produced by XORing +the round key with each element group of `vd`. + +This instruction must always be implemented such that its execution latency does not depend +on the data being operated upon. + +[NOTE] +==== +This instruction is needed to avoid the need to "splat" a 128-bit vector register group when the round key is the same for +all 128-bit "lanes". Such a splat would typically be implemented with a `vrgather` instruction which would hurt performance +in many implementations. +This instruction only exists in the `.vs` form because the `.vv` form would be identical to the `vxor.vv vd, vs2, vd` instruction. +==== + +// +// The number of element groups to be processed is `vl`/`EGS`. +// `vl` must be set to the number of `SEW=32` elements to be processed and +// therefore must be a multiple of `EGS=4`. + +// Likewise, `vstart` must be a multiple of `EGS=4`. + +Operation:: +[source,sail] +-- +function clause execute (VAESZ(vs2, vd) = { + if(((vstart%EGS)<>0) | (LMUL*VLEN < EGW)) then { + handle_illegal(); // illegal-instruction exception + RETIRE_FAIL + } else { + + eg_len = (vl/EGS) + eg_start = (vstart/EGS) + + foreach (i from eg_start to eg_len-1) { + let state : bits(128) = get_velem(vd, EGW=128, i); + let rkey : bits(128) = get_velem(vs2, EGW=128, 0); + let ark : bits(128) = state ^ rkey; + set_velem(vd, EGW=128, i, ark); + } + RETIRE_SUCCESS + } +} +-- + +Included in:: +<>, <>, <>, <> + +<<< + +[[insns-vandn, Vector And-Not]] +==== vandn.[vv,vx] + +Synopsis:: +Bitwise And-Not + +Mnemonic:: +vandn.vv vd, vs2, vs1, vm + +vandn.vx vd, vs2, rs1, vm + +Encoding (Vector-Vector):: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-V'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPIVV'}, +{bits: 5, name: 'vs1'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: 'vm'}, +{bits: 6, name: '000001'}, +]} +.... + +Encoding (Vector-Scalar):: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-V'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPIVX'}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: 'vm'}, +{bits: 6, name: '000001'}, +]} +.... + +Vector-Vector Arguments:: + +[%autowidth] +[%header,cols="4,2,2"] +|=== +|Register +|Direction +|Definition + +| Vs1 | input | Op1 (to be inverted) +| Vs2 | input | Op2 +| Vd | output | Result +|=== + +Vector-Scalar Arguments:: + +[%autowidth] +[%header,cols="4,2,2"] +|=== +|Register +|Direction +|Definition + +| Rs1 | input | Op1 (to be inverted) +| Vs2 | input | Op2 +| Vd | output | Result +|=== + +Description:: +A bitwise _and-not_ operation is performed. + +[#norm:vandn_op]#Each bit of `Op1` is inverted and logically ANDed with the corresponding bits in `vs2`.# +[#norm:vandn-vx_rs1]#In the vector-scalar version, `Op1` is the sign-extended or truncated value in scalar +register `rs1`.# +[#norm:vandn-vv_vs1]#In the vector-vector version, `Op1` is `vs1`.# + +// This instruction must always be implemented such that its execution latency does not depend +// on the data being operated upon. + +[NOTE] +.Note on necessity of instruction +==== +This instruction is performance-critical to SHA3. Specifically, the Chi step of the FIPS 202 Keccak Permutation. +Emulating it via 2 instructions is expected to have significant performance impact. +The `.vv` form of the instruction is what is needed for SHA3; the `.vx` form was added for completeness. +==== + +[NOTE] +==== +There is no .vi version of this instruction because the same functionality can be achieved by using an inversion +of the immediate value with the `vand.vi` instruction. +==== + +Operation:: +[source,sail] +-- +function clause execute (VANDN(vs2, vs1, vd, suffix)) = { + foreach (i from vstart to vl-1) { + let op1 = match suffix { + "vv" => get_velem(vs1, SEW, i), + "vx" => sext_or_truncate_to_sew(X(vs1)) + }; + let op2 = get_velem(vs2, SEW, i); + set_velem(vd, EEW=SEW, i, ~op1 & op2); + } + RETIRE_SUCCESS +} + +-- + +Included in:: +<>, <>, <>, <>, <>, <> +<>, <> + +<<< + +[[insns-vbrev, Vector Reverse Bits in Elements]] +==== vbrev.v + +Synopsis:: +Vector Reverse Bits in Elements + +Mnemonic:: +vbrev.v vd, vs2, vm + +Encoding (Vector):: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-V'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPMVV'}, +{bits: 5, name: '01010'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: 'vm'}, +{bits: 6, name: '010010'}, +]} +.... + +Arguments:: + +[%autowidth] +[%header,cols="4,2,2"] +|=== +|Register +|Direction +|Definition + +| Vs2 | input | Input elements +| Vd | output | Elements with bits reversed +|=== + +Description:: +[#norm:vbrev-v_op]#A bit reversal is performed on the bits of each element.# + +Operation:: +[source,sail] +-- +function clause execute (VBREV(vs2)) = { + + foreach (i from vstart to vl-1) { + let input = get_velem(vs2, SEW, i); + let output : bits(SEW) = 0; + foreach (i from 0 to SEW-1) + let output[SEW-1-i] = input[i]; + set_velem(vd, SEW, i, output) + } + RETIRE_SUCCESS +} +-- + +Included in:: +<> + +<<< + +[[insns-vbrev8, Vector Reverse Bits in Bytes]] +==== vbrev8.v + +Synopsis:: +Vector Reverse Bits in Bytes + +Mnemonic:: +vbrev8.v vd, vs2, vm + +Encoding (Vector):: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-V'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPMVV'}, +{bits: 5, name: '01000'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: 'vm'}, +{bits: 6, name: '010010'}, +]} +.... + +Arguments:: + +[%autowidth] +[%header,cols="4,2,2"] +|=== +|Register +|Direction +|Definition + +| Vs2 | input | Input elements +| Vd | output | Elements with bit-reversed bytes +|=== + +Description:: +[#norm:vbrev8-v_op]#A bit reversal is performed on the bits of each byte.# + +// This instruction must always be implemented such that its execution latency does not depend +// on the data being operated upon. + +[NOTE] +==== +This instruction is commonly used for GCM when the zvkg extension is not implemented. +This byte-wise instruction is defined for all SEWs to eliminate the need to change SEW when operating on wider elements. +==== + +Operation:: +[source,sail] +-- +function clause execute (VBREV8(vs2)) = { + + foreach (i from vstart to vl-1) { + let input = get_velem(vs2, SEW, i); + let output : bits(SEW) = 0; + foreach (i from 0 to SEW-8 by 8) + let output[i+7..i] = reverse_bits_in_byte(input[i+7..i]); + set_velem(vd, SEW, i, output) + } + RETIRE_SUCCESS +} +-- + +Included in:: +<>, <>, <>, <>, <>, <> +<>, <> + +<<< + +[[insns-vclmul, Vector Carry-less Multiply]] +==== vclmul.[vv,vx] + +Synopsis:: +Vector Carry-less Multiply by vector or scalar - returning low half of product. + +Mnemonic:: +vclmul.vv vd, vs2, vs1, vm + +vclmul.vx vd, vs2, rs1, vm + +Encoding (Vector-Vector):: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-V'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPMVV'}, +{bits: 5, name: 'vs1'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: 'vm'}, +{bits: 6, name: '001100'}, +]} +.... + +Encoding (Vector-Scalar):: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-V'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPMVX'}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: 'vm'}, +{bits: 6, name: '001100'}, +]} +.... +Reserved Encodings:: +* [#norm:vclmul_sewn64_rsv]#`SEW` is any value other than 64# + +Arguments:: + +[%autowidth] +[%header,cols="4,2,2"] +|=== +|Register +|Direction +|Definition + +| Vs1/Rs1 | input | multiplier +| Vs2 | input | multiplicand +| Vd | output | carry-less product low +|=== + +Description:: +Produces the low half of 128-bit carry-less product. + +[#norm:vclmul_op]#Each 64-bit element in the `vs2` vector register is carry-less multiplied by +either each 64-bit element in `vs1` (vector-vector), or the 64-bit value +from integer register `rs1` (vector-scalar). The result is the least +significant 64 bits of the carry-less product.# + +[NOTE] +==== +The 64-bit carry-less multiply instructions can be used for implementing GCM in the absence of the `zvkg` extension. +We do not make these instructions exclusive as the 64-bit carry-less multiply is readily derived from the +instructions in the `zvkg` extension and can have utility in other areas. +Likewise, we treat other SEW values as reserved so as not to preclude +future extensions from using this opcode with different element widths. +For example, a future extension might define an `SEW`=32 version of this instruction to enable `Zve32*` implementations to have +vector carry-less multiplication instructions. +==== + +Operation:: +[source,sail] +-- + + +function clause execute (VCLMUL(vs2, vs1, vd, suffix)) = { + + foreach (i from vstart to vl-1) { + let op1 : bits (64) = if suffix =="vv" then get_velem(vs1,i) + else zext_or_truncate_to_sew(X(vs1)); + let op2 : bits (64) = get_velem(vs2,i); + let product : bits (64) = clmul(op1,op2,SEW); + set_velem(vd, i, product); + } + RETIRE_SUCCESS +} + +function clmul(x, y, width) = { + let result : bits(width) = zeros(); + foreach (i from 0 to (width - 1)) { + if y[i] == 1 then result = result ^ (x << i); + } + result +} +-- + +Included in:: +<>, <>, <> + +<<< + +[[insns-vclmulh, Vector Carry-less Multiply Return High Half]] +==== vclmulh.[vv,vx] + +Synopsis:: +Vector Carry-less Multiply by vector or scalar - returning high half of product. + +Mnemonic:: +vclmulh.vv vd, vs2, vs1, vm + +vclmulh.vx vd, vs2, rs1, vm + +Encoding (Vector-Vector):: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-V'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPMVV'}, +{bits: 5, name: 'vs1'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: 'vm'}, +{bits: 6, name: '001101'}, +]} +.... + +Encoding (Vector-Scalar):: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-V'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPMVX'}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: 'vm'}, +{bits: 6, name: '001101'}, +]} +.... +Reserved Encodings:: +* [#norm:vclmulh_sewn64_rsv]#`SEW` is any value other than 64# + +Arguments:: + +[%autowidth] +[%header,cols="4,2,2"] +|=== +|Register +|Direction +|Definition + +| Vs1 | input | multiplier +| Vs2 | input | multiplicand +| Vd | output | carry-less product high +|=== + +Description:: +Produces the high half of 128-bit carry-less product. + +[#norm:vclmulh_op]#Each 64-bit element in the `vs2` vector register is carry-less multiplied by +either each 64-bit element in `vs1` (vector-vector), or the 64-bit value +from integer register `rs1` (vector-scalar). The result is the most +significant 64 bits of the carry-less product.# + +// This instruction must always be implemented such that its execution latency does not depend +// on the data being operated upon. + +Operation:: +[source,sail] +-- +function clause execute (VCLMULH(vs2, vs1, vd, suffix)) = { + + foreach (i from vstart to vl-1) { + let op1 : bits (64) = if suffix =="vv" then get_velem(vs1,i) + else zext_or_truncate_to_sew(X(vs1)); + let op2 : bits (64) = get_velem(vs2, i); + let product : bits (64) = clmulh(op1, op2, SEW); + set_velem(vd, i, product); + } + RETIRE_SUCCESS +} + +function clmulh(x, y, width) = { + let result : bits(width) = 0; + foreach (i from 1 to (width - 1)) { + if y[i] == 1 then result = result ^ (x >> (width - i)); + } + result +} + +-- + +Included in:: +<>, <>, <> + +<<< + +[[insns-vclz, Vector Count Leading Zeros]] +==== vclz.v + +Synopsis:: +Vector Count Leading Zeros + +Mnemonic:: +vclz.v vd, vs2, vm + +Encoding (Vector):: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-V'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPMVV'}, +{bits: 5, name: '01100'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: 'vm'}, +{bits: 6, name: '010010'}, +]} +.... + +Arguments:: + +[%autowidth] +[%header,cols="4,2,2"] +|=== +|Register +|Direction +|Definition + +| Vs2 | input | Input elements +| Vd | output | Count of leading zero bits +|=== + +Description:: +[#norm:vclz-v_op]#A leading zero count is performed on each element.# + +[#norm:vclz-v_op_zeroinput]#The result for zero-valued inputs is the value SEW.# + +Operation:: +[source,sail] +-- +function clause execute (VCLZ(vs2)) = { + + foreach (i from vstart to vl-1) { + let input = get_velem(vs2, SEW, i); + for (j = (SEW - 1); j >= 0; j--) + if [input[j]] == 0b1 then break; + set_velem(vd, SEW, i, SEW - 1 - j) + } + RETIRE_SUCCESS +} +-- + +Included in:: +<> + +[[insns-vcpop, Vector Population Count]] +==== vcpop.v + +Synopsis:: +Count the number of bits set in each element + +Mnemonic:: +vcpop.v vd, vs2, vm + +Encoding (Vector):: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-V'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPMVV'}, +{bits: 5, name: '01110'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: 'vm'}, +{bits: 6, name: '010010'}, +]} +.... + +Arguments:: + +[%autowidth] +[%header,cols="4,2,2"] +|=== +|Register +|Direction +|Definition + +| Vs2 | input | Input elements +| Vd | output | Count of bits set +|=== + +Description:: +[#norm:vcpop-v_op]#A population count is performed on each element.# + +Operation:: +[source,sail] +-- +function clause execute (VCPOP(vs2)) = { + + foreach (i from vstart to vl-1) { + let input = get_velem(vs2, SEW, i); + let output : bits(SEW) = 0; + for (j = 0; j < SEW; j++) + output = output + input[j]; + set_velem(vd, SEW, i, output) + } + RETIRE_SUCCESS +} +-- + +Included in:: +<> + +[[insns-vctz, Vector Count Trailing Zeros]] +==== vctz.v + +Synopsis:: +Vector Count Trailing Zeros + +Mnemonic:: +vctz.v vd, vs2, vm + +Encoding (Vector):: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-V'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPMVV'}, +{bits: 5, name: '01101'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: 'vm'}, +{bits: 6, name: '010010'}, +]} +.... + +Arguments:: + +[%autowidth] +[%header,cols="4,2,2"] +|=== +|Register +|Direction +|Definition + +| Vs2 | input | Input elements +| Vd | output | Count of trailing zero bits +|=== + +Description:: +[#norm:vctz-v_op]#A trailing zero count is performed on each element.# + +// The result for zero-valued inputs is the value SEW. + +Operation:: +[source,sail] +-- +function clause execute (VCTZ(vs2)) = { + + foreach (i from vstart to vl-1) { + let input = get_velem(vs2, SEW, i); + for (j = 0; j < SEW; j++) + if [input[j]] == 0b1 then break; + set_velem(vd, SEW, i, j) + } + RETIRE_SUCCESS +} +-- + +Included in:: +<> + +<<< + +[[insns-vghsh, Vector GHASH Add-Multiply]] +==== vghsh.vv + +Synopsis:: +Vector Add-Multiply over GHASH Galois-Field + +Mnemonic:: +vghsh.vv vd, vs2, vs1 + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-VE'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPMVV'}, +{bits: 5, name: 'vs1'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: '1'}, +{bits: 6, name: '101100'}, +]} +.... +Reserved Encodings:: +* [#norm:vghsh-vv_sewn32_rsv]#`SEW` is any value other than 32# + +Arguments:: + +[%autowidth] +[%header,cols="4,2,2,2,2,2"] +|=== +|Register +|Direction +|EGW +|EGS +|SEW +|Definition + +| Vd | input | 128 | 4 | 32 | Partial hash (Y~i~) +| Vs1 | input | 128 | 4 | 32 | Cipher text (X~i~) +| Vs2 | input | 128 | 4 | 32 | Hash Subkey (H) +| Vd | output | 128 | 4 | 32 | Partial-hash (Y~i+1~) +|=== + +Description:: +A single "iteration" of the GHASH~H~ algorithm is performed. + +[#norm:vghsh-vv_op]#This instruction treats all of the inputs and outputs as 128-bit polynomials and +performs operations over GF[2]. +It produces the next partial hash (Y~i+1~) by adding the current partial +hash (Y~i~) to the cipher text block (X~i~) and then multiplying (over GF(2^128^)) +this sum by the Hash Subkey (H).# + +[#norm:vghsh-vv_op_gf]#The multiplication over GF(2^128^) is a carry-less multiply of two 128-bit polynomials +modulo GHASH's irreducible polynomial (x^128^ + x^7^ + x^2^ + x + 1).# + +The operation can be compactly defined as +// Y~i+1~ = (Y~i~ {interpunct} H) ^ X~i~ +Y~i+1~ = ((Y~i~ ^ X~i~) {interpunct} H) + +[#norm:vghsh-vv_op_coeff]#The NIST specification (see <>) orders the coefficients from left to right x~0~x~1~x~2~...x~127~ +for a polynomial x~0~ + x~1~u +x~2~ u^2^ + ... + x~127~u^127^. This can be viewed as a collection of +byte elements in memory with the byte containing the lowest coefficients (i.e., 0,1,2,3,4,5,6,7) +residing at the lowest memory address. Since the bits in the bytes are reversed, +this instruction internally performs bit swaps within bytes to put the bits in the standard ordering +(e.g., 7,6,5,4,3,2,1,0).# + +[#norm:vghsh-vv_exeindepdata]#This instruction must always be implemented such that its execution latency does not depend +on the data being operated upon.# + +[NOTE] +==== +We are bit-reversing the bytes of inputs and outputs so that the intermediate values are consistent +with the NIST specification. These reversals are inexpensive to implement as they unconditionally +swap bit positions and therefore do not require any logic. +==== + +[NOTE] +==== +Since the same hash subkey `H` will typically be used repeatedly on a given message, +a future extension might define a vector-scalar version of this instruction where +`vs2` is the scalar element group. This would help reduce register pressure when `LMUL` > 1. +==== + +Operation:: +[source,pseudocode] +-- +function clause execute (VGHSH(vs2, vs1, vd)) = { + // operands are input with bits reversed in each byte + if(LMUL*VLEN < EGW) then { + handle_illegal(); // illegal-instruction exception + RETIRE_FAIL + } else { + + eg_len = (vl/EGS) + eg_start = (vstart/EGS) + + foreach (i from eg_start to eg_len-1) { + let Y = get_velem(vd,EGW=128,i); // current partial-hash + let X = get_velem(vs1,EGW=128,i); // block cipher output + let H = brev8(get_velem(vs2,EGW=128,i)); // Hash subkey + + let Z : bits(128) = 0; + + let S = brev8(Y ^ X); + + for (int bit = 0; bit < 128; bit++) { + if bit_to_bool(S[bit]) + Z ^= H + + bool reduce = bit_to_bool(H[127]); + H = H << 1; // left shift H by 1 + if (reduce) + H ^= 0x87; // Reduce using x^7 + x^2 + x^1 + 1 polynomial + } + + let result = brev8(Z); // bit reverse bytes to get back to GCM standard ordering + set_velem(vd, EGW=128, i, result); + } + RETIRE_SUCCESS + } +} +-- + +Included in:: +<>, <>, <> + +<<< + +[[insns-vgmul, Vector GHASH Multiply]] +==== vgmul.vv + +Synopsis:: +Vector Multiply over GHASH Galois-Field + +Mnemonic:: +vgmul.vv vd, vs2 + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-VE'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPMVV'}, +{bits: 5, name: '10001'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: '1'}, +{bits: 6, name: '101000'}, +]} +.... +Reserved Encodings:: +* [#norm:vgmul-vv_sewn32_rsv]#`SEW` is any value other than 32# + +Arguments:: + +[%autowidth] +[%header,cols="4,2,2,2,2,2"] +|=== +|Register +|Direction +|EGW +|EGS +|SEW +|Definition + +| Vd | input | 128 | 4 | 32 | Multiplier +| Vs2 | input | 128 | 4 | 32 | Multiplicand +| Vd | output | 128 | 4 | 32 | Product +|=== + +Description:: +A GHASH~H~ multiply is performed. + +[#norm:vgmul-vv_op]#This instruction treats all of the inputs and outputs as 128-bit polynomials and +performs operations over GF[2]. +It produces the product over GF(2^128^) of the two 128-bit inputs.# + +[#norm:vgmul-vv_op_gf]#The multiplication over GF(2^128^) is a carry-less multiply of two 128-bit polynomials +modulo GHASH's irreducible polynomial (x^128^ + x^7^ + x^2^ + x + 1).# + +[#norm:vgmul-vv_op_coeff]#The NIST specification (see <>) orders the coefficients from left to right x~0~x~1~x~2~...x~127~ +for a polynomial x~0~ + x~1~u +x~2~ u^2^ + ... + x~127~u^127^. This can be viewed as a collection of +byte elements in memory with the byte containing the lowest coefficients (i.e., 0,1,2,3,4,5,6,7) +residing at the lowest memory address. Since the bits in the bytes are reversed, +This instruction internally performs bit swaps within bytes to put the bits in the standard ordering +(e.g., 7,6,5,4,3,2,1,0).# + +[#norm:vgmul-vv_exeindepdata]#This instruction must always be implemented such that its execution latency does not depend +on the data being operated upon.# + +[NOTE] +==== +We are bit-reversing the bytes of inputs and outputs so that the intermediate values are consistent +with the NIST specification. These reversals are inexpensive to implement as they unconditionally +swap bit positions and therefore do not require any logic. +==== + +[NOTE] +==== +Since the same multiplicand will typically be used repeatedly on a given message, +a future extension might define a vector-scalar version of this instruction where +`vs2` is the scalar element group. This would help reduce register pressure when `LMUL` > 1. +==== + +[NOTE] +==== +This instruction is identical to `vghsh.vv` with vs1=0. +This instruction is often used in GHASH code. In some cases it is followed +by an XOR to perform a multiply-add. Implementations may choose to fuse these +two instructions to improve performance on GHASH code that +doesn't use the add-multiply form of the `vghsh.vv` instruction. +==== + + +Operation:: +[source,pseudocode] +-- +function clause execute (VGMUL(vs2, vs1, vd)) = { + // operands are input with bits reversed in each byte + if(LMUL*VLEN < EGW) then { + handle_illegal(); // illegal-instruction exception + RETIRE_FAIL + } else { + + eg_len = (vl/EGS) + eg_start = (vstart/EGS) + + foreach (i from eg_start to eg_len-1) { + let Y = brev8(get_velem(vd,EGW=128,i)); // Multiplier + let H = brev8(get_velem(vs2,EGW=128,i)); // Multiplicand + let Z : bits(128) = 0; + + for (int bit = 0; bit < 128; bit++) { + if bit_to_bool(Y[bit]) + Z ^= H + + bool reduce = bit_to_bool(H[127]); + H = H << 1; // left shift H by 1 + if (reduce) + H ^= 0x87; // Reduce using x^7 + x^2 + x^1 + 1 polynomial + } + + + let result = brev8(Z); + set_velem(vd, EGW=128, i, result); + } + RETIRE_SUCCESS + } +} +-- + +Included in:: +<>, <>, <> + +<<< + +[[insns-vrev8, Vector Reverse Bytes]] +==== vrev8.v + +Synopsis:: +Vector Reverse Bytes + +Mnemonic:: +vrev8.v vd, vs2, vm + +Encoding (Vector):: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-V'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPMVV'}, +{bits: 5, name: '01001'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: 'vm'}, +{bits: 6, name: '010010'}, +]} +.... + +Arguments:: + +[%autowidth] +[%header,cols="4,2,2"] +|=== +|Register +|Direction +|Definition + +| Vs2 | input | Input elements +| Vd | output | Byte-reversed elements +|=== + +Description:: +[#norm:vrev8-v_op]#A byte reversal is performed on each element of `vs2`, effectively performing an endian swap.# + +// This instruction must always be implemented such that its execution latency does not depend +// on the data being operated upon. + +[NOTE] +==== +This element-wise endian swapping is needed for several cryptographic algorithms including SHA2 and SM3. +==== + +Operation:: +[source,sail] +-- +function clause execute (VREV8(vs2)) = { + foreach (i from vstart to vl-1) { + input = get_velem(vs2, SEW, i); + let output : SEW = 0; + let j = SEW - 1; + foreach (k from 0 to (SEW - 8) by 8) { + output[k..(k + 7)] = input[(j - 7)..j]; + j = j - 8; + set_velem(vd, SEW, i, output) + } + RETIRE_SUCCESS +} +-- + +Included in:: +<>, <>, <>, <>, <>, <> +<>, <> + +<<< + +[[insns-vrol, Vector Rotate Left]] +==== vrol.[vv,vx] + +Synopsis:: +Vector rotate left by vector/scalar. + +Mnemonic:: +vrol.vv vd, vs2, vs1, vm + +vrol.vx vd, vs2, rs1, vm + + +Encoding (Vector-Vector):: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-V'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPIVV'}, +{bits: 5, name: 'vs1'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: 'vm'}, +{bits: 6, name: '010101'}, +]} +.... + +Encoding (Vector-Scalar):: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-V'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPIVX'}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: 'vm'}, +{bits: 6, name: '010101'}, +]} +.... + +Vector-Vector Arguments:: + +[%autowidth] +[%header,cols="4,2,2"] +|=== +|Register +|Direction +|Definition + +| Vs1 | input | Rotate amount +| Vs2 | input | Data +| Vd | output | Rotated data +|=== + +Vector-Scalar Arguments:: + +[%autowidth] +[%header,cols="4,2,2"] +|=== +|Register +|Direction +|Definition + +| Rs1 | input | Rotate amount +| Vs2 | input | Data +| Vd | output | Rotated data +|=== + +Description:: +A bitwise left rotation is performed on each element of `vs2` + +[#norm:vrol_op]#The elements in `vs2` are rotated left by the rotate amount specified by either +the corresponding elements of `vs1` (vector-vector), or integer register `rs1` +(vector-scalar). +Only the low log2(`SEW`) bits of the rotate-amount value are used, all other +bits are ignored.# + +// This instruction must always be implemented such that its execution latency does not depend +// on the data being operated upon. + +[NOTE] +==== +There is no immediate form of this instruction (i.e., `vrol.vi`) as the same result can be achieved by negating +the rotate amount and using the immediate form of rotate right instruction (i.e., vror.vi). +==== + +Operation:: +[source,sail] +-- +function clause execute (VROL_VV(vs2, vs1, vd)) = { + foreach (i from vstart to vl - 1) { + set_velem(vd, EEW=SEW, i, + get_velem(vs2, i) <<< (get_velem(vs1, i) & (SEW-1)) + ) + } + RETIRE_SUCCESS +} + +function clause execute (VROL_VX(vs2, rs1, vd)) = { + foreach (i from vstart to vl - 1) { + set_velem(vd, EEW=SEW, i, + get_velem(vs2, i) <<< (X(rs1) & (SEW-1)) + ) + } + RETIRE_SUCCESS +} + +-- + +Included in:: +<>, <>, <>, <>, <>, <> +<>, <> + +<<< + +[[insns-vror, Vector Rotate Right]] +==== vror.[vv,vx,vi] + +Synopsis:: +Vector rotate right by vector/scalar/immediate. + +Mnemonic:: +vror.vv vd, vs2, vs1, vm + +vror.vx vd, vs2, rs1, vm + +vror.vi vd, vs2, uimm, vm + +Encoding (Vector-Vector):: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-V'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPIVV'}, +{bits: 5, name: 'vs1'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: 'vm'}, +{bits: 6, name: '010100'}, +]} +.... + +Encoding (Vector-Scalar):: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-V'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPIVX'}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: 'vm'}, +{bits: 6, name: '010100'}, +]} +.... + +Encoding (Vector-Immediate):: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-V'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPIVI'}, +{bits: 5, name: 'uimm[4:0]'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: 'vm'}, +{bits: 1, name: 'i5'}, +{bits: 5, name: '01010'}, +]} +.... + +Vector-Vector Arguments:: + +[%autowidth] +[%header,cols="4,2,2"] +|=== +|Register +|Direction +|Definition + +| Vs1 | input | Rotate amount +| Vs2 | input | Data +| Vd | output | Rotated data +|=== + +Vector-Scalar/Immediate Arguments:: + +[%autowidth] +[%header,cols="4,2,2"] +|=== +|Register +|Direction +|Definition + +| Rs1/imm | input | Rotate amount +| Vs2 | input | Data +| Vd | output | Rotated data +|=== + + +Description:: +A bitwise right rotation is performed on each element of `vs2`. + +[#norm:vror_op]#The elements in `vs2` are rotated right by the rotate amount specified by either +the corresponding elements of `vs1` (vector-vector), integer register `rs1` +(vector-scalar), or an immediate value (vector-immediate). +Only the low log2(`SEW`) bits of the rotate-amount value are used, all other +bits are ignored.# + +// This instruction must always be implemented such that its execution latency does not depend +// on the data being operated upon. + +Operation:: +[source,sail] +-- +function clause execute (VROR_VV(vs2, vs1, vd)) = { + foreach (i from vstart to vl - 1) { + set_velem(vd, EEW=SEW, i, + get_velem(vs2, i) >>> (get_velem(vs1, i) & (SEW-1)) + ) + } + RETIRE_SUCCESS +} + +function clause execute (VROR_VX(vs2, rs1, vd)) = { + foreach (i from vstart to vl - 1) { + set_velem(vd, EEW=SEW, i, + get_velem(vs2, i) >>> (X(rs1) & (SEW-1)) + ) + } + RETIRE_SUCCESS +} + +function clause execute (VROR_VI(vs2, uimm[5:0], vd)) = { + foreach (i from vstart to vl - 1) { + set_velem(vd, EEW=SEW, i, + get_velem(vs2, i) >>> (uimm[5:0] & (SEW-1)) + ) + } + RETIRE_SUCCESS +} +-- + +Included in:: +<>, <>, <>, <>, <>, <> +<>, <> + +<<< + +[[insns-vsha2c, Vector SHA-2 Compression]] +==== vsha2c[hl].vv + +Synopsis:: +Vector SHA-2 two rounds of compression. + +Mnemonic:: +vsha2ch.vv vd, vs2, vs1 + +vsha2cl.vv vd, vs2, vs1 + +Encoding (Vector-Vector) High part:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-VE'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPMVV'}, +{bits: 5, name: 'vs1'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: '1'}, +{bits: 6, name: '101110'}, +]} +.... + +Encoding (Vector-Vector) Low part:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-VE'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPMVV'}, +{bits: 5, name: 'vs1'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: '1'}, +{bits: 6, name: '101111'}, +]} +.... +Reserved Encodings:: +* [#norm:vsha2chl-vv_Zvknha_sewn32_rsv]#`zvknha`: `SEW` is any value other than 32# +* [#norm:vsha2chl-vv_Zvknhb_sewn32or64_rsv]#`zvknhb`: `SEW` is any value other than 32 or 64# +* [#norm:vsha2chl-vv_vdoverlapvs1vs2_rsv]#The `vd` register group overlaps with either `vs1` or `vs2`# + +Arguments:: + +[%autowidth] +[%header,cols="4,2,2,2,2,2"] +|=== +|Register +|Direction +|EGW +|EGS +|EEW +|Definition + +| Vd | input | 4*SEW | 4 | SEW | current state {c, d, g, h} +| Vs1 | input | 4*SEW | 4 | SEW | MessageSched plus constant[3:0] +| Vs2 | input | 4*SEW | 4 | SEW | current state {a, b, e, f} +| Vd | output | 4*SEW | 4 | SEW | next state {a, b, e, f} +|=== + +Description:: +- [#norm:vsha2chl-vv_op_sew32]#`SEW`=32: 2 rounds of SHA-256 compression are performed (`zvknha` and `zvknhb`)# +- [#norm:vsha2chl-vv_op_sew64]#`SEW`=64: 2 rounds of SHA-512 compression are performed (`zvkhnb`)# + +[#norm:vsha2chl-vv_op]#Two words of `vs1` are processed with +the 8 words of current state held in `vd` and `vs2` to perform two +rounds of hash computation producing four words of the +next state.# + + +// These instructions take in two SEW words _W1_ and _W0_ which are the next two words of the message +// schedule incremented by the appropriate constant (see +// link:https://doi.org/10.6028/NIST.FIPS.180-4[FIPS PUB 180-4 Secure Hash Standard (SHS)]) +// and eight SEW word variables: _a_, _b_, _c_, _d_, _e_, _f_, _g,_ and _h_. The +// output is the new values of _a, b, e_ and _f_ after performing 2 rounds of the hash +// computation. The new values, _c_, _d_, _g_, and _h_, are equal to the input values for _a_, _b_, // _e_, _f_ respectively. + +// [NOTE] +// .Note to software developers +// ==== +// The MessageSchedplus constant input to this instruction is generated by Software +// increment each message schedule word by the corresponding +// round constant as defined in the NIST specification (see <>). +// ==== + +[NOTE] +.Note to software developers +==== +The NIST standard (see <>) requires the final hash to be in big-endian byte ordering +within SEW-sized words. Since this instruction treats all words as little-endian, +software needs to perform an endian swap on the final output of this instruction +after all of the message blocks have been processed. +==== + +[NOTE] +==== +The `vsha2ch` version of this instruction uses the two most significant message schedule +words from the element group in `vs1` +while the `vsha2cl` version uses the two least significant message schedule words. +Otherwise, these versions of the instruction are identical. +Having a high and low version of this instruction typically improves performance when +interleaving independent hashing operations (i.e., when hashing several files at once). +==== + +// [NOTE] +// .Note to software developers +// ==== +// These instructions take in two SEW words _W1_ and _W0_ which are the next two words of the message +// schedule incremented by the appropriate constant, +// and eight SEW word variables: _a_, _b_, _c_, _d_, _e_, _f_, _g,_ and _h_. The +// output is the new values of _a, b, e_ and _f_ after performing 2 rounds of the hash +// computation. The new values, _c_, _d_, _g_, and _h_, are equal to the input values for _a_, _b_, _e_, _f_ respectively. +// ==== + +// [NOTE] +// ==== +// Between executions this instruction it is helpful to swap the register _specifiers_ for +// `vd` and `vs2`. This is because the first instruction's `vd` next state output +// (_a_, _b_, _e_, _f_) +// becomes the second instruction's `vs2` current state input (_a_, _b_, _e_, _f_). +// Likewise the first instruction's `vs2` input (_a_, _b_, _e_, _f_) "ages" to +// becomes the second instruction's `vd` current state input of (_c_, _d_, _g_, _h_). +// ==== + + +[NOTE] +==== +Preventing overlap between `vd` and `vs1` or `vs2` simplifies implementation with `VLEN < EGW`. +This restriction does not have any coding impact since proper implementation of the algorithm requires +that `vd`, `vs1` and `vs2` each are different registers. +==== + + + +// The number of element groups to be processed is `vl`/`EGS`. +// `vl` must be set to the number of `SEW=32` elements to be processed and +// therefore must be a multiple of `EGS=4`. + +// Likewise, `vstart` must be a multiple of `EGS=4`. + +Operation:: +[source,sail] +-- +function clause execute (VSHA2c(vs2, vs1, vd)) = { + if(LMUL*VLEN < EGW) then { + handle_illegal(); // illegal-instruction exception + RETIRE_FAIL + } else { + + eg_len = (vl/EGS) + eg_start = (vstart/EGS) + + foreach (i from eg_start to eg_len-1) { + let {a @ b @ e @ f} : bits(4*SEW) = get_velem(vs2, 4*SEW, i); + let {c @ d @ g @ h} : bits(4*SEW) = get_velem(vd, 4*SEW, i); + let MessageSchedPlusC[3:0] : bits(4*SEW) = get_velem(vs1, 4*SEW, i); + let {W1, W0} == VSHA2cl ? MessageSchedPlusC[1:0] : MessageSchedPlusC[3:2]; // l vs h difference is the words selected + + let T1 : bits(SEW) = h + sum1(e) + ch(e,f,g) + W0; + let T2 : bits(SEW) = sum0(a) + maj(a,b,c); + h = g; + g = f; + f = e; + e = d + T1; + d = c; + c = b; + b = a; + a = T1 + T2; + + + T1 = h + sum1(e) + ch(e,f,g) + W1; + T2 = sum0(a) + maj(a,b,c); + h = g; + g = f; + f = e; + e = d + T1; + d = c; + c = b; + b = a; + a = T1 + T2; + set_velem(vd, 4*SEW, i, {a @ b @ e @ f}); + } + RETIRE_SUCCESS + } +} + +function sum0(x) = { + match SEW { + 32 => rotr(x,2) XOR rotr(x,13) XOR rotr(x,22), + 64 => rotr(x,28) XOR rotr(x,34) XOR rotr(x,39) + } +} + +function sum1(x) = { + match SEW { + 32 => rotr(x,6) XOR rotr(x,11) XOR rotr(x,25), + 64 => rotr(x,14) XOR rotr(x,18) XOR rotr(x,41) + } +} + +function ch(x, y, z) = ((x & y) ^ ((~x) & z)) + + +function maj(x, y, z) = ((x & y) ^ (x & z) ^ (y & z)) + +function ROTR(x,n) = (x >> n) | (x << SEW - n) + +-- + +Included in:: +<>, <>, <>, <> + +<<< + +[[insns-vsha2ms, Vector SHA-2 Message Schedule]] diff --git a/param_extraction/chunks/chunk_059.txt.license b/param_extraction/chunks/chunk_059.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_059.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_060.txt b/param_extraction/chunks/chunk_060.txt new file mode 100644 index 0000000000..0d679420b2 --- /dev/null +++ b/param_extraction/chunks/chunk_060.txt @@ -0,0 +1,1673 @@ +# Chunk: chunk_060 +# Source: vector-crypto.adoc +# Lines: 3311-4966 (of 4966) +# Content starts: line 3341 +# Line count: 1656 +# Overlap from line: 3311 +# Sections: 9 +# ==== vsha2ms.vv +# ==== vsm3c.vi +# ==== vsm3me.vv +# ==== vsm4k.vi +# ==== vsm4r.[vv,vs] +# ==== vwsll.[vv,vx,vi] +# === Crypto Vector Cryptographic Instructions +# === Vector Bitmanip and Carry-less Multiply Instructions +# === Supporting Sail Code +# + +function sum0(x) = { + match SEW { + 32 => rotr(x,2) XOR rotr(x,13) XOR rotr(x,22), + 64 => rotr(x,28) XOR rotr(x,34) XOR rotr(x,39) + } +} + +function sum1(x) = { + match SEW { + 32 => rotr(x,6) XOR rotr(x,11) XOR rotr(x,25), + 64 => rotr(x,14) XOR rotr(x,18) XOR rotr(x,41) + } +} + +function ch(x, y, z) = ((x & y) ^ ((~x) & z)) + + +function maj(x, y, z) = ((x & y) ^ (x & z) ^ (y & z)) + +function ROTR(x,n) = (x >> n) | (x << SEW - n) + +-- + +Included in:: +<>, <>, <>, <> + +<<< + +[[insns-vsha2ms, Vector SHA-2 Message Schedule]] +==== vsha2ms.vv + +Synopsis:: +Vector SHA-2 message schedule. + +Mnemonic:: +vsha2ms.vv vd, vs2, vs1 + +Encoding (Vector-Vector):: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-VE'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPMVV'}, +{bits: 5, name: 'vs1'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: '1'}, +{bits: 6, name: '101101'}, +]} +.... +Reserved Encodings:: +* [#norm:vsha2ms-vv_Zvknha_sewn32_rsv]#`zvknha`: `SEW` is any value other than 32# +* [#norm:vsha2ms-vv_Zvknhb_sewn32or64_rsv]#`zvknhb`: `SEW` is any value other than 32 or 64# +* [#norm:vsha2ms-vv_vdoverlapvs1vs2_rsv]#The `vd` register group overlaps with either `vs1` or `vs2`# +Arguments:: + +[%autowidth] +[%header,cols="4,2,2,2,2,2"] +|=== +|Register +|Direction +|EGW +|EGS +|EEW +|Definition + +| Vd | input | 4*SEW | 4 | SEW | Message words {W[3], W[2], W[1], W[0]} +| Vs2 | input | 4*SEW | 4 | SEW | Message words {W[11], W[10], W[9], W[4]} +| Vs1 | input | 4*SEW | 4 | SEW | Message words {W[15], W[14], -, W[12]} +| Vd | output | 4*SEW | 4 | SEW | Message words {W[19], W[18], W[17], W[16]} +|=== + +Description:: +- [#norm:vsha2ms-vv_op_sew32]#`SEW`=32: Four rounds of SHA-256 message schedule expansion are performed (`zvknha` and `zvknhb`)# +- [#norm:vsha2ms-vv_op_sew64]#`SEW`=64: Four rounds of SHA-512 message schedule expansion are performed (`zvkhnb`)# + +[#norm:vsha2ms-vv_op]#Eleven of the last 16 `SEW`-sized message-schedule words from `vd` (oldest), `vs2`, +and `vs1` (most recent) are processed to produce the +next 4 message-schedule words.# + +[NOTE] +.Note to software developers +==== +The first 16 SEW-sized words of the message schedule come from the _message block_ +in big-endian byte order. Since this instruction treats all words as little endian, +software is required to endian swap these words. + +All of the subsequent message schedule words are produced by this instruction and +therefore do not require an endian swap. +==== + +[NOTE] +.Note to software developers +==== +Software is required to pack the words into element groups +as shown above in the arguments table. The indices indicate the relate age with +lower indices indicating older words. +==== +// [NOTE] +// ==== +// W~13~ is not used by the instruction. +// ==== + +// Four `SEW` message schedule words are packed into each element group of the +// source and destination registers. From a vector register point of view, +// the message schedule words are packed into the +// element groups from the left to the right with the most significant word on the left +// and the least significant word on the right. + +// `{W~3~, W~2~, W~1~, W~0~} + +// {W~7~, W~6~, W~5~, W~4~} + +// {W~11~, W~10~, W~9~, W~8~} + +// {W~15~, W~14~, W~13~, W~12~}` + +// Since W~5~ through W~8~ are not needed in these calculations, we are able to compact these into +// three element groups +// +// `{W~3~, W~2~, W~1~, W~0~} + +// {W~11~, W~10~, W~9~, W~4~} + +// {W~15~, W~14~, W~13~, W~12~}` + +[NOTE] +.Note to software developers +==== +The {W~11~, W~10~, W~9~, W~4~} element group can easily be formed by using a vector +vmerge instruction with the appropriate mask (for example with `vl=4` and `4b0001` +as the 4 mask bits) + +`vmerge.vvm {W~11~, W~10~, W~9~, W~4~}, {W~11~, W~10~, W~9~, W~8~}, {W~7~, W~6~, W~5~, W~4~}, V0` +==== + +// The number of words to be processed is `vl`/`EGS`. +// `vl` must be set to the number of `SEW` elements to be processed and +// therefore must be a multiple of `EGS=4`. + +// Likewise, `vstart` must be a multiple of `EGS=4` + +[NOTE] +==== +Preventing overlap between `vd` and `vs1` or `vs2` simplifies implementation with `VLEN < EGW`. +This restriction does not have any coding impact since proper implementation of the algorithm requires +that `vd`, `vs1` and `vs2` each contain different portions of the message schedule. +==== + +// This instruction is not masked. If any element groups are not to be processed, the _vl_ +// must be set accordingly. It is not possible to skip an intermediary element group. +// `VLMUL` must be at least 1. In typical usage it is expected to be 1. +// There are three source operands: `vd`, `vs1` and `vs2`. The result +// is written to `vd`. + +// NB:: for implementations with `VLEN < EGW`, the minimal `VLMUL` is `EGW / VLEN`. + +// In this code the input elements are numbered from 0 (16 words ago) to 15 (most recent message-schedule word). +// The outputs are numbered from 16 to 19. + +// The number of element groups to be processed is `vl`/`EGS`. +// `vl` must be set to the number of `SEW=32` elements to be processed and +// therefore must be a multiple of `EGS=4`. + +// Likewise, `vstart` must be a multiple of `EGS=4`. + +Operation:: +[source,sail] +-- +function clause execute (VSHA2ms(vs2, vs1, vd)) = { + // SEW32 = SHA-256 + // SEW64 = SHA-512 + if(LMUL*VLEN < EGW) then { + handle_illegal(); // illegal-instruction exception + RETIRE_FAIL + } else { + + eg_len = (vl/EGS) + eg_start = (vstart/EGS) + + foreach (i from eg_start to eg_len-1) { + {W[3] @ W[2] @ W[1] @ W[0]} : bits(EGW) = get_velem(vd, EGW, i); + {W[11] @ W[10] @ W[9] @ W[4]} : bits(EGW) = get_velem(vs2, EGW, i); + {W[15] @ W[14] @ W[13] @ W[12]} : bits(EGW) = get_velem(vs1, EGW, i); + + W[16] = sig1(W[14]) + W[9] + sig0(W[1]) + W[0]; + W[17] = sig1(W[15]) + W[10] + sig0(W[2]) + W[1]; + W[18] = sig1(W[16]) + W[11] + sig0(W[3]) + W[2]; + W[19] = sig1(W[17]) + W[12] + sig0(W[4]) + W[3]; + + set_velem(vd, EGW, i, {W[19] @ W[18] @ W[17] @ W[16]}); + } + RETIRE_SUCCESS + } +} + +function sig0(x) = { + match SEW { + 32 => (ROTR(x,7) XOR ROTR(x,18) XOR SHR(x,3)), + 64 => (ROTR(x,1) XOR ROTR(x,8) XOR SHR(x,7))); + } +} + +function sig1(x) = { + match SEW { + 32 => (ROTR(x,17) XOR ROTR(x,19) XOR SHR(x,10), + 64 => ROTR(x,19) XOR ROTR(x,61) XOR SHR(x,6)); + } +} + +function ROTR(x,n) = (x >> n) | (x << SEW - n) +function SHR (x,n) = x >> n + +-- + +Included in:: + <>, <>, <>, <> + +<<< + +[[insns-vsm3c, SM3 Compression]] +==== vsm3c.vi + +Synopsis:: +Vector SM3 Compression + +Mnemonic:: +vsm3c.vi vd, vs2, uimm + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-VE'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPMVV'}, +{bits: 5, name: 'uimm'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: '1'}, +{bits: 6, name: '101011'}, +]} +.... +Reserved Encodings:: +* [#norm:vsm3c-vi_sewn32_rsv]#`SEW` is any value other than 32# +* [#norm:vsm3c-vi_vdoverlapvs2_rsv]#The `vd` register group overlaps with the `vs2` register group# + +Arguments:: + +[%autowidth] +[%header,cols="4,2,2,2,2,2"] +|=== +|Register +|Direction +|EGW +|EGS +|EEW +|Definition + +| Vd | input | 256 | 8 | 32 | Current state {H,G.F,E,D,C,B,A} +| uimm | input | - | - | - | round number (rnds) +| Vs2 | input | 256 | 8 | 32 | Message words {-,-,w[5],w[4],-,-,w[1],w[0]} +| Vd | output | 256 | 8 | 32 | Next state {H,G.F,E,D,C,B,A} +|=== + +Description:: +[#norm:vsm3c-vi_op]#Two rounds of SM3 compression are performed.# + +[#norm:vsm3c-vi_op_sm3]#The current state of eight 32-bit words is read in as an element group from `vd`. Eight 32-bit +message words are read in as an element group from `vs2`, although only four of them are used. +All of the 32-bit input words are byte-swapped from big endian to little endian. +These inputs are processed somewhat differently based on the round group (as specified in rnds), +and the next state is generated as an element group of eight 32-bit words. +The next state of eight 32-bit words are generated, +swapped from little endian to big endian, and are returned in +an eight-element group.# + +[#norm:vsm3c-vi_op_rnd]#The round number is provided by the 5-bit `rnds` unsigned immediate. Legal values are 0 - 31 +and indicate which group of two rounds are being performed. For example, if rnds=1, +then rounds 2 and 3 are being performed.# + +[NOTE] +==== +The round number is used in the rotation of the constant as well to inform the +behavior which differs between rounds 0-15 and rounds 16-63. +==== + +[NOTE] +==== +The endian byte swapping of the input and output words enables us to align with the SM3 +specification without requiring that software perform these swaps. +==== + +[NOTE] +==== +Preventing overlap between `vd` and `vs2` simplifies implementation with `VLEN < EGW`. +This restriction does not have any coding impact since proper implementation of the algorithm requires +that `vd` and `vs2` each are different registers. +==== + +// The elements are listed here in the order they appear in the register, with the most significant +// element on the left, and the least significant on the right. + +// vs2 = {w[7], w[6], w[5], w[4], w[3], w[2], w[1], w[0]} + +// The values consumed by the instruction are + +// vs2 = {- , - , w[5], w[4], -, -, w[1], w[0]} + +// Where the "-" characters are not consumed and are therefore don't cares. + +// This instruction consumes the "W" message schedule inputs and internally generates the "W'" values as needed + +// The number of element groups to be processed is `vl`/`EGS`. +// `vl` must be set to the number of `SEW=32` elements to be processed and +// therefore must be a multiple of `EGS=8`. + +// Likewise, `vstart` must be a multiple of `EGS=8`. + +Operation:: +[source,sail] +-- +function clause execute (VSM3C(rnds, vs2, vd)) = { + if(LMUL*VLEN < EGW) then { + handle_illegal(); // illegal-instruction exception + RETIRE_FAIL + } else { + + eg_len = (vl/EGS) + eg_start = (vstart/EGS) + + foreach (i from eg_start to eg_len-1) { + + // load state + let {Hi @ Gi @ Fi @ Ei @ Di @ Ci @ Bi @ Ai} : bits(256) : bits(256) = (get_velem(vd, 256, i)); + //load message schedule + let {u_w7 @ u_w6 @ w5i @ w4i @ u_w3 @ u_w2 @ w1i @ w0i} : bits(256) = (get_velem(vs2, 256, i)); + // u_w inputs are unused + +// perform endian swap +let H : bits(32) = rev8(Hi); +let G : bits(32) = rev8(Gi); +let F : bits(32) = rev8(Fi); +let E : bits(32) = rev8(Ei); +let D : bits(32) = rev8(Di); +let C : bits(32) = rev8(Ci); +let B : bits(32) = rev8(Bi); +let A : bits(32) = rev8(Ai); + +let w5 = : bits(32) rev8(w5i); +let w4 = : bits(32) rev8(w4i); +let w1 = : bits(32) rev8(w1i); +let w0 = : bits(32) rev8(w0i); + +let x0 :bits(32) = w0 ^ w4; // W'[0] +let x1 :bits(32) = w1 ^ w5; // W'[1] + +let j = 2 * rnds; +let ss1 : bits(32) = ROL32(ROL32(A, 12) + E + ROL32(T_j(j), j % 32), 7); +let ss2 : bits(32) = ss1 ^ ROL32(A, 12); +let tt1 : bits(32) = FF_j(A, B, C, j) + D + ss2 + x0; +let tt2 : bits(32) = GG_j(E, F, G, j) + H + ss1 + w0; +D = C; +let : bits(32) C1 = ROL32(B, 9); +B = A; +let A1 : bits(32) = tt1; +H = G; +let G1 : bits(32) = ROL32(F, 19); +F = E; +let E1 : bits(32) = P_0(tt2); + +j = 2 * rnds + 1; +ss1 = ROL32(ROL32(A1, 12) + E1 + ROL32(T_j(j), j % 32), 7); +ss2 = ss1 ^ ROL32(A1, 12); +tt1 = FF_j(A1, B, C1, j) + D + ss2 + x1; +tt2 = GG_j(E1, F, G1, j) + H + ss1 + w1; +D = C1; +let C2 : bits(32) = ROL32(B, 9); +B = A1; +let A2 : bits(32) = tt1; +H = G1; +let G2 = : bits(32) ROL32(F, 19); +F = E1; +let E2 = : bits(32) P_0(tt2); + +// Update the destination register - swap back to big endian +let result : bits(256) = {rev8(G1) @ rev8(G2) @ rev8(E1) @ rev8(E2) @ rev8(C1) @ rev8(C2) @ rev8(A1) @ rev8(A2)}; +set_velem(vd, 256, i, result); + } + +RETIRE_SUCCESS + } +} + +function FF1(X, Y, Z) = ((X) ^ (Y) ^ (Z)) +function FF2(X, Y, Z) = (((X) & (Y)) | ((X) & (Z)) | ((Y) & (Z))) + +function FF_j(X, Y, Z, J) = (((J) <= 15) ? FF1(X, Y, Z) : FF2(X, Y, Z)) + +function GG1(X, Y, Z) = ((X) ^ (Y) ^ (Z)) +function GG2(X, Y, Z) = (((X) & (Y)) | ((~(X)) & (Z))) +. +function GG_j(X, Y, Z, J) = (((J) <= 15) ? GG1(X, Y, Z) : GG2(X, Y, Z)) + +function T_j(J) = (((J) <= 15) ? (0x79CC4519) : (0x7A879D8A)) + +function P_0(X) = ((X) ^ ROL32((X), 9) ^ ROL32((X), 17)) + +-- + +Included in:: +<>, <>, <>, <> + +<<< + +[[insns-vsm3me, SM3 Message Expansion]] +==== vsm3me.vv + +Synopsis:: +Vector SM3 Message Expansion + +Mnemonic:: +vsm3me.vv vd, vs2, vs1 + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-VE'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPMVV'}, +{bits: 5, name: 'vs1'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: '1'}, +{bits: 6, name: '100000'}, +]} +.... +Reserved Encodings:: +* [#norm:vsm3me-vv_sewn32_rsv]#`SEW` is any value other than 32# +* [#norm:vsm3me-vv_vdoverlapvs2_rsv]#The `vd` register group overlaps with the `vs2` register group.# + +Arguments:: + +[%autowidth] +[%header,cols="4,2,2,2,2,2"] +|=== +|Register +|Direction +|EGW +|EGS +|EEW +|Definition + +| Vs1 | input | 256 | 8 | 32 | Message words W[7:0] +| Vs2 | input | 256 | 8 | 32 | Message words W[15:8] +| Vd | output | 256 | 8 | 32 | Message words W[23:16] +|=== + +Description:: +[#norm:vsm3me-vv_op]#Eight rounds of SM3 message expansion are performed.# + + +[#norm:vsm3me-vv_op_sm3]#The sixteen most recent 32-bit message words are read in as two +eight-element groups from `vs1` and `vs2`. Each of these words is +swapped from big endian to little endian. +The next eight 32-bit message words are generated, +swapped from little endian to big endian, and are returned in +an eight-element group.# + +[NOTE] +==== +The endian byte swapping of the input and output words enables us to align with the SM3 +specification without requiring that software perform these swaps. +==== + +// NOTE +// ==== +// For the best performance, it is recommended that implementations have VLEN{ge}256. +// When VLEN>, <>, <>, <> + +<<< + +[[insns-vsm4k, Vector SM4 Key Expansion]] +==== vsm4k.vi + +Synopsis:: +Vector SM4 KeyExpansion + +Mnemonic:: +vsm4k.vi vd, vs2, uimm + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-VE'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPMVV'}, +{bits: 5, name: 'uimm'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: '1'}, +{bits: 6, name: '100001'}, +]} +.... +Reserved Encodings:: +* [#norm:vsm4k-vi_sewn32_rsv]#`SEW` is any value other than 32# + +Arguments:: + +[%autowidth] +[%header,cols="4,2,2,2,2,2"] +|=== +|Register +|Direction +|EGW +|EGS +|EEW +|Definition + +| uimm | input | - | - | - | Round group (rnd) +| Vs2 | input | 128 | 4 | 32 | Current 4 round keys rK[0:3] +| Vd | output | 128 | 4 | 32 | Next 4 round keys rK'[0:3] +|=== + +Description:: +[#norm:vsm4k-vi_op]#Four rounds of the SM4 Key Expansion are performed.# + +[#norm:vsm4k-vi_op_sm4k]#Four round keys are read in as a 4-element group from `vs2`. Each of the next four round keys are generated +by iteratively XORing the last three round keys with a constant that is indexed by the Round Group Number, +performing a byte-wise substitution, and then performing XORs between rotated versions of this value +and the corresponding current round key.# + +[#norm:vsm4k-vi_op_rnd]#The Round group number (`rnd`) comes from `uimm[2:0]`; the bits in `uimm[4:3]` are ignored. +Round group numbers range from 0 to 7 and indicate which +group of four round keys are being generated. Round Keys range from 0-31. +For example, if `rnd`=1, then round keys 4, 5, 6, and 7 are being generated.# + +// vs2 = {rK[i-4], rK[i-3],rK[i-2], rK[i-1]} // last 4 round keys +// rnd = 0 to 7; // group of 4 rounds +// vd (out) = {rK[i], rK[i+1],rK[i+2], rK[i+3]} // next 4 rounds keys + +// Each of the 32 rounds consumes the last 4 32-bit keys along with a round constant and +// produces the next 32-bit key. + + +[NOTE] +==== +Software needs to generate the initial round keys. This is done by XORing the 128-bit encryption key with +the system parameters: FK[0:3] +==== + +.System Parameters +[%autowidth] +[%header,cols="^2,^2"] +|=== +|FK +|constant + +| 0 | A3B1BAC6 +| 1 | 56AA3350 +| 2 | 677D9197 +| 3 | B27022DC +|=== + + +//// +.System Parameters +[%autowidth] +[%header,cols="^2,^2"] +|=== +|FK +|constant + +| 0 | A3B1BAC6 +| 1 | 56AA3350 +| 2 | 677D9197 +| 3 | B27022DC +|=== +//// + +// MK = {MK[0], MK[1], MK[2], MK[3]} // Encryption Key +// rK[-4,-1] = K[0:3] = MK[0:3] ^ FK[0:3] + + +// The round keys are rK[0] to rK[31] +// B = (rK[i-3] XOR rK[i-2] XOR rK[i-1] XOR CK[round]); + +// S = subBytes(B); + +// rK[i]= rK[i-4] XOR S XOR ROTL13(S) XOR ROTR23(S); + +// +// The round constants and the S-box are described below and can be found at https://datatracker.ietf.org/doc/id/// draft-crypto-sm4-00 + +[NOTE] +==== +Implementation Hint + +The round constants (CK) can be generated on the fly fairly cheaply. +If the bytes of the constants are assigned an incrementing index from 0 to 127, the value of each byte is equal to its index multiplied by 7 modulo 256. +Since the results are all limited to 8 bits, the modulo operation occurs for free: + + B[n] = n + 2n + 4n; + = 8n + ~n + 1; +==== + +// This instruction only returns the generated keys to the same element group as the source. +// If it is desired to have the same key in all vector groups, either the input vector groups +// need to contain the same values, or the output from a particular group needs to be "broadcast" +// to the other groups using an instruction such as vrgather. + +// The number of element groups to be processed is `vl`/`EGS`. +// `vl` must be set to the number of `SEW=32` elements to be processed and +// therefore must be a multiple of `EGS=4`. + +// Likewise, `vstart` must be a multiple of `EGS=4`. + +//// +.System Parameters +[%autowidth] +[%header,cols="^2,^2"] +|=== +|FK +|constant + +| 0 | A3B1BAC6 +| 1 | 56AA3350 +| 2 | 677D9197 +| 3 | B27022DC +|=== +//// + +Operation:: +[source,sail] +-- + +function clause execute (vsm4k(uimm, vs2)) = { + if(LMUL*VLEN < EGW) then { + handle_illegal(); // illegal-instruction exception + RETIRE_FAIL + } else { + + eg_len = (vl/EGS) + eg_start = (vstart/EGS) + + let B : bits(32) = 0; + let S : bits(32) = 0; + let rk4 : bits(32) = 0; + let rk5 : bits(32) = 0; + let rk6 : bits(32) = 0; + let rk7 : bits(32) = 0; + let rnd : bits(3) = uimm[2:0]; // Lower 3 bits + + foreach (i from eg_start to eg_len-1) { + let (rk3 @ rk2 @ rk1 @ rk0) : bits(128) = get_velem(vs2, 128, i); + + B = rk1 ^ rk2 ^ rk3 ^ ck(4 * rnd); + S = sm4_subword(B); + rk4 = ROUND_KEY(rk0, S); + + B = rk2 ^ rk3 ^ rk4 ^ ck(4 * rnd + 1); + S = sm4_subword(B); + rk5 = ROUND_KEY(rk1, S); + + B = rk3 ^ rk4 ^ rk5 ^ ck(4 * rnd + 2); + S = sm4_subword(B); + rk6 = ROUND_KEY(rk2, S); + + B = rk4 ^ rk5 ^ rk6 ^ ck(4 * rnd + 3); + S = sm4_subword(B); + rk7 = ROUND_KEY(rk3, S); + + // Update the destination register. + set_velem(vd, EGW=128, i, (rk7 @ rk6 @ rk5 @ rk4)); + } + RETIRE_SUCCESS + } +} + +val round_key : bits(32) -> bits(32) +function ROUND_KEY(X, S) = ((X) ^ ((S) ^ ROL32((S), 13) ^ ROL32((S), 23))) + +// SM4 Constant Key (CK) +let ck : list(bits(32)) = [| + 0x00070E15, 0x1C232A31, 0x383F464D, 0x545B6269, + 0x70777E85, 0x8C939AA1, 0xA8AFB6BD, 0xC4CBD2D9, + 0xE0E7EEF5, 0xFC030A11, 0x181F262D, 0x343B4249, + 0x50575E65, 0x6C737A81, 0x888F969D, 0xA4ABB2B9, + 0xC0C7CED5, 0xDCE3EAF1, 0xF8FF060D, 0x141B2229, + 0x30373E45, 0x4C535A61, 0x686F767D, 0x848B9299, + 0xA0A7AEB5, 0xBCC3CAD1, 0xD8DFE6ED, 0xF4FB0209, + 0x10171E25, 0x2C333A41, 0x484F565D, 0x646B7279 + |] +}; + + +-- + +Included in:: +<>, <>, <>, <> + +<<< + +[[insns-vsm4r, SM4 Block Cipher Rounds]] +==== vsm4r.[vv,vs] + +Synopsis:: +Vector SM4 Rounds + +Mnemonic:: +vsm4r.vv vd, vs2 + +vsm4r.vs vd, vs2 + +Encoding (Vector-Vector):: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-VE'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPMVV'}, +{bits: 5, name: '10000'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: '1'}, +{bits: 6, name: '101000'}, +]} +.... + +Encoding (Vector-Scalar):: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-VE'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPMVV'}, +{bits: 5, name: '10000'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: '1'}, +{bits: 6, name: '101001'}, +]} +.... +Reserved Encodings:: +* [#norm:vsm4r_sewn32_rsv]#`SEW` is any value other than 32# +* [#norm:vsm4r-vs_vdoverlapvs2_rsv]#Only for the `.vs` form: the `vd` register group overlaps the `vs2` register# + +Arguments:: + +[%autowidth] +[%header,cols="4,2,2,2,2,2"] +|=== +|Register +|Direction +|EGW +|EGS +|EEW +|Definition + +| Vd | input | 128 | 4 | 32 | Current state X[0:3] +| Vs2 | input | 128 | 4 | 32 | Round keys rk[0:3] +| Vd | output | 128 | 4 | 32 | Next state X'[0:3] +|=== + +Description:: +[#norm:vsm4r_op]#Four rounds of SM4 Encryption/Decryption are performed.# + +[#norm:vsm4r_op_sm4encdec]#The four words of current state are read as a 4-element group from 'vd' +and the round keys are read from either the corresponding 4-element group +in `vs2` (vector-vector form) or the scalar element group in `vs2` +(vector-scalar form). +The next four words of state are generated +by iteratively XORing the last three words of the state with +the corresponding round key, performing +a byte-wise substitution, and then performing XORs between rotated +versions of this value and the corresponding current state.# + +[NOTE] +==== +In SM4, encryption and decryption are identical except that decryption consumes the round keys in the reverse order. +==== + +[NOTE] +==== +For the first four rounds of encryption, the _current state_ is the plain text. +For the first four rounds of decryption, the _current state_ is the cipher text. +For all subsequent rounds, the _current state_ is the _next state_ from the +previous four rounds. +==== + +// The number of element groups to be processed is `vl`/`EGS`. +// `vl` must be set to the number of `SEW=32` elements to be processed and +// therefore must be a multiple of `EGS=4`. + +// Likewise, `vstart` must be a multiple of `EGS=4`. + +Operation:: +[source,pseudocode] +-- +function clause execute (VSM4R(vd, vs2)) = { + if(LMUL*VLEN < EGW) then { + handle_illegal(); // illegal-instruction exception + RETIRE_FAIL + } else { + + eg_len = (vl/EGS) + eg_start = (vstart/EGS) + + let B : bits(32) = 0; + let S : bits(32) = 0; + let rk0 : bits(32) = 0; + let rk1 : bits(32) = 0; + let rk2 : bits(32) = 0; + let rk3 : bits(32) = 0; + let x0 : bits(32) = 0; + let x1 : bits(32) = 0; + let x2 : bits(32) = 0; + let x3 : bits(32) = 0; + let x4 : bits(32) = 0; + let x5 : bits(32) = 0; + let x6 : bits(32) = 0; + let x7 : bits(32) = 0; + + let keyelem : bits(32) = 0; + + foreach (i from eg_start to eg_len-1) { + keyelem = if suffix == "vv" then i else 0; + {rk3 @ rk2 @ rk1 @ rk0} : bits(128) = get_velem(vs2, EGW=128, keyelem); + {x3 @ x2 @ x1 @ x0} : bits(128) = get_velem(vd, EGW=128, i); + + B = x1 ^ x2 ^ x3 ^ rk0; + S = sm4_subword(B); + x4 = sm4_round(x0, S); + + B = x2 ^ x3 ^ x4 ^ rk1; + S = sm4_subword(B); + x5= sm4_round(x1, S); + + B = x3 ^ x4 ^ x5 ^ rk2; + S = sm4_subword(B); + x6 = sm4_round(x2, S); + + B = x4 ^ x5 ^ x6 ^ rk3; + S = sm4_subword(B); + x7 = sm4_round(x3, S); + + set_velem(vd, EGW=128, i, (x7 @ x6 @ x5 @ x4)); + + } + RETIRE_SUCCESS + } +} + +val sm4_round : bits(32) -> bits(32) +function sm4_round(X, S) = \ + ((X) ^ ((S) ^ ROL32((S), 2) ^ ROL32((S), 10) ^ ROL32((S), 18) ^ ROL32((S), 24))) + +-- + +Included in:: +<>, <>, <>, <> + +<<< + +[[insns-vwsll, Vector Widening Shift Left Logical]] +==== vwsll.[vv,vx,vi] + +Synopsis:: +Vector widening shift left logical by vector/scalar/immediate. + +Mnemonic:: +vwsll.vv vd, vs2, vs1, vm + +vwsll.vx vd, vs2, rs1, vm + +vwsll.vi vd, vs2, uimm, vm + +Encoding (Vector-Vector):: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-V'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPIVV'}, +{bits: 5, name: 'vs1'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: 'vm'}, +{bits: 6, name: '110101'}, +]} +.... + +Encoding (Vector-Scalar):: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-V'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPIVX'}, +{bits: 5, name: 'rs1'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: 'vm'}, +{bits: 6, name: '110101'}, +]} +.... + +Encoding (Vector-Immediate):: +[wavedrom, , svg] +.... +{reg:[ +{bits: 7, name: 'OP-V'}, +{bits: 5, name: 'vd'}, +{bits: 3, name: 'OPIVI'}, +{bits: 5, name: 'uimm[4:0]'}, +{bits: 5, name: 'vs2'}, +{bits: 1, name: 'vm'}, +{bits: 6, name: '110101'}, +]} +.... + +Vector-Vector Arguments:: + +[%autowidth] +[%header,cols="4,2,2"] +|=== +|Register +|Direction +|Definition + +| Vs1 | input | Shift amount +| Vs2 | input | Data +| Vd | output | Shifted data +|=== + +Vector-Scalar/Immediate Arguments:: + +[%autowidth] +[%header,cols="4,2,2,2"] +|=== +|Register +|Direction +|EEW +|Definition + +| Rs1/imm | input | SEW | Shift amount +| Vs2 | input | SEW | Data +| Vd | output | 2*SEW | Shifted data +|=== + + +Description:: +A widening logical shift left is performed on each element of `vs2`. + +[#norm:vwsll_op]#The elements in `vs2` are zero-extended to 2*`SEW` bits, then shifted left +by the shift amount specified by either +the corresponding elements of `vs1` (vector-vector), integer register `rs1` +(vector-scalar), or an immediate value (vector-immediate). +Only the low log2(2*`SEW`) bits of the shift-amount value are used, all other +bits are ignored.# + +Operation:: +[source,sail] +-- +function clause execute (VWSLL_VV(vs2, vs1, vd)) = { + foreach (i from vstart to vl - 1) { + set_velem(vd, EEW=2*SEW, i, + get_velem(vs2, i) << (get_velem(vs1, i) & ((2*SEW)-1)) + ) + } + RETIRE_SUCCESS +} + +function clause execute (VWSLL_VX(vs2, rs1, vd)) = { + foreach (i from vstart to vl - 1) { + set_velem(vd, EEW=2*SEW, i, + get_velem(vs2, i) << (X(rs1) & ((2*SEW)-1)) + ) + } + RETIRE_SUCCESS +} + +function clause execute (VWSLL_VI(vs2, uimm[4:0], vd)) = { + foreach (i from vstart to vl - 1) { + set_velem(vd, EEW=2*SEW, i, + get_velem(vs2, i) << (uimm[4:0] & ((2*SEW)-1)) + ) + } + RETIRE_SUCCESS +} +-- + +Included in:: +<> + +<<< + + +[[crypto_vector_instructions]] +=== Crypto Vector Cryptographic Instructions + +OP-VE (0x77) +Crypto Vector instructions except Zvbb and Zvbc + +// [cols="4,1,1,1,8,4,1,1,8,4,1,1,8"] +[cols="4,1,1,1,1,4,1,1,1,4,1,1,1"] +|=== +5+^|Integer 4+^|Integer 4+^| FP + +| funct3 | | | | | funct3 | | | | funct3 | | | +| OPIVV |V| | | | OPMVV |V| | | OPFVV |V| | +| OPIVX | |X| | | OPMVX | |X| | OPFVF | |F| +| OPIVI | | |I| | | | | | | | | +|=== + +// [cols="4,1,1,1,8,4,1,1,8,4,1,1,8"] +[cols="6,1,1,1,1,6,1,1,6,6,1,1,1"] + +|=== +5+^| funct6 4+^| funct6 4+^| funct6 + +|100000||||| 100000 |V| | vsm3me | 100000 | | | +| 100001 | | | | | 100001 |V| | vsm4k.vi | 100001 | | | +| 100010 | | | | | 100010 |V| | vaeskf1.vi | 100010 | | | +| 100011 | | | | | 100011 | | | | 100011 | | | +| 100100 | | | | | 100100 | | | | 100100 | | | +| 100101 | | | | | 100101 | | | | 100101 | | | +| 100110 | | | | | 100110 | | | | 100110 | | | +| 100111 | | | | | 100111 | | | | 100111 | | | +| | | | | | | | | | | | | +| 101000 | | | | | 101000 |V| | *VAES.vv* | 101000 | | | +| 101001 | | | | | 101001 |V| | *VAES.vs* | 101001 | | | +| 101010 | | | | | 101010 |V| | vaeskf2.vi | 101010 | | | +| 101011 | | | | | 101011 |V| | vsm3c.vi | 101011 | | | +| 101100 | | | | | 101100 |V| | vghsh | 101100 | | | +| 101101 | | | | | 101101 |V| | vsha2ms | 101101 | | | +| 101110 | | | | | 101110 |V| | vsha2ch | 101110 | | | +| 101111 | | | | | 101111 |V| | vsha2cl | 101111 | | | +|=== + +<<< + +.VAES.vv and VAES.vs encoding space +[cols="2,14"] +|=== +|vs1| + +| 00000 | vaesdm +| 00001 | vaesdf +| 00010 | vaesem +| 00011 | vaesef +| 00111 | vaesz +| 10000 | vsm4r +| 10001 | vgmul +|=== + +[[crypto_vector_instructions_Zvbb_Zvbc]] +=== Vector Bitmanip and Carry-less Multiply Instructions + +OP-V (0x57) +*Zvbb*, *Zvkb*, and *Zvbc* Vector instructions *in bold* +//[%auto-width] +[%autowidth,cols="4,1,1,1,8,4,1,1,8,4,1,1,8"] +|=== +5+| Integer 4+| Integer 4+| FP + +| funct3 | | | | | funct3 | | | | funct3 | | | +| OPIVV |V| | | | OPMVV |V| | | OPFVV |V| | +| OPIVX | |X| | | OPMVX | |X| | OPFVF | |F| +| OPIVI | | |I| | | | | | | | | +|=== + +//[%auto-width] +[%autowidth,cols="4,1,1,1,8,4,1,1,8,4,1,1,8"] +|=== +5+| funct6 4+| funct6 4+| funct6 + +| 000000 |V|X|I| vadd | 000000 |V| | vredsum | 000000 |V|F| vfadd +| 000001 |V|X| | *vandn* | 000001 |V| | vredand | 000001 |V| | vfredusum +| 000010 |V|X| | vsub | 000010 |V| | vredor | 000010 |V|F| vfsub +| 000011 | |X|I| vrsub | 000011 |V| | vredxor | 000011 |V| | vfredosum +| 000100 |V|X| | vminu | 000100 |V| | vredminu | 000100 |V|F| vfmin +| 000101 |V|X| | vmin | 000101 |V| | vredmin | 000101 |V| | vfredmin +| 000110 |V|X| | vmaxu | 000110 |V| | vredmaxu | 000110 |V|F| vfmax +| 000111 |V|X| | vmax | 000111 |V| | vredmax | 000111 |V| | vfredmax +| 001000 | | | | | 001000 |V|X| vaaddu | 001000 |V|F| vfsgnj +| 001001 |V|X|I| vand | 001001 |V|X| vaadd | 001001 |V|F| vfsgnjn +| 001010 |V|X|I| vor | 001010 |V|X| vasubu | 001010 |V|F| vfsgnjx +| 001011 |V|X|I| vxor | 001011 |V|X| vasub | 001011 | | | +| 001100 |V|X|I| vrgather | 001100 |V|X| *vclmul* | 001100 | | | +| 001101 | | | | | 001101 |V|X| *vclmulh* | 001101 | | | +| 001110 | |X|I| vslideup | 001110 | |X| vslide1up | 001110 | |F| vfslide1up +| 001110 |V| | | vrgatherei16| | | | | | | | +| 001111 | |X|I| vslidedown | 001111 | |X| vslide1down | 001111 | |F| vfslide1down +|=== + +[%autowidth,cols="4,1,1,1,8,4,1,1,8,4,1,1,8"] +|=== +5+| funct6 4+| funct6 4+| funct6 + +| 010000 |V|X|I| vadc | 010000 |V| | VWXUNARY0 | 010000 |V| | VWFUNARY0 +| | | | | | 010000 | |X| VRXUNARY0 | 010000 | |F| VRFUNARY0 +| 010001 |V|X|I| vmadc | 010001 | | | | 010001 | | | +| 010010 |V|X| | vsbc | 010010 |V| | VXUNARY0 | 010010 |V| | VFUNARY0 +| 010011 |V|X| | vmsbc | 010011 | | | | 010011 |V| | VFUNARY1 +| 010100 |V|X| | *vror* | 010100 |V| | VMUNARY0 | 010100 | | | +| 010101 |V|X| | *vrol* | 010101 | | | | 010101 | | | +| 01010x | | |I| *vror* | | | | | | | | +| 010110 | | | | | 010110 | | | | 010110 | | | +| 010111 |V|X|I| vmerge/vmv | 010111 |V| | vcompress | 010111 | |F| vfmerge/vfmv +| 011000 |V|X|I| vmseq | 011000 |V| | vmandn | 011000 |V|F| vmfeq +| 011001 |V|X|I| vmsne | 011001 |V| | vmand | 011001 |V|F| vmfle +| 011010 |V|X| | vmsltu | 011010 |V| | vmor | 011010 | | | +| 011011 |V|X| | vmslt | 011011 |V| | vmxor | 011011 |V|F| vmflt +| 011100 |V|X|I| vmsleu | 011100 |V| | vmorn | 011100 |V|F| vmfne +| 011101 |V|X|I| vmsle | 011101 |V| | vmnand | 011101 | |F| vmfgt +| 011110 | |X|I| vmsgtu | 011110 |V| | vmnor | 011110 | | | +| 011111 | |X|I| vmsgt | 011111 |V| | vmxnor | 011111 | |F| vmfge +|=== + +[%autowidth,cols="4,1,1,1,8,4,1,1,8,4,1,1,8"] +|=== +5+| funct6 4+| funct6 4+| funct6 + +| 100000 |V|X|I| vsaddu | 100000 |V|X| vdivu | 100000 |V|F| vfdiv +| 100001 |V|X|I| vsadd | 100001 |V|X| vdiv | 100001 | |F| vfrdiv +| 100010 |V|X| | vssubu | 100010 |V|X| vremu | 100010 | | | +| 100011 |V|X| | vssub | 100011 |V|X| vrem | 100011 | | | +| 100100 | | | | | 100100 |V|X| vmulhu | 100100 |V|F| vfmul +| 100101 |V|X|I| vsll | 100101 |V|X| vmul | 100101 | | | +| 100110 | | | | | 100110 |V|X| vmulhsu | 100110 | | | +| 100111 |V|X| | vsmul | 100111 |V|X| vmulh | 100111 | |F| vfrsub +| | | |I| vmvr | | | | | | | | +| 101000 |V|X|I| vsrl | 101000 | | | | 101000 |V|F| vfmadd +| 101001 |V|X|I| vsra | 101001 |V|X| vmadd | 101001 |V|F| vfnmadd +| 101010 |V|X|I| vssrl | 101010 | | | | 101010 |V|F| vfmsub +| 101011 |V|X|I| vssra | 101011 |V|X| vnmsub | 101011 |V|F| vfnmsub +| 101100 |V|X|I| vnsrl | 101100 | | | | 101100 |V|F| vfmacc +| 101101 |V|X|I| vnsra | 101101 |V|X| vmacc | 101101 |V|F| vfnmacc +| 101110 |V|X|I| vnclipu | 101110 | | | | 101110 |V|F| vfmsac +| 101111 |V|X|I| vnclip | 101111 |V|X| vnmsac | 101111 |V|F| vfnmsac +|=== + +[%autowidth,cols="4,1,1,1,8,4,1,1,8,4,1,1,8"] +|=== +5+| funct6 4+| funct6 4+| funct6 + +| 110000 |V| | | vwredsumu | 110000 |V|X| vwaddu | 110000 |V|F| vfwadd +| 110001 |V| | | vwredsum | 110001 |V|X| vwadd | 110001 |V| | vfwredusum +| 110010 | | | | | 110010 |V|X| vwsubu | 110010 |V|F| vfwsub +| 110011 | | | | | 110011 |V|X| vwsub | 110011 |V| | vfwredosum +| 110100 | | | | | 110100 |V|X| vwaddu.w | 110100 |V|F| vfwadd.w +| 110101 |V|X|I| *vwsll* | 110101 |V|X| vwadd.w | 110101 | | | +| 110110 | | | | | 110110 |V|X| vwsubu.w | 110110 |V|F| vfwsub.w +| 110111 | | | | | 110111 |V|X| vwsub.w | 110111 | | | +| 111000 | | | | | 111000 |V|X| vwmulu | 111000 |V|F| vfwmul +| 111001 | | | | | 111001 | | | | 111001 | | | +| 111010 | | | | | 111010 |V|X| vwmulsu | 111010 | | | +| 111011 | | | | | 111011 |V|X| vwmul | 111011 | | | +| 111100 | | | | | 111100 |V|X| vwmaccu | 111100 |V|F| vfwmacc +| 111101 | | | | | 111101 |V|X| vwmacc | 111101 |V|F| vfwnmacc +| 111110 | | | | | 111110 | |X| vwmaccus | 111110 |V|F| vfwmsac +| 111111 | | | | | 111111 |V|X| vwmaccsu | 111111 |V|F| vfwnmsac +|=== + +<<< + +//[%auto-width] +.VXUNARY0 encoding space +[%autowidth,cols="2,14"] +|=== +| vs1 | + +| 00010 | vzext.vf8 +| 00011 | vsext.vf8 +| 00100 | vzext.vf4 +| 00101 | vsext.vf4 +| 00110 | vzext.vf2 +| 00111 | vsext.vf2 +| 01000 | *vbrev8* +| 01001 | *vrev8* +| 01010 | *vbrev* +| 01100 | *vclz* +| 01101 | *vctz* +| 01110 | *vcpop* + +|=== + +[[crypto_vector_appx_sail]] +=== Supporting Sail Code + +This section contains the supporting Sail code referenced by the +instruction descriptions throughout the specification. +The +link:https://alasdair.github.io/manual.html[Sail Manual] +is recommended reading in order to best understand the supporting code. + +[source,sail] +---- +/* Auxiliary function for performing GF multiplication */ +val xt2 : bits(8) -> bits(8) +function xt2(x) = { + (x << 1) ^ (if bit_to_bool(x[7]) then 0x1b else 0x00) +} + +val xt3 : bits(8) -> bits(8) +function xt3(x) = x ^ xt2(x) + +/* Multiply 8-bit field element by 4-bit value for AES MixCols step */ +val gfmul : (bits(8), bits(4)) -> bits(8) +function gfmul( x, y) = { + (if bit_to_bool(y[0]) then x else 0x00) ^ + (if bit_to_bool(y[1]) then xt2( x) else 0x00) ^ + (if bit_to_bool(y[2]) then xt2(xt2( x)) else 0x00) ^ + (if bit_to_bool(y[3]) then xt2(xt2(xt2(x))) else 0x00) +} + +/* 8-bit to 32-bit partial AES Mix Column - forwards */ +val aes_mixcolumn_byte_fwd : bits(8) -> bits(32) +function aes_mixcolumn_byte_fwd(so) = { + gfmul(so, 0x3) @ so @ so @ gfmul(so, 0x2) +} + +/* 8-bit to 32-bit partial AES Mix Column - inverse*/ +val aes_mixcolumn_byte_inv : bits(8) -> bits(32) +function aes_mixcolumn_byte_inv(so) = { + gfmul(so, 0xb) @ gfmul(so, 0xd) @ gfmul(so, 0x9) @ gfmul(so, 0xe) +} + +/* 32-bit to 32-bit AES forward MixColumn */ +val aes_mixcolumn_fwd : bits(32) -> bits(32) +function aes_mixcolumn_fwd(x) = { + let s0 : bits (8) = x[ 7.. 0]; + let s1 : bits (8) = x[15.. 8]; + let s2 : bits (8) = x[23..16]; + let s3 : bits (8) = x[31..24]; + let b0 : bits (8) = xt2(s0) ^ xt3(s1) ^ (s2) ^ (s3); + let b1 : bits (8) = (s0) ^ xt2(s1) ^ xt3(s2) ^ (s3); + let b2 : bits (8) = (s0) ^ (s1) ^ xt2(s2) ^ xt3(s3); + let b3 : bits (8) = xt3(s0) ^ (s1) ^ (s2) ^ xt2(s3); + b3 @ b2 @ b1 @ b0 /* Return value */ +} + +/* 32-bit to 32-bit AES inverse MixColumn */ +val aes_mixcolumn_inv : bits(32) -> bits(32) +function aes_mixcolumn_inv(x) = { + let s0 : bits (8) = x[ 7.. 0]; + let s1 : bits (8) = x[15.. 8]; + let s2 : bits (8) = x[23..16]; + let s3 : bits (8) = x[31..24]; + let b0 : bits (8) = gfmul(s0, 0xE) ^ gfmul(s1, 0xB) ^ gfmul(s2, 0xD) ^ gfmul(s3, 0x9); + let b1 : bits (8) = gfmul(s0, 0x9) ^ gfmul(s1, 0xE) ^ gfmul(s2, 0xB) ^ gfmul(s3, 0xD); + let b2 : bits (8) = gfmul(s0, 0xD) ^ gfmul(s1, 0x9) ^ gfmul(s2, 0xE) ^ gfmul(s3, 0xB); + let b3 : bits (8) = gfmul(s0, 0xB) ^ gfmul(s1, 0xD) ^ gfmul(s2, 0x9) ^ gfmul(s3, 0xE); + b3 @ b2 @ b1 @ b0 /* Return value */ +} + +val aes_decode_rcon : bits(4) -> bits(32) +function aes_decode_rcon(r) = { + match r { + 0x0 => 0x00000001, + 0x1 => 0x00000002, + 0x2 => 0x00000004, + 0x3 => 0x00000008, + 0x4 => 0x00000010, + 0x5 => 0x00000020, + 0x6 => 0x00000040, + 0x7 => 0x00000080, + 0x8 => 0x0000001b, + 0x9 => 0x00000036, + 0xA => 0x00000000, + 0xB => 0x00000000, + 0xC => 0x00000000, + 0xD => 0x00000000, + 0xE => 0x00000000, + 0xF => 0x00000000 + } +} + +/* SM4 SBox - only one sbox for forwards and inverse */ +let sm4_sbox_table : list(bits(8)) = [| +0xD6, 0x90, 0xE9, 0xFE, 0xCC, 0xE1, 0x3D, 0xB7, 0x16, 0xB6, 0x14, 0xC2, 0x28, +0xFB, 0x2C, 0x05, 0x2B, 0x67, 0x9A, 0x76, 0x2A, 0xBE, 0x04, 0xC3, 0xAA, 0x44, +0x13, 0x26, 0x49, 0x86, 0x06, 0x99, 0x9C, 0x42, 0x50, 0xF4, 0x91, 0xEF, 0x98, +0x7A, 0x33, 0x54, 0x0B, 0x43, 0xED, 0xCF, 0xAC, 0x62, 0xE4, 0xB3, 0x1C, 0xA9, +0xC9, 0x08, 0xE8, 0x95, 0x80, 0xDF, 0x94, 0xFA, 0x75, 0x8F, 0x3F, 0xA6, 0x47, +0x07, 0xA7, 0xFC, 0xF3, 0x73, 0x17, 0xBA, 0x83, 0x59, 0x3C, 0x19, 0xE6, 0x85, +0x4F, 0xA8, 0x68, 0x6B, 0x81, 0xB2, 0x71, 0x64, 0xDA, 0x8B, 0xF8, 0xEB, 0x0F, +0x4B, 0x70, 0x56, 0x9D, 0x35, 0x1E, 0x24, 0x0E, 0x5E, 0x63, 0x58, 0xD1, 0xA2, +0x25, 0x22, 0x7C, 0x3B, 0x01, 0x21, 0x78, 0x87, 0xD4, 0x00, 0x46, 0x57, 0x9F, +0xD3, 0x27, 0x52, 0x4C, 0x36, 0x02, 0xE7, 0xA0, 0xC4, 0xC8, 0x9E, 0xEA, 0xBF, +0x8A, 0xD2, 0x40, 0xC7, 0x38, 0xB5, 0xA3, 0xF7, 0xF2, 0xCE, 0xF9, 0x61, 0x15, +0xA1, 0xE0, 0xAE, 0x5D, 0xA4, 0x9B, 0x34, 0x1A, 0x55, 0xAD, 0x93, 0x32, 0x30, +0xF5, 0x8C, 0xB1, 0xE3, 0x1D, 0xF6, 0xE2, 0x2E, 0x82, 0x66, 0xCA, 0x60, 0xC0, +0x29, 0x23, 0xAB, 0x0D, 0x53, 0x4E, 0x6F, 0xD5, 0xDB, 0x37, 0x45, 0xDE, 0xFD, +0x8E, 0x2F, 0x03, 0xFF, 0x6A, 0x72, 0x6D, 0x6C, 0x5B, 0x51, 0x8D, 0x1B, 0xAF, +0x92, 0xBB, 0xDD, 0xBC, 0x7F, 0x11, 0xD9, 0x5C, 0x41, 0x1F, 0x10, 0x5A, 0xD8, +0x0A, 0xC1, 0x31, 0x88, 0xA5, 0xCD, 0x7B, 0xBD, 0x2D, 0x74, 0xD0, 0x12, 0xB8, +0xE5, 0xB4, 0xB0, 0x89, 0x69, 0x97, 0x4A, 0x0C, 0x96, 0x77, 0x7E, 0x65, 0xB9, +0xF1, 0x09, 0xC5, 0x6E, 0xC6, 0x84, 0x18, 0xF0, 0x7D, 0xEC, 0x3A, 0xDC, 0x4D, +0x20, 0x79, 0xEE, 0x5F, 0x3E, 0xD7, 0xCB, 0x39, 0x48 +|] + +let aes_sbox_fwd_table : list(bits(8)) = [| +0x63, 0x7c, 0x77, 0x7b, 0xf2, 0x6b, 0x6f, 0xc5, 0x30, 0x01, 0x67, 0x2b, 0xfe, +0xd7, 0xab, 0x76, 0xca, 0x82, 0xc9, 0x7d, 0xfa, 0x59, 0x47, 0xf0, 0xad, 0xd4, +0xa2, 0xaf, 0x9c, 0xa4, 0x72, 0xc0, 0xb7, 0xfd, 0x93, 0x26, 0x36, 0x3f, 0xf7, +0xcc, 0x34, 0xa5, 0xe5, 0xf1, 0x71, 0xd8, 0x31, 0x15, 0x04, 0xc7, 0x23, 0xc3, +0x18, 0x96, 0x05, 0x9a, 0x07, 0x12, 0x80, 0xe2, 0xeb, 0x27, 0xb2, 0x75, 0x09, +0x83, 0x2c, 0x1a, 0x1b, 0x6e, 0x5a, 0xa0, 0x52, 0x3b, 0xd6, 0xb3, 0x29, 0xe3, +0x2f, 0x84, 0x53, 0xd1, 0x00, 0xed, 0x20, 0xfc, 0xb1, 0x5b, 0x6a, 0xcb, 0xbe, +0x39, 0x4a, 0x4c, 0x58, 0xcf, 0xd0, 0xef, 0xaa, 0xfb, 0x43, 0x4d, 0x33, 0x85, +0x45, 0xf9, 0x02, 0x7f, 0x50, 0x3c, 0x9f, 0xa8, 0x51, 0xa3, 0x40, 0x8f, 0x92, +0x9d, 0x38, 0xf5, 0xbc, 0xb6, 0xda, 0x21, 0x10, 0xff, 0xf3, 0xd2, 0xcd, 0x0c, +0x13, 0xec, 0x5f, 0x97, 0x44, 0x17, 0xc4, 0xa7, 0x7e, 0x3d, 0x64, 0x5d, 0x19, +0x73, 0x60, 0x81, 0x4f, 0xdc, 0x22, 0x2a, 0x90, 0x88, 0x46, 0xee, 0xb8, 0x14, +0xde, 0x5e, 0x0b, 0xdb, 0xe0, 0x32, 0x3a, 0x0a, 0x49, 0x06, 0x24, 0x5c, 0xc2, +0xd3, 0xac, 0x62, 0x91, 0x95, 0xe4, 0x79, 0xe7, 0xc8, 0x37, 0x6d, 0x8d, 0xd5, +0x4e, 0xa9, 0x6c, 0x56, 0xf4, 0xea, 0x65, 0x7a, 0xae, 0x08, 0xba, 0x78, 0x25, +0x2e, 0x1c, 0xa6, 0xb4, 0xc6, 0xe8, 0xdd, 0x74, 0x1f, 0x4b, 0xbd, 0x8b, 0x8a, +0x70, 0x3e, 0xb5, 0x66, 0x48, 0x03, 0xf6, 0x0e, 0x61, 0x35, 0x57, 0xb9, 0x86, +0xc1, 0x1d, 0x9e, 0xe1, 0xf8, 0x98, 0x11, 0x69, 0xd9, 0x8e, 0x94, 0x9b, 0x1e, +0x87, 0xe9, 0xce, 0x55, 0x28, 0xdf, 0x8c, 0xa1, 0x89, 0x0d, 0xbf, 0xe6, 0x42, +0x68, 0x41, 0x99, 0x2d, 0x0f, 0xb0, 0x54, 0xbb, 0x16 +|] + +let aes_sbox_inv_table : list(bits(8)) = [| +0x52, 0x09, 0x6a, 0xd5, 0x30, 0x36, 0xa5, 0x38, 0xbf, 0x40, 0xa3, 0x9e, 0x81, +0xf3, 0xd7, 0xfb, 0x7c, 0xe3, 0x39, 0x82, 0x9b, 0x2f, 0xff, 0x87, 0x34, 0x8e, +0x43, 0x44, 0xc4, 0xde, 0xe9, 0xcb, 0x54, 0x7b, 0x94, 0x32, 0xa6, 0xc2, 0x23, +0x3d, 0xee, 0x4c, 0x95, 0x0b, 0x42, 0xfa, 0xc3, 0x4e, 0x08, 0x2e, 0xa1, 0x66, +0x28, 0xd9, 0x24, 0xb2, 0x76, 0x5b, 0xa2, 0x49, 0x6d, 0x8b, 0xd1, 0x25, 0x72, +0xf8, 0xf6, 0x64, 0x86, 0x68, 0x98, 0x16, 0xd4, 0xa4, 0x5c, 0xcc, 0x5d, 0x65, +0xb6, 0x92, 0x6c, 0x70, 0x48, 0x50, 0xfd, 0xed, 0xb9, 0xda, 0x5e, 0x15, 0x46, +0x57, 0xa7, 0x8d, 0x9d, 0x84, 0x90, 0xd8, 0xab, 0x00, 0x8c, 0xbc, 0xd3, 0x0a, +0xf7, 0xe4, 0x58, 0x05, 0xb8, 0xb3, 0x45, 0x06, 0xd0, 0x2c, 0x1e, 0x8f, 0xca, +0x3f, 0x0f, 0x02, 0xc1, 0xaf, 0xbd, 0x03, 0x01, 0x13, 0x8a, 0x6b, 0x3a, 0x91, +0x11, 0x41, 0x4f, 0x67, 0xdc, 0xea, 0x97, 0xf2, 0xcf, 0xce, 0xf0, 0xb4, 0xe6, +0x73, 0x96, 0xac, 0x74, 0x22, 0xe7, 0xad, 0x35, 0x85, 0xe2, 0xf9, 0x37, 0xe8, +0x1c, 0x75, 0xdf, 0x6e, 0x47, 0xf1, 0x1a, 0x71, 0x1d, 0x29, 0xc5, 0x89, 0x6f, +0xb7, 0x62, 0x0e, 0xaa, 0x18, 0xbe, 0x1b, 0xfc, 0x56, 0x3e, 0x4b, 0xc6, 0xd2, +0x79, 0x20, 0x9a, 0xdb, 0xc0, 0xfe, 0x78, 0xcd, 0x5a, 0xf4, 0x1f, 0xdd, 0xa8, +0x33, 0x88, 0x07, 0xc7, 0x31, 0xb1, 0x12, 0x10, 0x59, 0x27, 0x80, 0xec, 0x5f, +0x60, 0x51, 0x7f, 0xa9, 0x19, 0xb5, 0x4a, 0x0d, 0x2d, 0xe5, 0x7a, 0x9f, 0x93, +0xc9, 0x9c, 0xef, 0xa0, 0xe0, 0x3b, 0x4d, 0xae, 0x2a, 0xf5, 0xb0, 0xc8, 0xeb, +0xbb, 0x3c, 0x83, 0x53, 0x99, 0x61, 0x17, 0x2b, 0x04, 0x7e, 0xba, 0x77, 0xd6, +0x26, 0xe1, 0x69, 0x14, 0x63, 0x55, 0x21, 0x0c, 0x7d +|] + +/* Lookup function - takes an index and a list, and retrieves the + * x'th element of that list. + */ +val sbox_lookup : (bits(8), list(bits(8))) -> bits(8) +function sbox_lookup(x, table) = { + match (x, table) { + (0x00, t0::tn) => t0, + ( y, t0::tn) => sbox_lookup(x - 0x01, tn) + } +} + +/* Easy function to perform a forward AES SBox operation on 1 byte. */ +val aes_sbox_fwd : bits(8) -> bits(8) +function aes_sbox_fwd(x) = sbox_lookup(x, aes_sbox_fwd_table) + +/* Easy function to perform an inverse AES SBox operation on 1 byte. */ +val aes_sbox_inv : bits(8) -> bits(8) +function aes_sbox_inv(x) = sbox_lookup(x, aes_sbox_inv_table) + +/* AES SubWord function used in the key expansion + * - Applies the forward sbox to each byte in the input word. + */ +val aes_subword_fwd : bits(32) -> bits(32) +function aes_subword_fwd(x) = { + aes_sbox_fwd(x[31..24]) @ + aes_sbox_fwd(x[23..16]) @ + aes_sbox_fwd(x[15.. 8]) @ + aes_sbox_fwd(x[ 7.. 0]) +} + +/* AES Inverse SubWord function. + * - Applies the inverse sbox to each byte in the input word. + */ +val aes_subword_inv : bits(32) -> bits(32) +function aes_subword_inv(x) = { + aes_sbox_inv(x[31..24]) @ + aes_sbox_inv(x[23..16]) @ + aes_sbox_inv(x[15.. 8]) @ + aes_sbox_inv(x[ 7.. 0]) +} + +/* Easy function to perform an SM4 SBox operation on 1 byte. */ +val sm4_sbox : bits(8) -> bits(8) +function sm4_sbox(x) = sbox_lookup(x, sm4_sbox_table) + +val aes_get_column : (bits(128), nat) -> bits(32) +function aes_get_column(state,c) = (state >> (to_bits(7, 32 * c)))[31..0] + +/* 64-bit to 64-bit function which applies the AES forward sbox to each byte + * in a 64-bit word. + */ +val aes_apply_fwd_sbox_to_each_byte : bits(64) -> bits(64) +function aes_apply_fwd_sbox_to_each_byte(x) = { + aes_sbox_fwd(x[63..56]) @ + aes_sbox_fwd(x[55..48]) @ + aes_sbox_fwd(x[47..40]) @ + aes_sbox_fwd(x[39..32]) @ + aes_sbox_fwd(x[31..24]) @ + aes_sbox_fwd(x[23..16]) @ + aes_sbox_fwd(x[15.. 8]) @ + aes_sbox_fwd(x[ 7.. 0]) +} + +/* 64-bit to 64-bit function which applies the AES inverse sbox to each byte + * in a 64-bit word. + */ +val aes_apply_inv_sbox_to_each_byte : bits(64) -> bits(64) +function aes_apply_inv_sbox_to_each_byte(x) = { + aes_sbox_inv(x[63..56]) @ + aes_sbox_inv(x[55..48]) @ + aes_sbox_inv(x[47..40]) @ + aes_sbox_inv(x[39..32]) @ + aes_sbox_inv(x[31..24]) @ + aes_sbox_inv(x[23..16]) @ + aes_sbox_inv(x[15.. 8]) @ + aes_sbox_inv(x[ 7.. 0]) +} + +/* + * AES full-round transformation functions. + */ + +val getbyte : (bits(64), int) -> bits(8) +function getbyte(x, i) = (x >> to_bits(6, i * 8))[7..0] + +val aes_rv64_shiftrows_fwd : (bits(64), bits(64)) -> bits(64) +function aes_rv64_shiftrows_fwd(rs2, rs1) = { + getbyte(rs1, 3) @ + getbyte(rs2, 6) @ + getbyte(rs2, 1) @ + getbyte(rs1, 4) @ + getbyte(rs2, 7) @ + getbyte(rs2, 2) @ + getbyte(rs1, 5) @ + getbyte(rs1, 0) +} + +val aes_rv64_shiftrows_inv : (bits(64), bits(64)) -> bits(64) +function aes_rv64_shiftrows_inv(rs2, rs1) = { + getbyte(rs2, 3) @ + getbyte(rs2, 6) @ + getbyte(rs1, 1) @ + getbyte(rs1, 4) @ + getbyte(rs1, 7) @ + getbyte(rs2, 2) @ + getbyte(rs2, 5) @ + getbyte(rs1, 0) +} + +/* 128-bit to 128-bit implementation of the forward AES ShiftRows transform. + * Byte 0 of state is input column 0, bits 7..0. + * Byte 5 of state is input column 1, bits 15..8. + */ +val aes_shift_rows_fwd : bits(128) -> bits(128) +function aes_shift_rows_fwd(x) = { + let ic3 : bits(32) = aes_get_column(x, 3); + let ic2 : bits(32) = aes_get_column(x, 2); + let ic1 : bits(32) = aes_get_column(x, 1); + let ic0 : bits(32) = aes_get_column(x, 0); + let oc0 : bits(32) = ic3[31..24] @ ic2[23..16] @ ic1[15.. 8] @ ic0[ 7.. 0]; + let oc1 : bits(32) = ic0[31..24] @ ic3[23..16] @ ic2[15.. 8] @ ic1[ 7.. 0]; + let oc2 : bits(32) = ic1[31..24] @ ic0[23..16] @ ic3[15.. 8] @ ic2[ 7.. 0]; + let oc3 : bits(32) = ic2[31..24] @ ic1[23..16] @ ic0[15.. 8] @ ic3[ 7.. 0]; + (oc3 @ oc2 @ oc1 @ oc0) /* Return value */ +} + +/* 128-bit to 128-bit implementation of the inverse AES ShiftRows transform. + * Byte 0 of state is input column 0, bits 7..0. + * Byte 5 of state is input column 1, bits 15..8. + */ +val aes_shift_rows_inv : bits(128) -> bits(128) +function aes_shift_rows_inv(x) = { + let ic3 : bits(32) = aes_get_column(x, 3); /* In column 3 */ + let ic2 : bits(32) = aes_get_column(x, 2); + let ic1 : bits(32) = aes_get_column(x, 1); + let ic0 : bits(32) = aes_get_column(x, 0); + let oc0 : bits(32) = ic1[31..24] @ ic2[23..16] @ ic3[15.. 8] @ ic0[ 7.. 0]; + let oc1 : bits(32) = ic2[31..24] @ ic3[23..16] @ ic0[15.. 8] @ ic1[ 7.. 0]; + let oc2 : bits(32) = ic3[31..24] @ ic0[23..16] @ ic1[15.. 8] @ ic2[ 7.. 0]; + let oc3 : bits(32) = ic0[31..24] @ ic1[23..16] @ ic2[15.. 8] @ ic3[ 7.. 0]; + (oc3 @ oc2 @ oc1 @ oc0) /* Return value */ +} + +/* Applies the forward sub-bytes step of AES to a 128-bit vector + * representation of its state. + */ +val aes_subbytes_fwd : bits(128) -> bits(128) +function aes_subbytes_fwd(x) = { + let oc0 : bits(32) = aes_subword_fwd(aes_get_column(x, 0)); + let oc1 : bits(32) = aes_subword_fwd(aes_get_column(x, 1)); + let oc2 : bits(32) = aes_subword_fwd(aes_get_column(x, 2)); + let oc3 : bits(32) = aes_subword_fwd(aes_get_column(x, 3)); + (oc3 @ oc2 @ oc1 @ oc0) /* Return value */ +} + +/* Applies the inverse sub-bytes step of AES to a 128-bit vector + * representation of its state. + */ +val aes_subbytes_inv : bits(128) -> bits(128) +function aes_subbytes_inv(x) = { + let oc0 : bits(32) = aes_subword_inv(aes_get_column(x, 0)); + let oc1 : bits(32) = aes_subword_inv(aes_get_column(x, 1)); + let oc2 : bits(32) = aes_subword_inv(aes_get_column(x, 2)); + let oc3 : bits(32) = aes_subword_inv(aes_get_column(x, 3)); + (oc3 @ oc2 @ oc1 @ oc0) /* Return value */ +} + +/* Applies the forward MixColumns step of AES to a 128-bit vector + * representation of its state. + */ +val aes_mixcolumns_fwd : bits(128) -> bits(128) +function aes_mixcolumns_fwd(x) = { + let oc0 : bits(32) = aes_mixcolumn_fwd(aes_get_column(x, 0)); + let oc1 : bits(32) = aes_mixcolumn_fwd(aes_get_column(x, 1)); + let oc2 : bits(32) = aes_mixcolumn_fwd(aes_get_column(x, 2)); + let oc3 : bits(32) = aes_mixcolumn_fwd(aes_get_column(x, 3)); + (oc3 @ oc2 @ oc1 @ oc0) /* Return value */ +} + +/* Applies the inverse MixColumns step of AES to a 128-bit vector + * representation of its state. + */ +val aes_mixcolumns_inv : bits(128) -> bits(128) +function aes_mixcolumns_inv(x) = { + let oc0 : bits(32) = aes_mixcolumn_inv(aes_get_column(x, 0)); + let oc1 : bits(32) = aes_mixcolumn_inv(aes_get_column(x, 1)); + let oc2 : bits(32) = aes_mixcolumn_inv(aes_get_column(x, 2)); + let oc3 : bits(32) = aes_mixcolumn_inv(aes_get_column(x, 3)); + (oc3 @ oc2 @ oc1 @ oc0) /* Return value */ +} + +/* Performs the word rotation for AES key schedule +*/ + +val aes_rotword : bits(32) -> bits(32) +function aes_rotword(x) = { + let a0 : bits (8) = x[ 7.. 0]; + let a1 : bits (8) = x[15.. 8]; + let a2 : bits (8) = x[23..16]; + let a3 : bits (8) = x[31..24]; + (a0 @ a3 @ a2 @ a1) /* Return Value */ +} + +val brev : bits(SEW) -> bits(SEW) +function brev(x) = { + let output : bits(SEW) = 0; + foreach (i from 0 to SEW-8 by 8) + output[i+7..i] = reverse_bits_in_byte(input[i+7..i]); + output /* Return Value */ +} + +val reverse_bits_in_byte : bits(8) -> bits(8) +function reverse_bits_in_byte(x) = { + let output : bits(8) = 0; + foreach (i from 0 to 7) + output[i] = x[7-i]); + output /* Return Value */ +} + +val rev8 : bits(SEW) -> bits(SEW) +function rev8(x) = { // endian swap + let output : bits(SEW) = 0; + let j = SEW - 1; + foreach (k from 0 to (SEW - 8) by 8) { + output[k..(k + 7)] = x[(j - 7)..j]; + j = j - 8; + output /* Return Value */ + } + RETIRE_SUCCESS + + +val rol32 : bits(32) -> bits(32) +function ROL32(x,n) = (X << N) | (X >> (32 - N)) + +val sm4_subword : bits(32) -> bits(32) +function sm4_subword(x) = { + sm4_sbox(x[31..24]) @ + sm4_sbox(x[23..16]) @ + sm4_sbox(x[15.. 8]) @ + sm4_sbox(x[ 7.. 0]) +} +---- diff --git a/param_extraction/chunks/chunk_060.txt.license b/param_extraction/chunks/chunk_060.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_060.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_061.txt b/param_extraction/chunks/chunk_061.txt new file mode 100644 index 0000000000..62999b3177 --- /dev/null +++ b/param_extraction/chunks/chunk_061.txt @@ -0,0 +1,142 @@ +# Chunk: chunk_061 +# Source: vector-examples.adoc +# Lines: 1-125 (of 125) +# Content starts: line 1 +# Line count: 125 +# Sections: 10 +# == Vector Assembly Code Examples +# === Vector-vector add example +# === Example with mixed-width mask and compute. +# === Memcpy example +# === Conditional example +# === SAXPY example +# === SGEMM example +# === Division approximation example +# === Square root approximation example +# === C standard library strcmp example +# +[appendix] +== Vector Assembly Code Examples + +The following are provided as non-normative text to help explain the vector ISA. + +=== Vector-vector add example + +---- +include::example/vvaddint32.s[lines=4..-1] +---- + +=== Example with mixed-width mask and compute. + +---- +# Code using one width for predicate and different width for masked +# compute. +# int8_t a[]; int32_t b[], c[]; +# for (i=0; i +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_062.txt b/param_extraction/chunks/chunk_062.txt new file mode 100644 index 0000000000..205aa20ecb --- /dev/null +++ b/param_extraction/chunks/chunk_062.txt @@ -0,0 +1,77 @@ +# Chunk: chunk_062 +# Source: zabha.adoc +# Lines: 1-68 (of 68) +# Content starts: line 1 +# Line count: 68 +# Sections: 2 +# == "Zabha" Extension for Byte and Halfword Atomic Memory Operations, Version 1.0 +# === Byte and Halfword Atomic Memory Operation Instructions +# +== "Zabha" Extension for Byte and Halfword Atomic Memory Operations, Version 1.0 + +The A-extension offers atomic memory operation (AMO) instructions for _words_, +_doublewords_, and _quadwords_ (only for `AMOCAS`). The absence of atomic +operations for subword data types necessitates emulation strategies. For bitwise +operations, this emulation can be performed via word-sized bitwise AMO* +instructions. For non-bitwise operations, emulation is achievable using +word-sized `LR`/`SC` instructions. + +Several limitations arise from this emulation approach: + +. In systems with large-scale or Non-Uniform Memory Access (NUMA) + configurations, emulation based on `LR`/`SC` introduces issues related to + scalability and fairness, particularly under conditions of high contention. + +. Emulation of narrower AMOs through wider AMO* instructions on non-idempotent + IO memory regions may result in unintended side effects. + +. Utilizing wider AMO* instructions for emulating narrower AMOs risks activating + extraneous breakpoints or watchpoints. + +. In the absence of native support for subword atomics, compilers often resort + to inlining code sequences to provide the required emulation. This practice + contributes to an increase in code size, with consequent impacts on system + performance and memory utilization. + +The Zabha extension addresses these limitations by adding support for _byte_ and +_halfword_ atomic memory operations to the RISC-V Unprivileged ISA. The Zabha +extension depends upon the Zaamo standard extension. + +=== Byte and Halfword Atomic Memory Operation Instructions + +Zabha extension provides the `AMO[ADD|AND|OR|XOR|SWAP|MIN[U]|MAX[U]].[B|H]` +instructions. If Zacas extension is also implemented, Zabha further provides the +`AMOCAS.[B|H]` instructions. + +[wavedrom, zabha-ext-wavedrom-reg,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr:['AMO','AMO','AMO','AMO','AMO','AMO','AMO','AMO']}, + {bits: 5, name: 'rd', attr:['dest','dest','dest','dest','dest','dest','dest','dest']}, + {bits: 3, name: 'funct3', attr:['width=0/1','width=0/1','width=0/1','width=0/1','width=0/1','width=0/1','width=0/1','width=0/1']}, + {bits: 5, name: 'rs1', attr:['addr','addr','addr','addr','addr','addr','addr','addr']}, + {bits: 5, name: 'rs2', attr:['src','src','src','src','src','src','src','src']}, + {bits: 1, name: 'rl'}, + {bits: 1, name: 'aq', attr:['ordering','ordering','ordering','ordering','ordering','ordering','ordering','ordering']}, + {bits: 5, name: 'funct5', attr:['AMOSWAP.B/H','AMOADD.B/H','AMOAND.B/H','AMOOR.B/H','AMOXOR.B/H','AMOMAX[U].B/H','AMOMIN[U].B/H','AMOCAS.B/H']}, +], config:{lanes: 1, hspace:1024}} +.... + +Byte and halfword AMOs always sign-extend the value placed in `rd`, and ignore +the stem:[XLEN-1:2^{(width + 3)}] bits of the original value in `rs2`. The +`AMOCAS.[B|H]` instructions similarly ignore the stem:[XLEN-1:2^{(width + 3)}] +bits of the original value in `rd`. + +Similar to the AMOs specified in the A extension, the Zabha extension mandates +that the address contained in the `rs1` register must be naturally aligned to +the size of the operand. The same exception options as specified in the A +extension are applicable in cases where the address is not naturally aligned. + +Similar to the AMOs specified in the A and Zacas extensions, the AMOs in the +Zabha extension optionally provide release consistency semantics, using the `aq` +and `rl` bits, to help implement multiprocessor synchronization. + +[NOTE] +==== +Zabha omits _byte_ and _halfword_ support for `LR` and `SC` due to low utility. +==== diff --git a/param_extraction/chunks/chunk_062.txt.license b/param_extraction/chunks/chunk_062.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_062.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_063.txt b/param_extraction/chunks/chunk_063.txt new file mode 100644 index 0000000000..29b236b58c --- /dev/null +++ b/param_extraction/chunks/chunk_063.txt @@ -0,0 +1,234 @@ +# Chunk: chunk_063 +# Source: zacas.adoc +# Lines: 1-225 (of 225) +# Content starts: line 1 +# Line count: 225 +# Sections: 2 +# == "Zacas" Extension for Atomic Compare-and-Swap (CAS) Instructions, Version 1.0.0 +# === Word/Doubleword/Quadword CAS (AMOCAS.W/D/Q) Instructions +# +== "Zacas" Extension for Atomic Compare-and-Swap (CAS) Instructions, Version 1.0.0 + +Compare-and-Swap (CAS) provides an easy and typically faster way to perform +thread synchronization operations when supported as a hardware instruction. CAS +is typically used by lock-free and wait-free algorithms. This extension defines +CAS instructions to operate on 32-bit, 64-bit, and 128-bit (RV64 only) data +values. The Zacas extension depends upon the Zaamo extension. + +=== Word/Doubleword/Quadword CAS (AMOCAS.W/D/Q) Instructions + +[wavedrom, , svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr:'AMO'}, + {bits: 5, name: 'rd', attr:'dest'}, + {bits: 3, name: 'funct3', attr:['010', '011', '100']}, + {bits: 5, name: 'rs1', attr:'addr'}, + {bits: 5, name: 'rs2', attr:'src'}, + {bits: 1, name: 'rl'}, + {bits: 1, name: 'aq'}, + {bits: 5, name: '00101', attr:['AMOCAS.W', 'AMOCAS.D', 'AMOCAS.Q']}, +], config:{lanes: 1, hspace:1024}} +.... + +For RV32, `AMOCAS.W` atomically loads a 32-bit data value from address in `rs1`, +compares the loaded value to the 32-bit value held in `rd`, and if the comparison +is bitwise equal, then stores the 32-bit value held in `rs2` to the original +address in `rs1`. The value loaded from memory is placed into register `rd`. The +operation performed by `AMOCAS.W` for RV32 is as follows: + +[listing] +---- + temp = mem[X(rs1)] + if ( temp == X(rd) ) + mem[X(rs1)] = X(rs2) + X(rd) = temp +---- + +`AMOCAS.D` is similar to `AMOCAS.W` but operates on 64-bit data values. + +For RV32, `AMOCAS.D` atomically loads 64-bits of a data value from address in +`rs1`, compares the loaded value to a 64-bit value held in a register pair +consisting of `rd` and `rd+1`, and if the comparison is bitwise equal, then +stores the 64-bit value held in the register pair `rs2` and `rs2+1` to the +original address in `rs1`. The value loaded from memory is placed into the +register pair `rd` and `rd+1`. The instruction requires the first register in +the pair to be even numbered; encodings with odd numbered registers specified +in `rs2` and `rd` are reserved. When the first register of a source register +pair is `x0`, then both halves of the pair read as zero. When the first +register of a destination register pair is `x0`, then the entire register +result is discarded and neither destination register is written. +The operation performed by `AMOCAS.D` for RV32 is as follows: + +<<< + +[listing] + temp0 = mem[X(rs1)+0] + temp1 = mem[X(rs1)+4] + comp0 = (rd == x0) ? 0 : X(rd) + comp1 = (rd == x0) ? 0 : X(rd+1) + swap0 = (rs2 == x0) ? 0 : X(rs2) + swap1 = (rs2 == x0) ? 0 : X(rs2+1) + if ( temp0 == comp0 ) && ( temp1 == comp1 ) + mem[X(rs1)+0] = swap0 + mem[X(rs1)+4] = swap1 + endif + if ( rd != x0 ) + X(rd) = temp0 + X(rd+1) = temp1 + endif + +For RV64, `AMOCAS.W` atomically loads a 32-bit data value from address in +`rs1`, compares the loaded value to the lower 32 bits of the value held in `rd`, +and if the comparison is bitwise equal, then stores the lower 32 bits of the +value held in `rs2` to the original address in `rs1`. The 32-bit value loaded +from memory is sign-extended and is placed into register `rd`. The operation +performed by `AMOCAS.W` for RV64 is as follows: + +[listing] + temp[31:0] = mem[X(rs1)] + if ( temp[31:0] == X(rd)[31:0] ) + mem[X(rs1)] = X(rs2)[31:0] + X(rd) = SignExtend(temp[31:0]) + +For RV64, `AMOCAS.D` atomically loads 64-bits of a data value from address in +`rs1`, compares the loaded value to a 64-bit value held in `rd`, and if the +comparison is bitwise equal, then stores the 64-bit value held in `rs2` to the +original address in `rs1`. The value loaded from memory is placed into register +`rd`. The operation performed by `AMOCAS.D` for RV64 is as follows: +[listing] + temp = mem[X(rs1)] + if ( temp == X(rd) ) + mem[X(rs1)] = X(rs2) + X(rd) = temp + +`AMOCAS.Q` (RV64 only) atomically loads 128-bits of a data value from address in +`rs1`, compares the loaded value to a 128-bit value held in a register pair +consisting of `rd` and `rd+1`, and if the comparison is bitwise equal, then +stores the 128-bit value held in the register pair `rs2` and `rs2+1` to the +original address in `rs1`. The value loaded from memory is placed into the +register pair `rd` and `rd+1`. The instruction requires the first register in +the pair to be even numbered; encodings with odd numbered registers specified in +`rs2` and `rd` are reserved. When the first register of a source register pair +is `x0`, then both halves of the pair read as zero. When the first register of a +destination register pair is `x0`, then the entire register result is discarded +and neither destination register is written. The operation performed by +`AMOCAS.Q` is as follows: + +<<< + +[listing] + temp0 = mem[X(rs1)+0] + temp1 = mem[X(rs1)+8] + comp0 = (rd == x0) ? 0 : X(rd) + comp1 = (rd == x0) ? 0 : X(rd+1) + swap0 = (rs2 == x0) ? 0 : X(rs2) + swap1 = (rs2 == x0) ? 0 : X(rs2+1) + if ( temp0 == comp0 ) && ( temp1 == comp1 ) + mem[X(rs1)+0] = swap0 + mem[X(rs1)+8] = swap1 + endif + if ( rd != x0 ) + X(rd) = temp0 + X(rd+1) = temp1 + endif + +[NOTE] +==== +Some algorithms may load the previous data value of a memory location into the +register used as the compare data value source by a Zacas instruction. When +using a Zacas instruction that uses a register pair to source the compare value, +the two registers may be loaded using two individual loads. The two individual +loads may read an inconsistent pair of values but that is not an issue since the +`AMOCAS` operation itself uses an atomic load-pair from memory to obtain the +data value for its comparison. + +The following example code sequence illustrates the use of `AMOCAS.D` in a RV32 +implementation to atomically increment a 64-bit counter. +[listing] +# a0 - address of the counter. +increment: + lw a2, (a0) # Load current counter value using + lw a3, 4(a0) # two individual loads. +retry: + mv a6, a2 # Save the low 32 bits of the current value. + mv a7, a3 # Save the high 32 bits of the current value. + addi a4, a2, 1 # Increment the low 32 bits. + sltu a1, a4, a2 # Determine if there is a carry out. + add a5, a3, a1 # Add the carry if any to high 32 bits. + amocas.d.aqrl a2, a4, (a0) + bne a2, a6, retry # If amocas.d failed then retry + bne a3, a7, retry # using current values loaded by amocas.d. + ret +==== + +Just as for AMOs in the A extension, `AMOCAS.W/D/Q` requires that the address +held in `rs1` be naturally aligned to the size of the operand (i.e., 16-byte +aligned for _quadwords_, eight-byte aligned for _doublewords_, and four-byte +aligned for _words_). And the same exception options apply if the address +is not naturally aligned. + +Just as for AMOs in the A extension, the `AMOCAS.W/D/Q` optionally provide +release consistency semantics, using the `aq` and `rl` bits, to help implement +multiprocessor synchronization. The memory operation performed by an +`AMOCAS.W/D/Q`, when successful, has acquire semantics if `aq` bit is 1 and has +release semantics if `rl` bit is 1. The memory operation performed by an +`AMOCAS.W/D/Q`, when not successful, has acquire semantics if `aq` bit is 1 but +does not have release semantics, regardless of `rl`. + +A FENCE instruction may be used to order the memory read access and, if +produced, the memory write access by an `AMOCAS.W/D/Q` instruction. + +[NOTE] +==== +An unsuccessful `AMOCAS.W/D/Q` may either not perform a memory write or may +write back the old value loaded from memory. The memory write, if produced, does +not have release semantics, regardless of `rl`. +Irrespective of whether a write is actually performed, the instruction is +treated as an AMO for the purposes of the RVWMO PPO rules. +==== + +An `AMOCAS.W/D/Q` instruction always requires write permissions. + +[NOTE] +==== +The following example code sequence illustrates the use of `AMOCAS.Q` to +implement the _enqueue_ operation for a non-blocking concurrent queue using the +algorithm outlined in cite:[queue]. The algorithm atomically operates on a +pointer and its associated modification counter using the `AMOCAS.Q` instruction +to avoid the ABA problem. + +[listing] +# Enqueue operation of a non-blocking concurrent queue. +# Data structures used by the queue: +# structure pointer_t {ptr: node_t *, count: uint64_t} +# structure node_t {next: pointer_t, value: data type} +# structure queue_t {Head: pointer_t, Tail: pointer_t} +# Inputs to the procedure: +# a0 - address of Tail variable +# a4 - address of a new node to insert at tail +enqueue: + ld a6, (a0) # a6 = Tail.ptr + ld a7, 8(a0) # a7 = Tail.count + ld a2, (a6) # a2 = Tail.ptr->next.ptr + ld a3, 8(a6) # a3 = Tail.ptr->next.count + ld t1, (a0) + ld t2, 8(a0) + bne a6, t1, enqueue # Retry if Tail & next are not consistent + bne a7, t2, enqueue # Retry if Tail & next are not consistent + bne a2, x0, move_tail # Was tail pointing to the last node? + mv t1, a2 # Save Tail.ptr->next.ptr + mv t2, a3 # Save Tail.ptr->next.count + addi a5, a3, 1 # Link the node at the end of the list + amocas.q.aqrl a2, a4, (a6) + bne a2, t1, enqueue # Retry if CAS failed + bne a3, t2, enqueue # Retry if CAS failed + addi a5, a7, 1 # Update Tail to the inserted node + amocas.q.aqrl a6, a4, (a0) + ret # Enqueue done +move_tail: # Tail was not pointing to the last node + addi a3, a7, 1 # Try to swing Tail to the next node + amocas.q.aqrl a6, a2, (a0) + j enqueue # Retry + +==== diff --git a/param_extraction/chunks/chunk_063.txt.license b/param_extraction/chunks/chunk_063.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_063.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_064.txt b/param_extraction/chunks/chunk_064.txt new file mode 100644 index 0000000000..9a32d11ac5 --- /dev/null +++ b/param_extraction/chunks/chunk_064.txt @@ -0,0 +1,146 @@ +# Chunk: chunk_064 +# Source: zalasr.adoc +# Lines: 1-135 (of 135) +# Content starts: line 1 +# Line count: 135 +# Sections: 4 +# == "Zalasr" Atomic Load-Acquire and Store-Release Instructions, Version 1.0 +# === Load-Acquire and Store-Release Instructions +# === Load Acquire +# === Store Release +# +== "Zalasr" Atomic Load-Acquire and Store-Release Instructions, Version 1.0 + +The Zalasr (Load-Acquire and Store-Release) extension provides load-acquire and store-release instructions in RISC-V. +These can be important for high performance designs by enabling finer-grained synchronisation than is possible with fences alone, by providing a unidirectional fence. +Load-acquire and store-release are widely used in language-level memory models: +both the Java and {cpp} memory models make use of acquire-release semantics, and {cpp}'s `atomic` provides primitives that are meant to map directly to load-acquire and store-release instructions. + +The Zalasr extension builds on the atomic support provided by the Zaamo (Atomic Memory Operations), Zalrsc (Load-Reserved and Store-Conditional), and Zabha (Byte and Halfword Atomic Memory Operations) extensions by providing additional atomic operations (although it can be implemented independently of them). +All of the AMO operations in Zaamo (and Zabha) are read-modify-write operations that both load and store. +The Zalrsc extension provides operations that are only loads or stores. +However, since it is designed to perform an atomic operation on a single memory word or doubleword, the loads and stores are designed to be paired. +The load-reserved implies that a future store-conditional will follow while store-conditional requires that there was a previous load-reserved without other intervening loads or stores. +Therefore, the Zalrsc extension does not provide a general atomic and ordered load or store. + +Zalasr fills this gap by offering truly standalone atomic and ordered loads and stores. +The Zalasr instructions are atomic loads and stores that support ordering annotations. +With the combination of Zaamo, Zabha, and Zalasr all {cpp} atomic operations can be supported with single instructions. + +=== Load-Acquire and Store-Release Instructions + +The Zalasr instructions always sign-extend the value placed in _rd_ and ignore the upper bits of the value of _rs2_. +The instructions in the Zalasr extension require that the address held in _rs1_ be naturally aligned to the size in bytes (2^width^) of the operand. +If the address is not naturally aligned, an address-misaligned exception or an access-fault exception will be generated. +The access-fault exception can be generated for a memory access that would otherwise be able to complete except for the misalignment, if the misaligned access should not be emulated. + +The misaligned atomicity granule PMA, defined in Volume II of this manual, optionally relaxes this alignment requirement. +If all accessed bytes lie within the same misaligned atomicity granule, the instruction will not raise an exception for reasons of address alignment, and the instruction will give rise to only one memory operation for the purposes of RVWMO—i.e., it will execute atomically. + +<<< + +[#insns-ldatomic,reftext="Load Acquire"] +=== Load Acquire + +Synopsis:: +The load-acquire instruction atomically loads a 2^width^-byte value from the address in _rs1_ and places the sign-extended value into the register _rd_, subject to the ordering annotations specified in the instruction. + +Mnemonic:: +==== +lb.{aq,aqrl} _rd_, (_rs1_) + +lh.{aq,aqrl} _rd_, (_rs1_) + +lw.{aq,aqrl} _rd_, (_rs1_) + +ld.{aq,aqrl} _rd_, (_rs1_) +==== +Encoding:: +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'AMO'], type: 8}, + {bits: 5, name: 'rd', attr: ['5', 'dest'], type: 2}, + {bits: 3, name: 'funct3', attr: ['3', 'width'], type: 8}, + {bits: 5, name: 'rs1', attr: ['5', 'addr'], type: 4}, + {bits: 5, name: 'rs2', attr: ['5', '0'], type: 4}, + {bits: 1, name: 'rl', attr: ['1', 'ring'], type: 8}, + {bits: 1, name: 'aq', attr: ['1', 'orde', '1'], type: 8}, + {bits: 5, name: 'funct5', attr: ['5', 'Load Acquire', '00110'], type: 8}, +]} +.... + +Description:: + +This instruction loads 2^width^ bytes of memory from rs1 atomically and writes the result into rd. +If the size (2^width+3^) is less than XLEN, it is sign-extended to fill the destination register. +This load must have the ordering annotation _aq_ and may have ordering annotation _rl_ encoded in the instruction. +The instruction always has an "acquire-RCsc" annotation, and if the bit _rl_ is set the instruction has a "release-RCsc" annotation. ++ +The versions without the _aq_ bit set are RESERVED. +LD.{AQ, AQRL} is RV64-only. + + +[NOTE] +==== +The _aq_ bit is mandatory because the two encodings that would be produced are not seen as useful at this time. +The version with neither the _aq_ nor the _rl_ bit set would correspond to a load with no ordering annotations that was guaranteed to be performed atomically. +This can be achieved with ordinary load instructions by suitably aligning pointers. +The version with only the _rl_ bit would correspond to load-release. +Load-release has theoretical applications in seqlocks, but is not supported in language-level memory models and so is not included. +==== + +<<< + +[#insns-sdatomic,reftext="Store Release"] +=== Store Release + +Synopsis:: +The store-release instruction atomically stores the 2^width^-byte value from the low bits of register _rs2_ to the address in _rs1_, subject to the ordering annotations specified in the instruction. + +Mnemonic:: +==== +sb.{rl,aqrl} _rs2_, (_rs1_) + +sh.{rl,aqrl} _rs2_, (_rs1_) + +sw.{rl,aqrl} _rs2_, (_rs1_) + +sd.{rl,aqrl} _rs2_, (_rs1_) +==== + +Encoding:: +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['7', 'AMO'], type: 8}, + {bits: 5, name: 'rd', attr: ['5', '0'], type: 2}, + {bits: 3, name: 'funct3', attr: ['3', 'width'], type: 8}, + {bits: 5, name: 'rs1', attr: ['5', 'addr'], type: 4}, + {bits: 5, name: 'rs2', attr: ['5', 'src'], type: 4}, + {bits: 1, name: 'rl', attr: ['1', 'ring', '1'], type: 8}, + {bits: 1, name: 'aq', attr: ['1', 'orde'], type: 8}, + {bits: 5, name: 'funct5', attr: ['5', 'Store Release', '00111'], type: 8}, +]} +.... + +Description:: + +This instruction stores 2^width^ bytes of memory from rs1 atomically. +This store must have ordering annotation _rl_ and may have ordering annotation _aq_ encoded in the instruction. +The instruction always has an "release-RCsc" annotation, and if the bit _aq_ is set the instruction has a "acquire-RCsc" annotation. ++ +The versions without the _rl_ bit set are RESERVED. +SD.{RL, AQRL} is RV64-only. + + +[NOTE] +==== +The _rl_ bit is mandatory because the two encodings that would be produced are not seen as useful at this time. +The version with neither the _aq_ nor the _rl_ bit set would correspond to a store with no ordering annotations that was guaranteed to be performed atomically. +This can be achieved with ordinary store instructions by suitably aligned pointers. +The version with only the _aq_ bit would correspond to store-acquire. +Store-acquire has theoretical applications in seqlocks, but is not supported in language-level memory models and so is not included. +==== + +<<< diff --git a/param_extraction/chunks/chunk_064.txt.license b/param_extraction/chunks/chunk_064.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_064.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_065.txt b/param_extraction/chunks/chunk_065.txt new file mode 100644 index 0000000000..c963ad8a3a --- /dev/null +++ b/param_extraction/chunks/chunk_065.txt @@ -0,0 +1,112 @@ +# Chunk: chunk_065 +# Source: zawrs.adoc +# Lines: 1-103 (of 103) +# Content starts: line 1 +# Line count: 103 +# Sections: 2 +# == "Zawrs" Extension for Wait-on-Reservation-Set instructions, Version 1.01 +# === Wait-on-Reservation-Set Instructions +# +== "Zawrs" Extension for Wait-on-Reservation-Set instructions, Version 1.01 + +The Zawrs extension defines a pair of instructions to be used in polling loops +that allows a core to enter a low-power state and wait on a store to a memory +location. Waiting for a memory location to be updated is a common pattern in +many use cases such as: + +. Contenders for a lock waiting for the lock variable to be updated. + +. Consumers waiting on the tail of an empty queue for the producer to queue + work/data. The producer may be code executing on a RISC-V hart, an accelerator + device, an external I/O agent. + +. Code waiting on a flag to be set in memory indicative of an event occurring. + For example, software on a RISC-V hart may wait on a "done" flag to be set in + memory by an accelerator device indicating completion of a job previously + submitted to the device. + +Such use cases involve polling on memory locations, and such busy loops can be a +wasteful expenditure of energy. To mitigate the wasteful looping in such usages, +a `WRS.NTO` (WRS-with-no-timeout) instruction is provided. Instead of polling +for a store to a specific memory location, software registers a reservation set +that includes all the bytes of the memory location using the `LR` instruction. +Then a subsequent `WRS.NTO` instruction would cause the hart to temporarily +stall execution in a low-power state until a store occurs to the reservation set +or an interrupt is observed. + +Sometimes the program waiting on a memory update may also need to carry out a +task at a future time or otherwise place an upper bound on the wait. To support +such use cases a second instruction `WRS.STO` (WRS-with-short-timeout) is +provided that works like `WRS.NTO` but bounds the stall duration to an +implementation-define short timeout such that the stall is terminated on the +timeout if no other conditions have occurred to terminate the stall. The +program using this instruction may then determine if its deadline has been +reached. + +[NOTE] +==== +The instructions in the Zawrs extension are only useful in conjunction with the +LR instruction, which is provided by the Zalrsc component of the A extension. +==== +[[Zawrs]] +=== Wait-on-Reservation-Set Instructions + +The `WRS.NTO` and `WRS.STO` instructions cause the hart to temporarily stall +execution in a low-power state as long as the reservation set is valid and no +pending interrupts, even if disabled, are observed. For `WRS.STO` the stall +duration is bounded by an implementation defined short timeout. These +instructions are available in all privilege modes. + +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 'opcode', attr: ['SYSTEM(0x73)'] }, + {bits: 5, name: 'rd', attr: ['0'] }, + {bits: 3, name: 'funct3', attr: ['0'] }, + {bits: 5, name: 'rs1', attr: ['0'] }, + {bits: 12, name: 'funct12', attr:['WRS.NTO(0x0d)', 'WRS.STO(0x1d)'] }, +], config:{lanes: 1, hspace:1024}} +.... + +<<< + +Hart execution may be stalled while the following conditions are all satisfied: +[loweralpha] + . The reservation set is valid + . If `WRS.STO`, a "short" duration since start of stall has not elapsed + . No pending interrupt is observed (see the rules below) + +While stalled, an implementation is permitted to occasionally terminate the +stall and complete execution for any reason. + +`WRS.NTO` and `WRS.STO` instructions follow the rules of the `WFI` instruction +for resuming execution on a pending interrupt. + +When the `TW` (Timeout Wait) bit in `mstatus` is set and `WRS.NTO` is executed +in any privilege mode other than M mode, and it does not complete within an +implementation-specific bounded time limit, the `WRS.NTO` instruction will cause +an illegal-instruction exception. + +When executing in VS or VU mode, if the `VTW` bit is set in `hstatus`, the +`TW` bit in `mstatus` is clear, and the `WRS.NTO` does not complete within an +implementation-specific bounded time limit, the `WRS.NTO` instruction will cause +a virtual-instruction exception. + +[NOTE] +==== +Since the `WRS.STO` and `WRS.NTO` instructions can complete execution for +reasons other than stores to the reservation set, software will likely need +a means of looping until the required stores have occurred. + +The duration of a `WRS.STO` instruction's timeout may vary significantly within +and among implementations. In typical implementations this duration should be +roughly in the range of 10 to 100 times an on-chip cache miss latency or a +cacheless access to main memory. + +`WRS.NTO`, unlike `WFI`, is not specified to cause an illegal-instruction +exception if executed in U-mode when the governing `TW` bit is 0. `WFI` is +typically not expected to be used in U-mode and on many systems may promptly +cause an illegal-instruction exception if used at U-mode. Unlike `WFI`, +`WRS.NTO` is expected to be used by software in U-mode when waiting on +memory but without a deadline for that wait. +==== diff --git a/param_extraction/chunks/chunk_065.txt.license b/param_extraction/chunks/chunk_065.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_065.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_066.txt b/param_extraction/chunks/chunk_066.txt new file mode 100644 index 0000000000..404ec1571b --- /dev/null +++ b/param_extraction/chunks/chunk_066.txt @@ -0,0 +1,2614 @@ +# Chunk: chunk_066 +# Source: zc.adoc +# Lines: 1-2587 (of 2587) +# Content starts: line 1 +# Line count: 2587 +# Sections: 20 +# == "Zc*" Extension for Code Size Reduction, Version 1.0.0 +# === Zc* Overview +# === C +# === Zce +# === MISA.C +# === Zca +# === Zcf (RV32 only) +# === Zcd +# === Zcb +# === Zcmp +# === Zcmt +# === Zc instruction formats +# === Zcb instructions +# ==== c.lbu +# ==== c.lhu +# ==== c.lh +# ==== c.sb +# ==== c.sh +# ==== c.zext.b +# ==== c.sext.b +# +[#Zc] +== "Zc*" Extension for Code Size Reduction, Version 1.0.0 + +=== Zc* Overview + +Zc* is a group of extensions that define subsets of the existing C extension (Zca, Zcd, Zcf) and new extensions which only contain 16-bit encodings. + +Zcm* all reuse the encodings for _c.fld_, _c.fsd_, _c.fldsp_, _c.fsdsp_. + +.Zc* extension overview +[width="100%",options=header,cols="3,1,1,1,1,1,1"] +|==================================================================================== +|Instruction |Zca |Zcf |Zcd |Zcb |Zcmp |Zcmt +7+|*The Zca extension is added as way to refer to instructions in the C extension that do not include the floating-point loads and stores* +|C excl. c.f* |yes | | | | | +7+|*The Zcf extension is added as a way to refer to compressed single-precision floating-point load/stores* +|c.flw | |rv32 | | | | +|c.flwsp | |rv32 | | | | +|c.fsw | |rv32 | | | | +|c.fswsp | |rv32 | | | | +7+|*The Zcd extension is added as a way to refer to compressed double-precision floating-point load/stores* +|c.fld | | |yes | | | +|c.fldsp | | |yes | | | +|c.fsd | | |yes | | | +|c.fsdsp | | |yes | | | +7+|*Simple operations for use on all architectures* +|c.lbu | | | |yes | | +|c.lh | | | |yes | | +|c.lhu | | | |yes | | +|c.sb | | | |yes | | +|c.sh | | | |yes | | +|c.zext.b | | | |yes | | +|c.sext.b | | | |yes | | +|c.zext.h | | | |yes | | +|c.sext.h | | | |yes | | +|c.zext.w | | | |yes | | +|c.mul | | | |yes | | +|c.not | | | |yes | | +7+|*PUSH/POP and double move which overlap with _c.fsdsp_. Complex operations intended for embedded CPUs* +|cm.push | | | | |yes | +|cm.pop | | | | |yes | +|cm.popret | | | | |yes | +|cm.popretz | | | | |yes | +|cm.mva01s | | | | |yes | +|cm.mvsa01 | | | | |yes | +7+|*Table jump which overlaps with _c.fsdsp_. Complex operations intended for embedded CPUs* +|cm.jt | | | | | |yes +|cm.jalt | | | | | |yes +|==================================================================================== + +[#C] +=== C + +The C extension is the superset of the following extensions: + +* Zca +* Zcf if F is specified (RV32 only) +* Zcd if D is specified + +As C defines the same instructions as Zca, Zcf, and Zcd, the rule is that: + +* C always implies Zca +* C+F implies Zcf (RV32 only) +* C+D implies Zcd + +[reftext="Zce"] +=== Zce + +The Zce extension is intended to be used for microcontrollers, and includes all relevant Zc extensions. + +* Specifying Zce on RV32 without F includes Zca, Zcb, Zcmp, Zcmt +* Specifying Zce on RV32 with F includes Zca, Zcb, Zcmp, Zcmt _and_ Zcf +* Specifying Zce on RV64 always includes Zca, Zcb, Zcmp, Zcmt +** Zcf doesn't exist for RV64 + +Therefore common ISA strings can be updated as follows to include the relevant Zc extensions, for example: + +* RV32IMC becomes RV32IM_Zce +* RV32IMCF becomes RV32IMF_Zce + +[#misaC] +=== MISA.C + +[#norm:misa-c_set_line]#MISA.C is set if the following extensions are selected:# + +[[norm:misa-c_set_list]] +* Zca and not F +* Zca, Zcf and F (but not D) is specified (RV32 only) +* Zca, Zcf and Zcd if D is specified (RV32 only) +** this configuration excludes Zcmp, Zcmt +* Zca, Zcd if D is specified (RV64 only) +** this configuration excludes Zcmp, Zcmt + +[reftext="Zca"] +=== Zca + +The Zca extension is added as way to refer to instructions in the C extension that do not include the floating-point loads and stores. + +Therefore it _excluded_ all 16-bit floating point loads and stores: _c.flw_, _c.flwsp_, _c.fsw_, _c.fswsp_, _c.fld_, _c.fldsp_, _c.fsd_, _c.fsdsp_. + +[NOTE] +==== +the C extension only includes F/D instructions when D and F are also specified +==== + +[reftext="Zcf"] +=== Zcf (RV32 only) + +Zcf is the existing set of compressed single precision floating point loads and stores: _c.flw_, _c.flwsp_, _c.fsw_, _c.fswsp_. + +Zcf is only relevant to RV32, it cannot be specified for RV64. + +The Zcf extension depends on the <> and F extensions. + +[reftext="Zcd"] +=== Zcd + +Zcd is the existing set of compressed double precision floating point loads and stores: _c.fld_, _c.fldsp_, _c.fsd_, _c.fsdsp_. + +The Zcd extension depends on the <> and D extensions. + +[reftext="Zcb"] +=== Zcb + +Zcb has simple code-size saving instructions which are easy to implement on all CPUs. + +All encodings are currently reserved for all architectures, and have no conflicts with any existing extensions. + +NOTE: Zcb can be implemented on _any_ CPU as the instructions are 16-bit versions of existing 32-bit instructions from the application class profile. + +The Zcb extension depends on the <> extension. + +As shown on the individual instruction pages, many of the instructions in Zcb depend upon another extension being implemented. For example, _c.mul_ is only implemented if M or Zmmul is implemented, and _c.sext.b_ is only implemented if Zbb is implemented. + +The _c.mul_ encoding uses the CA register format along with other instructions such as _c.sub_, _c.xor_ etc. + +[NOTE] + + _c.sext.w_ is a pseudoinstruction for _c.addiw rd, 0_ (RV64) + +[%header,cols="^1,^1,4,8"] +|=== +|RV32 +|RV64 +|Mnemonic +|Instruction + +|yes +|yes +|c.lbu _rd'_, uimm(_rs1'_) +|<<#insns-c_lbu>> + +|yes +|yes +|c.lhu _rd'_, uimm(_rs1'_) +|<<#insns-c_lhu>> + +|yes +|yes +|c.lh _rd'_, uimm(_rs1'_) +|<<#insns-c_lh>> + +|yes +|yes +|c.sb _rs2'_, uimm(_rs1'_) +|<<#insns-c_sb>> + +|yes +|yes +|c.sh _rs2'_, uimm(_rs1'_) +|<<#insns-c_sh>> + +|yes +|yes +|c.zext.b _rsd'_ +|<<#insns-c_zext_b>> + +|yes +|yes +|c.sext.b _rsd'_ +|<<#insns-c_sext_b>> + +|yes +|yes +|c.zext.h _rsd'_ +|<<#insns-c_zext_h>> + +|yes +|yes +|c.sext.h _rsd'_ +|<<#insns-c_sext_h>> + +| +|yes +|c.zext.w _rsd'_ +|<<#insns-c_zext_w>> + +|yes +|yes +|c.not _rsd'_ +|<<#insns-c_not>> + +|yes +|yes +|c.mul _rsd'_, _rs2'_ +|<<#insns-c_mul>> + +|=== + +<<< + +[#Zcmp] +=== Zcmp + +The Zcmp extension is a set of instructions which may be executed as a series of existing 32-bit RISC-V instructions. + +This extension reuses some encodings from _c.fsdsp_. Therefore it is _incompatible_ with <>, + which is included when C and D extensions are both present. + +NOTE: Zcmp is primarily targeted at embedded class CPUs due to implementation complexity. Additionally, it is not compatible with application class profiles. + +The Zcmp extension depends on the <> extension. + +The PUSH/POP assembly syntax uses several variables, the meaning of which are: + +* _reg_list_ is a list containing 1 to 13 registers (ra and 0 to 12 s registers) +** valid values: \{ra}, \{ra, s0}, \{ra, s0-s1}, \{ra, s0-s2}, ..., \{ra, s0-s8}, \{ra, s0-s9}, \{ra, s0-s11} +** note that \{ra, s0-s10} is _not_ valid, giving 12 lists not 13 for better encoding +* _stack_adj_ is the total size of the stack frame. +** valid values vary with register list length and the specific encoding, see the instruction pages for details. + +[%header,cols="^1,^1,4,8"] +|=== +|RV32 +|RV64 +|Mnemonic +|Instruction + +|yes +|yes +|cm.push _\{reg_list}, -stack_adj_ +|<<#insns-cm_push>> + +|yes +|yes +|cm.pop _\{reg_list}, stack_adj_ +|<<#insns-cm_pop>> + +|yes +|yes +|cm.popret _\{reg_list}, stack_adj_ +|<<#insns-cm_popret>> + +|yes +|yes +|cm.popretz _\{reg_list}, stack_adj_ +|<<#insns-cm_popretz>> + +|yes +|yes +|cm.mva01s _rs1', rs2'_ +|<<#insns-cm_mva01s>> + +|yes +|yes +|cm.mvsa01 _r1s', r2s'_ +|<<#insns-cm_mvsa01>> + +|=== + +<<< + +[#Zcmt] +=== Zcmt + +Zcmt adds the table jump instructions and also adds the jvt CSR. The jvt CSR requires a +state enable if Smstateen is implemented. See <> for details. + +This extension reuses some encodings from _c.fsdsp_. Therefore it is _incompatible_ with <>, + which is included when C and D extensions are both present. + +NOTE: Zcmt is primarily targeted at embedded class CPUs due to implementation complexity. Additionally, it is not compatible with RVA profiles. + +The Zcmt extension depends on the <> and Zicsr extensions. + +[%header,cols="^1,^1,4,8"] +|=== +|RV32 +|RV64 +|Mnemonic +|Instruction + +|yes +|yes +|cm.jt _index_ +|<<#insns-cm_jt>> + +|yes +|yes +|cm.jalt _index_ +|<<#insns-cm_jalt>> + +|=== + +[#Zc_formats] +=== Zc instruction formats + +Several instructions in this specification use the following new instruction formats. + +[%header,cols="2,3,2,1,1,1,1,1,1,1,1,1,1"] +|===================================================================== +| Format | instructions | 15:10 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 +| CLB | c.lbu | funct6 3+| rs1' 2+| uimm 3+| rd' 2+| op +| CSB | c.sb | funct6 3+| rs1' 2+| uimm 3+| rs2' 2+| op +| CLH | c.lhu, c.lh | funct6 3+| rs1' | funct1 | uimm 3+| rd' 2+| op +| CSH | c.sh | funct6 3+| rs1' | funct1 | uimm 3+| rs2' 2+| op +| CU | c.[sz]ext.*, c.not | funct6 3+| rd'/rs1' 5+| funct5 2+| op +| CMMV | cm.mvsa01 cm.mva01s| funct6 3+| r1s' 2+| funct2 3+| r2s' 2+| op +| CMJT | cm.jt cm.jalt | funct6 8+| index 2+| op +| CMPP | cm.push*, cm.pop* | funct6 2+| funct2 4+| urlist 2+| spimm 2+| op +|===================================================================== + +[NOTE] +==== +c.mul uses the existing CA format. +==== + +<<< + +[#Zcb_instructions] +=== Zcb instructions + +[#insns-c_lbu,reftext="Load unsigned byte, 16-bit encoding"] +==== c.lbu + +Synopsis:: + +Load unsigned byte, 16-bit encoding + +Mnemonic:: + +c.lbu _rd'_, _uimm_(_rs1'_) + +Encoding (RV32, RV64): + +[wavedrom, , svg] +.... +{reg:[ + { bits: 2, name: 0x0, attr: ['C0'] }, + { bits: 3, name: 'rd\'' }, + { bits: 2, name: 'uimm[0|1]' }, + { bits: 3, name: 'rs1\'' }, + { bits: 3, name: 0x0 }, + { bits: 3, name: 0x4, attr: ['FUNCT3'] }, +],config:{bits:16}} +.... + +The immediate offset is formed as follows: + +[source,sail] +-- + uimm[31:2] = 0; + uimm[1] = encoding[5]; + uimm[0] = encoding[6]; +-- + +Description:: + +This instruction [#norm:c-lbu_op]#loads a byte from the memory address formed by adding _rs1'_ to the zero extended immediate _uimm_. The resulting byte is zero extended to XLEN bits and is written to _rd'_.# + +[NOTE] +==== +_rd'_ and _rs1'_ are from the standard 8-register set x8-x15. +==== + +Prerequisites:: + +None +//32-bit equivalent: +//<> + +Operation:: + +[source,sail] +---- +//This is not SAIL, it's pseudocode. The SAIL hasn't been written yet. + +X(rdc) = EXTZ(mem[X(rs1c)+EXTZ(uimm)][7..0]); +---- + +<<< +[#insns-c_lhu,reftext="Load unsigned halfword, 16-bit encoding"] +==== c.lhu + +Synopsis:: + +Load unsigned halfword, 16-bit encoding + +Mnemonic:: + +c.lhu _rd'_, _uimm_(_rs1'_) + +Encoding (RV32, RV64): + +[wavedrom, , svg] +.... +{reg:[ + { bits: 2, name: 0x0, attr: ['C0'] }, + { bits: 3, name: 'rd\'' }, + { bits: 1, name: 'uimm[1]' }, + { bits: 1, name: 0x0 }, + { bits: 3, name: 'rs1\'' }, + { bits: 3, name: 0x1 }, + { bits: 3, name: 0x4, attr: ['FUNCT3'] }, +],config:{bits:16}} +.... + +The immediate offset is formed as follows: + +[source,sail] +---- + uimm[31:2] = 0; + uimm[1] = encoding[5]; + uimm[0] = 0; +---- + +Description:: + +This instruction [#norm:c-lhu_op]#loads a halfword from the memory address formed by adding _rs1'_ to the zero extended immediate _uimm_. The resulting halfword is zero extended to XLEN bits and is written to _rd'_.# + +[NOTE] +==== +_rd'_ and _rs1'_ are from the standard 8-register set x8-x15. +==== + +Prerequisites:: + +None +//32-bit equivalent: +// +//<> + +Operation:: + +[source,sail] +-- +//This is not SAIL, it's pseudocode. The SAIL hasn't been written yet. + +X(rdc) = EXTZ(load_mem[X(rs1c)+EXTZ(uimm)][15..0]); +-- + +<<< +[#insns-c_lh,reftext="Load signed halfword, 16-bit encoding"] +==== c.lh + +Synopsis:: + +Load signed halfword, 16-bit encoding + +Mnemonic:: + +c.lh _rd'_, _uimm_(_rs1'_) + +Encoding (RV32, RV64): + +[wavedrom, , svg] +.... +{reg:[ + { bits: 2, name: 0x0, attr: ['C0'] }, + { bits: 3, name: 'rd\'' }, + { bits: 1, name: 'uimm[1]' }, + { bits: 1, name: 0x1 }, + { bits: 3, name: 'rs1\'' }, + { bits: 3, name: 0x1 }, + { bits: 3, name: 0x4, attr: ['FUNCT3'] }, +],config:{bits:16}} +.... + +The immediate offset is formed as follows: + +[source,sail] +---- + uimm[31:2] = 0; + uimm[1] = encoding[5]; + uimm[0] = 0; +---- + +Description:: + +This instruction [#norm:c-lh_op]#loads a halfword from the memory address formed by adding _rs1'_ to the zero extended immediate _uimm_. The resulting halfword is sign extended to XLEN bits and is written to _rd'_.# + +[NOTE] +==== +_rd'_ and _rs1'_ are from the standard 8-register set x8-x15. +==== + +Prerequisites:: + +None +//32-bit equivalent: +// +//<> + +Operation:: + +[source,sail] +---- +//This is not SAIL, it's pseudocode. The SAIL hasn't been written yet. + +X(rdc) = EXTS(load_mem[X(rs1c)+EXTZ(uimm)][15..0]); +---- + +<<< +[#insns-c_sb,reftext="Store byte, 16-bit encoding"] +==== c.sb + +Synopsis:: + +Store byte, 16-bit encoding + +Mnemonic:: + +c.sb _rs2'_, _uimm_(_rs1'_) + +Encoding (RV32, RV64): + +[wavedrom, , svg] +.... +{reg:[ + { bits: 2, name: 0x0, attr: ['C0'] }, + { bits: 3, name: 'rs2\'' }, + { bits: 2, name: 'uimm[0|1]' }, + { bits: 3, name: 'rs1\'' }, + { bits: 3, name: 0x2 }, + { bits: 3, name: 0x4, attr: ['FUNCT3'] }, +],config:{bits:16}} +.... + +The immediate offset is formed as follows: + +[source,sail] +---- + uimm[31:2] = 0; + uimm[1] = encoding[5]; + uimm[0] = encoding[6]; +---- + +Description:: + +This instruction [#norm:c-sb_op]#stores the least significant byte of _rs2'_ to the memory address formed by adding _rs1'_ to the zero extended immediate _uimm_.# + +[NOTE] +==== +_rs1'_ and _rs2'_ are from the standard 8-register set x8-x15. +==== + +Prerequisites:: + +None +// +//32-bit equivalent: +// +//<> + +Operation:: + +[source,sail] +-- +//This is not SAIL, it's pseudocode. The SAIL hasn't been written yet. + +mem[X(rs1c)+EXTZ(uimm)][7..0] = X(rs2c) +-- + +<<< +[#insns-c_sh,reftext="Store halfword, 16-bit encoding"] +==== c.sh + +Synopsis:: + +Store halfword, 16-bit encoding + +Mnemonic:: + +c.sh _rs2'_, _uimm_(_rs1'_) + +Encoding (RV32, RV64): + +[wavedrom, , svg] +.... +{reg:[ + { bits: 2, name: 0x0, attr: ['C0'] }, + { bits: 3, name: 'rs2\'' }, + { bits: 1, name: 'uimm[1]' }, + { bits: 1, name: '0' }, + { bits: 3, name: 'rs1\'' }, + { bits: 3, name: 0x3 }, + { bits: 3, name: 0x4, attr: ['FUNCT3'] }, +],config:{bits:16}} +.... + +The immediate offset is formed as follows: + +[source,sail] +---- + uimm[31:2] = 0; + uimm[1] = encoding[5]; + uimm[0] = 0; +---- + +Description:: + +This instruction [#norm:c-sh_op]#stores the least significant halfword of _rs2'_ to the memory address formed by adding _rs1'_ to the zero extended immediate _uimm_.# + +[NOTE] +==== +_rs1'_ and _rs2'_ are from the standard 8-register set x8-x15. +==== + +Prerequisites:: + +None +// +//32-bit equivalent: +// +//<> + +Operation:: +[source,sail] +---- +//This is not SAIL, it's pseudocode. The SAIL hasn't been written yet. + +mem[X(rs1c)+EXTZ(uimm)][15..0] = X(rs2c) +---- + +<<< +[#insns-c_zext_b,reftext="Zero extend byte, 16-bit encoding"] +==== c.zext.b + +Synopsis:: + +Zero extend byte, 16-bit encoding + +Mnemonic:: + +c.zext.b _rd'/rs1'_ + +Encoding (RV32, RV64): + +[wavedrom, , svg] +.... +{reg:[ + { bits: 2, name: 0x1, attr: ['C1'] }, + { bits: 3, name: 0x0, attr: ['C.ZEXT.B'] }, + { bits: 2, name: 0x3, attr: ['FUNCT2'] }, + { bits: 3, name: 'rd\'/rs1\'', attr: ['SRCDST'] }, + { bits: 3, name: 0x7 }, + { bits: 3, name: 0x4, attr: ['FUNCT3'] }, +],config:{bits:16}} +.... + +Description:: + +This instruction takes a single source/destination operand. +It [#norm:c-zext-b_op]#zero-extends the least-significant byte of the operand to XLEN bits by inserting zeros into all of +the bits more significant than 7.# + +[NOTE] +==== +_rd'/rs1'_ is from the standard 8-register set x8-x15. +==== + +Prerequisites:: + +None + +32-bit equivalent: + +[source,asm] +---- +andi rd'/rs1', rd'/rs1', 0xff +---- + +[NOTE] +==== +The SAIL module variable for _rd'/rs1'_ is called _rsdc_. +==== + +Operation:: + +[source,sail] +---- +X(rsdc) = EXTZ(X(rsdc)[7..0]); +---- + +<<< +[#insns-c_sext_b,reftext="Sign extend byte, 16-bit encoding"] +==== c.sext.b + +Synopsis:: + +Sign extend byte, 16-bit encoding + +Mnemonic:: + +c.sext.b _rd'/rs1'_ + +Encoding (RV32, RV64): + +[wavedrom, , svg] +.... +{reg:[ + { bits: 2, name: 0x1, attr: ['C1'] }, + { bits: 3, name: 0x1, attr: ['C.SEXT.B'] }, + { bits: 2, name: 0x3, attr: ['FUNCT2'] }, + { bits: 3, name: 'rd\'/rs1\'', attr: ['SRCDST'] }, + { bits: 3, name: 0x7 }, + { bits: 3, name: 0x4, attr: ['FUNCT3'] }, +],config:{bits:16}} +.... + +Description:: + +This instruction takes a single source/destination operand. +It [#norm:c-sext-b_op]#sign-extends the least-significant byte in the operand to XLEN bits by copying the most-significant bit +in the byte (i.e., bit 7) to all of the more-significant bits.# + +[NOTE] +==== +_rd'/rs1'_ is from the standard 8-register set x8-x15. +==== + +Prerequisites:: + +Zbb is also required. +// +//32-bit equivalent: +// +//<> from Zbb + +[NOTE] + +The SAIL module variable for _rd'/rs1'_ is called _rsdc_. + +Operation:: + +[source,sail] +---- +X(rsdc) = EXTS(X(rsdc)[7..0]); +---- + +<<< +[#insns-c_zext_h,reftext="Zero extend halfword, 16-bit encoding"] +==== c.zext.h + +Synopsis:: + +Zero extend halfword, 16-bit encoding + +Mnemonic:: + +c.zext.h _rd'/rs1'_ + +Encoding (RV32, RV64): + +[wavedrom, , svg] +.... +{reg:[ + { bits: 2, name: 0x1, attr: ['C1'] }, + { bits: 3, name: 0x2, attr: ['C.ZEXT.H'] }, + { bits: 2, name: 0x3, attr: ['FUNCT2'] }, + { bits: 3, name: 'rd\'/rs1\'', attr: ['SRCDST'] }, + { bits: 3, name: 0x7 }, + { bits: 3, name: 0x4, attr: ['FUNCT3'] }, +],config:{bits:16}} +.... + +Description:: + +This instruction takes a single source/destination operand. +It [#norm:c-zext-h_op]#zero-extends the least-significant halfword of the operand to XLEN bits by inserting zeros into all of +the bits more significant than 15.# + +[NOTE] +==== +_rd'/rs1'_ is from the standard 8-register set x8-x15. +==== + +Prerequisites:: + +Zbb is also required. +// +//32-bit equivalent: +// +//<> from Zbb + +[NOTE] +==== +The SAIL module variable for _rd'/rs1'_ is called _rsdc_. +==== + +Operation:: + +[source,sail] +---- +X(rsdc) = EXTZ(X(rsdc)[15..0]); +---- + +<<< +[#insns-c_sext_h,reftext="Sign extend halfword, 16-bit encoding"] +==== c.sext.h + +Synopsis:: + +Sign extend halfword, 16-bit encoding + +Mnemonic:: + +c.sext.h _rd'/rs1'_ + +Encoding (RV32, RV64): + +[wavedrom, , svg] +.... +{reg:[ + { bits: 2, name: 0x1, attr: ['C1'] }, + { bits: 3, name: 0x3, attr: ['C.SEXT.H'] }, + { bits: 2, name: 0x3, attr: ['FUNCT2'] }, + { bits: 3, name: 'rd\'/rs1\'', attr: ['SRCDST'] }, + { bits: 3, name: 0x7 }, + { bits: 3, name: 0x4, attr: ['FUNCT3'] }, +],config:{bits:16}} +.... + +Description:: + +This instruction takes a single source/destination operand. +It [#norm:c-sext-h_op]#sign-extends the least-significant halfword in the operand to XLEN bits by copying the most-significant bit +in the halfword (i.e., bit 15) to all of the more-significant bits.# + +[NOTE] +==== +_rd'/rs1'_ is from the standard 8-register set x8-x15. +==== + +Prerequisites:: + +Zbb is also required. +// +//32-bit equivalent: +// +//<> from Zbb + +[NOTE] +==== +The SAIL module variable for _rd'/rs1'_ is called _rsdc_. +==== + +Operation:: + +[source,sail] +---- +X(rsdc) = EXTS(X(rsdc)[15..0]); +---- + +<<< +[#insns-c_zext_w,reftext="Zero extend word, 16-bit encoding"] +==== c.zext.w + +Synopsis:: + +Zero extend word, 16-bit encoding + +Mnemonic:: + +c.zext.w _rd'/rs1'_ + +Encoding (RV64): + +[wavedrom, , svg] +.... +{reg:[ + { bits: 2, name: 0x1, attr: ['C1'] }, + { bits: 3, name: 0x4, attr: ['C.ZEXT.W'] }, + { bits: 2, name: 0x3, attr: ['FUNCT2'] }, + { bits: 3, name: 'rd\'/rs1\'', attr: ['SRCDST'] }, + { bits: 3, name: 0x7 }, + { bits: 3, name: 0x4, attr: ['FUNCT3'] }, +],config:{bits:16}} +.... + +Description:: + +This instruction takes a single source/destination operand. +It [#norm:c-zext-w_op]#zero-extends the least-significant word of the operand to XLEN bits by inserting zeros into all of +the bits more significant than 31.# + +[NOTE] +==== +_rd'/rs1'_ is from the standard 8-register set x8-x15. +==== + +Prerequisites:: + +Zba is also required. + +32-bit equivalent: + +[source,asm] +---- +add.uw rd'/rs1', rd'/rs1', zero +---- + +[NOTE] +==== +The SAIL module variable for _rd'/rs1'_ is called _rsdc_. +==== + +Operation:: + +[source,sail] +---- +X(rsdc) = EXTZ(X(rsdc)[31..0]); +---- + +<<< +[#insns-c_not,reftext="Bitwise not, 16-bit encoding"] +==== c.not + +Synopsis:: + +Bitwise not, 16-bit encoding + +Mnemonic:: + +c.not _rd'/rs1'_ + +Encoding (RV32, RV64): + +[wavedrom, , svg] +.... +{reg:[ + { bits: 2, name: 0x1, attr: ['C1'] }, + { bits: 3, name: 0x5, attr: ['C.NOT'] }, + { bits: 2, name: 0x3, attr: ['FUNCT2'] }, + { bits: 3, name: 'rd\'/rs1\'', attr: ['SRCDST'] }, + { bits: 3, name: 0x7 }, + { bits: 3, name: 0x4, attr: ['FUNCT3'] }, +],config:{bits:16}} +.... + +Description:: + +This instruction [#norm:c-not_op]#takes the one's complement of _rd'/rs1'_ and writes the result to the same register.# + +[NOTE] +==== +rd'/rs1' is from the standard 8-register set x8-x15. +==== + +Prerequisites:: + +None + +32-bit equivalent: + +[source,asm] +---- +xori rd'/rs1', rd'/rs1', -1 +---- + +[NOTE] +==== +The SAIL module variable for _rd'/rs1'_ is called _rsdc_. +==== + +Operation:: + +[source,sail] +---- +X(rsdc) = X(rsdc) XOR -1; +---- + +<<< +[#insns-c_mul,reftext="Multiply, 16-bit encoding"] +==== c.mul + +Synopsis:: + +Multiply, 16-bit encoding + +Mnemonic:: + +c.mul _rsd'_, _rs2'_ + +Encoding (RV32, RV64): + +[wavedrom, , svg] +.... +{reg:[ + { bits: 2, name: 0x1, attr: ['C1'] }, + { bits: 3, name: 'rs2\'', attr: ['SRC2'] }, + { bits: 2, name: 0x2, attr: ['FUNCT2'] }, + { bits: 3, name: 'rd\'/rs1\'', attr: ['SRCDST'] }, + { bits: 3, name: 0x7 }, + { bits: 3, name: 0x4, attr: ['FUNCT3'] }, +],config:{bits:16}} +.... + +Description:: + +This instruction [#norm:c-mul_op]#multiplies XLEN bits of the source operands from _rsd'_ and _rs2'_ and writes the lowest XLEN bits of the result to _rsd'_.# + +[NOTE] +==== +_rd'/rs1'_ and _rs2'_ are from the standard 8-register set x8-x15. +==== + +Prerequisites:: + +M or Zmmul must be configured. +// +//32-bit equivalent: +// +//<> + +[NOTE] +==== +The SAIL module variable for _rd'/rs1'_ is called _rsdc_, and for _rs2'_ is called _rs2c_. +==== + +Operation:: + +[source,sail] +---- +let result_wide = to_bits(2 * sizeof(xlen), signed(X(rsdc)) * signed(X(rs2c))); +X(rsdc) = result_wide[(sizeof(xlen) - 1) .. 0]; +---- + +<<< + +[#insns-pushpop,reftext="PUSH/POP Register Instructions"] +=== PUSH/POP register instructions + +These instructions are collectively referred to as PUSH/POP: + +* <<#insns-cm_push>> +* <<#insns-cm_pop>> +* <<#insns-cm_popret>> +* <<#insns-cm_popretz>> + +The term PUSH refers to _cm.push_. + +The term POP refers to _cm.pop_. + +The term POPRET refers to _cm.popret and cm.popretz_. + +Common details for these instructions are in this section. + +==== PUSH/POP functional overview + +PUSH, POP, POPRET are used to reduce the size of function prologues and epilogues. + +. The PUSH instruction +** adjusts the stack pointer to create the stack frame +** pushes (stores) the registers specified in the register list to the stack frame + +. The POP instruction +** pops (loads) the registers in the register list from the stack frame +** adjusts the stack pointer to destroy the stack frame + +. The POPRET instructions +** pop (load) the registers in the register list from the stack frame +** _cm.popretz_ also moves zero into _a0_ as the return value +** adjust the stack pointer to destroy the stack frame +** execute a _ret_ instruction to return from the function + +<<< +==== Example usage + +This example gives an illustration of the use of PUSH and POPRET. + +The function _processMarkers_ in the EMBench benchmark picojpeg in the following file on github: https://github.com/embench/embench-iot/blob/master/src/picojpeg/libpicojpeg.c[libpicojpeg.c] + +The prologue and epilogue compile with GCC10 to: + +[source,asm] +---- + + 0001098a : + 1098a: 711d addi sp,sp,-96 ;#cm.push(1) + 1098c: c8ca sw s2,80(sp) ;#cm.push(2) + 1098e: c6ce sw s3,76(sp) ;#cm.push(3) + 10990: c4d2 sw s4,72(sp) ;#cm.push(4) + 10992: ce86 sw ra,92(sp) ;#cm.push(5) + 10994: cca2 sw s0,88(sp) ;#cm.push(6) + 10996: caa6 sw s1,84(sp) ;#cm.push(7) + 10998: c2d6 sw s5,68(sp) ;#cm.push(8) + 1099a: c0da sw s6,64(sp) ;#cm.push(9) + 1099c: de5e sw s7,60(sp) ;#cm.push(10) + 1099e: dc62 sw s8,56(sp) ;#cm.push(11) + 109a0: da66 sw s9,52(sp) ;#cm.push(12) + 109a2: d86a sw s10,48(sp);#cm.push(13) + 109a4: d66e sw s11,44(sp);#cm.push(14) +... + 109f4: 4501 li a0,0 ;#cm.popretz(1) + 109f6: 40f6 lw ra,92(sp) ;#cm.popretz(2) + 109f8: 4466 lw s0,88(sp) ;#cm.popretz(3) + 109fa: 44d6 lw s1,84(sp) ;#cm.popretz(4) + 109fc: 4946 lw s2,80(sp) ;#cm.popretz(5) + 109fe: 49b6 lw s3,76(sp) ;#cm.popretz(6) + 10a00: 4a26 lw s4,72(sp) ;#cm.popretz(7) + 10a02: 4a96 lw s5,68(sp) ;#cm.popretz(8) + 10a04: 4b06 lw s6,64(sp) ;#cm.popretz(9) + 10a06: 5bf2 lw s7,60(sp) ;#cm.popretz(10) + 10a08: 5c62 lw s8,56(sp) ;#cm.popretz(11) + 10a0a: 5cd2 lw s9,52(sp) ;#cm.popretz(12) + 10a0c: 5d42 lw s10,48(sp);#cm.popretz(13) + 10a0e: 5db2 lw s11,44(sp);#cm.popretz(14) + 10a10: 6125 addi sp,sp,96 ;#cm.popretz(15) + 10a12: 8082 ret ;#cm.popretz(16) +---- + +<<< + +with the GCC option _-msave-restore_ the output is the following: + +[source,asm] +---- +0001080e : + 1080e: 73a012ef jal t0,11f48 <__riscv_save_12> + 10812: 1101 addi sp,sp,-32 +... + 10862: 4501 li a0,0 + 10864: 6105 addi sp,sp,32 + 10866: 71e0106f j 11f84 <__riscv_restore_12> +---- + +with PUSH/POPRET this reduces to + +[source,asm] +---- +0001080e : + 1080e: b8fa cm.push \{ra,s0-s11},-96 +... + 10866: bcfa cm.popretz \{ra,s0-s11}, 96 +---- + +The prologue / epilogue reduce from 60-bytes in the original code, to 14-bytes with _-msave-restore_, +and to 4-bytes with PUSH and POPRET. +As well as reducing the code-size PUSH and POPRET eliminate the branches from +calling the millicode _save/restore_ routines and so may also perform better. + +[NOTE] +==== +The calls to _/_ become 64-bit when the target functions are out of the ±1{nbsp}MB range, increasing the prologue/epilogue size to 22-bytes. +==== + +[NOTE] +==== +POP is typically used in tail-calling sequences where _ret_ is not used to return to _ra_ after destroying the stack frame. +==== + +[#pushpop-areg-list] + +===== Stack pointer adjustment handling + +The instructions all automatically adjust the stack pointer by enough to cover the memory required for the registers being saved or restored. +Additionally the _spimm_ field in the encoding allows the stack pointer to be adjusted in additional increments of 16-bytes. There is only a small restricted +range available in the encoding; if the range is insufficient then a separate _c.addi16sp_ can be used to increase the range. + +===== Register list handling + +There is no support for the _\{ra, s0-s10}_ register list without also adding _s11_. Therefore the _\{ra, s0-s11}_ register list must be used in this case. + +[#pushpop-idempotent-memory] +==== PUSH/POP Fault handling + +[[norm:Zcmp_reexecute]] +Correct execution requires that _sp_ refers to idempotent memory (also see <>), because the core must be able to +handle traps detected during the sequence. +The entire PUSH/POP sequence is re-executed after returning from the trap handler, and multiple traps are possible during the sequence. + +[#norm:Zcmp_trap]#If a trap occurs during the sequence then _xEPC_ is updated with the PC of the instruction, _xTVAL_ (if not read-only-zero) updated with the bad address if it was an access fault and _xCAUSE_ updated with the type of trap.# + +[[norm:interrupts_allowed_in_pushpop_param]] +NOTE: It is implementation defined whether interrupts can also be taken during the sequence execution. + +[#pushpop-software-view] +==== Software view of execution + +===== Software view of the PUSH sequence + +From a software perspective the PUSH sequence appears as: + +* A sequence of stores writing the bytes required by the pseudocode +** The bytes may be written in any order. +** The bytes may be grouped into larger accesses. +** Any of the bytes may be written multiple times. +* A stack pointer adjustment + +[NOTE] +==== +If an implementation allows interrupts during the sequence, and the interrupt handler uses _sp_ to allocate stack memory, then any stores which were executed before the interrupt may be overwritten by the handler. This is safe because the memory is idempotent and the stores will be re-executed when execution resumes. +==== + +[#norm:Zcmp_push_sp_commit]#The stack pointer adjustment must only be committed only when it is certain that the entire PUSH instruction will commit.# + +[[norm:Zcmp_bus_fault]] +Stores may also return imprecise faults from the bus. +It is platform defined whether the core implementation waits for the bus responses before continuing to the final stage of the sequence, +or handles errors responses after completing the PUSH instruction. + +<<< + +For example: + +[source,asm] +---- +cm.push \{ra, s0-s5}, -64 +---- + +Appears to software as: + +[source,asm] +---- +# any bytes from sp-1 to sp-28 may be written multiple times before +# the instruction completes therefore these updates may be visible in +# the interrupt/exception handler below the stack pointer +sw s5, -4(sp) +sw s4, -8(sp) +sw s3,-12(sp) +sw s2,-16(sp) +sw s1,-20(sp) +sw s0,-24(sp) +sw ra,-28(sp) + +# this must only execute once, and will only execute after all stores +# completed without any precise faults, therefore this update is only +# visible in the interrupt/exception handler if cm.push has completed +addi sp, sp, -64 +---- + +===== Software view of the POP/POPRET sequence + +From a software perspective the POP/POPRET sequence appears as: + +* A sequence of loads reading the bytes required by the pseudocode. +** The bytes may be loaded in any order. +** The bytes may be grouped into larger accesses. +** Any of the bytes may be loaded multiple times. +* A stack pointer adjustment +* An optional `li a0, 0` +* An optional `ret` + +If a trap occurs during the sequence, then any loads which were executed before the trap may update architectural state. +The loads will be re-executed once the trap handler completes, so the values will be overwritten. +Therefore it is permitted for an implementation to update some of the destination registers before taking a fault. + +[#norm:Zcmp_pop_sp_commit]#The optional `li a0, 0`, stack pointer adjustment and optional `ret` must only be committed only when it is certain that the entire POP/POPRET instruction will commit.# + +For POPRET once the stack pointer adjustment has been committed the `ret` must execute. + +<<< +For example: + +[source,asm] +---- +cm.popretz \{ra, s0-s3}, 32; +---- + +Appears to software as: + +[source,asm] +---- +# any or all of these load instructions may execute multiple times +# therefore these updates may be visible in the interrupt/exception handler +lw s3, 28(sp) +lw s2, 24(sp) +lw s1, 20(sp) +lw s0, 16(sp) +lw ra, 12(sp) + +# these must only execute once, will only execute after all loads +# complete successfully all instructions must execute atomically +# therefore these updates are not visible in the interrupt/exception handler +li a0, 0 +addi sp, sp, 32 +ret +---- + +[[pushpop_non-idem-mem,Non-idempotent memory handling]] +==== Non-idempotent memory handling + +An implementation may have a requirement to issue a PUSH/POP instruction to non-idempotent memory. + +If the core implementation does not support PUSH/POP to non-idempotent memories, the core may use an idempotency PMA to detect it and take a +load (POP/POPRET) or store (PUSH) access-fault exception in order to avoid unpredictable results. + +Software should only use these instructions on non-idempotent memory regions when software can tolerate the required memory accesses +being issued repeatedly in the case that they cause exceptions. + +<<< + +==== Example RV32I PUSH/POP sequences + +The examples are included show the load/store series expansion and the stack adjustment. +Examples of _cm.popret_ and _cm.popretz_ are not included, as the difference in the expanded sequence from _cm.pop_ is trivial in all cases. + +===== cm.push \{ra, s0-s2}, -64 + +Encoding: _rlist_=7, _spimm_=3 + +expands to: + +[source,asm] +---- +sw s2, -4(sp); +sw s1, -8(sp); +sw s0, -12(sp); +sw ra, -16(sp); +addi sp, sp, -64; +---- + +===== cm.push \{ra, s0-s11}, -112 + +Encoding: _rlist_=15, _spimm_=3 + +expands to: + +[source,asm] +---- +sw s11, -4(sp); +sw s10, -8(sp); +sw s9, -12(sp); +sw s8, -16(sp); +sw s7, -20(sp); +sw s6, -24(sp); +sw s5, -28(sp); +sw s4, -32(sp); +sw s3, -36(sp); +sw s2, -40(sp); +sw s1, -44(sp); +sw s0, -48(sp); +sw ra, -52(sp); +addi sp, sp, -112; +---- + +<<< + +===== cm.pop \{ra}, 16 + +Encoding: _rlist_=4, _spimm_=0 + +expands to: + +[source,asm] +---- +lw ra, 12(sp); +addi sp, sp, 16; +---- + +===== cm.pop \{ra, s0-s3}, 48 + +Encoding: _rlist_=8, _spimm_=1 + +expands to: + +[source,asm] +---- +lw s3, 44(sp); +lw s2, 40(sp); +lw s1, 36(sp); +lw s0, 32(sp); +lw ra, 28(sp); +addi sp, sp, 48; +---- + +===== cm.pop \{ra, s0-s4}, 64 + +Encoding: _rlist_=9, _spimm_=2 + +expands to: + +[source,asm] +---- +lw s4, 60(sp); +lw s3, 56(sp); +lw s2, 52(sp); +lw s1, 48(sp); +lw s0, 44(sp); +lw ra, 40(sp); +addi sp, sp, 64; +---- + + +<<< +[#insns-cm_push,reftext="cm.push"] +==== cm.push + +Synopsis:: + +Create stack frame: store ra and 0 to 12 saved registers to the stack frame, optionally allocate additional stack space. + +Mnemonic:: + +cm.push _\{reg_list}, -stack_adj_ + +Encoding (RV32, RV64): + +[wavedrom, , svg] +.... +{reg:[ + { bits: 2, name: 0x2, attr: ['C2'] }, + { bits: 2, name: 'spimm', attr: [] }, + { bits: 4, name: 'rlist', attr: [] }, + { bits: 5, name: 0x18, attr: [] }, + { bits: 3, name: 0x5, attr: ['FUNCT3'] }, +],config:{bits:16}} +.... + +[NOTE] +==== +_rlist_ values 0 to 3 are reserved for a future EABI variant called _cm.push.e_ +==== + +Assembly Syntax: + +[source,asm] +-- +cm.push \{reg_list}, -stack_adj +cm.push {xreg_list}, -stack_adj +-- + +The variables used in the assembly syntax are defined below. + +[source,sail] +---- +RV32E: + +switch (rlist){ + case 4: \{reg_list="ra"; xreg_list="x1";} + case 5: \{reg_list="ra, s0"; xreg_list="x1, x8";} + case 6: \{reg_list="ra, s0-s1"; xreg_list="x1, x8-x9";} + default: reserved(); +} +stack_adj = stack_adj_base + spimm * 16; +---- + +[source,sail] +---- +RV32I, RV64: +switch (rlist){ + case 4: \{reg_list="ra"; xreg_list="x1";} + case 5: \{reg_list="ra, s0"; xreg_list="x1, x8";} + case 6: \{reg_list="ra, s0-s1"; xreg_list="x1, x8-x9";} + case 7: \{reg_list="ra, s0-s2"; xreg_list="x1, x8-x9, x18";} + case 8: \{reg_list="ra, s0-s3"; xreg_list="x1, x8-x9, x18-x19";} + case 9: \{reg_list="ra, s0-s4"; xreg_list="x1, x8-x9, x18-x20";} + case 10: \{reg_list="ra, s0-s5"; xreg_list="x1, x8-x9, x18-x21";} + case 11: \{reg_list="ra, s0-s6"; xreg_list="x1, x8-x9, x18-x22";} + case 12: \{reg_list="ra, s0-s7"; xreg_list="x1, x8-x9, x18-x23";} + case 13: \{reg_list="ra, s0-s8"; xreg_list="x1, x8-x9, x18-x24";} + case 14: \{reg_list="ra, s0-s9"; xreg_list="x1, x8-x9, x18-x25";} + //note - to include s10, s11 must also be included + case 15: \{reg_list="ra, s0-s11"; xreg_list="x1, x8-x9, x18-x27";} + default: reserved(); +} +stack_adj = stack_adj_base + spimm * 16; +---- + +[source,sail] +---- +RV32E: + +stack_adj_base = 16; +Valid values: +stack_adj = [16|32|48|64]; +---- + +[source,sail] +---- +RV32I: + +switch (rlist) { + case 4.. 7: stack_adj_base = 16; + case 8..11: stack_adj_base = 32; + case 12..14: stack_adj_base = 48; + case 15: stack_adj_base = 64; +} + +Valid values: +switch (rlist) { + case 4.. 7: stack_adj = [16|32|48| 64]; + case 8..11: stack_adj = [32|48|64| 80]; + case 12..14: stack_adj = [48|64|80| 96]; + case 15: stack_adj = [64|80|96|112]; +} +---- + +[source,sail] +---- +RV64: + +switch (rlist) { + case 4.. 5: stack_adj_base = 16; + case 6.. 7: stack_adj_base = 32; + case 8.. 9: stack_adj_base = 48; + case 10..11: stack_adj_base = 64; + case 12..13: stack_adj_base = 80; + case 14: stack_adj_base = 96; + case 15: stack_adj_base = 112; +} + +Valid values: +switch (rlist) { + case 4.. 5: stack_adj = [ 16| 32| 48| 64]; + case 6.. 7: stack_adj = [ 32| 48| 64| 80]; + case 8.. 9: stack_adj = [ 48| 64| 80| 96]; + case 10..11: stack_adj = [ 64| 80| 96|112]; + case 12..13: stack_adj = [ 80| 96|112|128]; + case 14: stack_adj = [ 96|112|128|144]; + case 15: stack_adj = [112|128|144|160]; +} +---- + +<<< +Description:: + +This instruction [#norm:cm-push_op]#pushes (stores) the registers in _reg_list_ to the memory below the stack pointer, +and then creates the stack frame by decrementing the stack pointer by _stack_adj_, +including any additional stack space requested by the value of _spimm_.# + + +[NOTE] +==== +All ABI register mappings are for the UABI. An EABI version is planned once the EABI is frozen. +==== + +For further information see <>. + +Stack Adjustment Calculation: + +_stack_adj_base_ is the minimum number of bytes, in multiples of 16-byte address increments, required to cover the registers in the list. + +_spimm_ is the number of additional 16-byte address increments allocated for the stack frame. + +The total stack adjustment represents the total size of the stack frame, which is _stack_adj_base_ added to _spimm_ scaled by 16, +as defined above. + +Prerequisites:: + +None + +32-bit equivalent: + +No direct equivalent encoding exists + +Operation:: + +The first section of pseudocode may be executed multiple times before the instruction successfully completes. + +[source,sail] +---- +//This is not SAIL, it's pseudocode. The SAIL hasn't been written yet. + +if (XLEN==32) bytes=4; else bytes=8; + +addr=sp-bytes; +for(i in 27,26,25,24,23,22,21,20,19,18,9,8,1) { + //if register i is in xreg_list + if (xreg_list[i]) { + switch(bytes) { + 4: asm("sw x[i], 0(addr)"); + 8: asm("sd x[i], 0(addr)"); + } + addr-=bytes; + } +} +---- + +The final section of pseudocode executes atomically, and only executes if the section above completes without any exceptions or interrupts. + +[source,sail] +---- +//This is not SAIL, it's pseudocode. The SAIL hasn't been written yet. + +sp-=stack_adj; +---- + +<<< +[#insns-cm_pop,reftext="cm.pop"] +==== cm.pop + +Synopsis:: + +Destroy stack frame: load ra and 0 to 12 saved registers from the stack frame, deallocate the stack frame. + +Mnemonic:: + +cm.pop _\{reg_list}, stack_adj_ + +Encoding (RV32, RV64): + +[wavedrom, , svg] +.... +{reg:[ + { bits: 2, name: 0x2, attr: ['C2'] }, + { bits: 2, name: 'spimm', attr: [] }, + { bits: 4, name: 'rlist', attr: [] }, + { bits: 5, name: 0x1a, attr: [] }, + { bits: 3, name: 0x5, attr: ['FUNCT3'] }, +],config:{bits:16}} +.... + +[NOTE] +==== +_rlist_ values 0 to 3 are reserved for a future EABI variant called _cm.pop.e_ +==== + +Assembly Syntax: + +[source,asm] +---- +cm.pop \{reg_list}, stack_adj +cm.pop {xreg_list}, stack_adj +---- + +The variables used in the assembly syntax are defined below. + +[source,sail] +---- +RV32E: +switch (rlist){ + case 4: \{reg_list="ra"; xreg_list="x1";} + case 5: \{reg_list="ra, s0"; xreg_list="x1, x8";} + case 6: \{reg_list="ra, s0-s1"; xreg_list="x1, x8-x9";} + default: reserved(); +} +stack_adj = stack_adj_base + spimm * 16; +---- + +[source,sail] +---- +RV32I, RV64: +switch (rlist){ + case 4: \{reg_list="ra"; xreg_list="x1";} + case 5: \{reg_list="ra, s0"; xreg_list="x1, x8";} + case 6: \{reg_list="ra, s0-s1"; xreg_list="x1, x8-x9";} + case 7: \{reg_list="ra, s0-s2"; xreg_list="x1, x8-x9, x18";} + case 8: \{reg_list="ra, s0-s3"; xreg_list="x1, x8-x9, x18-x19";} + case 9: \{reg_list="ra, s0-s4"; xreg_list="x1, x8-x9, x18-x20";} + case 10: \{reg_list="ra, s0-s5"; xreg_list="x1, x8-x9, x18-x21";} + case 11: \{reg_list="ra, s0-s6"; xreg_list="x1, x8-x9, x18-x22";} + case 12: \{reg_list="ra, s0-s7"; xreg_list="x1, x8-x9, x18-x23";} + case 13: \{reg_list="ra, s0-s8"; xreg_list="x1, x8-x9, x18-x24";} + case 14: \{reg_list="ra, s0-s9"; xreg_list="x1, x8-x9, x18-x25";} + //note - to include s10, s11 must also be included + case 15: \{reg_list="ra, s0-s11"; xreg_list="x1, x8-x9, x18-x27";} + default: reserved(); +} +stack_adj = stack_adj_base + spimm * 16; +---- + +[source,sail] +---- +RV32E: + +stack_adj_base = 16; +Valid values: +stack_adj = [16|32|48|64]; +---- + +[source,sail] +---- +RV32I: + +switch (rlist) { + case 4.. 7: stack_adj_base = 16; + case 8..11: stack_adj_base = 32; + case 12..14: stack_adj_base = 48; + case 15: stack_adj_base = 64; +} + +Valid values: +switch (rlist) { + case 4.. 7: stack_adj = [16|32|48| 64]; + case 8..11: stack_adj = [32|48|64| 80]; + case 12..14: stack_adj = [48|64|80| 96]; + case 15: stack_adj = [64|80|96|112]; +} +---- + +[source,sail] +---- +RV64: + +switch (rlist) { + case 4.. 5: stack_adj_base = 16; + case 6.. 7: stack_adj_base = 32; + case 8.. 9: stack_adj_base = 48; + case 10..11: stack_adj_base = 64; + case 12..13: stack_adj_base = 80; + case 14: stack_adj_base = 96; + case 15: stack_adj_base = 112; +} + +Valid values: +switch (rlist) { + case 4.. 5: stack_adj = [ 16| 32| 48| 64]; + case 6.. 7: stack_adj = [ 32| 48| 64| 80]; + case 8.. 9: stack_adj = [ 48| 64| 80| 96]; + case 10..11: stack_adj = [ 64| 80| 96|112]; + case 12..13: stack_adj = [ 80| 96|112|128]; + case 14: stack_adj = [ 96|112|128|144]; + case 15: stack_adj = [112|128|144|160]; +} +---- + +<<< + +Description:: + +[#norm:cm-pop_op]#This instruction pops (loads) the registers in _reg_list_ from stack memory, +and then adjusts the stack pointer by _stack_adj_.# + +[NOTE] +==== +All ABI register mappings are for the UABI. An EABI version is planned once the EABI is frozen. +==== + +For further information see <>. + +Stack Adjustment Calculation: + +_stack_adj_base_ is the minimum number of bytes, in multiples of 16-byte address increments, required to cover the registers in the list. + +_spimm_ is the number of additional 16-byte address increments allocated for the stack frame. + +The total stack adjustment represents the total size of the stack frame, which is _stack_adj_base_ added to _spimm_ scaled by 16, +as defined above. + +Prerequisites:: + +None + +32-bit equivalent: + +No direct equivalent encoding exists + +Operation:: + +The first section of pseudocode may be executed multiple times before the instruction successfully completes. + +[source,sail] +---- +//This is not SAIL, it's pseudocode. The SAIL hasn't been written yet. + +if (XLEN==32) bytes=4; else bytes=8; + +addr=sp+stack_adj-bytes; +for(i in 27,26,25,24,23,22,21,20,19,18,9,8,1) { + //if register i is in xreg_list + if (xreg_list[i]) { + switch(bytes) { + 4: asm("lw x[i], 0(addr)"); + 8: asm("ld x[i], 0(addr)"); + } + addr-=bytes; + } +} +---- + +The final section of pseudocode executes atomically, and only executes if the section above completes without any exceptions or interrupts. + +[source,sail] +---- +//This is not SAIL, it's pseudocode. The SAIL hasn't been written yet. + +sp+=stack_adj; +---- + +<<< +[#insns-cm_popretz,reftext="cm.popretz"] +==== cm.popretz + +Synopsis:: + +Destroy stack frame: load ra and 0 to 12 saved registers from the stack frame, deallocate the stack frame, move zero into a0, return to ra. + +Mnemonic:: + +cm.popretz _\{reg_list}, stack_adj_ + +Encoding (RV32, RV64): + +[wavedrom, , svg] +.... +{reg:[ + { bits: 2, name: 0x2, attr: ['C2'] }, + { bits: 2, name: 'spimm\[5:4\]', attr: [] }, + { bits: 4, name: 'rlist', attr: [] }, + { bits: 5, name: 0x1c, attr: [] }, + { bits: 3, name: 0x5, attr: ['FUNCT3'] }, +],config:{bits:16}} +.... + +[NOTE] +==== +_rlist_ values 0 to 3 are reserved for a future EABI variant called _cm.popretz.e_ +==== + +Assembly Syntax: + +[source,sail] +---- +cm.popretz \{reg_list}, stack_adj +cm.popretz {xreg_list}, stack_adj +---- + +[source,sail] +---- +RV32E: +switch (rlist){ + case 4: \{reg_list="ra"; xreg_list="x1";} + case 5: \{reg_list="ra, s0"; xreg_list="x1, x8";} + case 6: \{reg_list="ra, s0-s1"; xreg_list="x1, x8-x9";} + default: reserved(); +} +stack_adj = stack_adj_base + spimm * 16; +---- + +[source,sail] +---- +RV32I, RV64: + +switch (rlist){ + case 4: \{reg_list="ra"; xreg_list="x1";} + case 5: \{reg_list="ra, s0"; xreg_list="x1, x8";} + case 6: \{reg_list="ra, s0-s1"; xreg_list="x1, x8-x9";} + case 7: \{reg_list="ra, s0-s2"; xreg_list="x1, x8-x9, x18";} + case 8: \{reg_list="ra, s0-s3"; xreg_list="x1, x8-x9, x18-x19";} + case 9: \{reg_list="ra, s0-s4"; xreg_list="x1, x8-x9, x18-x20";} + case 10: \{reg_list="ra, s0-s5"; xreg_list="x1, x8-x9, x18-x21";} + case 11: \{reg_list="ra, s0-s6"; xreg_list="x1, x8-x9, x18-x22";} + case 12: \{reg_list="ra, s0-s7"; xreg_list="x1, x8-x9, x18-x23";} + case 13: \{reg_list="ra, s0-s8"; xreg_list="x1, x8-x9, x18-x24";} + case 14: \{reg_list="ra, s0-s9"; xreg_list="x1, x8-x9, x18-x25";} + //note - to include s10, s11 must also be included + case 15: \{reg_list="ra, s0-s11"; xreg_list="x1, x8-x9, x18-x27";} + default: reserved(); +} +stack_adj = stack_adj_base + spimm * 16; +---- + +[source,sail] +---- +RV32E: + +stack_adj_base = 16; +Valid values: +stack_adj = [16|32|48|64]; +---- + +[source,sail] +---- +RV32I: + +switch (rlist) { + case 4.. 7: stack_adj_base = 16; + case 8..11: stack_adj_base = 32; + case 12..14: stack_adj_base = 48; + case 15: stack_adj_base = 64; +} + +Valid values: +switch (rlist) { + case 4.. 7: stack_adj = [16|32|48| 64]; + case 8..11: stack_adj = [32|48|64| 80]; + case 12..14: stack_adj = [48|64|80| 96]; + case 15: stack_adj = [64|80|96|112]; +} +---- + +[source,sail] +---- +RV64: + +switch (rlist) { + case 4.. 5: stack_adj_base = 16; + case 6.. 7: stack_adj_base = 32; + case 8.. 9: stack_adj_base = 48; + case 10..11: stack_adj_base = 64; + case 12..13: stack_adj_base = 80; + case 14: stack_adj_base = 96; + case 15: stack_adj_base = 112; +} + +Valid values: +switch (rlist) { + case 4.. 5: stack_adj = [ 16| 32| 48| 64]; + case 6.. 7: stack_adj = [ 32| 48| 64| 80]; + case 8.. 9: stack_adj = [ 48| 64| 80| 96]; + case 10..11: stack_adj = [ 64| 80| 96|112]; + case 12..13: stack_adj = [ 80| 96|112|128]; + case 14: stack_adj = [ 96|112|128|144]; + case 15: stack_adj = [112|128|144|160]; +} +---- + +<<< + +Description:: + +This instruction [#norm:cm-popretz_op]#pops (loads) the registers in _reg_list_ from stack memory, adjusts the stack pointer by _stack_adj_, moves zero into a0 and then returns to _ra_.# + +[NOTE] +==== +All ABI register mappings are for the UABI. An EABI version is planned once the EABI is frozen. +==== + +For further information see <>. + +Stack Adjustment Calculation: + +_stack_adj_base_ is the minimum number of bytes, in multiples of 16-byte address increments, required to cover the registers in the list. + +_spimm_ is the number of additional 16-byte address increments allocated for the stack frame. + +The total stack adjustment represents the total size of the stack frame, which is _stack_adj_base_ added to _spimm_ scaled by 16, as defined above. + +Prerequisites:: + +None + +32-bit equivalent: + +No direct equivalent encoding exists + + +Operation:: + +The first section of pseudocode may be executed multiple times before the instruction successfully completes. + +[source,sail] +---- +//This is not SAIL, it's pseudocode. The SAIL hasn't been written yet. + +if (XLEN==32) bytes=4; else bytes=8; + +addr=sp+stack_adj-bytes; +for(i in 27,26,25,24,23,22,21,20,19,18,9,8,1) { + //if register i is in xreg_list + if (xreg_list[i]) { + switch(bytes) { + 4: asm("lw x[i], 0(addr)"); + 8: asm("ld x[i], 0(addr)"); + } + addr-=bytes; + } +} +---- + +The final section of pseudocode executes atomically, and only executes if the section above completes without any exceptions or interrupts. + +[NOTE] +==== +The _li a0, 0_ *could* be executed more than once, but is included in the atomic section for convenience. +==== + +[source,sail] +---- +//This is not SAIL, it's pseudocode. The SAIL hasn't been written yet. + +asm("li a0, 0"); +sp+=stack_adj; +asm("ret"); +---- + +<<< +[#insns-cm_popret,reftext="cm.popret"] +==== cm.popret + +Synopsis:: + +Destroy stack frame: load ra and 0 to 12 saved registers from the stack frame, deallocate the stack frame, return to ra. + +Mnemonic:: + +cm.popret _\{reg_list}, stack_adj_ + +Encoding (RV32, RV64): + +[wavedrom, , svg] +.... +{reg:[ + { bits: 2, name: 0x2, attr: ['C2'] }, + { bits: 2, name: 'spimm', attr: [] }, + { bits: 4, name: 'rlist', attr: [] }, + { bits: 5, name: 0x1e, attr: [] }, + { bits: 3, name: 0x5, attr: ['FUNCT3'] }, +],config:{bits:16}} +.... + +[NOTE] +==== +_rlist_ values 0 to 3 are reserved for a future EABI variant called _cm.popret.e_ +==== + +Assembly Syntax: + +[source,sail] +---- +cm.popret \{reg_list}, stack_adj +cm.popret {xreg_list}, stack_adj +---- + +The variables used in the assembly syntax are defined below. + +[source,sail] +---- +RV32E: + +switch (rlist){ + case 4: \{reg_list="ra"; xreg_list="x1";} + case 5: \{reg_list="ra, s0"; xreg_list="x1, x8";} + case 6: \{reg_list="ra, s0-s1"; xreg_list="x1, x8-x9";} + default: reserved(); +} +stack_adj = stack_adj_base + spimm * 16; +---- + +[source,sail] +---- +RV32I, RV64: + +switch (rlist){ + case 4: \{reg_list="ra"; xreg_list="x1";} + case 5: \{reg_list="ra, s0"; xreg_list="x1, x8";} + case 6: \{reg_list="ra, s0-s1"; xreg_list="x1, x8-x9";} + case 7: \{reg_list="ra, s0-s2"; xreg_list="x1, x8-x9, x18";} + case 8: \{reg_list="ra, s0-s3"; xreg_list="x1, x8-x9, x18-x19";} + case 9: \{reg_list="ra, s0-s4"; xreg_list="x1, x8-x9, x18-x20";} + case 10: \{reg_list="ra, s0-s5"; xreg_list="x1, x8-x9, x18-x21";} + case 11: \{reg_list="ra, s0-s6"; xreg_list="x1, x8-x9, x18-x22";} + case 12: \{reg_list="ra, s0-s7"; xreg_list="x1, x8-x9, x18-x23";} + case 13: \{reg_list="ra, s0-s8"; xreg_list="x1, x8-x9, x18-x24";} + case 14: \{reg_list="ra, s0-s9"; xreg_list="x1, x8-x9, x18-x25";} + //note - to include s10, s11 must also be included + case 15: \{reg_list="ra, s0-s11"; xreg_list="x1, x8-x9, x18-x27";} + default: reserved(); +} +stack_adj = stack_adj_base + spimm * 16; +---- + +[source,sail] +---- +RV32E: + +stack_adj_base = 16; +Valid values: +stack_adj = [16|32|48|64]; +---- + +[source,sail] +---- +RV32I: + +switch (rlist) { + case 4.. 7: stack_adj_base = 16; + case 8..11: stack_adj_base = 32; + case 12..14: stack_adj_base = 48; + case 15: stack_adj_base = 64; +} + +Valid values: +switch (rlist) { + case 4.. 7: stack_adj = [16|32|48| 64]; + case 8..11: stack_adj = [32|48|64| 80]; + case 12..14: stack_adj = [48|64|80| 96]; + case 15: stack_adj = [64|80|96|112]; +} +---- + +[source,sail] +---- +RV64: + +switch (rlist) { + case 4.. 5: stack_adj_base = 16; + case 6.. 7: stack_adj_base = 32; + case 8.. 9: stack_adj_base = 48; + case 10..11: stack_adj_base = 64; + case 12..13: stack_adj_base = 80; + case 14: stack_adj_base = 96; + case 15: stack_adj_base = 112; +} + +Valid values: +switch (rlist) { + case 4.. 5: stack_adj = [ 16| 32| 48| 64]; + case 6.. 7: stack_adj = [ 32| 48| 64| 80]; + case 8.. 9: stack_adj = [ 48| 64| 80| 96]; + case 10..11: stack_adj = [ 64| 80| 96|112]; + case 12..13: stack_adj = [ 80| 96|112|128]; + case 14: stack_adj = [ 96|112|128|144]; + case 15: stack_adj = [112|128|144|160]; +} +---- + +<<< + +Description:: + +This instruction [#norm:cm-popret_op]#pops (loads) the registers in _reg_list_ from stack memory, adjusts the stack pointer by _stack_adj_ and then returns to _ra_.# + +[NOTE] +==== +All ABI register mappings are for the UABI. An EABI version is planned once the EABI is frozen. +==== + +For further information see <>. + +Stack Adjustment Calculation: + +_stack_adj_base_ is the minimum number of bytes, in multiples of 16-byte address increments, required to cover the registers in the list. + +_spimm_ is the number of additional 16-byte address increments allocated for the stack frame. + +The total stack adjustment represents the total size of the stack frame, which is _stack_adj_base_ added to _spimm_ scaled by 16, as defined above. + +Prerequisites:: + +None + +32-bit equivalent: + +No direct equivalent encoding exists + +Operation:: + +The first section of pseudocode may be executed multiple times before the instruction successfully completes. + +[source,sail] +---- +//This is not SAIL, it's pseudocode. The SAIL hasn't been written yet. + +if (XLEN==32) bytes=4; else bytes=8; + +addr=sp+stack_adj-bytes; +for(i in 27,26,25,24,23,22,21,20,19,18,9,8,1) { + //if register i is in xreg_list + if (xreg_list[i]) { + switch(bytes) { + 4: asm("lw x[i], 0(addr)"); + 8: asm("ld x[i], 0(addr)"); + } + addr-=bytes; + } +} +---- + +The final section of pseudocode executes atomically, and only executes if the section above completes without any exceptions or interrupts. + +[source,sail] +---- +//This is not SAIL, it's pseudocode. The SAIL hasn't been written yet. + +sp+=stack_adj; +asm("ret"); +---- + +<<< + +[#insns-cm_mvsa01,reftext="Move a0-a1 into two different s0-s7 registers"] +==== cm.mvsa01 + +Synopsis:: + +Move a0-a1 into two registers of s0-s7 + +Mnemonic:: + +cm.mvsa01 _r1s'_, _r2s'_ + +Encoding (RV32, RV64): + +[wavedrom, , svg] +.... +{reg:[ + { bits: 2, name: 0x2, attr: ['C2'] }, + { bits: 3, name: 'r2s\'', attr: [] }, + { bits: 2, name: 0x1, attr: [] }, + { bits: 3, name: 'r1s\'', attr: [] }, + { bits: 3, name: 0x3, attr: [] }, + { bits: 3, name: 0x5, attr: ['FUNCT3'] }, +],config:{bits:16}} +.... + +[NOTE] +==== +[#norm:cm-mvsa01_res]#For the encoding to be legal _r1s'_ != _r2s'_.# +==== + +Assembly Syntax: + +[source,asm] +---- +cm.mvsa01 r1s', r2s' +---- + +Description:: +This instruction [#norm:cm-mvsa01_op]#moves _a0_ into _r1s'_ and _a1_ into _r2s'_. _r1s'_ and _r2s'_ must be different.# +The execution is atomic, so it is not possible to observe state where only one of _r1s'_ or _r2s'_ has been updated. + +[#norm:cm-mvsa01_sreg]#The encoding uses _sreg_ number specifiers instead of _xreg_ number specifiers to save encoding space.# +The mapping between them is specified in the pseudocode below. + +[NOTE] +==== +The _s_ register mapping is taken from the UABI, and may not match the currently unratified EABI. _cm.mvsa01.e_ may be included in the future. +==== + +Prerequisites:: + +None + +32-bit equivalent: + +No direct equivalent encoding exists. + +Operation:: + +[source,sail] +---- +//This is not SAIL, it's pseudocode. The SAIL hasn't been written yet. +if (RV32E && (r1sc>1 || r2sc>1)) { + reserved(); +} +xreg1 = {r1sc[2:1]>0,r1sc[2:1]==0,r1sc[2:0]}; +xreg2 = {r2sc[2:1]>0,r2sc[2:1]==0,r2sc[2:0]}; +X[xreg1] = X[10]; +X[xreg2] = X[11]; +---- + +<<< + +[#insns-cm_mva01s,reftext="Move two s0-s7 registers into a0-a1"] +==== cm.mva01s + +Synopsis:: + +Move two s0-s7 registers into a0-a1 + +Mnemonic:: + +cm.mva01s _r1s'_, _r2s'_ + +Encoding (RV32, RV64): + +[wavedrom, , svg] +.... +{reg:[ + { bits: 2, name: 0x2, attr: ['C2'] }, + { bits: 3, name: 'r2s\'', attr: [] }, + { bits: 2, name: 0x3, attr: [] }, + { bits: 3, name: 'r1s\'', attr: [] }, + { bits: 3, name: 0x3, attr: [] }, + { bits: 3, name: 0x5, attr: ['FUNCT3'] }, +],config:{bits:16}} +.... + +Assembly Syntax: + +[source,asm] +---- +cm.mva01s r1s', r2s' +---- + +Description:: +This instruction [#norm:cm-mva01s_op]#moves _r1s'_ into _a0_ and _r2s'_ into _a1_.# +The execution is atomic, so it is not possible to observe state where only one of _a0_ or _a1_ have been updated. + +[#norm:cm-mva01s_sreg]#The encoding uses _sreg_ number specifiers instead of _xreg_ number specifiers to save encoding space.# +The mapping between them is specified in the pseudocode below. + +[NOTE] +==== +The _s_ register mapping is taken from the UABI, and may not match the currently unratified EABI. _cm.mva01s.e_ may be included in the future. +==== + +Prerequisites:: + +None + +32-bit equivalent: + +No direct equivalent encoding exists. + +Operation:: + +[source,sail] +---- +//This is not SAIL, it's pseudocode. The SAIL hasn't been written yet. +if (RV32E && (r1sc>1 || r2sc>1)) { + reserved(); +} +xreg1 = {r1sc[2:1]>0,r1sc[2:1]==0,r1sc[2:0]}; +xreg2 = {r2sc[2:1]>0,r2sc[2:1]==0,r2sc[2:0]}; +X[10] = X[xreg1]; +X[11] = X[xreg2]; +---- + +<<< + +[#insns-tablejump,reftext="Table Jump Overview"] +=== Table Jump Overview + +_cm.jt_ (<<#insns-cm_jt>>) and _cm.jalt_ (<<#insns-cm_jalt>>) are referred to as table jump. + +[#norm:Zcmt_table]#Table jump uses a 256-entry XLEN wide table in instruction memory to contain function addresses. +The table must be a minimum of 64-byte aligned.# + +[#norm:Zcmt_endian]#Table entries follow the current data endianness. This is different from normal instruction fetch which is always little-endian.# + +_cm.jt_ and _cm.jalt_ encodings index the table, giving access to functions within the full XLEN wide address space. + +This is used as a form of dictionary compression to reduce the code size of _jal_ / _auipc+jalr_ / _jr_ / _auipc+jr_ instructions. + +Table jump allows the linker to replace the following instruction sequences with a _cm.jt_ or _cm.jalt_ encoding, and an entry in the table: + +* 32-bit _j_ calls +* 32-bit _jal_ ra calls +* 64-bit _auipc+jr_ calls to fixed locations +* 64-bit _auipc+jalr ra_ calls to fixed locations +** The _auipc+jr/jalr_ sequence is used because the offset from the PC is out of the ±1{nbsp}MB range. + +If a return address stack is implemented, then as _cm.jalt_ is equivalent to _jal ra_, it pushes to the stack. + +==== jvt + +[#norm:Zcmt_entry_sz]#The base of the table is in the jvt CSR (see <>), each table entry is XLEN bits.# + +If the same function is called with and without linking then it must have two entries in the table. +This is typically caused by the same function being called with and without tail calling. + +[#tablejump-fault-handling] +==== Table Jump Fault handling + +[#norm:Zcmt_fetch]#For a table jump instruction, the table entry that the instruction selects is considered an extension of the instruction itself. +Hence, the execution of a table jump instruction involves two instruction fetches, the first to read the instruction (_cm.jt_/_cm.jalt_) +and the second to read from the jump vector table (JVT). Both instruction fetches are _implicit_ reads, and both require +execute permission; read permission is irrelevant. It is recommended that the second fetch be ignored for hardware triggers and breakpoints.# + +Memory writes to the jump vector table require an instruction barrier (_fence.i_) to guarantee that they are visible to the instruction fetch. + +Multiple contexts may have different jump vector tables. JVT may be switched between them without an instruction barrier +if the tables have not been updated in memory since the last _fence.i_. + +[#norm:Zcmt_trap]#If an exception occurs on either instruction fetch, xEPC is set to the PC of the table jump instruction, xCAUSE is set as expected for the type of fault and xTVAL (if not set to zero) contains the fetch address which caused the fault.# + +<<< +[#csrs-jvt,reftext="jvt CSR, table jump base vector and control register"] +==== jvt CSR + +Synopsis:: + +Table jump base vector and control register + +Address: + +0x017 + +Permissions: + +URW + +Format (RV32): + +[wavedrom, , svg] +.... +{reg:[ + { bits: 6, name: 'mode', attr: ['6'] }, + { bits: 26, name: 'base[XLEN-1:6] (WARL)', attr: ['XLEN-6'] }, +],config:{bits:32}} +.... + +Format (RV64): + +[wavedrom, , svg] +.... +{reg:[ + { bits: 6, name: 'mode', attr: ['6'] }, + { bits: 58, name: 'base[XLEN-1:6] (WARL)', attr: ['XLEN-6'] }, +],config:{bits:64}} +.... + +Description:: + +[#norm:jvt_reg]#The _jvt_ register is an XLEN-bit *WARL* read/write register that holds the jump table configuration, consisting of the jump table base address (BASE) and the jump table mode (MODE).# + +[#norm:jvt_op]#If <> is implemented then _jvt_ must also be implemented, but can contain a read-only value. If _jvt_ is writable, the set of values the register may hold can vary by implementation. The value in the BASE field must always be aligned on a 64-byte boundary. +Note that the CSR contains only bits XLEN-1 through 6 of the address _base_. When computing jump-table accesses, the lower six bits of _base_ are filled with zeroes to obtain an XLEN-bit jump-table base address _jvt.base_ that is always aligned on a 64-byte boundary.# + +[#norm:jvt_base_vm]#_jvt.base_ is a virtual address, whenever virtual memory is enabled.# + +The memory pointed to by _jvt.base_ is treated as instruction memory for the purpose of executing table jump instructions, implying execute access permission. + +[#JVT-config-table] +._jvt.mode_ definition +[width="60%",options=header] +|============================================================================================= +| jvt.mode | Comment +| 000000 | Jump table mode +| others | *reserved for future standard use* +|============================================================================================= + +[#norm:jvt_mode_acc]#_jvt.mode_ is a *WARL* field, so can only be programmed to modes which are implemented.# Therefore the discovery mechanism is to +attempt to program different modes and read back the values to see which are available. Jump table mode _must_ be implemented. + +[NOTE] +==== +in future the RISC-V Unified Discovery method will report the available modes. +==== + +Architectural State: + +_jvt_ CSR adds architectural state to the system software context (such as an OS process), therefore must be saved/restored on context switches. + +State Enable: + +[#norm:jvt_en]#If the Smstateen extension is implemented, then bit 2 in _mstateen0_, _sstateen0_, and _hstateen0_ is implemented. If bit 2 of a controlling _stateen0_ CSR is zero, then access to the _jvt_ CSR and execution of a _cm.jalt_ or _cm.jt_ instruction by a lower privilege level results in an illegal-instruction trap (or, if appropriate, a virtual-instruction trap).# + +<<< +[#insns-cm_jt,reftext="Jump via table"] +==== cm.jt + +Synopsis:: + +jump via table + +Mnemonic:: + +cm.jt _index_ + +Encoding (RV32, RV64): + +[wavedrom, , svg] +.... +{reg:[ + { bits: 2, name: 0x2, attr: ['C2'] }, + { bits: 8, name: 'index', attr: [] }, + { bits: 3, name: 0x0, attr: [] }, + { bits: 3, name: 0x5, attr: ['FUNCT3'] }, +],config:{bits:16}} +.... + +[NOTE] +==== +For this encoding to decode as _cm.jt_, _index<32_, otherwise it decodes as _cm.jalt_, see <>. +==== + +[NOTE] +==== +If jvt.mode = 0 (Jump Table Mode) then _cm.jt_ behaves as specified here. If jvt.mode is a reserved value, then _cm.jt_ is also reserved. In the future other defined values of jvt.mode may change the behaviour of _cm.jt_. +==== + +Assembly Syntax: + +[source,asm] +---- +cm.jt index +---- + +Description:: + +[#norm:cm-jt_op]#_cm.jt_ reads an entry from the jump vector table in memory and jumps to the address that was read.# + +For further information see <>. + +Prerequisites:: + +None + +32-bit equivalent: + +No direct equivalent encoding exists. + +<<< + +[#insns-cm_jt-SAIL,reftext="cm.jt SAIL code"] +Operation:: + +[source,sail] +---- +//This is not SAIL, it's pseudocode. The SAIL hasn't been written yet. + +# table_address is temporary internal state, it doesn't represent a real register +# InstMemory is byte indexed + +switch(XLEN) { + 32: table_address[XLEN-1:0] = jvt.base + (index<<2); + 64: table_address[XLEN-1:0] = jvt.base + (index<<3); +} + +//fetch from the jump table +pc = InstMemory[table_address][XLEN-1:0]&~0x1; // Clear bit 0. + +---- + +<<< +[#insns-cm_jalt,reftext="Jump and link via table"] +==== cm.jalt + +Synopsis:: + +jump via table with optional link + +Mnemonic:: + +cm.jalt _index_ + +Encoding (RV32, RV64): + +[wavedrom, , svg] +.... +{reg:[ + { bits: 2, name: 0x2, attr: ['C2'] }, + { bits: 8, name: 'index', attr: [] }, + { bits: 3, name: 0x0, attr: [] }, + { bits: 3, name: 0x5, attr: ['FUNCT3'] }, +],config:{bits:16}} +.... + +[NOTE] +==== +For this encoding to decode as _cm.jalt_, _index>=32_, otherwise it decodes as _cm.jt_, see <>. +==== + +[NOTE] +==== +If jvt.mode = 0 (Jump Table Mode) then _cm.jalt_ behaves as specified here. If jvt.mode is a reserved value, then _cm.jalt_ is also reserved. In the future other defined values of jvt.mode may change the behaviour of _cm.jalt_. +==== + +Assembly Syntax: + +[source,asm] +---- +cm.jalt index +---- + +Description:: + +[#norm:cm-jalt_op]#_cm.jalt_ reads an entry from the jump vector table in memory and jumps to the address that was read, linking to _ra_.# + +For further information see <>. + +Prerequisites:: + +None + +32-bit equivalent: + +No direct equivalent encoding exists. + +<<< + +[#insns-cm_jalt-SAIL,reftext="cm.jalt SAIL code"] +Operation:: + +[source,sail] +---- +//This is not SAIL, it's pseudocode. The SAIL hasn't been written yet. + +# table_address is temporary internal state, it doesn't represent a real register +# InstMemory is byte indexed + +switch(XLEN) { + 32: table_address[XLEN-1:0] = jvt.base + (index<<2); + 64: table_address[XLEN-1:0] = jvt.base + (index<<3); +} + +//fetch from the jump table + +ra = pc+2; +pc = InstMemory[table_address][XLEN-1:0]&~0x1; // Clear bit 0. + +---- diff --git a/param_extraction/chunks/chunk_066.txt.license b/param_extraction/chunks/chunk_066.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_066.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_067.txt b/param_extraction/chunks/chunk_067.txt new file mode 100644 index 0000000000..81747b3ee6 --- /dev/null +++ b/param_extraction/chunks/chunk_067.txt @@ -0,0 +1,275 @@ +# Chunk: chunk_067 +# Source: zfa.adoc +# Lines: 1-261 (of 261) +# Content starts: line 1 +# Line count: 261 +# Sections: 7 +# == "Zfa" Extension for Additional Floating-Point Instructions, Version 1.0 +# === Load-Immediate Instructions +# === Minimum and Maximum Instructions +# === Round-to-Integer Instructions +# === Modular Convert-to-Integer Instruction +# === Move Instructions +# === Comparison Instructions +# +[[zfa]] +== "Zfa" Extension for Additional Floating-Point Instructions, Version 1.0 + +This chapter describes the Zfa standard extension, which adds +instructions for immediate loads, IEEE 754-2019 minimum and maximum +operations, round-to-integer operations, and quiet floating-point +comparisons. For RV32D, the Zfa extension also adds instructions to +transfer double-precision floating-point values to and from integer +registers, and for RV64Q, it adds analogous instructions for +quad-precision floating-point values. The Zfa extension depends on the F +extension. + +=== Load-Immediate Instructions + +[[norm:fli-s_op]] +The FLI.S instruction loads one of 32 single-precision floating-point +constants, encoded in the _rs1_ field, into floating-point register +_rd_. The correspondence of _rs1_ field values and single-precision +floating-point values is shown in <>. FLI.S is encoded +like FMV.W.X, but with _rs2_=1. + +[[tab:flis]] +.Immediate values loaded by the FLI.S instruction. +[%autowidth,float="center",align="center",cols=">,>,^,^,^",options="header",] +|=== +|_rs1_ |Value |Sign |Exponent |Significand +|0 |−1.0 |`1` |`01111111` |`000...000` +|1 |_Minimum positive normal_ |`0` |`00000001` |`000...000` +|2 |1.0 × 2^−16^ |`0` |`01101111` |`000...000` +|3 |1.0 × 2^−15^ |`0` |`01110000` |`000...000` +|4 |1.0 × 2^−8^ |`0` |`01110111` |`000...000` +|5 |1.0 × 2^−7^ |`0` |`01111000` |`000...000` +|6 |0.0625 (2^−4^) |`0` |`01111011` |`000...000` +|7 |0.125 (2^−3^) |`0` |`01111100` |`000...000` +|8 |0.25 |`0` |`01111101` |`000...000` +|9 |0.3125 |`0` |`01111101` |`010...000` +|10 |0.375 |`0` |`01111101` |`100...000` +|11 |0.4375 |`0` |`01111101` |`110...000` +|12 |0.5 |`0` |`01111110` |`000...000` +|13 |0.625 |`0` |`01111110` |`010...000` +|14 |0.75 |`0` |`01111110` |`100...000` +|15 |0.875 |`0` |`01111110` |`110...000` +|16 |1.0 |`0` |`01111111` |`000...000` +|17 |1.25 |`0` |`01111111` |`010...000` +|18 |1.5 |`0` |`01111111` |`100...000` +|19 |1.75 |`0` |`01111111` |`110...000` +|20 |2.0 |`0` |`10000000` |`000...000` +|21 |2.5 |`0` |`10000000` |`010...000` +|22 |3 |`0` |`10000000` |`100...000` +|23 |4 |`0` |`10000001` |`000...000` +|24 |8 |`0` |`10000010` |`000...000` +|25 |16 |`0` |`10000011` |`000...000` +|26 |128 (2^7^) |`0` |`10000110` |`000...000` +|27 |256 (2^8^) |`0` |`10000111` |`000...000` +|28 |2^15^ |`0` |`10001110` |`000...000` +|29 |2^16^ |`0` |`10001111` |`000...000` +|30 |+{inf} |`0` |`11111111` |`000...000` +|31 |_Canonical NaN_ |`0` |`11111111` |`100...000` +|=== + +[NOTE] +==== +The preferred assembly syntax for entries 1, 30, and 31 is `min`, `inf`, +and `nan`, respectively. For entries 0 through 29 (including entry 1), +the assembler will accept decimal constants in C-like syntax. +==== +[NOTE] +==== +The set of 32 constants was chosen by examining floating-point +libraries, including the C standard math library, and to optimize +fixed-point to floating-point conversion. + +Entries 8-22 follow a regular encoding pattern. No entry sets mantissa +bits other than the two most significant ones. +==== + +[[norm:fli-d_op]] +If the D extension is implemented, FLI.D performs the analogous +operation, but loads a double-precision value into floating-point +register _rd_. Note that entry 1 (corresponding to the minimum positive +normal value) has a numerically different value for double-precision +than for single-precision. FLI.D is encoded like FLI.S, but with +_fmt_=D. + +[[norm:fli-q_op]] +If the Q extension is implemented, FLI.Q performs the analogous +operation, but loads a quad-precision value into floating-point register +_rd_. Note that entry 1 (corresponding to the minimum positive normal +value) has a numerically different value for quad-precision. FLI.Q is +encoded like FLI.S, but with _fmt_=Q. + +[[norm:fli-h_op]] +If the Zfh or Zvfh extension is implemented, FLI.H performs the +analogous operation, but loads a half-precision floating-point value +into register _rd_. Note that entry 1 (corresponding to the minimum +positive normal value) has a numerically different value for +half-precision. Furthermore, since 2^16^ is not +representable in half-precision floating-point, entry 29 in the table +instead loads positive infinity—i.e., it is redundant with entry 30. +FLI.H is encoded like FLI.S, but with _fmt_=H. +[NOTE] +==== +Additionally, since 2^−16^ and 2^−15^ are subnormal in half-precision, entry 1 is numerically greater than entries 2 and 3 for FLI.H. +==== +The FLI._fmt_ instructions never set any floating-point exception flags. + +=== Minimum and Maximum Instructions + +[[norm:fmaxm-s_fminm-s_op]] +The FMINM.S and FMAXM.S instructions are defined like the FMIN.S and +FMAX.S instructions, except that if either input is NaN, the result is +the canonical NaN. + +[[norm:fmaxm-d_fminm-d_op]] +If the D extension is implemented, FMINM.D and FMAXM.D instructions are +analogously defined to operate on double-precision numbers. + +[[norm:fmaxm-h_fminm-h_op]] +If the Zfh extension is implemented, FMINM.H and FMAXM.H instructions +are analogously defined to operate on half-precision numbers. + +[[norm:fmaxm-q_fminm-q_op]] +If the Q extension is implemented, FMINM.Q and FMAXM.Q instructions are +analogously defined to operate on quad-precision numbers. + +These instructions are encoded like their FMIN and FMAX counterparts, +but with instruction bit 13 set to 1. +[NOTE] +==== +These instructions implement the IEEE 754-2019 minimum and maximum +operations. +==== +=== Round-to-Integer Instructions + +[#norm:fround-s_op]#The FROUND.S instruction rounds the single-precision floating-point +number in floating-point register _rs1_ to an integer, according to the +rounding mode specified in the instruction's _rm_ field. It then writes +that integer, represented as a single-precision floating-point number, +to floating-point register _rd_#. [#norm:fround-s_zero_inf]#Zero and infinite inputs are copied to +_rd_ unmodified#. [#norm:fround-s_nan_nv]#Signaling NaN inputs cause the invalid operation +exception flag to be set; no other exception flags are set#. FROUND.S is +encoded like FCVT.S.D, but with _rs2_=4. + +[[norm:froundnx-s_op]] +The FROUNDNX.S instruction is defined similarly, but it also sets the +inexact exception flag if the input differs from the rounded result and +is not NaN. FROUNDNX.S is encoded like FCVT.S.D, but with _rs2_=5. + +[[norm:fround-d_froundnx-d_op]] +If the D extension is implemented, FROUND.D and FROUNDNX.D instructions +are analogously defined to operate on double-precision numbers. They are +encoded like FCVT.D.S, but with _rs2_=4 and 5, respectively, + +[[norm:fround-h_froundnx-h_op]] +If the Zfh extension is implemented, FROUND.H and FROUNDNX.H +instructions are analogously defined to operate on half-precision +numbers. They are encoded like FCVT.H.S, but with _rs2_=4 and 5, +respectively, + +[[norm:fround-q_froundnx-q_op]] +If the Q extension is implemented, FROUND.Q and FROUNDNX.Q instructions +are analogously defined to operate on quad-precision numbers. They are +encoded like FCVT.Q.S, but with _rs2_=4 and 5, respectively, +[NOTE] +==== +The FROUNDNX._fmt_ instructions implement the IEEE 754-2019 +roundToIntegralExact operation, and the FROUND._fmt_ instructions +implement the other operations in the roundToIntegral family. +==== +=== Modular Convert-to-Integer Instruction + +[[norm:fcvtmod-w-d_op]] +The FCVTMOD.W.D instruction is defined similarly to the FCVT.W.D +instruction, with the following differences. FCVTMOD.W.D always rounds +towards zero. Bits 31:0 are taken from the rounded, unbounded two's +complement result, then sign-extended to XLEN bits and written to +integer register _rd_. ±{inf} and NaN are converted to +zero. + +[[norm:fcvtmod-w-d_flags]] +Floating-point exception flags are raised the same as they would be for +FCVT.W.D with the same input operand. + +This instruction is only provided if the D extension is implemented. [#norm:fcvtmod-w-d_rsw]#It +is encoded like FCVT.W.D, but with the rs2 field set to 8 and the _rm_ +field set to 1 (RTZ). Other _rm_ values are _reserved_.# +[NOTE] +==== +The assembly syntax requires the RTZ rounding mode to be explicitly +specified, i.e., `fcvtmod.w.d rd, rs1, rtz`. + +The FCVTMOD.W.D instruction was added principally to accelerate the +processing of JavaScript Numbers. Numbers are double-precision +values, but some operators implicitly truncate them to signed integers +mod 2^32^. +==== +=== Move Instructions + +[[norm:fmvh-x-d_op]] +For RV32 only, if the D extension is implemented, the FMVH.X.D +instruction moves bits 63:32 of floating-point register _rs1_ into +integer register _rd_. It is encoded in the OP-FP major opcode with +_funct3_=0, _rs2_=1, and _funct7_=1110001. +[NOTE] +==== +FMVH.X.D is used in conjunction with the existing FMV.X.W instruction to +move a double-precision floating-point number to a pair of x-registers. +==== +[[norm:fmvp-d-x_op]] +For RV32 only, if the D extension is implemented, the FMVP.D.X +instruction moves a double-precision number from a pair of integer +registers into a floating-point register. Integer registers _rs1_ and +_rs2_ supply bits 31:0 and 63:32, respectively; the result is written to +floating-point register _rd_. FMVP.D.X is encoded in the OP-FP major +opcode with _funct3_=0 and _funct7_=1011001. + +[[norm:fmvh-x-q_op]] +For RV64 only, if the Q extension is implemented, the FMVH.X.Q +instruction moves bits 127:64 of floating-point register _rs1_ into +integer register _rd_. It is encoded in the OP-FP major opcode with +_funct3_=0, _rs2_=1, and _funct7_=1110011. +[NOTE] +==== +FMVH.X.Q is used in conjunction with the existing FMV.X.D instruction to +move a quad-precision floating-point number to a pair of x-registers. +==== +[[norm:fmvp-q-x_op]] +For RV64 only, if the Q extension is implemented, the FMVP.Q.X +instruction moves a double-precision number from a pair of integer +registers into a floating-point register. Integer registers _rs1_ and +_rs2_ supply bits 63:0 and 127:64, respectively; the result is written +to floating-point register _rd_. FMVP.Q.X is encoded in the OP-FP major +opcode with _funct3_=0 and _funct7_=1011011. + +=== Comparison Instructions + +[[norm:fleq-s_fltq-s_op]] +The FLEQ.S and FLTQ.S instructions are defined like the FLE.S and FLT.S +instructions, except that quiet NaN inputs do not cause the invalid +operation exception flag to be set. + +[[norm:fleq-d_fltq-d_op]] +If the D extension is implemented, FLEQ.D and FLTQ.D instructions are +analogously defined to operate on double-precision numbers. + +[[norm:fleq-h_fltq-h_op]] +If the Zfh extension is implemented, FLEQ.H and FLTQ.H instructions are +analogously defined to operate on half-precision numbers. + +[[norm:fleq-q_fltq-q_op]] +If the Q extension is implemented, FLEQ.Q and FLTQ.Q instructions are +analogously defined to operate on quad-precision numbers. + +These instructions are encoded like their FLE and FLT counterparts, but +with instruction bit 14 set to 1. +[NOTE] +==== +We do not expect analogous comparison instructions will be added to the +vector ISA, since they can be reasonably efficiently emulated using +masking. +==== diff --git a/param_extraction/chunks/chunk_067.txt.license b/param_extraction/chunks/chunk_067.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_067.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_068.txt b/param_extraction/chunks/chunk_068.txt new file mode 100644 index 0000000000..678b0620bf --- /dev/null +++ b/param_extraction/chunks/chunk_068.txt @@ -0,0 +1,200 @@ +# Chunk: chunk_068 +# Source: zfh.adoc +# Lines: 1-186 (of 186) +# Content starts: line 1 +# Line count: 186 +# Sections: 7 +# == "Zfh" and "Zfhmin" Extensions for Half-Precision Floating-Point, Version 1.0 +# === Half-Precision Load and Store Instructions +# === Half-Precision Computational Instructions +# === Half-Precision Conversion and Move Instructions +# === Half-Precision Floating-Point Compare Instructions +# === Half-Precision Floating-Point Classify Instruction +# === "Zfhmin" Standard Extension for Minimal Half-Precision Floating-Point +# +[[chap:zfh]] +== "Zfh" and "Zfhmin" Extensions for Half-Precision Floating-Point, Version 1.0 + +This chapter describes the Zfh standard extension for 16-bit +half-precision binary floating-point instructions compliant with the +IEEE 754-2008 arithmetic standard. The Zfh extension depends on the +single-precision floating-point extension, F. The NaN-boxing scheme +described in <> is extended to allow a +half-precision value to be NaN-boxed inside a single-precision value +(which may be recursively NaN-boxed inside a double- or quad-precision +value when the D or Q extension is present). + +[NOTE] +==== +This extension primarily provides instructions that consume +half-precision operands and produce half-precision results. However, it +is also common to compute on half-precision data using higher +intermediate precision. Although this extension provides explicit +conversion instructions that suffice to implement that pattern, future +extensions might further accelerate such computation with additional +instructions that implicitly widen their operands—e.g., +half{times}half+single->single—or +implicitly narrow their results—e.g., +half+single->half. +==== +=== Half-Precision Load and Store Instructions + +[[norm:fsh_flh_op]] +New 16-bit variants of LOAD-FP and STORE-FP instructions are added, +encoded with a new value for the funct3 width field. + +include::images/wavedrom/sp-load-store.edn[] +[[sp-load-store]] +//.Half-precision load and store instructions + +[[norm:fsh_flh_atomic_align]] +FLH and FSH are only guaranteed to execute atomically if the effective +address is naturally aligned. + +[[norm:fsh_flh_bits_maintained]] +FLH and FSH do not modify the bits being transferred; in particular, the +payloads of non-canonical NaNs are preserved. FLH NaN-boxes the result +written to _rd_, whereas FSH ignores all but the lower 16 bits in _rs2_. + +=== Half-Precision Computational Instructions + +A new supported format is added to the format field of most +instructions, as shown in <>. + +[[tab:fpextfmth]] +.Format field encoding. +[%autowidth,float="center",align="center",cols="^,^,<",options="header",] +|=== +|_fmt_ field |Mnemonic |Meaning +|00 |S |32-bit single-precision +|01 |D |64-bit double-precision +|10 |H |16-bit half-precision +|11 |Q |128-bit quad-precision +|=== + +[[norm:Zfh_computational_instrs]] +The half-precision floating-point computational instructions are defined +analogously to their single-precision counterparts, but operate on +half-precision operands and produce half-precision results. + +include::images/wavedrom/spfloat-zfh.edn[] + +include::images/wavedrom/spfloat2-zfh.edn[] + +=== Half-Precision Conversion and Move Instructions + +New floating-point-to-integer and integer-to-floating-point conversion +instructions are added. These instructions are defined analogously to +the single-precision-to-integer and integer-to-single-precision +conversion instructions. [#norm:fcvt-w-h_fcvt-l-h_op]#FCVT.W.H or FCVT.L.H converts a half-precision +floating-point number to a signed 32-bit or 64-bit integer, +respectively#. [#norm:fcvt-h-w_fcvt-h-l_op]#FCVT.H.W or FCVT.H.L converts a 32-bit or 64-bit signed +integer, respectively, into a half-precision floating-point number#. +[#norm:fcvt-wu-h_fcvt-lu-h_fcvt-h-wu_fcvt-h-lu_op]#FCVT.WU.H, FCVT.LU.H, FCVT.H.WU, and FCVT.H.LU variants convert to or +from unsigned integer values#. [#norm:fcvt_long_half_rv64_only]#FCVT.L[U].H and FCVT.H.L[U] are RV64-only +instructions.# + +include::images/wavedrom/half-prec-conv-and-mv.edn[] +[[half-prec-conv-and-mv]] + +New floating-point-to-floating-point conversion instructions are added. +These instructions are defined analogously to the double-precision +floating-point-to-floating-point conversion instructions. [#norm:fcvt-s-h_fcvt-h-s_op]#FCVT.S.H or +FCVT.H.S converts a half-precision floating-point number to a +single-precision floating-point number, or vice-versa, respectively#. [#norm:fcvt-d-h_fcvt-h-d_op]#If +the D extension is present, FCVT.D.H or FCVT.H.D converts a +half-precision floating-point number to a double-precision +floating-point number, or vice-versa, respectively#. [#norm:fcvt-q-h_fcvt-h-q_op]#If the Q extension +is present, FCVT.Q.H or FCVT.H.Q converts a half-precision +floating-point number to a quad-precision floating-point number, or +vice-versa, respectively#. + +include::images/wavedrom/half-prec-flpt-to-flpt-conv.edn[] +[[half-prec-flpt-to-flpt-conv]] + +[[norm:fsgnj-h_fsgnjn-h_fsgnjx-h_op]] +Floating-point to floating-point sign-injection instructions, FSGNJ.H, +FSGNJN.H, and FSGNJX.H are defined analogously to the single-precision +sign-injection instruction. + +include::images/wavedrom/flt-to-flt-sgn-inj-instr.edn[] +[[flt-to-flt-sgn-inj-instr]] + +Instructions are provided to move bit patterns between the +floating-point and integer registers. [#norm:fmv-x-h_op]#FMV.X.H moves the half-precision +value in floating-point register _rs1_ to a representation in IEEE +754-2008 standard encoding in integer register _rd_, filling the upper +XLEN-16 bits with copies of the floating-point number's sign bit#. + +[[norm:fmv-h-x_op]] +FMV.H.X moves the half-precision value encoded in IEEE 754-2008 standard +encoding from the lower 16 bits of integer register _rs1_ to the +floating-point register _rd_, NaN-boxing the result. + +[[norm:fmv_half_bits_preverved]] +FMV.X.H and FMV.H.X do not modify the bits being transferred; in +particular, the payloads of non-canonical NaNs are preserved. + +include::images/wavedrom/flt-pt-to-int-move.edn[] +[[flt-pt-to-int-move]] + +=== Half-Precision Floating-Point Compare Instructions + +[[norm:Zfh_compare_instrs]] +The half-precision floating-point compare instructions are defined +analogously to their single-precision counterparts, but operate on +half-precision operands. + +include::images/wavedrom/half-pr-flt-pt-compare.edn[] +[[half-pr-flt-pt-compare]] + +=== Half-Precision Floating-Point Classify Instruction + +[[norm:fclass-h_op]] +The half-precision floating-point classify instruction, FCLASS.H, is +defined analogously to its single-precision counterpart, but operates on +half-precision operands. + +include::images/wavedrom/half-pr-flt-pt-class.edn[] +[[half-pr-flt-class]] + +=== "Zfhmin" Standard Extension for Minimal Half-Precision Floating-Point + +This section describes the Zfhmin standard extension, which provides +minimal support for 16-bit half-precision binary floating-point +instructions. The Zfhmin extension is a subset of the Zfh extension, +consisting only of data transfer and conversion instructions. Like Zfh, +the Zfhmin extension depends on the single-precision floating-point +extension, F. The expectation is that Zfhmin software primarily uses the +half-precision format for storage, performing most computation in higher +precision. + +[[norm:zfhmin]] +The Zfhmin extension includes the following instructions from the Zfh +extension: FLH, FSH, FMV.X.H, FMV.H.X, FCVT.S.H, and FCVT.H.S. If the D +extension is present, the FCVT.D.H and FCVT.H.D instructions are also +included. If the Q extension is present, the FCVT.Q.H and FCVT.H.Q +instructions are additionally included. + +[NOTE] +==== +Zfhmin does not include the FSGNJ.H instruction, because it suffices to +instead use the FSGNJ.S instruction to move half-precision values +between floating-point registers. + +Half-precision addition, subtraction, multiplication, division, and +square-root operations can be faithfully emulated by converting the +half-precision operands to single-precision, performing the operation +using single-precision arithmetic, then converting back to +half-precision. cite:[roux:hal-01091186] Performing half-precision fused multiply-addition using +this method incurs a 1-ulp error on some inputs for the RNE and RMM +rounding modes. + +Conversion from 8- or 16-bit integers to half-precision can be emulated +by first converting to single-precision, then converting to +half-precision. Conversion from 32-bit integer can be emulated by first +converting to double-precision. If the D extension is not present and a +1-ulp error under RNE or RMM is tolerable, 32-bit integers can be first +converted to single-precision instead. The same remark applies to +conversions from 64-bit integers without the Q extension. +==== diff --git a/param_extraction/chunks/chunk_068.txt.license b/param_extraction/chunks/chunk_068.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_068.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_069.txt b/param_extraction/chunks/chunk_069.txt new file mode 100644 index 0000000000..e6070a2429 --- /dev/null +++ b/param_extraction/chunks/chunk_069.txt @@ -0,0 +1,176 @@ +# Chunk: chunk_069 +# Source: zfinx.adoc +# Lines: 1-162 (of 162) +# Content starts: line 1 +# Line count: 162 +# Sections: 7 +# == "Zfinx", "Zdinx", "Zhinx", "Zhinxmin" Extensions for Floating-Point in Integer Registers, Version 1.0 +# === Processing of Narrower Values +# === Zdinx +# === Processing of Wider Values +# === Zhinx +# === Zhinxmin +# === Privileged Architecture Implications +# +[[sec:zfinx]] +== "Zfinx", "Zdinx", "Zhinx", "Zhinxmin" Extensions for Floating-Point in Integer Registers, Version 1.0 + +This chapter defines the "Zfinx" extension (pronounced "z-f-in-x") +that provides instructions similar to those in the standard +floating-point F extension for single-precision floating-point +instructions but which operate on the `x` registers instead of the `f` +registers. This chapter also defines the "Zdinx", "Zhinx", and +"Zhinxmin" extensions that provide similar instructions for other +floating-point precisions. + +[NOTE] +==== +The F extension uses separate `f` registers for floating-point +computation, to reduce register pressure and simplify the provision of +register-file ports for wide superscalars. However, the additional +architectural state increases the minimal implementation cost. By +eliminating the `f` registers, the Zfinx extension substantially reduces +the cost of simple RISC-V implementations with floating-point +instruction-set support. Zfinx also reduces context-switch cost. + +In general, software that assumes the presence of the F extension is +incompatible with software that assumes the presence of the Zfinx +extension, and vice versa. +==== + +[[norm:Zfinx_F_instrs]] +The Zfinx extension adds all of the instructions that the F extension +adds, _except_ for the transfer instructions FLW, FSW, FMV.W.X, FMV.X.W, +C.FLW[SP], and C.FSW[SP]. + +[NOTE] +==== +Zfinx software uses integer loads and stores to transfer floating-point +values from and to memory. Transfers between registers use either +integer arithmetic or floating-point sign-injection instructions. +==== +[[norm:Zfinx_x_regs]] +The Zfinx variants of these F-extension instructions have the same +semantics, except that whenever such an instruction would have accessed +an `f` register, it instead accesses the `x` register with the same +number. + +The Zfinx extension depends on the "Zicsr" extension for control and status register access. + +=== Processing of Narrower Values +[[norm:Zfinx_narrow_operands]] +Floating-point operands of width _w_ < XLEN bits occupy +bits _w_-1:0 of an `x` register. Floating-point operations on _w_-bit +operands ignore operand bits XLEN-1: _w_. + +[[norm:Zfinx_narrow_result]] +Floating-point operations that produce _w_ < XLEN-bit +results fill bits XLEN-1: _w_ with copies of bit _w_-1 (the sign bit). + +[NOTE] +==== +The NaN-boxing scheme employed in the `f` registers was designed to +efficiently support recoded floating-point formats. Recoding is less +practical for Zfinx, though, since the same registers hold both +floating-point and integer operands. Hence, the need for NaN boxing is +diminished. + +Sign-extending 32-bit floating-point numbers when held in RV64 `x` +registers is compatible with the existing RV64 calling conventions, which leave bits 63-32 undefined when passing a 32-bit floating point value in `x` registers. To keep the architecture more regular, we extend this pattern to 16-bit floating-point numbers in both RV32 and RV64. +==== +=== Zdinx + +The Zdinx extension provides analogous double-precision floating-point +instructions. The Zdinx extension depends upon the Zfinx extension. + +[[norm:Zdinx_D_instrs]] +The Zdinx extension adds all of the instructions that the D extension +adds, _except_ for the transfer instructions FLD, FSD, FMV.D.X, FMV.X.D, +C.FLD[SP], and C.FSD[SP]. + +[[norm:Zdinx_x_regs]] +The Zdinx variants of these D-extension instructions have the same +semantics, except that whenever such an instruction would have accessed +an `f` register, it instead accesses the `x` register with the same +number. + +=== Processing of Wider Values + +[[norm:Zdinx_x_reg_pair]] +Double-precision operands in RV32Zdinx are held in aligned `x`-register +pairs, i.e., register numbers must be even. Use of misaligned +(odd-numbered) registers for double-width floating-point operands is +_reserved_. + +[[norm:Zdinx_endianness]] +Regardless of endianness, the lower-numbered register holds the +low-order bits, and the higher-numbered register holds the high-order +bits: e.g., bits 31:0 of a double-precision operand in RV32Zdinx might +be held in register `x14`, with bits 63:32 of that operand held in +`x15`. + +[[norm:Zdinx_x0_write]] +When a double-width floating-point result is written to `x0`, the entire +write takes no effect: e.g., for RV32Zdinx, writing a double-precision +result to `x0` does not cause `x1` to be written. + +[[norm:Zdinx_x0_read]] +When `x0` is used as a double-width floating-point operand, the entire +operand is zero—i.e., `x1` is not accessed. + +[NOTE] +==== +Load-pair and store-pair instructions are contained in a separate extension +(see Section <>). +In case this is not available, transferring double-precision operands in +RV32Zdinx from or to memory requires two loads or stores. Register moves need +only a single FSGNJ.D instruction, however. +==== +=== Zhinx + +The Zhinx extension provides analogous half-precision floating-point +instructions. The Zhinx extension depends upon the Zfinx extension. + +[[norm:Zhinx_Zfh_instrs]] +The Zhinx extension adds all of the instructions that the Zfh extension +adds, _except_ for the transfer instructions FLH, FSH, FMV.H.X, and +FMV.X.H. + +[[norm:Zhinx_x_regs]] +The Zhinx variants of these Zfh-extension instructions have the same +semantics, except that whenever such an instruction would have accessed +an `f` register, it instead accesses the `x` register with the same +number. + +=== Zhinxmin + +The Zhinxmin extension provides minimal support for 16-bit +half-precision floating-point instructions that operate on the `x` +registers. The Zhinxmin extension depends upon the Zfinx extension. + +[[norm:Zfhinxmin_instrs]] +The Zhinxmin extension includes the following instructions from the +Zhinx extension: FCVT.S.H and FCVT.H.S. If the Zdinx extension is +present, the FCVT.D.H and FCVT.H.D instructions are also included. +[NOTE] +==== +In the future, an RV64Zqinx quad-precision extension could be defined +analogously to RV32Zdinx. An RV32Zqinx extension could also be defined +but would require quad-register groups. +==== +=== Privileged Architecture Implications + +[[norm:Zfinx_mstatus-FS_zero]] +In the standard privileged architecture defined in Volume II, the +`mstatus` field FS is hardwired to 0 if the Zfinx extension is +implemented, and FS no longer affects the trapping behavior of +floating-point instructions or `fcsr` accesses. + +[[norm:Zfinx_misa-F_D_Q_zero]] +The `misa` bits F, D, and Q are hardwired to 0 when the Zfinx extension +is implemented. +[NOTE] +==== +A future discoverability mechanism might be used to probe the existence +of the Zfinx, Zhinx, and Zdinx extensions. +==== diff --git a/param_extraction/chunks/chunk_069.txt.license b/param_extraction/chunks/chunk_069.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_069.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_070.txt b/param_extraction/chunks/chunk_070.txt new file mode 100644 index 0000000000..4ce806883a --- /dev/null +++ b/param_extraction/chunks/chunk_070.txt @@ -0,0 +1,200 @@ +# Chunk: chunk_070 +# Source: zicond.adoc +# Lines: 1-187 (of 187) +# Content starts: line 1 +# Line count: 187 +# Sections: 6 +# == "Zicond" Extension for Integer Conditional Operations, Version 1.0.0 +# === Instructions (in alphabetical order) +# ==== czero.eqz +# ==== czero.nez +# === Usage examples +# ==== Instruction sequences +# +[[Zicond]] +== "Zicond" Extension for Integer Conditional Operations, Version 1.0.0 + +The Zicond extension defines two R-type instructions that support branchless +conditional operations. + +[%header,cols="^1,^1,4,8"] +|=== +|RV32 +|RV64 +|Mnemonic +|Instruction + +|{check} +|{check} +|czero.eqz _rd_, _rs1_, _rs2_ +|<<#insns-czero-eqz>> + +|{check} +|{check} +|czero.nez _rd_, _rs1_, _rs2_ +|<<#insns-czero-nez>> + +|=== + +=== Instructions (in alphabetical order) + +[#insns-czero-eqz,reftext="Conditional zero, if condition is equal to zero"] +==== czero.eqz + +Synopsis:: +Moves zero to a register _rd_, if the condition _rs2_ is equal to zero, otherwise moves _rs1_ to _rd_. + +Mnemonic:: +czero.eqz _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x33, attr: ['OP'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x5, attr: ['CZERO.EQZ']}, + { bits: 5, name: 'rs1', attr: ['value'] }, + { bits: 5, name: 'rs2', attr: ['condition'] }, + { bits: 7, name: 0x7, attr: ['CZERO'] }, +]} +.... + +Description:: +[[norm:czero-eqz_op]] +If _rs2_ contains the value zero, this instruction writes the value zero to _rd_. Otherwise, this instruction copies the contents of _rs1_ to _rd_. + +This instruction carries a syntactic dependency from both _rs1_ and _rs2_ to _rd_. +[[norm:czero-eqz_inst_ctime]] +Furthermore, if the Zkt extension is implemented, this instruction's timing is independent of the data values in _rs1_ and _rs2_. + +SAIL code:: +[source,sail] +-- + let condition = X(rs2); + result : xlenbits = if (condition == zeros()) then zeros() + else X(rs1); + X(rd) = result; +-- + +<<< + +[#insns-czero-nez,reftext="Conditional zero, if condition is nonzero"] +==== czero.nez + +Synopsis:: +Moves zero to a register _rd_, if the condition _rs2_ is nonzero, otherwise moves _rs1_ to _rd_. + +Mnemonic:: +czero.nez _rd_, _rs1_, _rs2_ + +Encoding:: +[wavedrom, , svg] +.... +{reg:[ + { bits: 7, name: 0x33, attr: ['OP'] }, + { bits: 5, name: 'rd' }, + { bits: 3, name: 0x7, attr: ['CZERO.NEZ']}, + { bits: 5, name: 'rs1', attr: ['value'] }, + { bits: 5, name: 'rs2', attr: ['condition'] }, + { bits: 7, name: 0x7, attr: ['CZERO'] }, +]} +.... + +Description:: +[[norm:czero-nez_op]] +If _rs2_ contains a nonzero value, this instruction writes the value zero to _rd_. Otherwise, this instruction copies the contents of _rs1_ to _rd_. + +This instruction carries a syntactic dependency from both _rs1_ and _rs2_ to _rd_. +[[norm:czero-nez_zkt_timing]] +Furthermore, if the Zkt extension is implemented, this instruction's timing is independent of the data values in _rs1_ and _rs2_. + +SAIL code:: +[source,sail] +-- + let condition = X(rs2); + result : xlenbits = if (condition != zeros()) then zeros() + else X(rs1); + X(rd) = result; +-- + +=== Usage examples + +The instructions from this extension can be used to construct sequences that perform conditional-arithmetic, conditional-bitwise-logical, and conditional-select operations. + +==== Instruction sequences + +[%header,cols="4,.^3l,^2"] +|=== +|Operation +|Instruction sequence +|Length + +|*Conditional add, if zero* + +`rd = (rc == 0) ? (rs1 + rs2) : rs1` +|czero.nez rd, rs2, rc +add rd, rs1, rd +.8+.^|2 insns + +|*Conditional add, if non-zero* + +`rd = (rc != 0) ? (rs1 + rs2) : rs1` +|czero.eqz rd, rs2, rc +add rd, rs1, rd + +|*Conditional subtract, if zero* + +`rd = (rc == 0) ? (rs1 - rs2) : rs1` +|czero.nez rd, rs2, rc +sub rd, rs1, rd + +|*Conditional subtract, if non-zero* + +`rd = (rc != 0) ? (rs1 - rs2) : rs1` +|czero.eqz rd, rs2, rc +sub rd, rs1, rd + +|*Conditional bitwise-or, if zero* + +`rd = (rc == 0) ? (rs1 \| rs2) : rs1` +|czero.nez rd, rs2, rc +or rd, rs1, rd + +|*Conditional bitwise-or, if non-zero* + +`rd = (rc != 0) ? (rs1 \| rs2) : rs1` +|czero.eqz rd, rs2, rc +or rd, rs1, rd + +|*Conditional bitwise-xor, if zero* + +`rd = (rc == 0) ? (rs1 ^ rs2) : rs1` +|czero.nez rd, rs2, rc +xor rd, rs1, rd + +|*Conditional bitwise-xor, if non-zero* + +`rd = (rc != 0) ? (rs1 ^ rs2) : rs1` +|czero.eqz rd, rs2, rc +xor rd, rs1, rd + +|*Conditional bitwise-and, if zero* + +`rd = (rc == 0) ? (rs1 & rs2) : rs1` +|and rd, rs1, rs2 +czero.eqz rtmp, rs1, rc +or rd, rd, rtmp +.4+.^|3 insns + +(requires 1 temporary) + +|*Conditional bitwise-and, if non-zero* + +`rd = (rc != 0) ? (rs1 & rs2) : rs1` +|and rd, rs1, rs2 +czero.nez rtmp, rs1, rc +or rd, rd, rtmp + +|*Conditional select, if zero* + +`rd = (rc == 0) ? rs1 : rs2` +|czero.nez rd, rs1, rc +czero.eqz rtmp, rs2, rc +add rd, rd, rtmp + +|*Conditional select, if non-zero* + +`rd = (rc != 0) ? rs1 : rs2` +|czero.eqz rd, rs1, rc +czero.nez rtmp, rs2, rc +add rd, rd, rtmp + +|=== diff --git a/param_extraction/chunks/chunk_070.txt.license b/param_extraction/chunks/chunk_070.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_070.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_071.txt b/param_extraction/chunks/chunk_071.txt new file mode 100644 index 0000000000..796ecbb3f5 --- /dev/null +++ b/param_extraction/chunks/chunk_071.txt @@ -0,0 +1,264 @@ +# Chunk: chunk_071 +# Source: zicsr.adoc +# Lines: 1-254 (of 254) +# Content starts: line 1 +# Line count: 254 +# Sections: 3 +# == "Zicsr", Extension for Control and Status Register (CSR) Instructions, Version 2.0 +# === CSR Instructions +# ==== CSR Access Ordering +# +[[csrinsts]] +== "Zicsr", Extension for Control and Status Register (CSR) Instructions, Version 2.0 + +RISC-V defines a separate address space of 4096 Control and Status +registers associated with each hart. This chapter defines the full set +of CSR instructions that operate on these CSRs. + +[NOTE] +==== +While CSRs are primarily used by the privileged architecture, there are +several uses in unprivileged code including for counters and timers, and +for floating-point status. + +The counters and timers are no longer considered mandatory parts of the +standard base ISAs, and so the CSR instructions required to access them +have been moved out of <> into this separate +chapter. +==== + +=== CSR Instructions + +All CSR instructions atomically read-modify-write a single CSR, whose +CSR specifier is encoded in the 12-bit _csr_ field of the instruction +held in bits 31-20. The immediate forms use a 5-bit zero-extended +immediate encoded in the _rs1_ field. + +include::images/wavedrom/csr-instr.edn[] + +[[norm:csrrw_op]] +The CSRRW (Atomic Read/Write CSR) instruction atomically swaps values in +the CSRs and integer registers. CSRRW reads the old value of the CSR, +zero-extends the value to XLEN bits, then writes it to integer register +_rd_. The initial value in _rs1_ is written to the CSR. If _rd_=`x0`, +then the instruction shall not read the CSR and shall not cause any of +the side effects that might occur on a CSR read. + +[[norm:csrrs_op]] +The CSRRS (Atomic Read and Set Bits in CSR) instruction reads the value +of the CSR, zero-extends the value to XLEN bits, and writes it to +integer register _rd_. The initial value in integer register _rs1_ is +treated as a bit mask that specifies bit positions to be set in the CSR. +Any bit that is high in _rs1_ will cause the corresponding bit to be set +in the CSR, if that CSR bit is writable. + +[[norm:csrrc_op]] +The CSRRC (Atomic Read and Clear Bits in CSR) instruction reads the +value of the CSR, zero-extends the value to XLEN bits, and writes it to +integer register _rd_. The initial value in integer register _rs1_ is +treated as a bit mask that specifies bit positions to be cleared in the +CSR. Any bit that is high in _rs1_ will cause the corresponding bit to +be cleared in the CSR, if that CSR bit is writable. + +[NOTE] +==== +Since CSRRS and CSRRC perform a read-modify-write operation, any bits that read as +a different value to their underlying value may be modified by these +instructions even if the corresponding bit is not set in _rs1_. For example, +pmpaddr__n__[G-1] may have an underlying value of 1 but read as 0. Executing +CSRRC or CSRRS to modify a different bit will cause 0 to be read from +pmpaddr__n__[G-1] and then written back, updating the underlying value to 0. +==== + +[[norm:csrrs_csrrc_rs1_x0]] +For both CSRRS and CSRRC, if _rs1_=`x0`, then the instruction will not +write to the CSR at all, and so shall not cause any of the side effects +that might otherwise occur on a CSR write, nor raise illegal-instruction +exceptions on accesses to read-only CSRs. Both CSRRS and CSRRC always +read the addressed CSR and cause any read side effects regardless of +_rs1_ and _rd_ fields. +Note that if _rs1_ specifies a register other than `x0`, and that register +holds a zero value, the instruction will not action any attendant per-field +side effects, but will action any side effects caused by writing to the entire +CSR. + +[[norm:csrrw_rs1_x0]] +A CSRRW with _rs1_=`x0` will attempt to write zero to the destination CSR. + +[[norm:csrrwi_csrrsi_csrrci_ops]] +The CSRRWI, CSRRSI, and CSRRCI variants are similar to CSRRW, CSRRS, and +CSRRC respectively, except they update the CSR using an XLEN-bit value +obtained by zero-extending a 5-bit unsigned immediate (uimm[4:0]) field +encoded in the _rs1_ field instead of a value from an integer register. +[#norm:csrrsi_csrrci_uimm_zero]#For CSRRSI and CSRRCI, if the uimm[4:0] field is zero, then these +instructions will not write to the CSR, and shall not cause any of the +side effects that might otherwise occur on a CSR write, nor raise +illegal-instruction exceptions on accesses to read-only CSRs.# [#norm:csrrwi_rd_x0]#For +CSRRWI, if _rd_=`x0`, then the instruction shall not read the CSR and +shall not cause any of the side effects that might occur on a CSR read.# +Both CSRRSI and CSRRCI will always read the CSR and cause any read side +effects regardless of _rd_ and _rs1_ fields. + +[[csrsideeffects]] +.Conditions determining whether a CSR instruction reads or writes the specified CSR. +[%autowidth,float="center",align="center",cols="<,^,^,^,^",options="header",] +|=== +5+^|*Register operand* +|Instruction |_rd_ is `x0` |_rs1_ is `x0` |Reads CSR |Writes CSR + +|CSRRW |Yes |- |No |Yes + +|CSRRW |No |- |Yes |Yes + +|CSRRS/CSRRC |- |Yes |Yes |No + +|CSRRS/CSRRC |- |No |Yes |Yes + +5+^|*Immediate operand* + +|Instruction |_rd_ is `x0` |_uimm_=0 |Reads CSR |Writes +CSR + +|CSRRWI |Yes |- |No |Yes + +|CSRRWI |No |- |Yes |Yes + +|CSRRSI/CSRRCI |- |Yes |Yes |No + +|CSRRSI/CSRRCI |- |No |Yes |Yes +|=== + +[[norm:csr_side_effects]] +<> summarizes the behavior of the CSR +instructions with respect to whether they read and/or write the CSR. + +In addition to side effects that occur as a consequence of reading or +writing a CSR, individual fields within a CSR might have side effects +when written. The CSRRW[I] instructions action side effects for all +such fields within the written CSR. [#norm:csr_rs1_uimm_side_effect]#The CSRRS[I] an CSRRC[I] instructions +only action side effects for fields for which the _rs1_ or _uimm_ argument +has at least one bit set corresponding to that field.# +[NOTE] +==== +As of this writing, no standard CSRs have side effects on field writes. +Hence, whether a standard CSR access has any side effects can be determined +solely from the opcode. + +Defining CSRs with side effects on field writes is not recommended. +==== + +For any event or consequence that occurs due to a CSR having a +particular value, if a write to the CSR gives it that value, the +resulting event or consequence is said to be an _indirect effect_ of the +write. Indirect effects of a CSR write are not considered by the RISC-V +ISA to be side effects of that write. +[NOTE] +==== +An example of side effects for CSR accesses would be if reading from a +specific CSR causes a light bulb to turn on, while writing an odd value +to the same CSR causes the light to turn off. Assume writing an even +value has no effect. In this case, both the read and write have side +effects controlling whether the bulb is lit, as this condition is not +determined solely from the CSR value. (Note that after writing an odd +value to the CSR to turn off the light, then reading to turn the light +on, writing again the same odd value causes the light to turn off again. +Hence, on the last write, it is not a change in the CSR value that turns +off the light.) + +On the other hand, if a bulb is rigged to light whenever the value of a +particular CSR is odd, then turning the light on and off is not +considered a side effect of writing to the CSR but merely an indirect +effect of such writes. + +More concretely, the RISC-V privileged architecture defined in Volume II +specifies that certain combinations of CSR values cause a trap to occur. +When an explicit write to a CSR creates the conditions that trigger the +trap, the trap is not considered a side effect of the write but merely +an indirect effect. + +Standard CSRs do not have any side effects on reads. Standard CSRs may +have side effects on writes. Custom extensions might add CSRs for which +accesses have side effects on either reads or writes. +==== +Some CSRs, such as the instructions-retired counter, `instret`, may be +modified as side effects of instruction execution. In these cases, if a +CSR access instruction reads a CSR, it reads the value prior to the +execution of the instruction. If a CSR access instruction writes such a +CSR, the explicit write is done instead of the update from the side effect. +In particular, a value +written to `instret` by one instruction will be the value read by the +following instruction. + +The assembler pseudoinstruction to read a CSR, CSRR _rd, csr_, is +encoded as CSRRS _rd, csr, x0_. The assembler pseudoinstruction to write +a CSR, CSRW _csr, rs1_, is encoded as CSRRW _x0, csr, rs1_, while CSRWI +_csr, uimm_, is encoded as CSRRWI _x0, csr, uimm_. + +Further assembler pseudoinstructions are defined to set and clear bits +in the CSR when the old value is not required: CSRS/CSRC _csr, rs1_; +CSRSI/CSRCI _csr, uimm_. + +==== CSR Access Ordering + +Each RISC-V hart normally observes its own CSR accesses, including its +implicit CSR accesses, as performed in program order. [#norm:csr_access_order]#In particular, +unless specified otherwise, a CSR access is performed after the +execution of any prior instructions in program order whose behavior +modifies or is modified by the CSR state and before the execution of any +subsequent instructions in program order whose behavior modifies or is +modified by the CSR state.# Furthermore, [#norm:csrr_order]#an explicit CSR read returns the +CSR state before the execution of the instruction#, while [#norm:csrw_order]#an explicit CSR +write suppresses and overrides any implicit writes or modifications to +the same CSR by the same instruction.# + +[#norm:csr_side_effects_synchronous]#Likewise, any side effects from an explicit CSR access are normally +observed to occur synchronously in program order. Unless specified +otherwise, the full consequences of any such side effects are observable +by the very next instruction, and no consequences may be observed +out-of-order by preceding instructions.# (Note the distinction made +earlier between side effects and indirect effects of CSR writes.) + +[#norm:csr_weakly_ordered]#For the RVWMO memory consistency model (<>), CSR accesses are weakly +ordered by default, so other harts or devices may observe CSR accesses +in an order different from program order.# [#norm:csr_memory_access_ordering]#In addition, CSR accesses are +not ordered with respect to explicit memory accesses, unless a CSR +access modifies the execution behavior of the instruction that performs +the explicit memory access or unless a CSR access and an explicit memory +access are ordered by either the syntactic dependencies defined by the +memory model or the ordering requirements defined by the Memory-Ordering +PMAs section in Volume II of this manual.# [#norm:csr_fence_ordering]#To enforce ordering in all +other cases, software should execute a FENCE instruction between the +relevant accesses. For the purposes of the FENCE instruction, CSR read +accesses are classified as device input (I), and CSR write accesses are +classified as device output (O).# +[NOTE] +==== +Informally, the CSR space acts as a weakly ordered memory-mapped I/O +region, as defined by the Memory-Ordering PMAs section in Volume II of +this manual. As a result, the order of CSR accesses with respect to all +other accesses is constrained by the same mechanisms that constrain the +order of memory-mapped I/O accesses to such a region. + +These CSR-ordering constraints are imposed to support ordering main +memory and memory-mapped I/O accesses with respect to CSR accesses that +are visible to, or affected by, devices or other harts. Examples include +the `time`, `cycle`, and `mcycle` CSRs, in addition to CSRs that reflect +pending interrupts, like `mip` and `sip`. Note that implicit reads of +such CSRs (e.g., taking an interrupt because of a change in `mip`) are +also ordered as device input. + +Most CSRs (including, e.g., the `fcsr`) are not visible to other harts; +their accesses can be freely reordered in the global memory order with +respect to FENCE instructions without violating this specification. +==== +[#norm:csr_strongly_ordered]#The hardware platform may define that accesses to certain CSRs are +strongly ordered, as defined by the Memory-Ordering PMAs section in +Volume II of this manual. Accesses to strongly ordered CSRs have +stronger ordering constraints with respect to accesses to both weakly +ordered CSRs and accesses to memory-mapped I/O regions.# + +[NOTE] +==== +The rules for the reordering of CSR accesses in the global memory order +should probably be moved to <> concerning the RVWMO memory consistency model. +==== diff --git a/param_extraction/chunks/chunk_071.txt.license b/param_extraction/chunks/chunk_071.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_071.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_072.txt b/param_extraction/chunks/chunk_072.txt new file mode 100644 index 0000000000..6bc8a59e35 --- /dev/null +++ b/param_extraction/chunks/chunk_072.txt @@ -0,0 +1,137 @@ +# Chunk: chunk_072 +# Source: zifencei.adoc +# Lines: 1-129 (of 129) +# Content starts: line 1 +# Line count: 129 +# Sections: 1 +# == "Zifencei" Extension for Instruction-Fetch Fence, Version 2.0 +# +[[zifencei]] +== "Zifencei" Extension for Instruction-Fetch Fence, Version 2.0 +This chapter defines the "Zifencei" extension, which includes the +FENCE.I instruction that provides explicit synchronization between +writes to instruction memory and instruction fetches on the same hart. +Currently, this instruction is the only standard mechanism to ensure +that stores visible to a hart will also be visible to its instruction +fetches. +(((store instruction word, not included))) + +[NOTE] +==== +We considered but did not include a "store instruction word" +instruction as in cite:[majc]. JIT compilers may generate a large trace of +instructions before a single FENCE.I, and amortize any instruction cache +snooping/invalidation overhead by writing translated instructions to +memory regions that are known not to reside in the I-cache. +==== +''' +[NOTE] +==== +The FENCE.I instruction was designed to support a wide variety of +implementations. A simple implementation can flush the local instruction +cache and the instruction pipeline when the FENCE.I is executed. A more +complex implementation might snoop the instruction (data) cache on every +data (instruction) cache miss, or use an inclusive unified private L2 +cache to invalidate lines from the primary instruction cache when they +are being written by a local store instruction. If instruction and data +caches are kept coherent in this way, or if the memory system consists +of only uncached RAMs, then just the fetch pipeline needs to be flushed +at a FENCE.I. + +The FENCE.I instruction was previously part of the base I instruction +set. Two main issues are driving moving this out of the mandatory base, +although at time of writing it is still the only standard method for +maintaining instruction-fetch coherence. + +First, it has been recognized that on some systems, FENCE.I will be +expensive to implement and alternate mechanisms are being discussed in +the memory model task group. In particular, for designs that have an +incoherent instruction cache and an incoherent data cache, or where the +instruction cache refill does not snoop a coherent data cache, both +caches must be completely flushed when a FENCE.I instruction is +encountered. This problem is exacerbated when there are multiple levels +of I and D cache in front of a unified cache or outer memory system. + +Second, the instruction is not powerful enough to make available at user +level in a Unix-like operating system environment. The FENCE.I only +synchronizes the local hart, and the OS can reschedule the user hart to +a different physical hart after the FENCE.I. This would require the OS +to execute an additional FENCE.I as part of every context migration. For +this reason, the standard Linux ABI has removed FENCE.I from user-level +and now requires a system call to maintain instruction-fetch coherence, +which allows the OS to minimize the number of FENCE.I executions +required on current systems and provides forward-compatibility with +future improved instruction-fetch coherence mechanisms. + +Future approaches to instruction-fetch coherence under discussion +include providing more restricted versions of FENCE.I that only target a +given address specified in _rs1_, and/or allowing software to use an ABI +that relies on machine-mode cache-maintenance operations. +==== + +include::images/wavedrom/zifencei-ff.edn[] +[[zifencei-ff]] +//.FENCE.I instruction +(((FENCE.I, synchronization))) + +The FENCE.I instruction is used to synchronize the instruction and data +streams. RISC-V does not guarantee that stores to instruction memory +will be made visible to instruction fetches on a RISC-V hart until that +hart executes a FENCE.I instruction. A FENCE.I instruction ensures that +a subsequent instruction fetch on a RISC-V hart will see any previous +data stores already visible to the same RISC-V hart. FENCE.I does _not_ +ensure that other RISC-V harts' instruction fetches will observe the +local hart's stores in a multiprocessor system. To make a store to +instruction memory visible to all RISC-V harts, the writing hart also +has to execute a data FENCE before requesting that all remote RISC-V +harts execute a FENCE.I. + +[[norm:fence_i_op]] +A FENCE.I instruction orders all explicit memory accesses that precede the +FENCE.I in program order before all instruction fetches that follow the +FENCE.I in program order. + +[NOTE] +==== +In the following litmus test, for example, the outcome `a0`=1, `a1`=0 on +the consumer hart is forbidden, assuming little-endian RV32IC harts: + +``` +Initially, flag = 0. + +Producer hart: Consumer hart: + +la t0, patch_me la t2, flag +li t1, 0x4585 lw a0, (t2) +sh t1, (t0) # patch_me := c.li a1, 1 fence.i +fence w, w # order flag write patch_me: +la t0, flag c.li a1, 0 +li t1, 1 +sw t1, (t0) # flag := 1 +``` + +Note that this example is only meant to illustrate the aforementioned ordering +property. +In a realistic producer-consumer code-generation scheme, the consumer would loop +until `flag` becomes 1 before executing the FENCE.I instruction. +==== + +An instruction fetch is always ordered before any explicit memory accesses +that instruction gives rise to. + +[[norm:fence_i_rsv]] +The unused fields in the FENCE.I instruction, _funct12_, _rs1_, and +_rd_, are reserved for finer-grain fences in future extensions. For +forward compatibility, base implementations shall ignore these fields, +and standard software shall zero these fields. +(((FENCE.I, finer-grained))) +(((FENCE.I, forward compatibility))) + +[NOTE] +==== +Because FENCE.I only orders stores with a hart's own instruction +fetches, application code should only rely upon FENCE.I if the +application thread will not be migrated to a different hart. The EEI can +provide mechanisms for efficient multiprocessor instruction-stream +synchronization. +==== diff --git a/param_extraction/chunks/chunk_072.txt.license b/param_extraction/chunks/chunk_072.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_072.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_073.txt b/param_extraction/chunks/chunk_073.txt new file mode 100644 index 0000000000..206618a619 --- /dev/null +++ b/param_extraction/chunks/chunk_073.txt @@ -0,0 +1,197 @@ +# Chunk: chunk_073 +# Source: zihintntl.adoc +# Lines: 1-189 (of 189) +# Content starts: line 1 +# Line count: 189 +# Sections: 1 +# == "Zihintntl" Extension for Non-Temporal Locality Hints, Version 1.0 +# +[[chap:zihintntl]] +== "Zihintntl" Extension for Non-Temporal Locality Hints, Version 1.0 + +The NTL instructions are HINTs that indicate that the explicit memory +accesses of the immediately subsequent instruction (henceforth "target +instruction") exhibit poor temporal locality of reference. +[#norm:NTL-target_definition]#The NTL instructions do not change architectural state, nor do they alter the +architecturally visible effects of the target instruction.# Four variants +are provided: + +[#norm:NTL-P1_op]#The NTL.P1 instruction indicates that the target instruction does not +exhibit temporal locality within the capacity of the innermost level of +private cache in the memory hierarchy.# [#norm:NTL-P1_enc]#NTL.P1 is encoded as +ADD _x0, x0, x2_.# + +[#norm:NTL-PALL_op]#The NTL.PALL instruction indicates that the target instruction does not +exhibit temporal locality within the capacity of any level of private +cache in the memory hierarchy.# [#norm:NTL-PALL_enc]#NTL.PALL is encoded as ADD _x0, x0, x3_.# + +[#norm:NTL-S1_op]#The NTL.S1 instruction indicates that the target instruction does not +exhibit temporal locality within the capacity of the innermost level of +shared cache in the memory hierarchy.# [#norm:NTL-S1_enc]#NTL.S1 is encoded as +ADD _x0, x0, x4_.# + +[#norm:NTL-ALL_op]#The NTL.ALL instruction indicates that the target instruction does not +exhibit temporal locality within the capacity of any level of cache in +the memory hierarchy.# [#norm:NTL-ALL_enc]#NTL.ALL is encoded as ADD _x0, x0, x5_.# + +[NOTE] +==== +The NTL instructions can be used to avoid cache pollution when streaming +data or traversing large data structures, or to reduce latency in +producer-consumer interactions. + +A microarchitecture might use the NTL instructions to inform the cache +replacement policy, or to decide which cache to allocate into, or to +avoid cache allocation altogether. For example, NTL.P1 might indicate +that an implementation should not allocate a line in a private L1 cache, +but should allocate in L2 (whether private or shared). In another +implementation, NTL.P1 might allocate the line in L1, but in the +least-recently used state. + +NTL.ALL will typically inform implementations not to allocate anywhere +in the cache hierarchy. Programmers should use NTL.ALL for accesses that +have no exploitable temporal locality. + +Like any HINTs, these instructions may be freely ignored. Hence, +although they are described in terms of cache-based memory hierarchies, +they do not mandate the provision of caches. + +Some implementations might respect these HINTs for some memory accesses +but not others: e.g., implementations that implement LR/SC by acquiring +a cache line in the exclusive state in L1 might ignore NTL instructions +on LR and SC, but might respect NTL instructions for AMOs and regular +loads and stores. +==== + +<> lists several software use cases and the recommended NTL variant that _portable_ software—i.e., software not tuned for any specific implementation's memory hierarchy—should use in each case. + +[[ntl-portable]] +.Recommended NTL variant for portable software to employ in various scenarios. +[%autowidth,float="center",align="center",cols="<,<",options="header",] +|=== +|Scenario |Recommended NTL variant +|Access to a working set between and in size |NTL.P1 +|Access to a working set between and in size |NTL.PALL +|Access to a working set greater than in size |NTL.S1 +|Access with no exploitable temporal locality (e.g., streaming) |NTL.ALL +|Access to a contended synchronization variable |NTL.PALL +|=== + +[NOTE] +==== +The working-set sizes listed in <> are not meant to +constrain implementers' cache-sizing decisions. +Cache sizes will obviously vary between implementations, and so software +writers should only take these working-set sizes as rough guidelines. +==== + +<> lists several sample memory hierarchies and +recommends how each NTL variant maps onto each cache level. The table +also recommends which NTL variant that implementation-tuned software +should use to avoid allocating in a particular cache level. For example, +for a system with a private L1 and a shared L2, it is recommended that +NTL.P1 and NTL.PALL indicate that temporal locality cannot be exploited +by the L1, and that NTL.S1 and NTL.ALL indicate that temporal locality +cannot be exploited by the L2. Furthermore, software tuned for such a +system should use NTL.P1 to indicate a lack of temporal locality +exploitable by the L1, or should use NTL.ALL indicate a lack of temporal +locality exploitable by the L2. + +[#norm:NTL-compressed_variants]#If the C or Zca extension is provided, compressed variants of these HINTs are +also provided: C.NTL.P1 is encoded as C.ADD _x0, x2_; C.NTL.PALL is +encoded as C.ADD _x0, x3_; C.NTL.S1 is encoded as C.ADD _x0, x4_; and +C.NTL.ALL is encoded as C.ADD _x0, x5_.# + +[#norm:NTL_range]#The NTL instructions affect all memory-access instructions except the +cache-management instructions in the Zicbom extension.# + +[NOTE] +==== +As of this writing, there are no other exceptions to this rule, and so +the NTL instructions affect all memory-access instructions defined in +the base ISAs and the A, F, D, Q, C, and V standard extensions, as well +as those defined within the hypervisor extension in Volume II. + +The NTL instructions can affect cache-management operations other than +those in the Zicbom extension. For example, NTL.PALL followed by +CBO.ZERO might indicate that the line should be allocated in L3 and +zeroed, but not allocated in L1 or L2. +==== + +<<< + +[[ntl]] +[%autowidth,float="center",align="center",cols="<,^,^,^,^,^,^,^,^",options="header"] +.Mapping of NTL variants to various memory hierarchies. +|=== +| Memory hierarchy 4+| Recommended mapping of NTL + +variant to actual cache level 4+| Recommended NTL variant for + +explicit cache management +| +|P1 |PALL |S1 |ALL +|L1 |L2 |L3 |L4/L5 + 9+^| Common Scenarios +| No caches 4+|--- 4+|none +|Private L1 only |L1 |L1 |L1 |L1| ALL |--- |--- |--- +|Private L1; shared L2 |L1 |L1 |L2 |L2 |P1|ALL|---|--- +|Private L1; shared L2/L3 |L1 | L1 | L2 | L3 |P1 |S1 |ALL |--- +|Private L1/L2 |L1 |L2 |L2 |L2 | P1 |ALL |--- |--- +|Private L1/L2; shared L3 |L1 | L2 | L3 | L3 | P1 | PALL| ALL |--- +|Private L1/L2; shared L3/L4 | L1 | L2| L3 | L4 | P1 | PALL | S1 | ALL + 9+^| Uncommon Scenarios +|Private L1/L2/L3; shared L4 | L1 | L3 |L4 |L4 |P1 |P1 |PALL |ALL +|Private L1; shared L2/L3/L4 |L1 | L1 |L2 |L4 |P1 |S1 |ALL |ALL +|Private L1/L2; shared L3/L4/L5 |L1 | L2 | L3 | L5 |P1 | PALL |S1 |ALL +|Private L1/L2/L3; shared L4/L5 |L1 |L3 |L4 |L5 |P1 |P1 |PALL |ALL +|=== + +[#norm:NTL_Zicob_prefetch_outer]#When an NTL instruction is applied to a prefetch hint in the Zicbop +extension, it indicates that a cache line should be prefetched into a +cache that is _outer_ from the level specified by the NTL.# + +[NOTE] +==== +For example, in a system with a private L1 and shared L2, NTL.P1 +followed by PREFETCH.R might prefetch into L2 with read intent. + +To prefetch into the innermost level of cache, do not prefix the +prefetch instruction with an NTL instruction. + +In some systems, NTL.ALL followed by a prefetch instruction might +prefetch into a cache or prefetch buffer internal to a memory +controller. +==== + +Software is discouraged from following an NTL instruction with an +instruction that does not explicitly access memory. Nonadherence to this +recommendation might reduce performance but otherwise has no +architecturally visible effect. + +[#norm:NTL-trap_behavior]#In the event that a trap is taken on the target instruction, +implementations are discouraged from applying the NTL to the first +instruction in the trap handler. Instead, implementations are +recommended to ignore the HINT in this case.# + +[NOTE] +==== +If an interrupt occurs between the execution of an NTL instruction and +its target instruction, execution will normally resume at the target +instruction. That the NTL instruction is not re-executed does not change +the semantics of the program. + +Some implementations might prefer not to process the NTL instruction +until the target instruction is seen (e.g., so that the NTL can be fused +with the memory access it modifies). Such implementations might +preferentially take the interrupt before the NTL, rather than between +the NTL and the memory access. +==== + +[[norm:NTL-LR_SC_exception]] +[NOTE] +==== +Since the NTL instructions are encoded as ADDs, they can be used within +LR/SC loops without voiding the forward-progress guarantee. +But, since using other loads and stores within an LR/SC loop _does_ void the +forward-progress guarantee, the only reason to use an NTL within such a +loop is to modify the LR or the SC. +==== diff --git a/param_extraction/chunks/chunk_073.txt.license b/param_extraction/chunks/chunk_073.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_073.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_074.txt b/param_extraction/chunks/chunk_074.txt new file mode 100644 index 0000000000..86350662f2 --- /dev/null +++ b/param_extraction/chunks/chunk_074.txt @@ -0,0 +1,64 @@ +# Chunk: chunk_074 +# Source: zihintpause.adoc +# Lines: 1-56 (of 56) +# Content starts: line 1 +# Line count: 56 +# Sections: 1 +# == "Zihintpause" Extension for Pause Hint, Version 2.0 +# +[[zihintpause]] +== "Zihintpause" Extension for Pause Hint, Version 2.0 +[#norm:pause_op]#The PAUSE instruction is a HINT that indicates the current hart's rate +of instruction retirement should be temporarily reduced or paused. The +duration of its effect must be bounded and may be zero.# +(((PAUSE, HINT))) +(((HINT, PAUSE))) + +[NOTE] +==== +Software can use the PAUSE instruction to reduce energy consumption +while executing spin-wait code sequences. Multithreaded cores might +temporarily relinquish execution resources to other harts when PAUSE is +executed. It is recommended that a PAUSE instruction generally be +included in the code sequence for a spin-wait loop. +(((PAUSE, energy consumption))) + +The duration of a PAUSE instruction's effect may vary significantly +within and among implementations. In typical implementations this +duration should be much less than the time to perform a context switch, +probably more on the rough order of an on-chip cache miss latency or a +cacheless access to main memory. +(((PAUSE, duration))) + +A series of PAUSE instructions can be used to create a cumulative delay +loosely proportional to the number of PAUSE instructions. In spin-wait +loops in portable code, however, only one PAUSE instruction should be +used before re-evaluating loop conditions, else the hart might stall +longer than optimal on some implementations, degrading system +performance. +==== + +[#norm:pause_enc_fence]#PAUSE is encoded as a FENCE instruction with _pred_=`W`, _succ_=`0`, _fm_=`0`, +_rd_=`x0`, and _rs1_=`x0`.# + +//include::images/wavedrom/zihintpause-hint.edn[] +//[zihintpause-hint] +//.Zihintpause fence instructions + +[NOTE] +==== +PAUSE is encoded as a hint within the FENCE opcode because some +implementations are expected to deliberately stall the PAUSE instruction +until outstanding memory transactions have completed. Because the +successor set is null, however, PAUSE does not _mandate_ any particular +memory ordering—hence, it truly is a HINT. +(((PAUSE, encoding))) + +Like other FENCE instructions, PAUSE cannot be used within LR/SC +sequences without voiding the forward-progress guarantee. +(((PAUSE, LR/RC sequences))) + +The choice of a predecessor set of W is arbitrary, since the successor +set is null. Other HINTs similar to PAUSE might be encoded with other +predecessor sets. +==== diff --git a/param_extraction/chunks/chunk_074.txt.license b/param_extraction/chunks/chunk_074.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_074.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_075.txt b/param_extraction/chunks/chunk_075.txt new file mode 100644 index 0000000000..b5f82b604c --- /dev/null +++ b/param_extraction/chunks/chunk_075.txt @@ -0,0 +1,332 @@ +# Chunk: chunk_075 +# Source: zilsd.adoc +# Lines: 1-315 (of 315) +# Content starts: line 1 +# Line count: 315 +# Sections: 10 +# == "Zilsd", "Zclsd" Extensions for Load/Store pair for RV32, Version 1.0 +# === Load/Store pair instructions (Zilsd) +# === Compressed Load/Store pair instructions (Zclsd) +# === Use of x0 as operand +# === Exception Handling +# === Instructions +# ==== ld +# ==== sd +# ==== c.ldsp +# ==== c.sdsp +# +[[sec:zilsd]] +== "Zilsd", "Zclsd" Extensions for Load/Store pair for RV32, Version 1.0 + +The Zilsd & Zclsd extensions provide load/store pair instructions for RV32, reusing the existing RV64 doubleword load/store instruction encodings. + +[#norm:Zilsd_reg_pairs]#Operands containing `src` for store instructions and `dest` for load instructions are held in aligned `x`-register pairs, i.e., register numbers must be even.# Use of misaligned (odd-numbered) registers for these operands is _reserved_. + +[#norm:Zilsd_bits_to_pair]#Regardless of endianness, the lower-numbered register holds the +low-order bits, and the higher-numbered register holds the high-order bits#: +e.g., bits 31:0 of an operand in Zilsd might be held in register `x14`, with bits 63:32 of that operand held in `x15`. + +[[zilsd, Zilsd]] +=== Load/Store pair instructions (Zilsd) + +The Zilsd extension adds the following RV32-only instructions: + +[%header,cols="^1,^1,4,8"] +|=== +|RV32 +|RV64 +|Mnemonic +|Instruction + +|yes +|no +|ld rd, offset(rs1) +|<<#insns-ld>> + +|yes +|no +|sd rs2, offset(rs1) +|<<#insns-sd>> + +|=== + +[#norm:Zilsd_align8_no_exc]#As the access size is 64-bit, accesses are only considered naturally aligned for effective addresses that are a multiple of 8. +In this case, these instructions are guaranteed to not raise an address-misaligned exception.# +[#norm:Zilsd_align8_atomic]#Even if naturally aligned, the memory access might not be performed atomically.# + +[#norm:Zilsd_align4_atomic]#If the effective address is a multiple of 4, then each word access is required to be performed atomically.# + +The following table summarizes the required behavior: + +[%header] +|=== +|Alignment |Word accesses guaranteed atomic? |Can cause misaligned trap? +|8{nbsp}B |yes |no +|4{nbsp}B not 8{nbsp}B |yes |yes +|else |no | yes +|=== + +[#norm:Zilsd_ld_resume_trap]#To ensure resumable trap handling is possible for the load instructions, the base register must +have its original value if a trap is taken.# The other register in the pair can have been updated. +This affects x2 for the stack pointer relative instruction and rs1 otherwise. + +[NOTE] +==== +If an implementation performs a doubleword load access atomically and the register file implements write-back for even/odd register pairs, +the mentioned atomicity requirements are inherently fulfilled. +Otherwise, an implementation either needs to delay the write-back until the write can be performed atomically, +or order sequential writes to the registers to ensure the requirement above is satisfied. +==== + +[[zclsd, Zclsd]] +=== Compressed Load/Store pair instructions (Zclsd) + +Zclsd depends on Zilsd and Zca. It has overlapping encodings with Zcf and is thus incompatible with Zcf. + +Zclsd adds the following RV32-only instructions: + +[%header,cols="^1,^1,4,8"] +|=== +|RV32 +|RV64 +|Mnemonic +|Instruction + +|yes +|no +|c.ldsp rd, offset(sp) +|<<#insns-cldsp>> + +|yes +|no +|c.sdsp rs2, offset(sp) +|<<#insns-csdsp>> + +|yes +|no +|c.ld rd', offset(rs1') +|<<#insns-cld>> + +|yes +|no +|c.sd rs2', offset(rs1') +|<<#insns-csd>> + +|=== + +=== Use of x0 as operand + +[#norm:Zilsd_ld_x0]#LD instructions with destination `x0` are processed as any other load, +but the result is discarded entirely and x1 is not written.# +[#norm:Zilsd_c-ldsp_x0]#For C.LDSP, usage of `x0` as the destination is reserved.# + +[[norm:Zilsd_sd_x0]] +If using `x0` as `src` of SD or C.SDSP, the entire 64-bit operand is zero — i.e., register `x1` is not accessed. + +C.LD and C.SD instructions can only use `x8-15`. + +=== Exception Handling + +[#norm:Zilsd_RVWMO_exc_misaligned]#For the purposes of RVWMO and exception handling, LD and SD instructions are +considered to be misaligned loads and stores#, with one additional constraint: +[#norm:Zilsd_align4_two_4byte]#an LD or SD instruction whose effective address is a multiple of 4 gives rise +to two 4-byte memory operations.# + +NOTE: This definition permits LD and SD instructions giving rise to exactly one +memory access, regardless of alignment. +If instructions with 4-byte-aligned effective address are decomposed +into two 32b operations, there is no constraint on the order in which the +operations are performed and each operation is guaranteed to be atomic. +These decomposed sequences are interruptible. +Exceptions might occur on subsequent operations, making the effects of previous +operations within the same instruction visible. + +NOTE: Software should make no assumptions about the number or order of +accesses these instructions might give rise to, beyond the 4-byte constraint +mentioned above. +For example, an interrupted store might overwrite the same bytes upon return +from the interrupt handler. + +<<< + +=== Instructions +[#insns-ld,reftext="Load doubleword to register pair, 32-bit encoding"] +==== ld + +Synopsis:: +Load doubleword to even/odd register pair, 32-bit encoding + +Mnemonic:: +ld rd, offset(rs1) + +Encoding (RV32):: +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 0x3, attr: ['LOAD'], type: 8}, + {bits: 5, name: 'rd', attr: ['dest, dest[0]=0'], type: 2}, + {bits: 3, name: 0x3, attr: ['width=D'], type: 8}, + {bits: 5, name: 'rs1', attr: ['base'], type: 4}, + {bits: 12, name: 'imm[11:0]', attr: ['offset[11:0]'], type: 3}, +]} +.... + +Description:: +[[norm:Zilsd_ld_op]] +Loads a 64-bit value into registers `rd` and `rd+1`. +The effective address is obtained by adding register rs1 to the +sign-extended 12-bit offset. + +Included in: <> + +<<< + +[#insns-sd,reftext="Store doubleword from register pair, 32-bit encoding"] +==== sd + +Synopsis:: +Store doubleword from even/odd register pair, 32-bit encoding + +Mnemonic:: +sd rs2, offset(rs1) + +Encoding (RV32):: +[wavedrom, ,svg] +.... +{reg: [ + {bits: 7, name: 0x23, attr: ['STORE'], type: 8}, + {bits: 5, name: 'imm[4:0]', attr: ['offset[4:0]'], type: 3}, + {bits: 3, name: 0x3, attr: ['width=D'], type: 8}, + {bits: 5, name: 'rs1', attr: ['base'], type: 4}, + {bits: 5, name: 'rs2', attr: ['src, src[0]=0'], type: 4}, + {bits: 7, name: 'imm[11:5]', attr: ['offset[11:5]'], type: 3}, +]} +.... + +Description:: +[[norm:Zilsd_sd_op]] +Stores a 64-bit value from registers `rs2` and `rs2+1`. +The effective address is obtained by adding register rs1 to the +sign-extended 12-bit offset. + +Included in: <> + +<<< + +[#insns-cldsp,reftext="Stack-pointer based load doubleword to register pair, 16-bit encoding"] +==== c.ldsp + +Synopsis:: +Stack-pointer based load doubleword to even/odd register pair, 16-bit encoding + +Mnemonic:: +c.ldsp rd, offset(sp) + +Encoding (RV32):: +[wavedrom, ,svg] +.... +{reg: [ + {bits: 2, name: 0x2, type: 8, attr: ['C2']}, + {bits: 5, name: 'imm', type: 3, attr: ['offset[4:3|8:6]']}, + {bits: 5, name: 'rd', type: 2, attr: ['dest≠0, dest[0]=0']}, + {bits: 1, name: 'imm', type: 3, attr: ['offset[5]']}, + {bits: 3, name: 0x3, type: 8, attr: ['C.LDSP']}, +], config: {bits: 16}} +.... + +Description:: +[[norm:Zilsd_c-ldsp_op]] +Loads stack-pointer relative 64-bit value into registers `rd'` and `rd'+1`. It computes its effective address by adding the zero-extended offset, scaled by 8, to the stack pointer, `x2`. It expands to `ld rd, offset(x2)`. C.LDSP is only valid when _rd_{ne}x0; the code points with _rd_=x0 are reserved. + +Included in: <> + +<<< + +[#insns-csdsp,reftext="Stack-pointer based store doubleword from register pair, 16-bit encoding"] +==== c.sdsp + +Synopsis:: +Stack-pointer based store doubleword from even/odd register pair, 16-bit encoding + +Mnemonic:: +c.sdsp rs2, offset(sp) + +Encoding (RV32):: +[wavedrom, ,svg] +.... +{reg: [ + {bits: 2, name: 0x2, type: 8, attr: ['C2']}, + {bits: 5, name: 'rs2', type: 4, attr: ['src, src[0]=0']}, + {bits: 6, name: 'imm', type: 3, attr: ['offset[5:3|8:6]']}, + {bits: 3, name: 0x7, type: 8, attr: ['C.SDSP']}, +], config: {bits: 16}} +.... + +Description:: +[[norm:Zilsd_c-sdsp_op]] +Stores a stack-pointer relative 64-bit value from registers `rs2'` and `rs2'+1`. It computes an effective address by adding the _zero_-extended offset, scaled by 8, to the stack pointer, `x2`. It expands to `sd rs2, offset(x2)`. + +Included in: <> + +<<< + +[#insns-cld,reftext="Load doubleword to register pair, 16-bit encoding"] +==== c.ld + +Synopsis:: +Load doubleword to even/odd register pair, 16-bit encoding + +Mnemonic:: +c.ld rd', offset(rs1') + +Encoding (RV32):: +[wavedrom, ,svg] +.... +{reg: [ + {bits: 2, name: 0x0, type: 8, attr: ['C0']}, + {bits: 3, name: 'rd`', type: 2, attr: ['dest, dest[0]=0']}, + {bits: 2, name: 'imm', type: 3, attr: ['offset[7:6]']}, + {bits: 3, name: 'rs1`', type: 4, attr: ['base']}, + {bits: 3, name: 'imm', type: 3, attr: ['offset[5:3]']}, + {bits: 3, name: 0x3, type: 8, attr: ['C.LD']}, +], config: {bits: 16}} +.... + +Description:: +[[norm:Zilsd_c-ld_op]] +Loads a 64-bit value into registers `rd'` and `rd'+1`. +It computes an effective address by adding the zero-extended offset, scaled by 8, to the base address in register rs1'. + +Included in: <> + +<<< + +[#insns-csd,reftext="Store doubleword from register pair, 16-bit encoding"] +==== c.sd + +Synopsis:: +Store doubleword from even/odd register pair, 16-bit encoding + +Mnemonic:: +c.sd rs2', offset(rs1') + +Encoding (RV32):: +[wavedrom, ,svg] +.... +{reg: [ + {bits: 2, name: 0x0, type: 8, attr: ['C0']}, + {bits: 3, name: 'rs2`', type: 4, attr: ['src, src[0]=0']}, + {bits: 2, name: 'imm', type: 3, attr: ['offset[7:6]']}, + {bits: 3, name: 'rs1`', type: 4, attr: ['base']}, + {bits: 3, name: 'imm', type: 3, attr: ['offset[5:3]']}, + {bits: 3, name: 0x7, type: 8, attr: ['C.SD']}, +], config: {bits: 16}} +.... + +Description:: +[[norm:Zilsd_c-sd_op]] +Stores a 64-bit value from registers `rs2'` and `rs2'+1`. +It computes an effective address by adding the zero-extended offset, scaled by 8, to the base address in register rs1'. +It expands to `sd rs2', offset(rs1')`. + +Included in: <> diff --git a/param_extraction/chunks/chunk_075.txt.license b/param_extraction/chunks/chunk_075.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_075.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_076.txt b/param_extraction/chunks/chunk_076.txt new file mode 100644 index 0000000000..88edc6d928 --- /dev/null +++ b/param_extraction/chunks/chunk_076.txt @@ -0,0 +1,122 @@ +# Chunk: chunk_076 +# Source: zimop.adoc +# Lines: 1-113 (of 113) +# Content starts: line 1 +# Line count: 113 +# Sections: 2 +# == "Zimop" Extension for May-Be-Operations, Version 1.0 +# === "Zcmop" Compressed May-Be-Operations Extension, Version 1.0 +# +[[zimop]] +== "Zimop" Extension for May-Be-Operations, Version 1.0 + +This chapter defines the "Zimop" extension, which introduces the concept of +instructions that _may be operations_ (MOPs). MOPs are initially defined to +simply write zero to `x[rd]`, but are designed to be redefined by later +extensions to perform some other action. +The Zimop extension defines an encoding space for 40 MOPs. + + +[NOTE] +==== +It is sometimes desirable to define instruction-set extensions whose +instructions, rather than raising illegal-instruction exceptions when the extension is +not implemented, take no useful action (beyond writing `x[rd]`). +For example, programs with control-flow integrity checks can +execute correctly on implementations without the corresponding extension, +provided the checks are simply ignored. Implementing these checks as MOPs +allows the same programs to run on implementations with or without the +corresponding extension. + +Although similar in some respects to HINTs, MOPs cannot be encoded as HINTs, +because unlike HINTs, MOPs are allowed to alter architectural state. + +Because MOPs may be redefined by later extensions, standard software should +not execute a MOP unless it is deliberately targeting an extension that has +redefined that MOP. +==== + +[#norm:Zimop_mop-r_op]#The Zimop extension defines 32 MOP instructions named MOP.R.__n__, where +__n__ is an integer between 0 and 31, inclusive. +Unless redefined by another extension, these instructions simply write 0 to +`x[rd]`.# Their encoding allows future extensions to define them to read `x[rs1]`, +as well as write `x[rd]`. + +[[norm:Zimop_mop-r_enc]] +include::images/wavedrom/mop-r.edn[] +[[mop-r]] + +[#norm:Zimop_mop-rr_op]#The Zimop extension additionally defines 8 MOP instructions named +MOP.RR.__n__, where __n__ is an integer between 0 and 7, inclusive. +Unless redefined by another extension, these instructions simply +write 0 to `x[rd]`.# Their encoding allows future extensions to define them to +read `x[rs1]` and `x[rs2]`, as well as write `x[rd]`. + +[[norm:Zimop_mop-rr_enc]] +include::images/wavedrom/mop-rr.edn[] +[[mop-rr]] + +NOTE: The recommended assembly syntax for MOP.R.__n__ is MOP.R.__n__ rd, rs1, +with any `x`-register specifier being valid for either argument. Similarly for +MOP.RR.__n__, the recommended syntax is MOP.RR.__n__ rd, rs1, rs2. +The extension that redefines a MOP may define an alternate assembly mnemonic. + +NOTE: These MOPs are encoded in the SYSTEM major opcode in part because it is +expected their behavior will be modulated by privileged CSR state. + +NOTE: These MOPs are defined to write zero to `x[rd]`, rather than performing +no operation, to simplify instruction decoding and to allow testing the +presence of features by branching on the zeroness of the result. + +The MOPs defined in the Zimop extension do not carry a syntactic dependency +from `x[rs1]` or `x[rs2]` to `x[rd]`, though an extension that redefines the +MOP may impose such a requirement. + +NOTE: Not carrying a syntactic dependency relieves straightforward +implementations of reading `x[rs1]` and `x[rs2]`. + +=== "Zcmop" Compressed May-Be-Operations Extension, Version 1.0 + +[#norm:Zcmop_op]#This section defines the "Zcmop" extension, which defines eight 16-bit MOP +instructions named C.MOP.__n__, where __n__ is an odd integer between 1 and +15, inclusive.# [#norm:Zcmop_enc]#C.MOP.__n__ is encoded in the reserved encoding space +corresponding to C.LUI x__n__, 0, as shown in <>.# +[#norm:Zcmop_instr_write]#Unlike the MOPs defined in the Zimop extension, the C.MOP.__n__ instructions +are defined to _not_ write any register.# +Their encoding allows future extensions to define them to read register +`x[__n__]`. + +The Zcmop extension depends upon the Zca extension. + +include::images/wavedrom/c-mop.edn[] +[[c-mop]] + +NOTE: Very few suitable 16-bit encoding spaces exist. This space was chosen +because it already has unusual behavior with respect to the `rd`/`rs1` +field--it encodes `c.addi16sp` when the field contains `x2`--and is +therefore of lower value for most purposes. + +[[norm:c-mop_enc]] +.C.MOP.__n__ instruction encoding. + +|=== +|Mnemonic | Encoding | Redefinable to read register + +|C.MOP.1 | `0110000010000001` | `x1` +|C.MOP.3 | `0110000110000001` | `x3` +|C.MOP.5 | `0110001010000001` | `x5` +|C.MOP.7 | `0110001110000001` | `x7` +|C.MOP.9 | `0110010010000001` | `x9` +|C.MOP.11 | `0110010110000001` | `x11` +|C.MOP.13 | `0110011010000001` | `x13` +|C.MOP.15 | `0110011110000001` | `x15` +|=== + +NOTE: The recommended assembly syntax for C.MOP.__n__ is simply the nullary +C.MOP.__n__. The possibly accessed register is implicitly `x__n__`. + +NOTE: The expectation is that each Zcmop instruction is equivalent to some +Zimop instruction, but the choice of expansion (if any) is left to the +extension that redefines the MOP. +Note, a Zcmop instruction that does not write a value can expand into a write +to `x0`. diff --git a/param_extraction/chunks/chunk_076.txt.license b/param_extraction/chunks/chunk_076.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_076.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_077.txt b/param_extraction/chunks/chunk_077.txt new file mode 100644 index 0000000000..1ea6732eb3 --- /dev/null +++ b/param_extraction/chunks/chunk_077.txt @@ -0,0 +1,240 @@ +# Chunk: chunk_077 +# Source: zpm.adoc +# Lines: 1-223 (of 223) +# Content starts: line 1 +# Line count: 223 +# Sections: 10 +# == Pointer Masking Extensions, Version 1.0.0 +# === Introduction +# === Background +# ==== Definitions +# ==== The “Ignore” Transformation +# ==== Example +# ==== Determining the Value of PMLEN +# ==== Pointer Masking and Privilege Modes +# ==== Memory Accesses Subject to Pointer Masking +# ==== Pointer Masking Extensions +# +[[Zpm]] +== Pointer Masking Extensions, Version 1.0.0 + +=== Introduction + +RISC-V Pointer Masking (PM) is a feature that, when enabled, causes the CPU to ignore the upper bits of the effective address (these terms will be defined more precisely in the Background section). This allows these bits to be used in whichever way the application chooses. The version of the extension being described here specifically targets **tag checks**: When an address is accessed, the tag stored in the masked bits can be compared against a range-based tag. This is used for dynamic safety checkers such as HWASAN cite:[HWASAN]. Such tools can be applied in all privilege modes (U, S, and M). + +HWASAN leverages tags in the upper bits of the address to identify memory errors such as use-after-free or buffer overflow errors. By storing a *pointer tag* in the upper bits of the address and checking it against a *memory tag* stored in a side table, it can identify whether a pointer is pointing to a valid location. Doing this without hardware support introduces significant overheads since the pointer tag needs to be manually removed for every conventional memory operation. Pointer masking support reduces these overheads. + +Pointer masking only adds the ability to ignore pointer tags during regular memory accesses. The tag checks themselves can be implemented in software or hardware. If implemented in software, pointer masking still provides performance benefits since non-checked accesses do not need to transform the address before every memory access. Hardware implementations are expected to provide even larger benefits due to performing tag checks out-of-band and hardening security guarantees derived from these checks. We anticipate that future extensions may build on pointer masking to support this functionality in hardware. + +It is worth mentioning that while HWASAN is the primary use-case for the current pointer masking extension, a number of other hardware/software features may be implemented leveraging Pointer Masking. Some of these use cases include sandboxing, object type checks and garbage collection bits in runtime systems. Note that the current version of the spec does not explicitly address these use cases, but future extensions may build on it to do so. + +While we describe the high-level concepts of pointer masking as if it was a single extension, it is, in reality, a family of extensions that implementations or profiles may choose to individually include or exclude (see <<_pointer_masking_extensions>>). + +=== Background + +==== Definitions + +We now define basic terms. Note that these rely on the definition of an “ignore” transformation, which is defined in <>. + +* **Effective address (as defined in the RISC-V Base ISA):** A load/store effective address sent to the memory subsystem (e.g., as generated during the execution of load/store instructions). This does not include addresses corresponding to implicit accesses, such as page-table walks. + +* **Masked bits:** The upper PMLEN bits of an address, where PMLEN is a configurable parameter. We will use PMLEN consistently throughout this document to refer to this parameter. + +* **Transformed address:** An effective address after the ignore transformation has been applied. + +* **Address translation mode:** The MODE of the currently active address translation scheme as defined in the RISC-V privileged specification. This could, for example, refer to Bare, Sv39, Sv48, and Sv57. In accordance with the privileged specification, non-Bare translation modes are referred to as virtual-memory schemes. For the purpose of this specification, M-mode translation is treated as equivalent to Bare. + +* **Address validity:** The RISC-V privileged spec defines validity of addresses based on the address translation mode that is currently in use (e.g., Sv57, Sv48, Sv39, etc.). For a virtual address to be valid, all bits in the unused portion of the address must be the same as the Most Significant Bit (MSB) of the used portion. For example, when page-based 48-bit virtual memory (Sv48) is used, load/store effective addresses, which are 64 bits, must have bits 63–48 all set to bit 47, or else a page-fault exception will occur. For physical addresses, validity means that bits XLEN-1 to PABITS are zero, where PABITS is the number of physical address bits supported by the processor. + +* **NVBITS:** The upper bits within a virtual address that have no effect on addressing memory and are only used for validity checks. These bits depend on the currently active address translation mode. For example, in Sv48, these are bits 63-48. + +* **VBITS:** The bits within a virtual address that affect which memory is addressed. These are the bits of an address which are used to index into page tables. + +[[sec-ignore-transform]] +==== The “Ignore” Transformation + +The ignore transformation differs depending on whether it applies to a virtual or physical address. For virtual addresses, it replaces the upper PMLEN bits with the sign extension of the PMLEN+1st bit. + +[source] +."Ignore" Transformation for virtual addresses, expressed in Verilog code. +---- +transformed_effective_address = + {{PMLEN{effective_address[XLEN-PMLEN-1]}}, effective_address[XLEN-PMLEN-1:0]} +---- + +[NOTE] +==== +If PMLEN is less than or equal to NVBITS for the largest supported address translation mode on a given architecture, this is equivalent to ignoring a subset of NVBITS. This enables cheap implementations that modify validity checks in the CPU instead of performing the sign extension. +==== + +When applied to a physical address, including guest-physical addresses (i.e., all cases except when the active satp register's MODE field != Bare), the ignore transformation replaces the upper PMLEN bits with 0. This includes both the case of running in M-mode and running in other privilege modes with Bare address translation mode. + +[source] +."Ignore" Transformation for physical addresses, expressed in Verilog code. +---- +transformed_effective_address = + {{PMLEN{0}}, effective_address[XLEN-PMLEN-1:0]} +---- + +[NOTE] +==== +This definition is consistent with the way that RISC-V already handles physical and virtual addresses differently. While the unused upper bits of virtual addresses are the sign-extension of the used bits (see the definition of "address validity" in <<_definitions>>), the equivalent bits in physical addresses are zero-extended. This is necessary due to their interactions with other mechanisms such as Physical Memory Protection (PMP). +==== + +When pointer masking is enabled, the ignore transformation will be applied to every explicit memory access (e.g., loads/stores, atomics operations, and floating point loads/stores). The transformation *does not* apply to implicit accesses such as page-table walks or instruction fetches. The set of accesses that pointer masking applies to is described in <<_memory_accesses_subject_to_pointer_masking>>. + +[WARNING] +==== +Pointer masking does not change the underlying address generation logic or permission checks. Under a fixed address translation mode, it is semantically equivalent to replacing a subset of instructions (e.g., loads and stores) with an instruction sequence that applies the ignore operation to the target address of this instruction and then applies the instruction to the transformed address. References to address translation and other implementation details in the text are primarily to explain design decisions and common implementation patterns. +==== + +Note that pointer masking is purely an arithmetic operation on the address that makes no assumption about the meaning of the addresses it is applied to. Pointer masking with the same value of PMLEN always has the same effect for the same type of address (virtual or physical). This ensures that code that relies on pointer masking does not need to be aware of the environment it runs in once pointer masking has been enabled, as long as the value of PMLEN is known, and whether or not addresses are virtual or physical. For example, the same application or library code can run in user mode, supervisor mode or M-mode (with different address translation modes) without modification. + +[NOTE] +==== +A common scenario for such code is that addresses are generated by mmap system calls. This abstracts away the details of the underlying address translation mode from the application code. Software therefore needs to be aware of the value of PMLEN to ensure that its minimally required number of tag bits is supported. <<_determining_the_value_of_pmlen>> covers how this value is derived. +==== + +==== Example + +<> shows an example of the pointer masking transformation on a virtual address when PM is enabled for RV64 under Sv57 (PMLEN=7). + +[[pm-example]] + +[%header, cols="25%,75%", options="header"] +.Example of PM address translation for RV64 under Sv57 +|=== +|Page-based profile|Sv57 on RV64 +|Effective Address |0xABFFFFFF12345678 + +NVBITS[1010101] VBITS[11111111111111111111111110001...000] +|PMLEN|7 +|Mask|0x01FFFFFFFFFFFFFF + +NVBITS[0000000] VBITS[11111111111111111111111111111...111] +|PMLEN+1st bit from the top (i.e., bit XLEN-PMLEN-1)|1 +|Transformed effective address |0xFFFFFFFF12345678 + +NVBITS[1111111] VBITS[11111111111111111111111110001...000] + +|=== + +If the address was a physical address rather than a virtual address with Sv57, the transformed address with PMLEN=7 would be 0x1FFFFFF12345678. + +==== Determining the Value of PMLEN + +From an implementation perspective, ignoring bits is deeply connected to the maximum virtual and physical address space supported by the processor (e.g., Bare, Sv48, Sv57). In particular, applying the above transformation is cheap if it covers only bits that are not used by **any** supported address translation mode (as it is equivalent to switching off validity checks). Masking NVBITS beyond those bits is more expensive as it requires ignoring them in the TLB tag, and even more expensive if the masked bits extend into the VBITS portion of the address (as it requires performing the actual sign extension). Similarly, when running in Bare or M mode, it is common for implementations to not use a particular number of bits at the top of the physical address range and fix them to zero. Applying the ignore transformation to those bits is cheap as well, since it will result in a valid physical address with all the upper bits fixed to 0. + +The current standard only supports PMLEN=XLEN-48 (i.e., PMLEN=16 in RV64) and PMLEN=XLEN-57 (i.e., PMLEN=7 in RV64). A setting has been reserved to potentially support other values of PMLEN in future standards. In such future standards, different supported values of PMLEN may be defined for each privilege mode (U/VU, S/HS, and M). + +[NOTE] +==== +Future versions of the pointer masking extension may introduce the ability to freely configure the value of PMLEN. The current extension does not define the behavior if PMLEN was different from the values defined above. In particular, there is no guarantee that a future pointer masking extension would define the ignore operation in the same way for those values of PMLEN. +==== + +==== Pointer Masking and Privilege Modes + +Pointer masking is controlled separately for different privilege modes. The subset of supported privilege modes is determined by the set of supported pointer masking extensions. Different privilege modes may have different pointer masking settings active simultaneously and the hardware will automatically apply the pointer masking settings of the currently active privilege mode. A privilege mode's pointer masking setting is configured by bits in configuration registers of the next-higher privilege mode. + +Note that the pointer masking setting that is applied only depends on the active privilege mode, not on the address that is being masked. Some operating systems (e.g., Linux) may use certain bits in the address to disambiguate between different types of addresses (e.g., kernel and user-mode addresses). Pointer masking _does not_ take these semantics into account and is purely an arithmetic operation on the address it is given. + +[NOTE] +==== +Linux places kernel addresses in the upper half of the address space and user addresses in the lower half of the address space. As such, the MSB is often used to identify the type of a particular address. With pointer masking enabled, this role is now played by bit XLEN-PMLEN-1 and code that checks whether a pointer is a kernel or a user address needs to inspect this bit instead. For backward compatibility, it may be desirable that the MSB still indicates whether an address is a user or a kernel address. An operating system's ABI may mandate this, but it does not affect the pointer masking mechanism itself. For example, the Linux ABI may choose to mandate that the MSB is not used for tagging and replicates bit XLEN-PMLEN-1 bit (note that for such a mechanism to be secure, the kernel needs to check the MSB of any user mode-supplied address and ensure that this invariant holds before using it; alternatively, it can apply the transformation from Listing 1 or 2 to ensure that the MSB is set to the correct value). +==== + +==== Memory Accesses Subject to Pointer Masking + +Pointer masking applies to all explicit memory accesses. Currently, in the Base and Privileged ISAs, these are: + +* **Base Instruction Set**: LB, LH, LW, LBU, LHU, LWU, LD, SB, SH, SW, SD. +* **Atomics**: All instructions in RV32A and RV64A. +* **Floating Point**: FLW, FLD, FLQ, FSW, FSD, FSQ. +* **Compressed**: All instructions mapping to any of the above, and C.LWSP, C.LDSP, C.FLWSP, C.FLDSP, C.SWSP, C.SDSP, C.FSWSP, C.FSDSP. +* **Hypervisor Extension**: HLV.\*, HSV.* (in some cases; see <>). +* **Cache Management Operations**: All instructions in Zicbom, Zicbop and Zicboz. +* **Vector Extension**: All vector load and store instructions in the ratified RVV 1.0 spec. +* **Zicfiss Extension**: SSPUSH, C.SSPUSH, SSPOPCHK, C.SSPOPCHK, SSAMOSWAP.W/D. +* **Assorted**: FENCE, FENCE.I (if the currently unused address fields become enabled in the future). + +[NOTE] +==== +This list will grow over time as new extensions introduce new instructions that perform explicit memory accesses. +==== + +For other extensions, pointer masking applies to all explicit memory accesses by default. Future extensions may add specific language to indicate whether particular accesses are or are not included in pointer masking. + +[NOTE] +==== +It is worth noting that pointer masking is not applied to `SFENCE.\*`, `HFENCE.*`, `SINVAL.\*`, or `HINVAL.*`. When such an operation is invoked, it is the responsibility of the software to provide the correct address. +==== + +MPRV and SPVP affect pointer masking as well, causing the pointer masking settings of the effective privilege mode to be applied. When MXR is in effect at the effective privilege mode where explicit memory access is performed, pointer masking does not apply. + +[NOTE] +==== +Note that this includes cases where page-based virtual memory is not in effect; i.e., although MXR has no effect on permissions checks when page-based virtual memory is not in effect, it is still used in determining whether or not pointer masking should be applied. +==== + +[NOTE] +==== +Cache Management Operations (CMOs) must respect and take into account pointer masking. Otherwise, a few serious security problems can appear, including: + +* CBO.ZERO may work as a STORE operation. If pointer masking is not respected, it would be possible to write to memory bypassing the mask enforcement. +* If CMOs did not respect pointer masking, it would be possible to weaponize this in a side-channel attack. For example, U-mode would be able to flush a physical address (without masking) that it should not be permitted to. +==== + +Pointer masking only applies to accesses generated by instructions on the CPU (including CPU extensions such as an FPU). E.g., it does not apply to accesses generated by page-table walks, the IOMMU, or devices. + +[NOTE] +==== +Pointer Masking does not apply to DMA controllers and other devices. It is therefore the responsibility of the software to manually untag these addresses. +==== + +Misaligned accesses are supported, subject to the same limitations as in the absence of pointer masking. The behavior is identical to applying the pointer masking transformation to every constituent aligned memory access. In other words, the accessed bytes should be identical to the bytes that would be accessed if the pointer masking transformation was individually applied to every byte of the access without pointer masking. This ensures that both hardware implementations and emulation of misaligned accesses in M-mode behave the same way, and that the M-mode implementation is identical whether or not pointer masking is enabled (e.g., such an implementation may leverage MPRV to apply the correct privilege mode's pointer masking setting). + +No pointer masking operations are applied when software reads/writes to CSRs, including those meant to hold addresses. If software stores tagged addresses into such CSRs, data load or data store operations based on those addresses are subject to pointer masking only if they are explicit (<<_memory_accesses_subject_to_pointer_masking>>) and pointer masking is enabled for the privilege mode that performs the access. The implemented WARL width of CSRs is unaffected by pointer masking (e.g., if a CSR supports 52 bits of valid addresses and pointer masking is supported with PMLEN=16, the necessary number of WARL bits remains 52 independently of whether pointer masking is enabled or disabled). + +In contrast to software writes, pointer masking, when applicable, **is applied** for hardware writes to a CSR (e.g., when the hardware writes the transformed address to `stval` when taking an exception). Pointer masking is also applied, when applicable, to the memory access address when matching address triggers in debug. + +For example, software is free to write a tagged or untagged address to `stvec`, but on trap delivery (e.g., due to an exception or interrupt), pointer masking **will not be applied** to the address of the trap handler. However, when delivering an exception, the hardware applies pointer masking to any address written into `stval` if pointer masking is applicable to that address. + +[NOTE] +==== +The rationale for this choice is that delivering the additional bits may add overheads in some hardware implementations. Further, pointer masking is configured per privilege mode, so all trap handlers in supervisor mode would need to be careful to configure pointer masking the same way as user mode or manually unmask (which is expensive). +==== + +==== Pointer Masking Extensions + +Pointer masking refers to a number of separate extensions, all of which are privileged. This approach is used to capture optionality of pointer masking features. Profiles and implementations may choose to support an arbitrary subset of these extensions and must define valid ranges for their corresponding values of PMLEN. + +**Extensions**: + +* **Ssnpm**: A supervisor-level extension that provides pointer masking for the next lower privilege mode (U-mode), and for VS- and VU-modes if the H extension is present. See <>, <>, <>, and <>. +* **Smnpm**: A machine-level extension that provides pointer masking for the next lower privilege mode (S/HS if S-mode is implemented, or U-mode otherwise). See <>. +* **Smmpm**: A machine-level extension that provides pointer masking for M-mode. See <>. + +In addition, the pointer masking standard defines two extensions that describe an execution environment but have no bearing on hardware implementations. These extensions are intended to be used in profile specifications where a User profile or a Supervisor profile can only reference User level or Supervisor level pointer masking functionality, and not the associated CSR controls that exist at a higher privilege level (i.e., in the execution environment). + +* **Sspm**: An extension that indicates that there is pointer-masking support available in supervisor mode, with some facility provided in the supervisor execution environment to control pointer masking. +* **Supm**: An extension that indicates that there is pointer-masking support available in user mode, with some facility provided in the application execution environment to control pointer masking. + +The precise nature of these facilities is left to the respective execution environment. + +Pointer masking only applies to RV64. In RV32, trying to enable pointer masking will result in an illegal WARL write and not update the pointer masking configuration bits (see <>, <>, <>, and <> for details). The same is the case on RV64 or larger systems when UXL/SXL/MXL is set to 1 for the corresponding privilege mode. Note that in RV32, the CSR bits introduced by pointer masking are still present, for compatibility between RV32 and larger systems with UXL/SXL/MXL set to 1. Setting UXL/SXL/MXL to 1 will clear the corresponding pointer masking configuration bits. + +[NOTE] +==== +Note that setting UXL/SXL/MXL to 1 and back to 0 does not preserve the previous values of the PMM bits. This includes the case of entering an RV32 virtual machine from an RV64 hypervisor and returning. +==== + +[NOTE] +==== +Future extensions may introduce additional CSRs to allow different privilege modes to modify their own pointer masking settings. This may be required for future use cases in managed runtime systems that are not currently addressed as part of this extension. +==== + +==== Number of Masked Bits + +As described in <<_determining_the_value_of_pmlen>>, the supported values of PMLEN may depend on the effective privilege mode. The current standard only defines PMLEN=XLEN-48 and PMLEN=XLEN-57, but this assumption may be relaxed in future extensions and profiles. Trying to enable pointer masking in an unsupported scenario represents an illegal write to the corresponding pointer masking enable bit and follows WARL semantics. Future profiles may choose to define certain combinations of privilege modes and supported values of PMLEN as mandatory. + +[NOTE] +==== +An option that was considered but discarded was to allow implementations to set PMLEN depending on the active addressing mode. For example, PMLEN could be set to 16 for Sv48 and to 25 for Sv39. However, having a single value of PMLEN (e.g., setting PMLEN to 16 for both Sv39 and Sv48 rather than 25) facilitates TLB implementations in designs that support Sv39 and Sv48 but not Sv57. 16 bits are sufficient for current pointer masking use cases but allow for a TLB implementation that matches against the same number of virtual tag bits independently of whether it is running with Sv39 or Sv48. However, if Sv57 is supported, tag matching may need to be conditional on the current address translation mode. +==== diff --git a/param_extraction/chunks/chunk_077.txt.license b/param_extraction/chunks/chunk_077.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_077.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/chunk_078.txt b/param_extraction/chunks/chunk_078.txt new file mode 100644 index 0000000000..b61a4602ec --- /dev/null +++ b/param_extraction/chunks/chunk_078.txt @@ -0,0 +1,57 @@ +# Chunk: chunk_078 +# Source: ztso-st-ext.adoc +# Lines: 1-49 (of 49) +# Content starts: line 1 +# Line count: 49 +# Sections: 1 +# == "Ztso" Extension for Total Store Ordering, Version 1.0 +# +[[ztso]] +== "Ztso" Extension for Total Store Ordering, Version 1.0 + +This chapter defines the "Ztso" extension for the RISC-V Total Store +Ordering (RVTSO) memory consistency model. RVTSO is defined as a delta +from RVWMO, which is defined in <>. +[NOTE] +==== +_The Ztso extension is meant to facilitate the porting of code originally +written for the x86 or SPARC architectures, both of which use TSO by +default. It also supports implementations which inherently provide RVTSO +behavior and want to expose that fact to software._ +==== + +[[norm:rvtso_adj_rvwmo]] +RVTSO makes the following adjustments to RVWMO: + +* [#norm:ztso_ld]#All load operations behave as if they have an acquire-RCpc annotation# +* [#norm:ztso_sd]#All store operations behave as if they have a release-RCpc annotation.# +* [#norm:ztso_amo]#All AMOs behave as if they have both acquire-RCsc and release-RCsc +annotations.# + +[NOTE] +==== +_These rules render all PPO rules except +<> redundant. They also make +redundant any non-I/O fences that do not have both PW and SR set. +Finally, they also imply that no memory operation will be reordered past +an AMO in either direction._ + +_In the context of RVTSO, as is the case for RVWMO, the storage ordering +annotations are concisely and completely defined by PPO rules +<>. In both of these +memory models, it is the <> that allows a hart to forward a value from its +store buffer to a subsequent (in program order) load—that is to say that +stores can be forwarded locally before they are visible to other harts._ +==== + +[#norm:ztso_vect_mem]#Additionally, if the Ztso extension is implemented, then vector memory +instructions in the V extension and Zve family of extensions follow RVTSO at +the instruction level.# +The Ztso extension does not strengthen the ordering of intra-instruction +element accesses. + +In spite of the fact that Ztso adds no new instructions to the ISA, code +written assuming RVTSO will not run correctly on implementations not +supporting Ztso. Binaries compiled to run only under Ztso should +indicate as such via a flag in the binary, so that platforms which do +not implement Ztso can simply refuse to run them. diff --git a/param_extraction/chunks/chunk_078.txt.license b/param_extraction/chunks/chunk_078.txt.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/chunk_078.txt.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/chunks/manifest.json b/param_extraction/chunks/manifest.json new file mode 100644 index 0000000000..fc344be23b --- /dev/null +++ b/param_extraction/chunks/manifest.json @@ -0,0 +1,1443 @@ +{ + "total_chunks": 78, + "total_files": 74, + "total_lines": 52700, + "chunks": [ + { + "chunk_id": "chunk_001", + "source_file": "a-st-ext.adoc", + "start_line": 1, + "end_line": 484, + "content_start_line": 1, + "total_source_lines": 484, + "section_headings": [ + "== \"A\" Extension for Atomic Instructions, Version 2.1", + "=== Specifying Ordering of Atomic Instructions", + "=== \"Zalrsc\" Extension for Load-Reserved/Store-Conditional Instructions", + "=== Eventual Success of Store-Conditional Instructions", + "=== \"Zaamo\" Extension for Atomic Memory Operations" + ], + "overlap_from_line": null, + "line_count": 484 + }, + { + "chunk_id": "chunk_002", + "source_file": "b-st-ext.adoc", + "start_line": 1, + "end_line": 3375, + "content_start_line": 1, + "total_source_lines": 3375, + "section_headings": [ + "== Bit Manipulation Extensions", + "=== \"B\" Extension for Bit Manipulation, Version 1.0.0", + "=== Zba: Extension for Address generation, Version 1.0.0", + "=== Zbb: Extension for Basic bit-manipulation, Version 1.0.0", + "==== Logical with negate", + "==== Count leading/trailing zero bits", + "==== Count population", + "==== Integer minimum/maximum", + "==== Sign extension and zero extension", + "==== Bitwise rotation", + "==== OR Combine", + "==== Byte-reverse", + "=== Zbc: Extension for Carry-less multiplication, Version 1.0.0", + "=== Zbs: Extension for Single-bit instructions, Version 1.0.0", + "=== Zbkb: Extension for Bit-manipulation for Cryptography, Version 1.0.0", + "=== Zbkc: Extension for Carry-less multiplication for Cryptography, Version 1.0.0", + "=== Zbkx: Extension for Crossbar permutations, Version 1.0.0", + "=== Instructions (in alphabetical order)", + "==== add.uw", + "==== andn" + ], + "overlap_from_line": null, + "line_count": 3375 + }, + { + "chunk_id": "chunk_003", + "source_file": "bfloat16.adoc", + "start_line": 1, + "end_line": 790, + "content_start_line": 1, + "total_source_lines": 790, + "section_headings": [ + "== \"BF16\" Extensions for BFloat16-precision Floating-Point, Version 1.0", + "=== Introduction", + "=== Intended Audience", + "=== Number Format", + "==== BF16 Operand Format", + "==== BF16 Behavior", + "===== Subnormal Numbers:", + "===== Infinities:", + "===== NaNs", + "===== Scalar NaN Boxing" + ], + "overlap_from_line": null, + "line_count": 790 + }, + { + "chunk_id": "chunk_004", + "source_file": "bibliography.adoc", + "start_line": 1, + "end_line": 4, + "content_start_line": 1, + "total_source_lines": 4, + "section_headings": ["== Bibliography"], + "overlap_from_line": null, + "line_count": 4 + }, + { + "chunk_id": "chunk_005", + "source_file": "bitmanip-examples.adoc", + "start_line": 1, + "end_line": 145, + "content_start_line": 1, + "total_source_lines": 145, + "section_headings": [ + "== Bit Manipulation Extensions Assembly Code Examples", + "=== strlen", + "=== strcmp" + ], + "overlap_from_line": null, + "line_count": 145 + }, + { + "chunk_id": "chunk_006", + "source_file": "c-st-ext.adoc", + "start_line": 1, + "end_line": 931, + "content_start_line": 1, + "total_source_lines": 931, + "section_headings": [ + "== \"C\" Extension for Compressed Instructions, Version 2.0", + "=== Overview", + "=== Compressed Instruction Formats", + "=== Load and Store Instructions", + "==== Stack-Pointer-Based Loads and Stores", + "==== Register-Based Loads and Stores", + "=== Control Transfer Instructions", + "=== Integer Computational Instructions", + "==== Integer Constant-Generation Instructions", + "==== Integer Register-Immediate Operations" + ], + "overlap_from_line": null, + "line_count": 931 + }, + { + "chunk_id": "chunk_007", + "source_file": "calling-convention.adoc", + "start_line": 1, + "end_line": 29, + "content_start_line": 1, + "total_source_lines": 29, + "section_headings": [ + "== Calling Convention for Vector State (Not authoritative - Placeholder Only)" + ], + "overlap_from_line": null, + "line_count": 29 + }, + { + "chunk_id": "chunk_008", + "source_file": "cmo.adoc", + "start_line": 1, + "end_line": 1094, + "content_start_line": 1, + "total_source_lines": 1094, + "section_headings": [ + "== \"CMO\" Extensions for Base Cache Management Operation ISA, Version 1.0.0", + "=== Pseudocode for instruction semantics", + "=== Introduction", + "=== Background", + "==== Memory and Caches", + "==== Cache-Block Operations", + "=== Coherent Agents and Caches", + "==== Memory Ordering", + "===== Preserved Program Order", + "===== Load Values" + ], + "overlap_from_line": null, + "line_count": 1094 + }, + { + "chunk_id": "chunk_009", + "source_file": "colophon.adoc", + "start_line": 1, + "end_line": 465, + "content_start_line": 1, + "total_source_lines": 465, + "section_headings": ["== Preface"], + "overlap_from_line": null, + "line_count": 465 + }, + { + "chunk_id": "chunk_010", + "source_file": "counters.adoc", + "start_line": 1, + "end_line": 237, + "content_start_line": 1, + "total_source_lines": 237, + "section_headings": [ + "== \"Zicntr\" and \"Zihpm\" Extensions for Counters, Version 2.0", + "=== \"Zicntr\" Extension for Base Counters and Timers", + "=== \"Zihpm\" Extension for Hardware Performance Counters" + ], + "overlap_from_line": null, + "line_count": 237 + }, + { + "chunk_id": "chunk_011", + "source_file": "d-st-ext.adoc", + "start_line": 1, + "end_line": 239, + "content_start_line": 1, + "total_source_lines": 239, + "section_headings": [ + "== \"D\" Extension for Double-Precision Floating-Point, Version 2.2", + "=== D Register State", + "=== NaN Boxing of Narrower Values", + "=== Double-Precision Load and Store Instructions", + "=== Double-Precision Floating-Point Computational Instructions", + "=== Double-Precision Floating-Point Conversion and Move Instructions", + "=== Double-Precision Floating-Point Compare Instructions", + "=== Double-Precision Floating-Point Classify Instruction" + ], + "overlap_from_line": null, + "line_count": 239 + }, + { + "chunk_id": "chunk_012", + "source_file": "f-st-ext.adoc", + "start_line": 1, + "end_line": 524, + "content_start_line": 1, + "total_source_lines": 524, + "section_headings": [ + "== \"F\" Extension for Single-Precision Floating-Point, Version 2.2", + "=== F Register State", + "=== Floating-Point Control and Status Register", + "=== NaN Generation and Propagation", + "=== Subnormal Arithmetic", + "=== Single-Precision Load and Store Instructions", + "=== Single-Precision Floating-Point Computational Instructions", + "=== Single-Precision Floating-Point Conversion and Move Instructions", + "=== Single-Precision Floating-Point Compare Instructions", + "=== Single-Precision Floating-Point Classify Instruction" + ], + "overlap_from_line": null, + "line_count": 524 + }, + { + "chunk_id": "chunk_013", + "source_file": "fraclmul.adoc", + "start_line": 1, + "end_line": 175, + "content_start_line": 1, + "total_source_lines": 175, + "section_headings": ["=== Fractional Lmul example"], + "overlap_from_line": null, + "line_count": 175 + }, + { + "chunk_id": "chunk_014", + "source_file": "hypervisor.adoc", + "start_line": 1, + "end_line": 2932, + "content_start_line": 1, + "total_source_lines": 2932, + "section_headings": [ + "== \"H\" Extension for Hypervisor Support, Version 1.0", + "=== Privilege Modes", + "=== Hypervisor and Virtual Supervisor CSRs", + "==== Hypervisor Status (`hstatus`) Register", + "==== Hypervisor Trap Delegation (`hedeleg` and `hideleg`) Registers", + "==== Hypervisor Interrupt (`hvip`, `hip`, and `hie`) Registers", + "==== Hypervisor Guest External Interrupt Registers (`hgeip` and `hgeie`)", + "==== Hypervisor Environment Configuration Register (`henvcfg`)", + "==== Hypervisor Counter-Enable (`hcounteren`) Register", + "==== Hypervisor Time Delta (`htimedelta`) Register", + "==== Hypervisor Trap Value (`htval`) Register", + "==== Hypervisor Trap Instruction (`htinst`) Register", + "==== Hypervisor Guest Address Translation and Protection (`hgatp`) Register", + "==== Virtual Supervisor Status (`vsstatus`) Register", + "==== Virtual Supervisor Interrupt (`vsip` and `vsie`) Registers", + "==== Virtual Supervisor Trap Vector Base Address (`vstvec`) Register", + "==== Virtual Supervisor Scratch (`vsscratch`) Register", + "==== Virtual Supervisor Exception Program Counter (`vsepc`) Register", + "==== Virtual Supervisor Cause (`vscause`) Register", + "==== Virtual Supervisor Trap Value (`vstval`) Register" + ], + "overlap_from_line": null, + "line_count": 2932 + }, + { + "chunk_id": "chunk_015", + "source_file": "index.adoc", + "start_line": 1, + "end_line": 2, + "content_start_line": 1, + "total_source_lines": 2, + "section_headings": ["== Index"], + "overlap_from_line": null, + "line_count": 2 + }, + { + "chunk_id": "chunk_016", + "source_file": "indirect-csr.adoc", + "start_line": 1, + "end_line": 333, + "content_start_line": 1, + "total_source_lines": 333, + "section_headings": [ + "== \"Smcsrind/Sscsrind\" Indirect CSR Access, Version 1.0", + "=== Introduction", + "=== Machine-level CSRs", + "=== Supervisor-level CSRs", + "=== Virtual Supervisor-level CSRs", + "=== Access control by the state-enable CSRs" + ], + "overlap_from_line": null, + "line_count": 333 + }, + { + "chunk_id": "chunk_017", + "source_file": "intro.adoc", + "start_line": 1, + "end_line": 696, + "content_start_line": 1, + "total_source_lines": 696, + "section_headings": [ + "== Introduction", + "=== RISC-V Hardware Platform Terminology", + "=== RISC-V Software Execution Environments and Harts", + "=== RISC-V ISA Overview", + "=== Memory", + "=== Base Instruction-Length Encoding", + "=== Exceptions, Traps, and Interrupts", + "=== UNSPECIFIED Behaviors and Values" + ], + "overlap_from_line": null, + "line_count": 696 + }, + { + "chunk_id": "chunk_018", + "source_file": "m-st-ext.adoc", + "start_line": 1, + "end_line": 157, + "content_start_line": 1, + "total_source_lines": 157, + "section_headings": [ + "== \"M\" Extension for Integer Multiplication and Division, Version 2.0", + "=== Multiplication Operations", + "=== Division Operations", + "=== `Zmmul` Extension, Version 1.0" + ], + "overlap_from_line": null, + "line_count": 157 + }, + { + "chunk_id": "chunk_019", + "source_file": "machine.adoc", + "start_line": 1, + "end_line": 3334, + "content_start_line": 1, + "total_source_lines": 3629, + "section_headings": [ + "== Machine-Level ISA, Version 1.13", + "=== Machine-Level CSRs", + "==== Machine ISA (`misa`) Register", + "==== Machine Vendor ID (`mvendorid`) Register", + "==== Machine Architecture ID (`marchid`) Register", + "==== Machine Implementation ID (`mimpid`) Register", + "==== Hart ID (`mhartid`) Register", + "==== Machine Status (`mstatus` and `mstatush`) Registers", + "===== Privilege and Global Interrupt-Enable Stack in `mstatus` register", + "===== Double Trap Control in `mstatus` Register", + "===== Base ISA Control in `mstatus` Register", + "===== Memory Privilege in `mstatus` Register", + "===== Endianness Control in `mstatus` and `mstatush` Registers", + "===== Virtualization Support in `mstatus` Register", + "===== Extension Context Status in `mstatus` Register", + "===== Previous Expected Landing Pad (ELP) State in `mstatus` Register", + "==== Machine Trap-Vector Base-Address (`mtvec`) Register", + "==== Machine Trap Delegation (`medeleg` and `mideleg`) Registers", + "==== Machine Interrupt (`mip` and `mie`) Registers", + "==== Hardware Performance Monitor" + ], + "overlap_from_line": null, + "line_count": 3334 + }, + { + "chunk_id": "chunk_020", + "source_file": "machine.adoc", + "start_line": 3305, + "end_line": 3629, + "content_start_line": 3335, + "total_source_lines": 3629, + "section_headings": [ + "==== Physical Memory Protection CSRs", + "===== Address Matching", + "===== Locking and Privilege Mode", + "===== Priority and Matching Logic", + "==== Physical Memory Protection and Paging" + ], + "overlap_from_line": 3305, + "line_count": 325 + }, + { + "chunk_id": "chunk_021", + "source_file": "mm-alloy.adoc", + "start_line": 1, + "end_line": 239, + "content_start_line": 1, + "total_source_lines": 239, + "section_headings": ["== Formal Axiomatic Specification in Alloy"], + "overlap_from_line": null, + "line_count": 239 + }, + { + "chunk_id": "chunk_022", + "source_file": "mm-eplan.adoc", + "start_line": 1, + "end_line": 1850, + "content_start_line": 1, + "total_source_lines": 1850, + "section_headings": [ + "== RVWMO Explanatory Material, Version 0.1", + "=== Why RVWMO?", + "=== Litmus Tests", + "=== Explaining the RVWMO Rules", + "==== Preserved Program Order and Global Memory Order", + "==== Load value axiom", + "==== Atomicity axiom", + "==== Progress axiom", + "==== Overlapping-Address Orderings (<>)", + "==== Fences (<>)" + ], + "overlap_from_line": null, + "line_count": 1850 + }, + { + "chunk_id": "chunk_023", + "source_file": "mm-formal.adoc", + "start_line": 1, + "end_line": 1425, + "content_start_line": 1, + "total_source_lines": 1425, + "section_headings": [ + "== Formal Memory Model Specifications, Version 0.1", + "=== Formal Axiomatic Specification in Alloy", + "=== Formal Axiomatic Specification in Herd", + "=== An Operational Memory Model", + "==== Intra-instruction Pseudocode Execution", + "==== Instruction Instance State", + "==== Hart State", + "==== Shared Memory State", + "==== Transitions", + "===== Fetch instruction" + ], + "overlap_from_line": null, + "line_count": 1425 + }, + { + "chunk_id": "chunk_024", + "source_file": "mm-herd.adoc", + "start_line": 1, + "end_line": 155, + "content_start_line": 1, + "total_source_lines": 155, + "section_headings": ["== Formal Axiomatic Specification in Herd"], + "overlap_from_line": null, + "line_count": 155 + }, + { + "chunk_id": "chunk_025", + "source_file": "naming.adoc", + "start_line": 1, + "end_line": 222, + "content_start_line": 1, + "total_source_lines": 222, + "section_headings": [ + "== ISA Extension Naming Conventions", + "=== Case Sensitivity", + "=== Base Integer ISA", + "=== Instruction-Set Extension Names", + "=== Underscores", + "=== Additional Standard Unprivileged Extension Names", + "=== Supervisor-level Instruction-Set Extension Names", + "=== Hypervisor-level Instruction-Set Extension Names", + "=== Machine-level Instruction-Set Extension Names", + "=== Non-Standard Extension Names" + ], + "overlap_from_line": null, + "line_count": 222 + }, + { + "chunk_id": "chunk_026", + "source_file": "priv-cfi.adoc", + "start_line": 1, + "end_line": 373, + "content_start_line": 1, + "total_source_lines": 373, + "section_headings": [ + "== Control-flow Integrity (CFI)", + "=== Landing Pad (Zicfilp)", + "==== Landing-Pad-Enabled (LPE) State", + "==== Preserving Expected Landing Pad State on Traps", + "=== Shadow Stack (Zicfiss)", + "==== Shadow Stack Pointer (`ssp`) CSR access control", + "==== Shadow-Stack-Enabled (SSE) State", + "==== Shadow Stack Memory Protection" + ], + "overlap_from_line": null, + "line_count": 373 + }, + { + "chunk_id": "chunk_027", + "source_file": "priv-csrs.adoc", + "start_line": 1, + "end_line": 1272, + "content_start_line": 1, + "total_source_lines": 1272, + "section_headings": [ + "== Control and Status Registers (CSRs)", + "=== CSR Address Mapping Conventions", + "=== CSR Listing", + "=== CSR Field Specifications", + "==== Reserved Writes Preserve Values, Reads Ignore Values (WPRI)", + "==== Write/Read Only Legal Values (WLRL)", + "==== Write Any Values, Reads Legal Values (WARL)", + "=== CSR Field Modulation", + "=== Implicit Reads of CSRs", + "=== CSR Width Modulation" + ], + "overlap_from_line": null, + "line_count": 1272 + }, + { + "chunk_id": "chunk_028", + "source_file": "priv-history.adoc", + "start_line": 1, + "end_line": 22, + "content_start_line": 1, + "total_source_lines": 22, + "section_headings": ["== History", "=== Research Funding at UC Berkeley"], + "overlap_from_line": null, + "line_count": 22 + }, + { + "chunk_id": "chunk_029", + "source_file": "priv-insns.adoc", + "start_line": 1, + "end_line": 12, + "content_start_line": 1, + "total_source_lines": 12, + "section_headings": ["== RISC-V Privileged Instruction Set Listings"], + "overlap_from_line": null, + "line_count": 12 + }, + { + "chunk_id": "chunk_030", + "source_file": "priv-intro.adoc", + "start_line": 1, + "end_line": 217, + "content_start_line": 1, + "total_source_lines": 217, + "section_headings": [ + "== Introduction", + "=== RISC-V Privileged Software Stack Terminology", + "=== Privilege Levels", + "=== Debug Mode" + ], + "overlap_from_line": null, + "line_count": 217 + }, + { + "chunk_id": "chunk_031", + "source_file": "priv-preface.adoc", + "start_line": 1, + "end_line": 598, + "content_start_line": 1, + "total_source_lines": 598, + "section_headings": ["== Preface"], + "overlap_from_line": null, + "line_count": 598 + }, + { + "chunk_id": "chunk_032", + "source_file": "priv-rationale.adoc", + "start_line": 1, + "end_line": 80, + "content_start_line": 1, + "total_source_lines": 80, + "section_headings": [ + "== Historical Rationale for Extensions", + "=== \"Smepmp\" Extension for PMP Enhancements for memory access and execution prevention in Machine mode" + ], + "overlap_from_line": null, + "line_count": 80 + }, + { + "chunk_id": "chunk_033", + "source_file": "q-st-ext.adoc", + "start_line": 1, + "end_line": 120, + "content_start_line": 1, + "total_source_lines": 120, + "section_headings": [ + "== \"Q\" Extension for Quad-Precision Floating-Point, Version 2.2", + "=== Quad-Precision Load and Store Instructions", + "=== Quad-Precision Computational Instructions", + "=== Quad-Precision Convert and Move Instructions", + "=== Quad-Precision Floating-Point Compare Instructions", + "=== Quad-Precision Floating-Point Classify Instruction" + ], + "overlap_from_line": null, + "line_count": 120 + }, + { + "chunk_id": "chunk_034", + "source_file": "rationale.adoc", + "start_line": 1, + "end_line": 107, + "content_start_line": 1, + "total_source_lines": 107, + "section_headings": [ + "== Historical Rationale for Extensions", + "=== \"Zihintpause\" Extension for Pause Hint", + "=== \"Zicond\" Extension for Integer Conditional Operations", + "=== \"Zacas\" Extension for Atomic Compare-and-Swap (CAS) Instructions", + "=== \"Zabha\" Extension for Byte and Halfword Atomic Memory Operations, Version 1.0" + ], + "overlap_from_line": null, + "line_count": 107 + }, + { + "chunk_id": "chunk_035", + "source_file": "riscv-privileged.adoc", + "start_line": 1, + "end_line": 136, + "content_start_line": 1, + "total_source_lines": 136, + "section_headings": [], + "overlap_from_line": null, + "line_count": 136 + }, + { + "chunk_id": "chunk_036", + "source_file": "riscv-unprivileged.adoc", + "start_line": 1, + "end_line": 206, + "content_start_line": 1, + "total_source_lines": 206, + "section_headings": [], + "overlap_from_line": null, + "line_count": 206 + }, + { + "chunk_id": "chunk_037", + "source_file": "rnmi.adoc", + "start_line": 1, + "end_line": 166, + "content_start_line": 1, + "total_source_lines": 166, + "section_headings": [ + "== \"Smrnmi\" Extension for Resumable Non-Maskable Interrupts, Version 1.0", + "=== RNMI Interrupt Signals", + "=== RNMI Handler Addresses", + "=== RNMI CSRs", + "=== MNRET Instruction", + "=== RNMI Operation" + ], + "overlap_from_line": null, + "line_count": 166 + }, + { + "chunk_id": "chunk_038", + "source_file": "rv-32-64g.adoc", + "start_line": 1, + "end_line": 461, + "content_start_line": 1, + "total_source_lines": 461, + "section_headings": ["== RV32/64G Instruction Set Listings"], + "overlap_from_line": null, + "line_count": 461 + }, + { + "chunk_id": "chunk_039", + "source_file": "rv32.adoc", + "start_line": 1, + "end_line": 1105, + "content_start_line": 1, + "total_source_lines": 1105, + "section_headings": [ + "== RV32I Base Integer Instruction Set, Version 2.1", + "=== Programmers' Model for Base Integer ISA", + "=== Base Instruction Formats", + "=== Immediate Encoding Variants", + "=== Integer Computational Instructions", + "==== Integer Register-Immediate Instructions", + "==== Integer Register-Register Instructions", + "==== NOP Instruction", + "=== Control Transfer Instructions", + "==== Unconditional Jumps" + ], + "overlap_from_line": null, + "line_count": 1105 + }, + { + "chunk_id": "chunk_040", + "source_file": "rv32e.adoc", + "start_line": 1, + "end_line": 47, + "content_start_line": 1, + "total_source_lines": 47, + "section_headings": [ + "== RV32E and RV64E Base Integer Instruction Sets, Version 2.0", + "=== RV32E and RV64E Programmers\u2019 Model", + "=== RV32E and RV64E Instruction Set Encoding" + ], + "overlap_from_line": null, + "line_count": 47 + }, + { + "chunk_id": "chunk_041", + "source_file": "rv64.adoc", + "start_line": 1, + "end_line": 260, + "content_start_line": 1, + "total_source_lines": 260, + "section_headings": [ + "== RV64I Base Integer Instruction Set, Version 2.1", + "=== Register State", + "=== Integer Computational Instructions", + "==== Integer Register-Immediate Instructions", + "==== Integer Register-Register Operations", + "=== Load and Store Instructions", + "=== HINT Instructions" + ], + "overlap_from_line": null, + "line_count": 260 + }, + { + "chunk_id": "chunk_042", + "source_file": "rvwmo.adoc", + "start_line": 1, + "end_line": 817, + "content_start_line": 1, + "total_source_lines": 817, + "section_headings": [ + "== RVWMO Memory Consistency Model, Version 2.0", + "=== Definition of the RVWMO Memory Model", + "==== Memory Model Primitives", + "==== Syntactic Dependencies", + "==== Preserved Program Order", + "==== Memory Model Axioms", + "===== Load Value Axiom", + "===== Atomicity Axiom", + "===== Progress Axiom", + "=== CSR Dependency Tracking Granularity" + ], + "overlap_from_line": null, + "line_count": 817 + }, + { + "chunk_id": "chunk_043", + "source_file": "scalar-crypto.adoc", + "start_line": 1, + "end_line": 3448, + "content_start_line": 1, + "total_source_lines": 5590, + "section_headings": [ + "== Cryptography Extensions: Scalar & Entropy Source Instructions, Version 1.0.1", + "=== Introduction", + "==== Intended Audience", + "==== Sail Specifications", + "==== Policies", + "=== Extensions Overview", + "==== `Zbkb` - Bitmanip instructions for Cryptography", + "==== `Zbkc` - Carry-less multiply instructions", + "==== `Zbkx` - Crossbar permutation instructions", + "==== `Zknd` - NIST Suite: AES Decryption", + "==== `Zkne` - NIST Suite: AES Encryption", + "==== `Zknh` - NIST Suite: Hash Function Instructions", + "==== `Zksed` - ShangMi Suite: SM4 Block Cipher Instructions", + "==== `Zksh` - ShangMi Suite: SM3 Hash Function Instructions", + "==== `Zkr` - Entropy Source Extension", + "==== `Zkn` - NIST Algorithm Suite", + "==== `Zks` - ShangMi Algorithm Suite", + "==== `Zk` - Standard scalar cryptography extension", + "==== `Zkt` - Data Independent Execution Latency", + "=== Instructions" + ], + "overlap_from_line": null, + "line_count": 3448 + }, + { + "chunk_id": "chunk_044", + "source_file": "scalar-crypto.adoc", + "start_line": 3419, + "end_line": 5590, + "content_start_line": 3449, + "total_source_lines": 5590, + "section_headings": [ + "==== zip", + "=== Entropy Source", + "==== The `seed` CSR", + "==== Entropy Source Requirements", + "===== NIST SP 800-90B / FIPS 140-3 Requirements", + "===== BSI AIS-31 PTG.2 / Common Criteria Requirements", + "===== Virtual Sources: Security Requirement", + "==== Access Control to `seed`", + "=== Data Independent Execution Latency Subset: Zkt", + "==== Scope and Goal", + "==== Background", + "==== Specific Instruction Rationale", + "==== Programming Information", + "==== Zkt listings", + "===== RVI (Base Instruction Set)", + "===== RVM (Multiply)", + "===== RVC (Compressed)", + "===== Zcb Extension", + "===== RVK (Scalar Cryptography)", + "===== RVB (Bitmanip)" + ], + "overlap_from_line": 3419, + "line_count": 2172 + }, + { + "chunk_id": "chunk_045", + "source_file": "smcdeleg.adoc", + "start_line": 1, + "end_line": 147, + "content_start_line": 1, + "total_source_lines": 147, + "section_headings": [ + "== \"Smcdeleg/Ssccfg\" Counter Delegation Extensions, Version 1.0", + "=== Counter Delegation", + "=== Supervisor Counter Inhibit (`scountinhibit`) Register", + "=== Virtualizing `scountovf`", + "=== Virtualizing Local-Counter-Overflow Interrupts" + ], + "overlap_from_line": null, + "line_count": 147 + }, + { + "chunk_id": "chunk_046", + "source_file": "smcntrpmf.adoc", + "start_line": 1, + "end_line": 69, + "content_start_line": 1, + "total_source_lines": 69, + "section_headings": [ + "== \"Smcntrpmf\" Cycle and Instret Privilege Mode Filtering, Version 1.0", + "=== Introduction", + "=== CSRs", + "==== Machine Counter Configuration (`mcyclecfg`, `minstretcfg`) Registers", + "=== Counter Behavior" + ], + "overlap_from_line": null, + "line_count": 69 + }, + { + "chunk_id": "chunk_047", + "source_file": "smctr.adoc", + "start_line": 1, + "end_line": 763, + "content_start_line": 1, + "total_source_lines": 763, + "section_headings": [ + "== \"Smctr\" Control Transfer Records Extension, Version 1.0", + "=== CSRs", + "==== Machine Control Transfer Records Control Register (`mctrctl`)", + "==== Supervisor Control Transfer Records Control Register (`sctrctl`)", + "==== Virtual Supervisor Control Transfer Records Control Register (`vsctrctl`)", + "==== Supervisor Control Transfer Records Depth Register (`sctrdepth`)", + "==== Supervisor Control Transfer Records Status Register (`sctrstatus`)", + "=== Entry Registers", + "==== Control Transfer Record Source Register (`ctrsource`)", + "==== Control Transfer Record Target Register (`ctrtarget`)" + ], + "overlap_from_line": null, + "line_count": 763 + }, + { + "chunk_id": "chunk_048", + "source_file": "smdbltrp.adoc", + "start_line": 1, + "end_line": 17, + "content_start_line": 1, + "total_source_lines": 17, + "section_headings": [ + "== \"Smdbltrp\" Double Trap Extension, Version 1.0" + ], + "overlap_from_line": null, + "line_count": 17 + }, + { + "chunk_id": "chunk_049", + "source_file": "smepmp.adoc", + "start_line": 1, + "end_line": 77, + "content_start_line": 1, + "total_source_lines": 77, + "section_headings": [ + "== \"Smepmp\" Extension for PMP Enhancements for memory access and execution prevention in Machine mode, Version 1.0", + "=== Threat model", + "=== Smepmp Physical Memory Protection Rules", + "=== Smepmp software discovery" + ], + "overlap_from_line": null, + "line_count": 77 + }, + { + "chunk_id": "chunk_050", + "source_file": "smstateen.adoc", + "start_line": 1, + "end_line": 373, + "content_start_line": 1, + "total_source_lines": 373, + "section_headings": [ + "== \"Smstateen/Ssstateen\" Extensions, Version 1.0", + "=== State Enable Extensions", + "=== State Enable 0 Registers", + "=== Usage" + ], + "overlap_from_line": null, + "line_count": 373 + }, + { + "chunk_id": "chunk_051", + "source_file": "sscofpmf.adoc", + "start_line": 1, + "end_line": 126, + "content_start_line": 1, + "total_source_lines": 126, + "section_headings": [ + "== \"Sscofpmf\" Extension for Count Overflow and Mode-Based Filtering, Version 1.0", + "=== Count Overflow Control", + "=== Supervisor Count Overflow (`scountovf`) Register" + ], + "overlap_from_line": null, + "line_count": 126 + }, + { + "chunk_id": "chunk_052", + "source_file": "ssdbltrp.adoc", + "start_line": 1, + "end_line": 15, + "content_start_line": 1, + "total_source_lines": 15, + "section_headings": [ + "== \"Ssdbltrp\" Double Trap Extension, Version 1.0" + ], + "overlap_from_line": null, + "line_count": 15 + }, + { + "chunk_id": "chunk_053", + "source_file": "sstc.adoc", + "start_line": 1, + "end_line": 24, + "content_start_line": 1, + "total_source_lines": 24, + "section_headings": [ + "== \"Sstc\" Extension for Supervisor-mode Timer Interrupts, Version 1.0" + ], + "overlap_from_line": null, + "line_count": 24 + }, + { + "chunk_id": "chunk_054", + "source_file": "supervisor.adoc", + "start_line": 1, + "end_line": 2630, + "content_start_line": 1, + "total_source_lines": 2630, + "section_headings": [ + "== Supervisor-Level ISA, Version 1.13", + "=== Supervisor CSRs", + "==== Supervisor Status (`sstatus`) Register", + "===== Base ISA Control in `sstatus` Register", + "===== Memory Privilege in `sstatus` Register", + "===== Endianness Control in `sstatus` Register", + "===== Previous Expected Landing Pad (ELP) State in `sstatus` Register", + "===== Double Trap Control in `sstatus` Register", + "==== Supervisor Trap Vector Base Address (`stvec`) Register", + "==== Supervisor Interrupt (`sip` and `sie`) Registers", + "==== Supervisor Timers and Performance Counters", + "==== Counter-Enable (`scounteren`) Register", + "==== Supervisor Scratch (`sscratch`) Register", + "==== Supervisor Exception Program Counter (`sepc`) Register", + "==== Supervisor Cause (`scause`) Register", + "==== Supervisor Trap Value (`stval`) Register", + "==== Supervisor Environment Configuration (`senvcfg`) Register", + "==== Supervisor Address Translation and Protection (`satp`) Register", + "==== Supervisor Timer (`stimecmp`) Register", + "=== Supervisor Instructions" + ], + "overlap_from_line": null, + "line_count": 2630 + }, + { + "chunk_id": "chunk_055", + "source_file": "symbols.adoc", + "start_line": 1, + "end_line": 17, + "content_start_line": 1, + "total_source_lines": 17, + "section_headings": [], + "overlap_from_line": null, + "line_count": 17 + }, + { + "chunk_id": "chunk_056", + "source_file": "unpriv-cfi.adoc", + "start_line": 1, + "end_line": 894, + "content_start_line": 1, + "total_source_lines": 894, + "section_headings": [ + "== Control-flow Integrity (CFI)", + "=== Landing Pad (Zicfilp)", + "==== Landing Pad Enforcement", + "==== Landing Pad Instruction", + "=== Shadow Stack (Zicfiss)", + "==== Zicfiss Instructions Summary", + "==== Shadow Stack Pointer (`ssp`)", + "==== Zicfiss Instructions", + "==== Push to the Shadow Stack", + "==== Pop from the Shadow Stack" + ], + "overlap_from_line": null, + "line_count": 894 + }, + { + "chunk_id": "chunk_057", + "source_file": "v-st-ext.adoc", + "start_line": 1, + "end_line": 3393, + "content_start_line": 1, + "total_source_lines": 5396, + "section_headings": [ + "== \"V\" Standard Extension for Vector Operations, Version 1.0", + "=== Introduction", + "=== Implementation-defined Constant Parameters", + "=== Vector Extension Programmer's Model", + "==== Vector Registers", + "==== Vector Context Status in `mstatus`", + "==== Vector Context Status in `vsstatus`", + "==== Vector Type (`vtype`) Register", + "===== Vector Selected Element Width (`vsew[2:0]`)", + "===== Vector Register Grouping (`vlmul[2:0]`)", + "===== Vector Tail Agnostic and Vector Mask Agnostic `vta` and `vma`", + "===== Vector Type Illegal (`vill`)", + "==== Vector Length (`vl`) Register", + "==== Vector Byte Length (`vlenb`) Register", + "==== Vector Start Index (`vstart`) Register", + "==== Vector Fixed-Point Rounding Mode (`vxrm`) Register", + "==== Vector Fixed-Point Saturation Flag (`vxsat`)", + "==== Vector Control and Status (`vcsr`) Register", + "==== State of Vector Extension at Reset", + "=== Mapping of Vector Elements to Vector Register State" + ], + "overlap_from_line": null, + "line_count": 3393 + }, + { + "chunk_id": "chunk_058", + "source_file": "v-st-ext.adoc", + "start_line": 3386, + "end_line": 5396, + "content_start_line": 3394, + "total_source_lines": 5396, + "section_headings": [ + "==== Vector Single-Width Floating-Point Fused Multiply-Add Instructions", + "==== Vector Widening Floating-Point Fused Multiply-Add Instructions", + "==== Vector Floating-Point Square-Root Instruction", + "==== Vector Floating-Point Reciprocal Square-Root Estimate Instruction", + "==== Vector Floating-Point Reciprocal Estimate Instruction", + "==== Vector Floating-Point MIN/MAX Instructions", + "==== Vector Floating-Point Sign-Injection Instructions", + "==== Vector Floating-Point Compare Instructions", + "==== Vector Floating-Point Classify Instruction", + "==== Vector Floating-Point Merge Instruction", + "==== Vector Floating-Point Move Instruction", + "==== Single-Width Floating-Point/Integer Type-Convert Instructions", + "==== Widening Floating-Point/Integer Type-Convert Instructions", + "==== Narrowing Floating-Point/Integer Type-Convert Instructions", + "=== Vector Reduction Operations", + "==== Vector Single-Width Integer Reduction Instructions", + "==== Vector Widening Integer Reduction Instructions", + "==== Vector Single-Width Floating-Point Reduction Instructions", + "===== Vector Ordered Single-Width Floating-Point Sum Reduction", + "===== Vector Unordered Single-Width Floating-Point Sum Reduction" + ], + "overlap_from_line": 3386, + "line_count": 2011 + }, + { + "chunk_id": "chunk_059", + "source_file": "vector-crypto.adoc", + "start_line": 1, + "end_line": 3340, + "content_start_line": 1, + "total_source_lines": 4966, + "section_headings": [ + "== Cryptography Extensions: Vector Instructions, Version 1.0", + "=== Introduction", + "==== Intended Audience", + "==== Sail Specifications", + "==== Policies", + "==== Element Groups", + "==== Instruction Constraints", + "==== Vector-Scalar Instructions", + "==== Software Portability", + "=== Extensions Overview", + "==== `Zvbb` - Vector Basic Bit-manipulation", + "==== `Zvbc` - Vector Carry-less Multiplication", + "==== `Zvkb` - Vector Cryptography Bit-manipulation", + "==== `Zvkg` - Vector GCM/GMAC", + "==== `Zvkned` - NIST Suite: Vector AES Block Cipher", + "==== `Zvknh[ab]` - NIST Suite: Vector SHA-2 Secure Hash", + "==== `Zvksed` - ShangMi Suite: SM4 Block Cipher", + "==== `Zvksh` - ShangMi Suite: SM3 Secure Hash", + "==== `Zvkn` - NIST Algorithm Suite", + "==== `Zvknc` - NIST Algorithm Suite with carry-less multiply" + ], + "overlap_from_line": null, + "line_count": 3340 + }, + { + "chunk_id": "chunk_060", + "source_file": "vector-crypto.adoc", + "start_line": 3311, + "end_line": 4966, + "content_start_line": 3341, + "total_source_lines": 4966, + "section_headings": [ + "==== vsha2ms.vv", + "==== vsm3c.vi", + "==== vsm3me.vv", + "==== vsm4k.vi", + "==== vsm4r.[vv,vs]", + "==== vwsll.[vv,vx,vi]", + "=== Crypto Vector Cryptographic Instructions", + "=== Vector Bitmanip and Carry-less Multiply Instructions", + "=== Supporting Sail Code" + ], + "overlap_from_line": 3311, + "line_count": 1656 + }, + { + "chunk_id": "chunk_061", + "source_file": "vector-examples.adoc", + "start_line": 1, + "end_line": 125, + "content_start_line": 1, + "total_source_lines": 125, + "section_headings": [ + "== Vector Assembly Code Examples", + "=== Vector-vector add example", + "=== Example with mixed-width mask and compute.", + "=== Memcpy example", + "=== Conditional example", + "=== SAXPY example", + "=== SGEMM example", + "=== Division approximation example", + "=== Square root approximation example", + "=== C standard library strcmp example" + ], + "overlap_from_line": null, + "line_count": 125 + }, + { + "chunk_id": "chunk_062", + "source_file": "zabha.adoc", + "start_line": 1, + "end_line": 68, + "content_start_line": 1, + "total_source_lines": 68, + "section_headings": [ + "== \"Zabha\" Extension for Byte and Halfword Atomic Memory Operations, Version 1.0", + "=== Byte and Halfword Atomic Memory Operation Instructions" + ], + "overlap_from_line": null, + "line_count": 68 + }, + { + "chunk_id": "chunk_063", + "source_file": "zacas.adoc", + "start_line": 1, + "end_line": 225, + "content_start_line": 1, + "total_source_lines": 225, + "section_headings": [ + "== \"Zacas\" Extension for Atomic Compare-and-Swap (CAS) Instructions, Version 1.0.0", + "=== Word/Doubleword/Quadword CAS (AMOCAS.W/D/Q) Instructions" + ], + "overlap_from_line": null, + "line_count": 225 + }, + { + "chunk_id": "chunk_064", + "source_file": "zalasr.adoc", + "start_line": 1, + "end_line": 135, + "content_start_line": 1, + "total_source_lines": 135, + "section_headings": [ + "== \"Zalasr\" Atomic Load-Acquire and Store-Release Instructions, Version 1.0", + "=== Load-Acquire and Store-Release Instructions", + "=== Load Acquire", + "=== Store Release" + ], + "overlap_from_line": null, + "line_count": 135 + }, + { + "chunk_id": "chunk_065", + "source_file": "zawrs.adoc", + "start_line": 1, + "end_line": 103, + "content_start_line": 1, + "total_source_lines": 103, + "section_headings": [ + "== \"Zawrs\" Extension for Wait-on-Reservation-Set instructions, Version 1.01", + "=== Wait-on-Reservation-Set Instructions" + ], + "overlap_from_line": null, + "line_count": 103 + }, + { + "chunk_id": "chunk_066", + "source_file": "zc.adoc", + "start_line": 1, + "end_line": 2587, + "content_start_line": 1, + "total_source_lines": 2587, + "section_headings": [ + "== \"Zc*\" Extension for Code Size Reduction, Version 1.0.0", + "=== Zc* Overview", + "=== C", + "=== Zce", + "=== MISA.C", + "=== Zca", + "=== Zcf (RV32 only)", + "=== Zcd", + "=== Zcb", + "=== Zcmp", + "=== Zcmt", + "=== Zc instruction formats", + "=== Zcb instructions", + "==== c.lbu", + "==== c.lhu", + "==== c.lh", + "==== c.sb", + "==== c.sh", + "==== c.zext.b", + "==== c.sext.b" + ], + "overlap_from_line": null, + "line_count": 2587 + }, + { + "chunk_id": "chunk_067", + "source_file": "zfa.adoc", + "start_line": 1, + "end_line": 261, + "content_start_line": 1, + "total_source_lines": 261, + "section_headings": [ + "== \"Zfa\" Extension for Additional Floating-Point Instructions, Version 1.0", + "=== Load-Immediate Instructions", + "=== Minimum and Maximum Instructions", + "=== Round-to-Integer Instructions", + "=== Modular Convert-to-Integer Instruction", + "=== Move Instructions", + "=== Comparison Instructions" + ], + "overlap_from_line": null, + "line_count": 261 + }, + { + "chunk_id": "chunk_068", + "source_file": "zfh.adoc", + "start_line": 1, + "end_line": 186, + "content_start_line": 1, + "total_source_lines": 186, + "section_headings": [ + "== \"Zfh\" and \"Zfhmin\" Extensions for Half-Precision Floating-Point, Version 1.0", + "=== Half-Precision Load and Store Instructions", + "=== Half-Precision Computational Instructions", + "=== Half-Precision Conversion and Move Instructions", + "=== Half-Precision Floating-Point Compare Instructions", + "=== Half-Precision Floating-Point Classify Instruction", + "=== \"Zfhmin\" Standard Extension for Minimal Half-Precision Floating-Point" + ], + "overlap_from_line": null, + "line_count": 186 + }, + { + "chunk_id": "chunk_069", + "source_file": "zfinx.adoc", + "start_line": 1, + "end_line": 162, + "content_start_line": 1, + "total_source_lines": 162, + "section_headings": [ + "== \"Zfinx\", \"Zdinx\", \"Zhinx\", \"Zhinxmin\" Extensions for Floating-Point in Integer Registers, Version 1.0", + "=== Processing of Narrower Values", + "=== Zdinx", + "=== Processing of Wider Values", + "=== Zhinx", + "=== Zhinxmin", + "=== Privileged Architecture Implications" + ], + "overlap_from_line": null, + "line_count": 162 + }, + { + "chunk_id": "chunk_070", + "source_file": "zicond.adoc", + "start_line": 1, + "end_line": 187, + "content_start_line": 1, + "total_source_lines": 187, + "section_headings": [ + "== \"Zicond\" Extension for Integer Conditional Operations, Version 1.0.0", + "=== Instructions (in alphabetical order)", + "==== czero.eqz", + "==== czero.nez", + "=== Usage examples", + "==== Instruction sequences" + ], + "overlap_from_line": null, + "line_count": 187 + }, + { + "chunk_id": "chunk_071", + "source_file": "zicsr.adoc", + "start_line": 1, + "end_line": 254, + "content_start_line": 1, + "total_source_lines": 254, + "section_headings": [ + "== \"Zicsr\", Extension for Control and Status Register (CSR) Instructions, Version 2.0", + "=== CSR Instructions", + "==== CSR Access Ordering" + ], + "overlap_from_line": null, + "line_count": 254 + }, + { + "chunk_id": "chunk_072", + "source_file": "zifencei.adoc", + "start_line": 1, + "end_line": 129, + "content_start_line": 1, + "total_source_lines": 129, + "section_headings": [ + "== \"Zifencei\" Extension for Instruction-Fetch Fence, Version 2.0" + ], + "overlap_from_line": null, + "line_count": 129 + }, + { + "chunk_id": "chunk_073", + "source_file": "zihintntl.adoc", + "start_line": 1, + "end_line": 189, + "content_start_line": 1, + "total_source_lines": 189, + "section_headings": [ + "== \"Zihintntl\" Extension for Non-Temporal Locality Hints, Version 1.0" + ], + "overlap_from_line": null, + "line_count": 189 + }, + { + "chunk_id": "chunk_074", + "source_file": "zihintpause.adoc", + "start_line": 1, + "end_line": 56, + "content_start_line": 1, + "total_source_lines": 56, + "section_headings": [ + "== \"Zihintpause\" Extension for Pause Hint, Version 2.0" + ], + "overlap_from_line": null, + "line_count": 56 + }, + { + "chunk_id": "chunk_075", + "source_file": "zilsd.adoc", + "start_line": 1, + "end_line": 315, + "content_start_line": 1, + "total_source_lines": 315, + "section_headings": [ + "== \"Zilsd\", \"Zclsd\" Extensions for Load/Store pair for RV32, Version 1.0", + "=== Load/Store pair instructions (Zilsd)", + "=== Compressed Load/Store pair instructions (Zclsd)", + "=== Use of x0 as operand", + "=== Exception Handling", + "=== Instructions", + "==== ld", + "==== sd", + "==== c.ldsp", + "==== c.sdsp" + ], + "overlap_from_line": null, + "line_count": 315 + }, + { + "chunk_id": "chunk_076", + "source_file": "zimop.adoc", + "start_line": 1, + "end_line": 113, + "content_start_line": 1, + "total_source_lines": 113, + "section_headings": [ + "== \"Zimop\" Extension for May-Be-Operations, Version 1.0", + "=== \"Zcmop\" Compressed May-Be-Operations Extension, Version 1.0" + ], + "overlap_from_line": null, + "line_count": 113 + }, + { + "chunk_id": "chunk_077", + "source_file": "zpm.adoc", + "start_line": 1, + "end_line": 223, + "content_start_line": 1, + "total_source_lines": 223, + "section_headings": [ + "== Pointer Masking Extensions, Version 1.0.0", + "=== Introduction", + "=== Background", + "==== Definitions", + "==== The \u201cIgnore\u201d Transformation", + "==== Example", + "==== Determining the Value of PMLEN", + "==== Pointer Masking and Privilege Modes", + "==== Memory Accesses Subject to Pointer Masking", + "==== Pointer Masking Extensions" + ], + "overlap_from_line": null, + "line_count": 223 + }, + { + "chunk_id": "chunk_078", + "source_file": "ztso-st-ext.adoc", + "start_line": 1, + "end_line": 49, + "content_start_line": 1, + "total_source_lines": 49, + "section_headings": [ + "== \"Ztso\" Extension for Total Store Ordering, Version 1.0" + ], + "overlap_from_line": null, + "line_count": 49 + } + ] +} diff --git a/param_extraction/chunks/manifest.json.license b/param_extraction/chunks/manifest.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/chunks/manifest.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/data/ground_truth.json b/param_extraction/data/ground_truth.json new file mode 100644 index 0000000000..0be0ddca9a --- /dev/null +++ b/param_extraction/data/ground_truth.json @@ -0,0 +1,17481 @@ +{ + "metadata": { + "total_parameters": 185, + "source": "spec/std/isa/param", + "csr_source": "spec/std/isa/csr" + }, + "statistics": { + "by_classification": { + "NORM_CSR_RW": 55, + "NORM_CSR_WARL": 26, + "NORM_DIRECT": 102, + "SW_RULE": 2 + }, + "by_value_type": { + "binary": 111, + "bitmask": 5, + "conditional": 10, + "enum": 36, + "range": 12, + "set": 8, + "value": 3 + }, + "by_confidence": { + "high": 150, + "low": 16, + "medium": 19 + }, + "params_with_csr_references": 94, + "params_with_requirements": 40, + "top_defining_extensions": { + "H": 61, + "Sm": 38, + "S": 29, + "Sdtrig": 10, + "V": 7, + "Ssstateen": 7, + "Zcmt": 6, + "Smstateen": 6, + "U": 5, + "Ssaia": 4, + "Zalrsc": 4, + "F": 3, + "Zicfilp": 3, + "Zicfiss": 3, + "Zicbom": 2 + } + }, + "parameters": [ + { + "name": "ARCH_ID_VALUE", + "long_name": "Vendor-specific architecture ID in `marchid`", + "description": "The value of `marchid`\nThe combination of mvendorid and marchid should uniquely identify the type of hart microarchitecture that is implemented.", + "defined_by": { + "extensions": [ + "Sm" + ], + "params": [ + { + "name": "MARCHID_IMPLEMENTED", + "condition": { + "equal": true + } + } + ], + "raw": { + "allOf": [ + { + "extension": { + "name": "Sm" + } + }, + { + "param": { + "name": "MARCHID_IMPLEMENTED", + "equal": true, + "reason": "When `marchid` is not implemented, its value is not relevant." + } + } + ] + }, + "summary": "ext:Sm AND param:MARCHID_IMPLEMENTED(equal=True)" + }, + "value_type": { + "type": "conditional", + "details": { + "branches": [ + { + "condition": "MXLEN == 32", + "inner_type": { + "type": "value", + "details": { + "complex": "allOf" + } + } + }, + { + "condition": "MXLEN == 64", + "inner_type": { + "type": "value", + "details": { + "complex": "allOf" + } + } + } + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "marchid", + "field": "Architecture", + "idl_key": "reset_value()" + } + ], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Well-known architectural parameter 'ARCH_ID_VALUE'", + "source_file": "spec/std/isa/param/ARCH_ID_VALUE.yaml" + }, + { + "name": "ASID_WIDTH", + "long_name": "TODO", + "description": "Number of implemented ASID bits. Maximum is 16 for XLEN==64, and 9 for XLEN==32", + "defined_by": { + "extensions": [ + "S" + ], + "params": [], + "raw": { + "extension": { + "name": "S" + } + }, + "summary": "ext:S" + }, + "value_type": { + "type": "conditional", + "details": { + "branches": [ + { + "condition": "MXLEN == 32", + "inner_type": { + "type": "range", + "details": { + "minimum": 0, + "maximum": 9 + } + } + }, + { + "condition": "MXLEN == 64", + "inner_type": { + "type": "range", + "details": { + "minimum": 0, + "maximum": 16 + } + } + } + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Well-known architectural parameter 'ASID_WIDTH'", + "source_file": "spec/std/isa/param/ASID_WIDTH.yaml" + }, + { + "name": "CACHE_BLOCK_SIZE", + "long_name": "TODO", + "description": "The observable size of a cache block, in bytes", + "defined_by": { + "extensions": [ + "Zicbom", + "Zicbop", + "Zicboz" + ], + "params": [], + "raw": { + "extension": { + "anyOf": [ + { + "name": "Zicbom" + }, + { + "name": "Zicbop" + }, + { + "name": "Zicboz" + } + ] + } + }, + "summary": "(ext:Zicbom OR ext:Zicbop OR ext:Zicboz)" + }, + "value_type": { + "type": "range", + "details": { + "minimum": 1, + "maximum": 18446744073709551615 + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Well-known architectural parameter 'CACHE_BLOCK_SIZE'", + "source_file": "spec/std/isa/param/CACHE_BLOCK_SIZE.yaml" + }, + { + "name": "CONFIG_PTR_ADDRESS", + "long_name": "Physical address in `mconfigptr`", + "description": "The value returned from `mconfigptr`", + "defined_by": { + "extensions": [ + "Sm" + ], + "params": [], + "raw": { + "extension": { + "name": "Sm", + "version": ">= 1.12.0" + } + }, + "summary": "ext:Sm(>= 1.12.0)" + }, + "value_type": { + "type": "conditional", + "details": { + "branches": [ + { + "condition": "MXLEN == 32", + "inner_type": { + "type": "value", + "details": { + "ref": "schema_defs.json#/$defs/uint32" + } + } + }, + { + "condition": "MXLEN == 64", + "inner_type": { + "type": "value", + "details": { + "ref": "schema_defs.json#/$defs/uint64" + } + } + } + ] + } + }, + "has_requirements": true, + "requirements_summary": "The pointer alignment in bits must be no smaller than MXLEN:\ni.e., if MXLEN is 8 x n, then mconfigptr[(log2(n)-1:0] must be zero.\n", + "csr_references": [ + { + "csr": "mconfigptr", + "field": "ADDRESS", + "idl_key": "reset_value()" + } + ], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Well-known architectural parameter 'CONFIG_PTR_ADDRESS'", + "source_file": "spec/std/isa/param/CONFIG_PTR_ADDRESS.yaml" + }, + { + "name": "COUNTINHIBIT_EN", + "long_name": "TODO", + "description": "Indicates which hardware performance monitor counters can be disabled from `mcountinhibit`.\n\nAn unimplemented counter cannot be specified, i.e., if HPM_COUNTER_EN[3] is false,\nit would be illegal to set COUNTINHIBIT_EN[3] to true.\n\nCOUNTINHIBIT_EN[1] can never be true, since it corresponds to `mcountinhibit.TM`,\nwhich is always read-only-0.\n\nCOUNTINHIBIT_EN[3:31] must all be false if `Zihpm` is not implemented.", + "defined_by": { + "extensions": [ + "Sm" + ], + "params": [], + "raw": { + "extension": { + "name": "Sm" + } + }, + "summary": "ext:Sm" + }, + "value_type": { + "type": "bitmask", + "details": { + "length": 32 + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "mcountinhibit", + "field": "CY", + "idl_key": "type()" + }, + { + "csr": "mcountinhibit", + "field": "CY", + "idl_key": "reset_value()" + }, + { + "csr": "mcountinhibit", + "field": "IR", + "idl_key": "type()" + }, + { + "csr": "mcountinhibit", + "field": "IR", + "idl_key": "reset_value()" + }, + { + "csr": "mcountinhibit", + "field": "HPM3", + "idl_key": "type()" + }, + { + "csr": "mcountinhibit", + "field": "HPM3", + "idl_key": "reset_value()" + }, + { + "csr": "mcountinhibit", + "field": "HPM4", + "idl_key": "type()" + }, + { + "csr": "mcountinhibit", + "field": "HPM4", + "idl_key": "reset_value()" + }, + { + "csr": "mcountinhibit", + "field": "HPM5", + "idl_key": "type()" + }, + { + "csr": "mcountinhibit", + "field": "HPM5", + "idl_key": "reset_value()" + }, + { + "csr": "mcountinhibit", + "field": "HPM6", + "idl_key": "type()" + }, + { + "csr": "mcountinhibit", + "field": "HPM6", + "idl_key": "reset_value()" + }, + { + "csr": "mcountinhibit", + "field": "HPM7", + "idl_key": "type()" + }, + { + "csr": "mcountinhibit", + "field": "HPM7", + "idl_key": "reset_value()" + }, + { + "csr": "mcountinhibit", + "field": "HPM8", + "idl_key": "type()" + }, + { + "csr": "mcountinhibit", + "field": "HPM8", + "idl_key": "reset_value()" + }, + { + "csr": "mcountinhibit", + "field": "HPM9", + "idl_key": "type()" + }, + { + "csr": "mcountinhibit", + "field": "HPM9", + "idl_key": "reset_value()" + }, + { + "csr": "mcountinhibit", + "field": "HPM10", + "idl_key": "type()" + }, + { + "csr": "mcountinhibit", + "field": "HPM10", + "idl_key": "reset_value()" + }, + { + "csr": "mcountinhibit", + "field": "HPM11", + "idl_key": "type()" + }, + { + "csr": "mcountinhibit", + "field": "HPM11", + "idl_key": "reset_value()" + }, + { + "csr": "mcountinhibit", + "field": "HPM12", + "idl_key": "type()" + }, + { + "csr": "mcountinhibit", + "field": "HPM12", + "idl_key": "reset_value()" + }, + { + "csr": "mcountinhibit", + "field": "HPM13", + "idl_key": "type()" + }, + { + "csr": "mcountinhibit", + "field": "HPM13", + "idl_key": "reset_value()" + }, + { + "csr": "mcountinhibit", + "field": "HPM14", + "idl_key": "type()" + }, + { + "csr": "mcountinhibit", + "field": "HPM14", + "idl_key": "reset_value()" + }, + { + "csr": "mcountinhibit", + "field": "HPM15", + "idl_key": "type()" + }, + { + "csr": "mcountinhibit", + "field": "HPM15", + "idl_key": "reset_value()" + }, + { + "csr": "mcountinhibit", + "field": "HPM16", + "idl_key": "type()" + }, + { + "csr": "mcountinhibit", + "field": "HPM16", + "idl_key": "reset_value()" + }, + { + "csr": "mcountinhibit", + "field": "HPM17", + "idl_key": "type()" + }, + { + "csr": "mcountinhibit", + "field": "HPM17", + "idl_key": "reset_value()" + }, + { + "csr": "mcountinhibit", + "field": "HPM18", + "idl_key": "type()" + }, + { + "csr": "mcountinhibit", + "field": "HPM18", + "idl_key": "reset_value()" + }, + { + "csr": "mcountinhibit", + "field": "HPM19", + "idl_key": "type()" + }, + { + "csr": "mcountinhibit", + "field": "HPM19", + "idl_key": "reset_value()" + }, + { + "csr": "mcountinhibit", + "field": "HPM20", + "idl_key": "type()" + }, + { + "csr": "mcountinhibit", + "field": "HPM20", + "idl_key": "reset_value()" + }, + { + "csr": "mcountinhibit", + "field": "HPM21", + "idl_key": "type()" + }, + { + "csr": "mcountinhibit", + "field": "HPM21", + "idl_key": "reset_value()" + }, + { + "csr": "mcountinhibit", + "field": "HPM22", + "idl_key": "type()" + }, + { + "csr": "mcountinhibit", + "field": "HPM22", + "idl_key": "reset_value()" + }, + { + "csr": "mcountinhibit", + "field": "HPM23", + "idl_key": "type()" + }, + { + "csr": "mcountinhibit", + "field": "HPM23", + "idl_key": "reset_value()" + }, + { + "csr": "mcountinhibit", + "field": "HPM24", + "idl_key": "type()" + }, + { + "csr": "mcountinhibit", + "field": "HPM24", + "idl_key": "reset_value()" + }, + { + "csr": "mcountinhibit", + "field": "HPM25", + "idl_key": "type()" + }, + { + "csr": "mcountinhibit", + "field": "HPM25", + "idl_key": "reset_value()" + }, + { + "csr": "mcountinhibit", + "field": "HPM26", + "idl_key": "type()" + }, + { + "csr": "mcountinhibit", + "field": "HPM26", + "idl_key": "reset_value()" + }, + { + "csr": "mcountinhibit", + "field": "HPM27", + "idl_key": "type()" + }, + { + "csr": "mcountinhibit", + "field": "HPM27", + "idl_key": "reset_value()" + }, + { + "csr": "mcountinhibit", + "field": "HPM28", + "idl_key": "type()" + }, + { + "csr": "mcountinhibit", + "field": "HPM28", + "idl_key": "reset_value()" + }, + { + "csr": "mcountinhibit", + "field": "HPM29", + "idl_key": "type()" + }, + { + "csr": "mcountinhibit", + "field": "HPM29", + "idl_key": "reset_value()" + }, + { + "csr": "mcountinhibit", + "field": "HPM30", + "idl_key": "type()" + }, + { + "csr": "mcountinhibit", + "field": "HPM30", + "idl_key": "reset_value()" + }, + { + "csr": "mcountinhibit", + "field": "HPM31", + "idl_key": "type()" + }, + { + "csr": "mcountinhibit", + "field": "HPM31", + "idl_key": "reset_value()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of mcountinhibit.CY", + "source_file": "spec/std/isa/param/COUNTINHIBIT_EN.yaml" + }, + { + "name": "DBG_HCONTEXT_WIDTH", + "long_name": "TODO", + "description": "Specifies the size of HCONTEXT", + "defined_by": { + "extensions": [ + "Sdtrig" + ], + "params": [], + "raw": { + "extension": { + "name": "Sdtrig" + } + }, + "summary": "ext:Sdtrig" + }, + "value_type": { + "type": "range", + "details": { + "minimum": 0, + "maximum": 14 + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "hcontext", + "field": "HCONTEXT", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "mcontext", + "field": "HCONTEXT", + "idl_key": "sw_write(csr_value)" + } + ], + "classification": "NORM_CSR_WARL", + "classification_confidence": "high", + "classification_reasoning": "Referenced in sw_write() of hcontext.HCONTEXT", + "source_file": "spec/std/isa/param/DBG_HCONTEXT_WIDTH.yaml" + }, + { + "name": "DBG_SCONTEXT_WIDTH", + "long_name": "TODO", + "description": "Specifies the size of SCONTEXT", + "defined_by": { + "extensions": [ + "Sdtrig" + ], + "params": [], + "raw": { + "extension": { + "name": "Sdtrig" + } + }, + "summary": "ext:Sdtrig" + }, + "value_type": { + "type": "range", + "details": { + "minimum": 0, + "maximum": 32 + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "scontext", + "field": "DATA", + "idl_key": "sw_write(csr_value)" + } + ], + "classification": "NORM_CSR_WARL", + "classification_confidence": "high", + "classification_reasoning": "Referenced in sw_write() of scontext.DATA", + "source_file": "spec/std/isa/param/DBG_SCONTEXT_WIDTH.yaml" + }, + { + "name": "DCSR_MPRVEN_TYPE", + "long_name": "TODO", + "description": "Implementation of dcsr.MPRVEN is optional.\nIt may be tied to either 0 or 1.\n\nBehavior of the dcsr.MPRVEN bit:\n * 'read-only-0': tied to 0\n * 'read-only-1': tied to 1\n * 'rw': read-write", + "defined_by": { + "extensions": [ + "Sdtrig" + ], + "params": [], + "raw": { + "extension": { + "name": "Sdtrig" + } + }, + "summary": "ext:Sdtrig" + }, + "value_type": { + "type": "enum", + "details": { + "values": [ + "read-only-0", + "read-only-1", + "rw" + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "dcsr", + "field": "MPRVEN", + "idl_key": "type()" + }, + { + "csr": "dcsr", + "field": "MPRVEN", + "idl_key": "reset_value()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of dcsr.MPRVEN", + "source_file": "spec/std/isa/param/DCSR_MPRVEN_TYPE.yaml" + }, + { + "name": "DCSR_STEPIE_TYPE", + "long_name": "TODO", + "description": "Implementation of dcsr.STEPIE is optional.\nIt may be tied to either 0 or 1.\n\nBehavior of the dcsr.STEPIE bit:\n * 'read-only-0': tied to 0\n * 'read-only-1': tied to 1\n * 'rw': read-write", + "defined_by": { + "extensions": [ + "Sdtrig" + ], + "params": [], + "raw": { + "extension": { + "name": "Sdtrig" + } + }, + "summary": "ext:Sdtrig" + }, + "value_type": { + "type": "enum", + "details": { + "values": [ + "read-only-0", + "read-only-1", + "rw" + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "dcsr", + "field": "STEPIE", + "idl_key": "type()" + }, + { + "csr": "dcsr", + "field": "STEPIE", + "idl_key": "reset_value()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of dcsr.STEPIE", + "source_file": "spec/std/isa/param/DCSR_STEPIE_TYPE.yaml" + }, + { + "name": "DCSR_STOPCOUNT_TYPE", + "long_name": "TODO", + "description": "Implementation of dcsr.STOPCOUNT is optional.\nIt may be tied to either 0 or 1.\n\nBehavior of the dcsr.STOPCOUNT bit:\n * 'read-only-0': tied to 0\n * 'read-only-1': tied to 1\n * 'rw': read-write", + "defined_by": { + "extensions": [ + "Sdtrig" + ], + "params": [], + "raw": { + "extension": { + "name": "Sdtrig" + } + }, + "summary": "ext:Sdtrig" + }, + "value_type": { + "type": "enum", + "details": { + "values": [ + "read-only-0", + "read-only-1", + "rw" + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "dcsr", + "field": "STOPCOUNT", + "idl_key": "type()" + }, + { + "csr": "dcsr", + "field": "STOPCOUNT", + "idl_key": "reset_value()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of dcsr.STOPCOUNT", + "source_file": "spec/std/isa/param/DCSR_STOPCOUNT_TYPE.yaml" + }, + { + "name": "DCSR_STOPTIME_TYPE", + "long_name": "TODO", + "description": "Implementation of dcsr.STOPTIME is optional.\nIt may be tied to either 0 or 1.\n\nBehavior of the dcsr.STOPTIME bit:\n * 'read-only-0': tied to 0\n * 'read-only-1': tied to 1\n * 'rw': read-write", + "defined_by": { + "extensions": [ + "Sdtrig" + ], + "params": [], + "raw": { + "extension": { + "name": "Sdtrig" + } + }, + "summary": "ext:Sdtrig" + }, + "value_type": { + "type": "enum", + "details": { + "values": [ + "read-only-0", + "read-only-1", + "rw" + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "dcsr", + "field": "STOPTIME", + "idl_key": "type()" + }, + { + "csr": "dcsr", + "field": "STOPTIME", + "idl_key": "reset_value()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of dcsr.STOPTIME", + "source_file": "spec/std/isa/param/DCSR_STOPTIME_TYPE.yaml" + }, + { + "name": "ELEN", + "long_name": "TODO", + "description": "The maximum size in bits of a vector element that any operation can produce or consume.", + "defined_by": { + "extensions": [ + "V" + ], + "params": [], + "raw": { + "extension": { + "name": "V" + } + }, + "summary": "ext:V" + }, + "value_type": { + "type": "value", + "details": { + "base": "integer" + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Well-known architectural parameter 'ELEN'", + "source_file": "spec/std/isa/param/ELEN.yaml" + }, + { + "name": "FOLLOW_VTYPE_RESET_RECOMMENDATION", + "long_name": "TODO", + "description": "It is recommended that at reset, vtype.vill is set, the remaining bits in vtype are zero, and vl is set to zero.\nIf this parameter is set to true, this recommendation is followed. If it is false, at reset the respective fields\nwill be UNDEFINED_LEGAL.", + "defined_by": { + "extensions": [ + "V" + ], + "params": [], + "raw": { + "extension": { + "name": "V" + } + }, + "summary": "ext:V" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "vl", + "field": "VALUE", + "idl_key": "reset_value()" + }, + { + "csr": "vtype", + "field": "VILL", + "idl_key": "reset_value()" + }, + { + "csr": "vtype", + "field": "VMA", + "idl_key": "reset_value()" + }, + { + "csr": "vtype", + "field": "VTA", + "idl_key": "reset_value()" + }, + { + "csr": "vtype", + "field": "VSEW", + "idl_key": "reset_value()" + }, + { + "csr": "vtype", + "field": "VLMUL", + "idl_key": "reset_value()" + } + ], + "classification": "NORM_DIRECT", + "classification_confidence": "medium", + "classification_reasoning": "Implementation behavioral choice parameter", + "source_file": "spec/std/isa/param/FOLLOW_VTYPE_RESET_RECOMMENDATION.yaml" + }, + { + "name": "FORCE_UPGRADE_CBO_INVAL_TO_FLUSH", + "long_name": "TODO", + "description": "When true, an implementation prohibits setting `menvcfg.CBIE` == `11` such that all `cbo.inval`\ninstructions either trap (when `menvcfg.CBIE` == '00') or flush (when `menvcfg.CBIE` == '01').\n\nWhen false, an implementation allows a true INVAL operation for `cbo.inval`, and thus supports\nthe setting `menvcfg.CBIE` == `11`.", + "defined_by": { + "extensions": [ + "Zicbom" + ], + "params": [], + "raw": { + "extension": { + "name": "Zicbom" + } + }, + "summary": "ext:Zicbom" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "menvcfg", + "field": "CBIE", + "idl_key": "sw_write(csr_value)" + } + ], + "classification": "NORM_CSR_WARL", + "classification_confidence": "high", + "classification_reasoning": "Referenced in sw_write() of menvcfg.CBIE", + "source_file": "spec/std/isa/param/FORCE_UPGRADE_CBO_INVAL_TO_FLUSH.yaml" + }, + { + "name": "GSTAGE_MODE_BARE", + "long_name": "TODO", + "description": "Whether or not writing mode=Bare is supported in the `hgatp` register.", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": true, + "requirements_summary": "# if host is 32 bit, then one of Bare or Sv32X4 must be supported\n$array_includes?(SXLEN, 32) && !SV32X4_TRANSLATION\n -> GSTAGE_MODE_BARE;\n\n# if host is 64 bit, then one of Bare, Sv39X4, Sv48x4, or S", + "csr_references": [ + { + "csr": "hgatp", + "field": "MODE", + "idl_key": "sw_write(csr_value)" + } + ], + "classification": "NORM_CSR_WARL", + "classification_confidence": "high", + "classification_reasoning": "Referenced in sw_write() of hgatp.MODE", + "source_file": "spec/std/isa/param/GSTAGE_MODE_BARE.yaml" + }, + { + "name": "HCONTEXT_AVAILABLE", + "long_name": "TODO", + "description": "Specifies if HCONTEXT is available", + "defined_by": { + "extensions": [ + "Sdtrig" + ], + "params": [], + "raw": { + "extension": { + "name": "Sdtrig" + } + }, + "summary": "ext:Sdtrig" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": true, + "requirements_summary": "HCONTEXT cannot exist without MCONTEXT", + "csr_references": [ + { + "csr": "hcontext", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "hcontext", + "field": "HCONTEXT", + "idl_key": "sw_write(csr_value)" + } + ], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Feature/CSR existence parameter ('AVAILABLE' suffix)", + "source_file": "spec/std/isa/param/HCONTEXT_AVAILABLE.yaml" + }, + { + "name": "HCOUNTENABLE_EN", + "long_name": "TODO", + "description": "Indicates which counters can delegated via `hcounteren`\n\nAn unimplemented counter cannot be specified, i.e., if\nHPM_COUNTER_EN[3] is false, it would be illegal to set\nHCOUNTENABLE_EN[3] to true.\n\nHCOUNTENABLE_EN[0:2] must all be false if `Zicntr` is not implemented.\nHCOUNTENABLE_EN[3:31] must all be false if `Zihpm` is not implemented.", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "bitmask", + "details": { + "length": 32 + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "hcounteren", + "field": "CY", + "idl_key": "type()" + }, + { + "csr": "hcounteren", + "field": "CY", + "idl_key": "reset_value()" + }, + { + "csr": "hcounteren", + "field": "TM", + "idl_key": "type()" + }, + { + "csr": "hcounteren", + "field": "TM", + "idl_key": "reset_value()" + }, + { + "csr": "hcounteren", + "field": "IR", + "idl_key": "type()" + }, + { + "csr": "hcounteren", + "field": "IR", + "idl_key": "reset_value()" + }, + { + "csr": "hcounteren", + "field": "HPM3", + "idl_key": "type()" + }, + { + "csr": "hcounteren", + "field": "HPM3", + "idl_key": "reset_value()" + }, + { + "csr": "hcounteren", + "field": "HPM4", + "idl_key": "type()" + }, + { + "csr": "hcounteren", + "field": "HPM4", + "idl_key": "reset_value()" + }, + { + "csr": "hcounteren", + "field": "HPM5", + "idl_key": "type()" + }, + { + "csr": "hcounteren", + "field": "HPM5", + "idl_key": "reset_value()" + }, + { + "csr": "hcounteren", + "field": "HPM6", + "idl_key": "type()" + }, + { + "csr": "hcounteren", + "field": "HPM6", + "idl_key": "reset_value()" + }, + { + "csr": "hcounteren", + "field": "HPM7", + "idl_key": "type()" + }, + { + "csr": "hcounteren", + "field": "HPM7", + "idl_key": "reset_value()" + }, + { + "csr": "hcounteren", + "field": "HPM8", + "idl_key": "type()" + }, + { + "csr": "hcounteren", + "field": "HPM8", + "idl_key": "reset_value()" + }, + { + "csr": "hcounteren", + "field": "HPM9", + "idl_key": "type()" + }, + { + "csr": "hcounteren", + "field": "HPM9", + "idl_key": "reset_value()" + }, + { + "csr": "hcounteren", + "field": "HPM10", + "idl_key": "type()" + }, + { + "csr": "hcounteren", + "field": "HPM10", + "idl_key": "reset_value()" + }, + { + "csr": "hcounteren", + "field": "HPM11", + "idl_key": "type()" + }, + { + "csr": "hcounteren", + "field": "HPM11", + "idl_key": "reset_value()" + }, + { + "csr": "hcounteren", + "field": "HPM12", + "idl_key": "type()" + }, + { + "csr": "hcounteren", + "field": "HPM12", + "idl_key": "reset_value()" + }, + { + "csr": "hcounteren", + "field": "HPM13", + "idl_key": "type()" + }, + { + "csr": "hcounteren", + "field": "HPM13", + "idl_key": "reset_value()" + }, + { + "csr": "hcounteren", + "field": "HPM14", + "idl_key": "type()" + }, + { + "csr": "hcounteren", + "field": "HPM14", + "idl_key": "reset_value()" + }, + { + "csr": "hcounteren", + "field": "HPM15", + "idl_key": "type()" + }, + { + "csr": "hcounteren", + "field": "HPM15", + "idl_key": "reset_value()" + }, + { + "csr": "hcounteren", + "field": "HPM16", + "idl_key": "type()" + }, + { + "csr": "hcounteren", + "field": "HPM16", + "idl_key": "reset_value()" + }, + { + "csr": "hcounteren", + "field": "HPM17", + "idl_key": "type()" + }, + { + "csr": "hcounteren", + "field": "HPM17", + "idl_key": "reset_value()" + }, + { + "csr": "hcounteren", + "field": "HPM18", + "idl_key": "type()" + }, + { + "csr": "hcounteren", + "field": "HPM18", + "idl_key": "reset_value()" + }, + { + "csr": "hcounteren", + "field": "HPM19", + "idl_key": "type()" + }, + { + "csr": "hcounteren", + "field": "HPM19", + "idl_key": "reset_value()" + }, + { + "csr": "hcounteren", + "field": "HPM20", + "idl_key": "type()" + }, + { + "csr": "hcounteren", + "field": "HPM20", + "idl_key": "reset_value()" + }, + { + "csr": "hcounteren", + "field": "HPM21", + "idl_key": "type()" + }, + { + "csr": "hcounteren", + "field": "HPM21", + "idl_key": "reset_value()" + }, + { + "csr": "hcounteren", + "field": "HPM22", + "idl_key": "type()" + }, + { + "csr": "hcounteren", + "field": "HPM22", + "idl_key": "reset_value()" + }, + { + "csr": "hcounteren", + "field": "HPM23", + "idl_key": "type()" + }, + { + "csr": "hcounteren", + "field": "HPM23", + "idl_key": "reset_value()" + }, + { + "csr": "hcounteren", + "field": "HPM24", + "idl_key": "type()" + }, + { + "csr": "hcounteren", + "field": "HPM24", + "idl_key": "reset_value()" + }, + { + "csr": "hcounteren", + "field": "HPM25", + "idl_key": "type()" + }, + { + "csr": "hcounteren", + "field": "HPM25", + "idl_key": "reset_value()" + }, + { + "csr": "hcounteren", + "field": "HPM26", + "idl_key": "type()" + }, + { + "csr": "hcounteren", + "field": "HPM26", + "idl_key": "reset_value()" + }, + { + "csr": "hcounteren", + "field": "HPM27", + "idl_key": "type()" + }, + { + "csr": "hcounteren", + "field": "HPM27", + "idl_key": "reset_value()" + }, + { + "csr": "hcounteren", + "field": "HPM28", + "idl_key": "type()" + }, + { + "csr": "hcounteren", + "field": "HPM28", + "idl_key": "reset_value()" + }, + { + "csr": "hcounteren", + "field": "HPM29", + "idl_key": "type()" + }, + { + "csr": "hcounteren", + "field": "HPM29", + "idl_key": "reset_value()" + }, + { + "csr": "hcounteren", + "field": "HPM30", + "idl_key": "type()" + }, + { + "csr": "hcounteren", + "field": "HPM30", + "idl_key": "reset_value()" + }, + { + "csr": "hcounteren", + "field": "HPM31", + "idl_key": "type()" + }, + { + "csr": "hcounteren", + "field": "HPM31", + "idl_key": "reset_value()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of hcounteren.CY", + "source_file": "spec/std/isa/param/HCOUNTENABLE_EN.yaml" + }, + { + "name": "HPM_COUNTER_EN", + "long_name": "TODO", + "description": "List of HPM counters that are enabled.\nThere is one entry for each hpmcounter.\n\nThe first three entries *must* be false (as they correspond to CY, IR, TM in, _e.g._ `mhmpcountinhibit`)\nIndex 3 in HPM_COUNTER_EN corresponds to hpmcounter3.\nIndex 31 in HPM_COUNTER_EN corresponds to hpmcounter31.", + "defined_by": { + "extensions": [ + "Smhpm" + ], + "params": [], + "raw": { + "extension": { + "name": "Smhpm" + } + }, + "summary": "ext:Smhpm" + }, + "value_type": { + "type": "bitmask", + "details": { + "length": 32 + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "scountovf", + "field": "OF3", + "idl_key": "type()" + }, + { + "csr": "scountovf", + "field": "OF3", + "idl_key": "reset_value()" + }, + { + "csr": "scountovf", + "field": "OF4", + "idl_key": "type()" + }, + { + "csr": "scountovf", + "field": "OF4", + "idl_key": "reset_value()" + }, + { + "csr": "scountovf", + "field": "OF5", + "idl_key": "type()" + }, + { + "csr": "scountovf", + "field": "OF5", + "idl_key": "reset_value()" + }, + { + "csr": "scountovf", + "field": "OF6", + "idl_key": "type()" + }, + { + "csr": "scountovf", + "field": "OF6", + "idl_key": "reset_value()" + }, + { + "csr": "scountovf", + "field": "OF7", + "idl_key": "type()" + }, + { + "csr": "scountovf", + "field": "OF7", + "idl_key": "reset_value()" + }, + { + "csr": "scountovf", + "field": "OF8", + "idl_key": "type()" + }, + { + "csr": "scountovf", + "field": "OF8", + "idl_key": "reset_value()" + }, + { + "csr": "scountovf", + "field": "OF9", + "idl_key": "type()" + }, + { + "csr": "scountovf", + "field": "OF9", + "idl_key": "reset_value()" + }, + { + "csr": "scountovf", + "field": "OF10", + "idl_key": "type()" + }, + { + "csr": "scountovf", + "field": "OF10", + "idl_key": "reset_value()" + }, + { + "csr": "scountovf", + "field": "OF11", + "idl_key": "type()" + }, + { + "csr": "scountovf", + "field": "OF11", + "idl_key": "reset_value()" + }, + { + "csr": "scountovf", + "field": "OF12", + "idl_key": "type()" + }, + { + "csr": "scountovf", + "field": "OF12", + "idl_key": "reset_value()" + }, + { + "csr": "scountovf", + "field": "OF13", + "idl_key": "type()" + }, + { + "csr": "scountovf", + "field": "OF13", + "idl_key": "reset_value()" + }, + { + "csr": "scountovf", + "field": "OF14", + "idl_key": "type()" + }, + { + "csr": "scountovf", + "field": "OF14", + "idl_key": "reset_value()" + }, + { + "csr": "scountovf", + "field": "OF15", + "idl_key": "type()" + }, + { + "csr": "scountovf", + "field": "OF15", + "idl_key": "reset_value()" + }, + { + "csr": "scountovf", + "field": "OF16", + "idl_key": "type()" + }, + { + "csr": "scountovf", + "field": "OF16", + "idl_key": "reset_value()" + }, + { + "csr": "scountovf", + "field": "OF17", + "idl_key": "type()" + }, + { + "csr": "scountovf", + "field": "OF17", + "idl_key": "reset_value()" + }, + { + "csr": "scountovf", + "field": "OF18", + "idl_key": "type()" + }, + { + "csr": "scountovf", + "field": "OF18", + "idl_key": "reset_value()" + }, + { + "csr": "scountovf", + "field": "OF19", + "idl_key": "type()" + }, + { + "csr": "scountovf", + "field": "OF19", + "idl_key": "reset_value()" + }, + { + "csr": "scountovf", + "field": "OF20", + "idl_key": "type()" + }, + { + "csr": "scountovf", + "field": "OF20", + "idl_key": "reset_value()" + }, + { + "csr": "scountovf", + "field": "OF21", + "idl_key": "type()" + }, + { + "csr": "scountovf", + "field": "OF21", + "idl_key": "reset_value()" + }, + { + "csr": "scountovf", + "field": "OF22", + "idl_key": "type()" + }, + { + "csr": "scountovf", + "field": "OF22", + "idl_key": "reset_value()" + }, + { + "csr": "scountovf", + "field": "OF23", + "idl_key": "type()" + }, + { + "csr": "scountovf", + "field": "OF23", + "idl_key": "reset_value()" + }, + { + "csr": "scountovf", + "field": "OF24", + "idl_key": "type()" + }, + { + "csr": "scountovf", + "field": "OF24", + "idl_key": "reset_value()" + }, + { + "csr": "scountovf", + "field": "OF25", + "idl_key": "type()" + }, + { + "csr": "scountovf", + "field": "OF25", + "idl_key": "reset_value()" + }, + { + "csr": "scountovf", + "field": "OF26", + "idl_key": "type()" + }, + { + "csr": "scountovf", + "field": "OF26", + "idl_key": "reset_value()" + }, + { + "csr": "scountovf", + "field": "OF27", + "idl_key": "type()" + }, + { + "csr": "scountovf", + "field": "OF27", + "idl_key": "reset_value()" + }, + { + "csr": "scountovf", + "field": "OF28", + "idl_key": "type()" + }, + { + "csr": "scountovf", + "field": "OF28", + "idl_key": "reset_value()" + }, + { + "csr": "scountovf", + "field": "OF29", + "idl_key": "type()" + }, + { + "csr": "scountovf", + "field": "OF29", + "idl_key": "reset_value()" + }, + { + "csr": "scountovf", + "field": "OF30", + "idl_key": "type()" + }, + { + "csr": "scountovf", + "field": "OF30", + "idl_key": "reset_value()" + }, + { + "csr": "scountovf", + "field": "OF31", + "idl_key": "type()" + }, + { + "csr": "scountovf", + "field": "OF31", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter12h", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter12h", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter12h", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter8", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter8", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter8", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent18h", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent18h", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent18h", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent18h", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent18h", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent18h", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent18h", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent18h", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent18h", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent18h", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent18h", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent18h", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent18h", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent18h", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter30", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter30", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter30", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent4h", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent4h", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent4h", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent4h", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent4h", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent4h", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent4h", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent4h", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent4h", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent4h", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent4h", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent4h", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent4h", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent4h", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent14", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent14", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent14", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent14", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent14", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent14", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent14", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent14", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent14", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent14", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent14", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent14", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent14", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent14", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent25h", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent25h", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent25h", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent25h", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent25h", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent25h", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent25h", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent25h", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent25h", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent25h", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent25h", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent25h", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent25h", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent25h", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter26", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter26", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter26", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent22", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent22", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent22", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent22", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent22", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent22", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent22", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent22", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent22", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent22", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent22", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent22", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent22", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent22", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent27h", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent27h", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent27h", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent27h", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent27h", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent27h", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent27h", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent27h", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent27h", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent27h", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent27h", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent27h", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent27h", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent27h", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter10", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter10", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter10", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent6h", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent6h", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent6h", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent6h", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent6h", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent6h", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent6h", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent6h", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent6h", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent6h", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent6h", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent6h", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent6h", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent6h", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter4", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter4", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter4", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent18", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent18", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent18", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent18", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent18", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent18", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent18", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent18", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent18", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent18", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent18", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent18", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent18", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent18", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter10h", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter10h", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter10h", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter9h", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter9h", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter9h", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter29h", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter29h", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter29h", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent19", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent19", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent19", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent19", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent19", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent19", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent19", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent19", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent19", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent19", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent19", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent19", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent19", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent19", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter14h", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter14h", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter14h", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter30h", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter30h", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter30h", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent23h", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent23h", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent23h", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent23h", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent23h", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent23h", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent23h", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent23h", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent23h", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent23h", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent23h", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent23h", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent23h", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent23h", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter11", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter11", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter11", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter5", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter5", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter5", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent23", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent23", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent23", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent23", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent23", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent23", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent23", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent23", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent23", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent23", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent23", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent23", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent23", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent23", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter27", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter27", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter27", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent21h", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent21h", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent21h", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent21h", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent21h", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent21h", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent21h", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent21h", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent21h", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent21h", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent21h", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent21h", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent21h", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent21h", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent15", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent15", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent15", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent15", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent15", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent15", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent15", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent15", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent15", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent15", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent15", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent15", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent15", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent15", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter31", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter31", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter31", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter16h", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter16h", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter16h", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter9", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter9", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter9", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent3", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent3", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent3", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent3", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent3", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent3", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent3", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent3", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent3", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent3", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent3", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent3", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent3", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent3", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent8", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent8", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent8", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent8", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent8", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent8", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent8", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent8", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent8", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent8", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent8", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent8", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent8", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent8", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent24", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent24", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent24", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent24", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent24", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent24", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent24", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent24", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent24", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent24", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent24", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent24", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent24", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent24", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent7h", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent7h", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent7h", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent7h", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent7h", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent7h", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent7h", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent7h", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent7h", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent7h", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent7h", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent7h", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent7h", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent7h", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter16", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter16", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter16", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent26h", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent26h", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent26h", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent26h", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent26h", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent26h", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent26h", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent26h", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent26h", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent26h", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent26h", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent26h", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent26h", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent26h", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter11h", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter11h", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter11h", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent28", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent28", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent28", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent28", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent28", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent28", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent28", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent28", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent28", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent28", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent28", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent28", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent28", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent28", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent4", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent4", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent4", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent4", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent4", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent4", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent4", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent4", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent4", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent4", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent4", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent4", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent4", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent4", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter13h", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter13h", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter13h", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent24h", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent24h", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent24h", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent24h", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent24h", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent24h", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent24h", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent24h", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent24h", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent24h", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent24h", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent24h", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent24h", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent24h", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent12", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent12", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent12", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent12", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent12", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent12", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent12", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent12", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent12", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent12", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent12", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent12", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent12", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent12", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent19h", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent19h", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent19h", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent19h", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent19h", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent19h", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent19h", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent19h", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent19h", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent19h", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent19h", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent19h", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent19h", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent19h", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter20", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter20", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter20", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent5h", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent5h", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent5h", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent5h", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent5h", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent5h", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent5h", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent5h", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent5h", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent5h", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent5h", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent5h", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent5h", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent5h", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter21", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter21", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter21", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent20h", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent20h", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent20h", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent20h", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent20h", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent20h", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent20h", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent20h", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent20h", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent20h", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent20h", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent20h", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent20h", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent20h", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent13", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent13", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent13", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent13", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent13", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent13", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent13", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent13", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent13", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent13", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent13", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent13", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent13", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent13", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent5", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent5", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent5", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent5", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent5", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent5", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent5", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent5", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent5", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent5", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent5", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent5", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent5", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent5", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter17h", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter17h", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter17h", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent29", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent29", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent29", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent29", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent29", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent29", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent29", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent29", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent29", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent29", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent29", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent29", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent29", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent29", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter15h", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter15h", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter15h", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter8h", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter8h", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter8h", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter28h", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter28h", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter28h", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent3h", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent3h", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent3h", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent3h", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent3h", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent3h", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent3h", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent3h", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent3h", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent3h", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent3h", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent3h", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent3h", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent3h", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter17", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter17", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter17", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter3", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter3", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter3", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent25", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent25", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent25", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent25", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent25", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent25", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent25", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent25", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent25", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent25", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent25", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent25", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent25", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent25", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter31h", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter31h", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter31h", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent22h", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent22h", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent22h", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent22h", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent22h", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent22h", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent22h", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent22h", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent22h", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent22h", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent22h", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent22h", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent22h", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent22h", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent9", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent9", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent9", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent9", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent9", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent9", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent9", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent9", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent9", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent9", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent9", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent9", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent9", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent9", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent13h", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent13h", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent13h", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent13h", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent13h", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent13h", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent13h", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent13h", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent13h", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent13h", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent13h", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent13h", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent13h", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent13h", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter4h", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter4h", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter4h", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent30", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent30", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent30", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent30", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent30", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent30", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent30", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent30", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent30", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent30", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent30", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent30", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent30", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent30", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter24h", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter24h", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter24h", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter14", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter14", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter14", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent26", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent26", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent26", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent26", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent26", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent26", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent26", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent26", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent26", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent26", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent26", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent26", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent26", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent26", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter19h", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter19h", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter19h", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter22", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter22", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter22", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter26h", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter26h", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter26h", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter6h", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter6h", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter6h", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent10", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent10", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent10", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent10", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent10", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent10", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent10", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent10", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent10", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent10", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent10", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent10", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent10", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent10", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent11h", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent11h", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent11h", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent11h", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent11h", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent11h", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent11h", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent11h", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent11h", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent11h", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent11h", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent11h", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent11h", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent11h", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter18", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter18", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter18", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent6", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent6", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent6", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent6", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent6", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent6", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent6", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent6", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent6", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent6", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent6", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent6", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent6", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent6", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent7", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent7", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent7", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent7", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent7", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent7", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent7", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent7", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent7", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent7", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent7", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent7", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent7", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent7", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent15h", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent15h", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent15h", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent15h", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent15h", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent15h", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent15h", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent15h", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent15h", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent15h", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent15h", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent15h", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent15h", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent15h", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent9h", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent9h", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent9h", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent9h", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent9h", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent9h", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent9h", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent9h", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent9h", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent9h", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent9h", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent9h", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent9h", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent9h", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent28h", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent28h", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent28h", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent28h", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent28h", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent28h", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent28h", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent28h", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent28h", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent28h", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent28h", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent28h", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent28h", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent28h", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter19", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter19", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter19", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent11", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent11", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent11", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent11", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent11", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent11", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent11", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent11", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent11", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent11", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent11", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent11", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent11", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent11", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter23", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter23", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter23", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter22h", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter22h", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter22h", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent31h", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent31h", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent31h", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent31h", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent31h", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent31h", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent31h", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent31h", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent31h", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent31h", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent31h", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent31h", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent31h", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent31h", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent27", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent27", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent27", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent27", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent27", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent27", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent27", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent27", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent27", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent27", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent27", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent27", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent27", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent27", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter20h", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter20h", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter20h", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter15", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter15", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter15", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent31", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent31", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent31", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent31", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent31", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent31", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent31", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent31", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent31", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent31", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent31", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent31", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent31", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent31", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent17h", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent17h", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent17h", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent17h", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent17h", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent17h", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent17h", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent17h", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent17h", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent17h", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent17h", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent17h", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent17h", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent17h", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter24", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter24", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter24", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter27h", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter27h", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter27h", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter7h", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter7h", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter7h", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent16", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent16", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent16", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent16", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent16", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent16", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent16", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent16", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent16", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent16", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent16", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent16", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent16", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent16", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent10h", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent10h", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent10h", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent10h", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent10h", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent10h", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent10h", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent10h", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent10h", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent10h", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent10h", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent10h", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent10h", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent10h", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter28", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter28", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter28", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent12h", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent12h", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent12h", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent12h", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent12h", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent12h", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent12h", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent12h", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent12h", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent12h", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent12h", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent12h", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent12h", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent12h", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter18h", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter18h", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter18h", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter6", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter6", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter6", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter12", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter12", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter12", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter5h", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter5h", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter5h", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent20", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent20", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent20", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent20", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent20", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent20", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent20", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent20", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent20", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent20", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent20", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent20", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent20", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent20", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter25h", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter25h", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter25h", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent21", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent21", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent21", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent21", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent21", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent21", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent21", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent21", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent21", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent21", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent21", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent21", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent21", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent21", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter21h", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter21h", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter21h", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter7", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter7", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter7", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter13", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter13", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter13", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent16h", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent16h", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent16h", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent16h", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent16h", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent16h", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent16h", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent16h", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent16h", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent16h", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent16h", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent16h", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent16h", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent16h", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter29", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter29", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter29", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent29h", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent29h", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent29h", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent29h", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent29h", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent29h", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent29h", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent29h", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent29h", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent29h", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent29h", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent29h", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent29h", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent29h", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent14h", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent14h", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent14h", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent14h", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent14h", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent14h", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent14h", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent14h", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent14h", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent14h", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent14h", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent14h", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent14h", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent14h", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent8h", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent8h", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent8h", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent8h", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent8h", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent8h", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent8h", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent8h", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent8h", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent8h", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent8h", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent8h", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent8h", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent8h", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter3h", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter3h", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter3h", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter23h", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter23h", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter23h", + "field": "COUNT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent30h", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent30h", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent30h", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent30h", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent30h", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent30h", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent30h", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent30h", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent30h", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent30h", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent30h", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent30h", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent30h", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent30h", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent17", + "field": "OF", + "idl_key": "type()" + }, + { + "csr": "mhpmevent17", + "field": "OF", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent17", + "field": "MINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent17", + "field": "MINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent17", + "field": "SINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent17", + "field": "SINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent17", + "field": "UINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent17", + "field": "UINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent17", + "field": "VSINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent17", + "field": "VSINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent17", + "field": "VUINH", + "idl_key": "type()" + }, + { + "csr": "mhpmevent17", + "field": "VUINH", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmevent17", + "field": "EVENT", + "idl_key": "type()" + }, + { + "csr": "mhpmevent17", + "field": "EVENT", + "idl_key": "reset_value()" + }, + { + "csr": "mhpmcounter25", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mhpmcounter25", + "field": "COUNT", + "idl_key": "type()" + }, + { + "csr": "mhpmcounter25", + "field": "COUNT", + "idl_key": "reset_value()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of scountovf.OF3", + "source_file": "spec/std/isa/param/HPM_COUNTER_EN.yaml" + }, + { + "name": "HPM_EVENTS", + "long_name": "TODO", + "description": "List of defined event numbers that can be written into hpmeventN", + "defined_by": { + "extensions": [ + "Smhpm" + ], + "params": [], + "raw": { + "extension": { + "name": "Smhpm" + } + }, + "summary": "ext:Smhpm" + }, + "value_type": { + "type": "set", + "details": { + "element_type": "integer", + "min_items": null, + "max_items": null + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "mhpmevent14", + "field": "EVENT", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "mhpmevent22", + "field": "EVENT", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "mhpmevent18", + "field": "EVENT", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "mhpmevent19", + "field": "EVENT", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "mhpmevent23", + "field": "EVENT", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "mhpmevent15", + "field": "EVENT", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "mhpmevent3", + "field": "EVENT", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "mhpmevent8", + "field": "EVENT", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "mhpmevent24", + "field": "EVENT", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "mhpmevent28", + "field": "EVENT", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "mhpmevent4", + "field": "EVENT", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "mhpmevent12", + "field": "EVENT", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "mhpmevent13", + "field": "EVENT", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "mhpmevent5", + "field": "EVENT", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "mhpmevent29", + "field": "EVENT", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "mhpmevent25", + "field": "EVENT", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "mhpmevent9", + "field": "EVENT", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "mhpmevent30", + "field": "EVENT", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "mhpmevent26", + "field": "EVENT", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "mhpmevent10", + "field": "EVENT", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "mhpmevent6", + "field": "EVENT", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "mhpmevent7", + "field": "EVENT", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "mhpmevent11", + "field": "EVENT", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "mhpmevent27", + "field": "EVENT", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "mhpmevent31", + "field": "EVENT", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "mhpmevent16", + "field": "EVENT", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "mhpmevent20", + "field": "EVENT", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "mhpmevent21", + "field": "EVENT", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "mhpmevent17", + "field": "EVENT", + "idl_key": "sw_write(csr_value)" + } + ], + "classification": "NORM_CSR_WARL", + "classification_confidence": "high", + "classification_reasoning": "Referenced in sw_write() of mhpmevent14.EVENT", + "source_file": "spec/std/isa/param/HPM_EVENTS.yaml" + }, + { + "name": "HSTATEEN_AIA_TYPE", + "long_name": "TODO", + "description": "Behavior of the hstateen0.AIA bit:\n\n * 'rw': read-write\n * 'read-only-0': read-only, fixed to 0\n * 'read-only-1': read-only, fixed to 1", + "defined_by": { + "extensions": [ + "H", + "Ssaia", + "Ssstateen" + ], + "params": [], + "raw": { + "extension": { + "allOf": [ + { + "name": "Ssaia" + }, + { + "name": "H" + }, + { + "name": "Ssstateen" + } + ] + } + }, + "summary": "ext:Ssaia AND ext:H AND ext:Ssstateen" + }, + "value_type": { + "type": "enum", + "details": { + "values": [ + "rw", + "read-only-0", + "read-only-1" + ] + } + }, + "has_requirements": true, + "requirements_summary": "HSTATEEN cannot have more options that MSTATEEN\nHSTATEEN cannot have more options that MSTATEEN\n", + "csr_references": [], + "classification": "NORM_CSR_RW", + "classification_confidence": "low", + "classification_reasoning": "CSR field type control parameter for 'hstateen' (determines RO/RW behavior)", + "source_file": "spec/std/isa/param/HSTATEEN_AIA_TYPE.yaml" + }, + { + "name": "HSTATEEN_CONTEXT_TYPE", + "long_name": "TODO", + "description": "Behavior of the hstateen0.CONTEXT bit:\n\n * 'rw': read-write\n * 'read-only-0': read-only, fixed to 0\n * 'read-only-1': read-only, fixed to 1", + "defined_by": { + "extensions": [ + "H", + "Sdtrig", + "Ssstateen" + ], + "params": [], + "raw": { + "extension": { + "allOf": [ + { + "name": "Sdtrig" + }, + { + "name": "H" + }, + { + "name": "Ssstateen" + } + ] + } + }, + "summary": "ext:Sdtrig AND ext:H AND ext:Ssstateen" + }, + "value_type": { + "type": "enum", + "details": { + "values": [ + "rw", + "read-only-0", + "read-only-1" + ] + } + }, + "has_requirements": true, + "requirements_summary": "When mstateen0.CONTEXT is read-only-0, hstateen0.CONTEXT must also be read-only-0\n\nWhen mstateen0.CONTEXT is read-only-1, hstateen0.CONTEXT must also be read-only-1\n", + "csr_references": [], + "classification": "NORM_CSR_RW", + "classification_confidence": "low", + "classification_reasoning": "CSR field type control parameter for 'hstateen' (determines RO/RW behavior)", + "source_file": "spec/std/isa/param/HSTATEEN_CONTEXT_TYPE.yaml" + }, + { + "name": "HSTATEEN_CSRIND_TYPE", + "long_name": "TODO", + "description": "Behavior of the hstateen0.CSRIND bit:\n\n * 'rw': read-write\n * 'read-only-0': read-only, fixed to 0\n * 'read-only-1': read-only, fixed to 1", + "defined_by": { + "extensions": [ + "H", + "Sscsrind", + "Ssstateen" + ], + "params": [], + "raw": { + "extension": { + "allOf": [ + { + "name": "Sscsrind" + }, + { + "name": "H" + }, + { + "name": "Ssstateen" + } + ] + } + }, + "summary": "ext:Sscsrind AND ext:H AND ext:Ssstateen" + }, + "value_type": { + "type": "enum", + "details": { + "values": [ + "rw", + "read-only-0", + "read-only-1" + ] + } + }, + "has_requirements": true, + "requirements_summary": "HSTATEEN cannot have more options that MSTATEEN\nHSTATEEN cannot have more options that MSTATEEN\n", + "csr_references": [], + "classification": "NORM_CSR_RW", + "classification_confidence": "low", + "classification_reasoning": "CSR field type control parameter for 'hstateen' (determines RO/RW behavior)", + "source_file": "spec/std/isa/param/HSTATEEN_CSRIND_TYPE.yaml" + }, + { + "name": "HSTATEEN_ENVCFG_TYPE", + "long_name": "TODO", + "description": "Behavior of the hstateen0.ENVCFG bit:\n\n * 'rw': read-write\n * 'read-only-0': read-only, fixed to 0\n * 'read-only-1': read-only, fixed to 1", + "defined_by": { + "extensions": [ + "H", + "Ssstateen" + ], + "params": [], + "raw": { + "extension": { + "allOf": [ + { + "name": "H", + "version": "~> 1.0" + }, + { + "name": "Ssstateen", + "version": "~> 1.0" + } + ] + } + }, + "summary": "ext:H(~> 1.0) AND ext:Ssstateen(~> 1.0)" + }, + "value_type": { + "type": "enum", + "details": { + "values": [ + "rw", + "read-only-0", + "read-only-1" + ] + } + }, + "has_requirements": true, + "requirements_summary": "When mstateen0.ENVCFG is read-only-0, hstateen0.ENVCFG must also be read-only-0\n\nWhen mstateen1.ENVCFG is read-only-1, hstateen0.ENVCFG must also be read-only-1\n", + "csr_references": [], + "classification": "NORM_CSR_RW", + "classification_confidence": "low", + "classification_reasoning": "CSR field type control parameter for 'hstateen' (determines RO/RW behavior)", + "source_file": "spec/std/isa/param/HSTATEEN_ENVCFG_TYPE.yaml" + }, + { + "name": "HSTATEEN_IMSIC_TYPE", + "long_name": "TODO", + "description": "Behavior of the hstateen0.IMSIC bit:\n\n * 'rw': read-write\n * 'read-only-0': read-only, fixed to 0\n * 'read-only-1': read-only, fixed to 1", + "defined_by": { + "extensions": [ + "H", + "Ssaia", + "Ssstateen" + ], + "params": [], + "raw": { + "extension": { + "allOf": [ + { + "name": "Ssaia" + }, + { + "name": "H" + }, + { + "name": "Ssstateen" + } + ] + } + }, + "summary": "ext:Ssaia AND ext:H AND ext:Ssstateen" + }, + "value_type": { + "type": "enum", + "details": { + "values": [ + "rw", + "read-only-0", + "read-only-1" + ] + } + }, + "has_requirements": true, + "requirements_summary": "HSTATEEN cannot have more options that MSTATEEN\nHSTATEEN cannot have more options that MSTATEEN\n", + "csr_references": [], + "classification": "NORM_CSR_RW", + "classification_confidence": "low", + "classification_reasoning": "CSR field type control parameter for 'hstateen' (determines RO/RW behavior)", + "source_file": "spec/std/isa/param/HSTATEEN_IMSIC_TYPE.yaml" + }, + { + "name": "HSTATEEN_JVT_TYPE", + "long_name": "TODO", + "description": "Behavior of the hstateen0.JVT bit:\n\n * 'rw': read-write\n * 'read-only-0': read-only, fixed to 0\n * 'read-only-1': read-only, fixed to 1", + "defined_by": { + "extensions": [ + "H", + "Ssstateen", + "Zcmt" + ], + "params": [], + "raw": { + "extension": { + "allOf": [ + { + "name": "Zcmt" + }, + { + "name": "H" + }, + { + "name": "Ssstateen" + } + ] + } + }, + "summary": "ext:Zcmt AND ext:H AND ext:Ssstateen" + }, + "value_type": { + "type": "enum", + "details": { + "values": [ + "rw", + "read-only-0", + "read-only-1" + ] + } + }, + "has_requirements": true, + "requirements_summary": "HSTATEEN cannot have more options that MSTATEEN\n", + "csr_references": [], + "classification": "NORM_CSR_RW", + "classification_confidence": "low", + "classification_reasoning": "CSR field type control parameter for 'hstateen' (determines RO/RW behavior)", + "source_file": "spec/std/isa/param/HSTATEEN_JVT_TYPE.yaml" + }, + { + "name": "HW_MSTATUS_FS_DIRTY_UPDATE", + "long_name": "TODO", + "description": "Indicates whether or not hardware will write to `mstatus.FS`\n\nValues are:\n[separator=\"!\"]\n!===\nh! never ! Hardware never writes `mstatus.FS`\nh! precise ! Hardware writes `mstatus.FS` to the Dirty (3) state precisely when F registers are modified\nh! imprecise ! Hardware writes `mstatus.FS` imprecisely. This will result in a call to unpredictable() on any attempt to read `mstatus` or write FP state.\n!===", + "defined_by": { + "extensions": [ + "F" + ], + "params": [], + "raw": { + "extension": { + "name": "F" + } + }, + "summary": "ext:F" + }, + "value_type": { + "type": "enum", + "details": { + "values": [ + "never", + "precise", + "imprecise" + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "mstatus", + "field": "SD", + "idl_key": "type()" + } + ], + "classification": "SW_RULE", + "classification_confidence": "medium", + "classification_reasoning": "Hardware update behavior (HW_ prefix) — software-deterministic with correct fencing", + "source_file": "spec/std/isa/param/HW_MSTATUS_FS_DIRTY_UPDATE.yaml" + }, + { + "name": "HW_MSTATUS_VS_DIRTY_UPDATE", + "long_name": "TODO", + "description": "Indicates whether or not hardware will write to `mstatus.VS`\n\nValues are:\n[separator=\"!\"]\n!===\nh! never ! Hardware never writes `mstatus.VS`\nh! precise ! Hardware writes `mstatus.VS` to the Dirty (3) state precisely when V registers are modified\nh! imprecise ! Hardware writes `mstatus.VS` imprecisely. This will result in a call to unpredictable() on any attempt to read `mstatus` or write vector state.\n!===", + "defined_by": { + "extensions": [ + "V" + ], + "params": [], + "raw": { + "extension": { + "name": "V" + } + }, + "summary": "ext:V" + }, + "value_type": { + "type": "enum", + "details": { + "values": [ + "never", + "precise", + "imprecise" + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "mstatus", + "field": "SD", + "idl_key": "type()" + } + ], + "classification": "SW_RULE", + "classification_confidence": "medium", + "classification_reasoning": "Hardware update behavior (HW_ prefix) — software-deterministic with correct fencing", + "source_file": "spec/std/isa/param/HW_MSTATUS_VS_DIRTY_UPDATE.yaml" + }, + { + "name": "IGNORE_INVALID_VSATP_MODE_WRITES_WHEN_V_EQ_ZERO", + "long_name": "TODO", + "description": "Whether writes from M-mode, U-mode, or S-mode to vsatp with an illegal mode setting are\nignored (as they are with satp), or if they are treated as WARL, leading to undpredictable\nbehavior.", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "vsatp", + "field": "MODE", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "vsatp", + "field": "ASID", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "vsatp", + "field": "PPN", + "idl_key": "sw_write(csr_value)" + } + ], + "classification": "NORM_CSR_WARL", + "classification_confidence": "high", + "classification_reasoning": "Referenced in sw_write() of vsatp.MODE", + "source_file": "spec/std/isa/param/IGNORE_INVALID_VSATP_MODE_WRITES_WHEN_V_EQ_ZERO.yaml" + }, + { + "name": "IMP_ID_VALUE", + "long_name": "Vendor-specific implementation ID in `mimpid`", + "description": "A unique encoding of the version of the processor implementation.", + "defined_by": { + "extensions": [ + "Sm" + ], + "params": [ + { + "name": "MIMPID_IMPLEMENTED", + "condition": { + "equal": true + } + } + ], + "raw": { + "allOf": [ + { + "extension": { + "name": "Sm" + } + }, + { + "param": { + "name": "MIMPID_IMPLEMENTED", + "equal": true, + "reason": "IMP_ID_VALUE is not needed if `mimpid` is not implemented." + } + } + ] + }, + "summary": "ext:Sm AND param:MIMPID_IMPLEMENTED(equal=True)" + }, + "value_type": { + "type": "conditional", + "details": { + "branches": [ + { + "condition": "MXLEN == 32", + "inner_type": { + "type": "value", + "details": { + "ref": "schema_defs.json#/$defs/uint32" + } + } + }, + { + "condition": "MXLEN == 64", + "inner_type": { + "type": "value", + "details": { + "ref": "schema_defs.json#/$defs/uint64" + } + } + } + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "mimpid", + "field": "Implementation", + "idl_key": "reset_value()" + } + ], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Well-known architectural parameter 'IMP_ID_VALUE'", + "source_file": "spec/std/isa/param/IMP_ID_VALUE.yaml" + }, + { + "name": "JVT_BASE_MASK", + "long_name": "Mask representing the implemented bits of jvt.BASE", + "description": "Mask representing the implemented bits of jvt.BASE.\nIncludes the implicitly-zero bits of jvt.BASE, so JVT_BASE_MASK[5:0] must always be 0.", + "defined_by": { + "extensions": [ + "Zcmt" + ], + "params": [ + { + "name": "JVT_BASE_TYPE", + "condition": { + "equal": "mask" + } + } + ], + "raw": { + "allOf": [ + { + "extension": { + "name": "Zcmt" + } + }, + { + "param": { + "name": "JVT_BASE_TYPE", + "equal": "mask" + } + } + ] + }, + "summary": "ext:Zcmt AND param:JVT_BASE_TYPE(equal=mask)" + }, + "value_type": { + "type": "range", + "details": { + "minimum": 64, + "maximum": 576460752303423487 + } + }, + "has_requirements": true, + "requirements_summary": "Includes the implicitly-zero bits of jvt.BASE, so JVT_BASE_MASK[5:0] must always be 0.\n", + "csr_references": [ + { + "csr": "jvt", + "field": "BASE", + "idl_key": "sw_write(csr_value)" + } + ], + "classification": "NORM_CSR_WARL", + "classification_confidence": "high", + "classification_reasoning": "Referenced in sw_write() of jvt.BASE", + "source_file": "spec/std/isa/param/JVT_BASE_MASK.yaml" + }, + { + "name": "JVT_BASE_TYPE", + "long_name": "Type of the jvt.BASE CSR field", + "description": "Type of the jvt.BASE CSR field. One of:\n\n* mask: jvt.BASE contains one or more implemented bits, which are indicated by JVT_BASE_MASK.\n* custom: Custom behavior. Will cause hart to enter 'unpredictable' state on a write to jvt.BASE.", + "defined_by": { + "extensions": [ + "Zcmt" + ], + "params": [], + "raw": { + "extension": { + "name": "Zcmt" + } + }, + "summary": "ext:Zcmt" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + "mask", + "custom" + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "jvt", + "field": "BASE", + "idl_key": "sw_write(csr_value)" + } + ], + "classification": "NORM_CSR_WARL", + "classification_confidence": "high", + "classification_reasoning": "Referenced in sw_write() of jvt.BASE", + "source_file": "spec/std/isa/param/JVT_BASE_TYPE.yaml" + }, + { + "name": "JVT_READ_ONLY", + "long_name": "Whether or not the JVT CSR is read-only", + "description": "If Zcmt is implemented, JVT is implemented, but can contain a read-only value", + "defined_by": { + "extensions": [ + "Zcmt" + ], + "params": [], + "raw": { + "extension": { + "name": "Zcmt" + } + }, + "summary": "ext:Zcmt" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "jvt", + "field": "BASE", + "idl_key": "type()" + }, + { + "csr": "jvt", + "field": "MODE", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "jvt", + "field": "MODE", + "idl_key": "type()" + } + ], + "classification": "NORM_CSR_WARL", + "classification_confidence": "high", + "classification_reasoning": "Referenced in sw_write() of jvt.MODE", + "source_file": "spec/std/isa/param/JVT_READ_ONLY.yaml" + }, + { + "name": "LRSC_FAIL_ON_NON_EXACT_LRSC", + "long_name": "TODO", + "description": "Whether or not a Store Conditional fails if its physical address and size do not\nexactly match the physical address and size of the last Load Reserved in program order\n(independent of whether or not the SC is in the current reservation set)", + "defined_by": { + "extensions": [ + "Zalrsc" + ], + "params": [], + "raw": { + "extension": { + "name": "Zalrsc" + } + }, + "summary": "ext:Zalrsc" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "medium", + "classification_reasoning": "Load-reserved/store-conditional behavior parameter", + "source_file": "spec/std/isa/param/LRSC_FAIL_ON_NON_EXACT_LRSC.yaml" + }, + { + "name": "LRSC_FAIL_ON_VA_SYNONYM", + "long_name": "TODO", + "description": "Whether or not an `sc.l`/`sc.d` will fail if its VA does not match the VA of the prior\n`lr.l`/`lr.d`, even if the physical address of the SC and LR are the same", + "defined_by": { + "extensions": [ + "Zalrsc" + ], + "params": [], + "raw": { + "extension": { + "name": "Zalrsc" + } + }, + "summary": "ext:Zalrsc" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "medium", + "classification_reasoning": "Load-reserved/store-conditional behavior parameter", + "source_file": "spec/std/isa/param/LRSC_FAIL_ON_VA_SYNONYM.yaml" + }, + { + "name": "LRSC_MISALIGNED_BEHAVIOR", + "long_name": "TODO", + "description": "What to do when an LR/SC address is misaligned and MISALIGNED_AMO == false.\n\n * 'always raise misaligned exception': self-explainitory\n * 'always raise access fault': self-explainitory\n * 'custom': Custom behavior; misaligned LR/SC may sometimes raise a misaligned exception and sometimes raise a access fault. Will lead to an 'unpredictable' call on any misaligned LR/SC access", + "defined_by": { + "extensions": [ + "Zalrsc" + ], + "params": [], + "raw": { + "extension": { + "name": "Zalrsc" + } + }, + "summary": "ext:Zalrsc" + }, + "value_type": { + "type": "enum", + "details": { + "values": [ + "always raise misaligned exception", + "always raise access fault", + "custom" + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "medium", + "classification_reasoning": "Load-reserved/store-conditional behavior parameter", + "source_file": "spec/std/isa/param/LRSC_MISALIGNED_BEHAVIOR.yaml" + }, + { + "name": "LRSC_RESERVATION_STRATEGY", + "long_name": "TODO", + "description": "Strategy used to handle reservation sets.\n\n * \"reserve naturally-aligned 64-byte region\": Always reserve the 64-byte block containing the LR/SC address\n * \"reserve naturally-aligned 128-byte region\": Always reserve the 128-byte block containing the LR/SC address\n * \"reserve exactly enough to cover the access\": Always reserve exactly the LR/SC access, and no more\n * \"custom\": Custom behavior, leading to an 'unpredictable' call on any LR/SC", + "defined_by": { + "extensions": [ + "Zalrsc" + ], + "params": [], + "raw": { + "extension": { + "name": "Zalrsc" + } + }, + "summary": "ext:Zalrsc" + }, + "value_type": { + "type": "enum", + "details": { + "values": [ + "reserve naturally-aligned 64-byte region", + "reserve naturally-aligned 128-byte region", + "reserve exactly enough to cover the access", + "custom" + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "medium", + "classification_reasoning": "Load-reserved/store-conditional behavior parameter", + "source_file": "spec/std/isa/param/LRSC_RESERVATION_STRATEGY.yaml" + }, + { + "name": "MARCHID_IMPLEMENTED", + "long_name": "Whether or not the `marchid` CSR is implemented.", + "description": "* false: `marchid` is not implemented, and must be read-only-0\n* true: `marchid` is implemented, and the value is determined by `ARCH_ID_VALUE`", + "defined_by": { + "extensions": [ + "Sm" + ], + "params": [], + "raw": { + "extension": { + "name": "Sm" + } + }, + "summary": "ext:Sm" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Feature/CSR existence parameter ('IMPLEMENTED' suffix)", + "source_file": "spec/std/isa/param/MARCHID_IMPLEMENTED.yaml" + }, + { + "name": "MCID_WIDTH", + "long_name": "TODO", + "description": "Number of bits used for the Monitoring Counter ID field (MCID).\nDefault is 12.", + "defined_by": { + "extensions": [ + "Ssqosid" + ], + "params": [], + "raw": { + "extension": { + "name": "Ssqosid" + } + }, + "summary": "ext:Ssqosid" + }, + "value_type": { + "type": "range", + "details": { + "minimum": 1, + "maximum": 12 + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "srmcfg", + "field": "MCID", + "idl_key": "sw_write(csr_value)" + } + ], + "classification": "NORM_CSR_WARL", + "classification_confidence": "high", + "classification_reasoning": "Referenced in sw_write() of srmcfg.MCID", + "source_file": "spec/std/isa/param/MCID_WIDTH.yaml" + }, + { + "name": "MCONTEXT_AVAILABLE", + "long_name": "TODO", + "description": "Specifies if MCONTEXT is available", + "defined_by": { + "extensions": [ + "Sdtrig" + ], + "params": [], + "raw": { + "extension": { + "name": "Sdtrig" + } + }, + "summary": "ext:Sdtrig" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "mcontext", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "mcontext", + "field": "HCONTEXT", + "idl_key": "sw_write(csr_value)" + } + ], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Feature/CSR existence parameter ('AVAILABLE' suffix)", + "source_file": "spec/std/isa/param/MCONTEXT_AVAILABLE.yaml" + }, + { + "name": "MCOUNTENABLE_EN", + "long_name": "TODO", + "description": "Indicates which counters can be delegated via `mcounteren`.\n\nAn unimplemented counter cannot be specified, i.e., if\nHPM_COUNTER_EN[3] is false, it would be illegal to set\nMCOUNTENABLE_EN[3] to true.\n\nMCOUNTENABLE_EN[0:2] must all be false if `Zicntr` is not implemented.\nMCOUNTENABLE_EN[3:31] must all be false if `Zihpm` is not implemented.", + "defined_by": { + "extensions": [ + "U" + ], + "params": [], + "raw": { + "extension": { + "name": "U" + } + }, + "summary": "ext:U" + }, + "value_type": { + "type": "bitmask", + "details": { + "length": 32 + } + }, + "has_requirements": true, + "requirements_summary": "for (U32 i=3; i < 32; i++) {\n MCOUNTENABLE_EN[i] -> !implemented?(ExtensionName::Smhpm) || HPM_COUNTER_EN[i];\n}\n", + "csr_references": [ + { + "csr": "mcounteren", + "field": "CY", + "idl_key": "type()" + }, + { + "csr": "mcounteren", + "field": "CY", + "idl_key": "reset_value()" + }, + { + "csr": "mcounteren", + "field": "IR", + "idl_key": "type()" + }, + { + "csr": "mcounteren", + "field": "IR", + "idl_key": "reset_value()" + }, + { + "csr": "mcounteren", + "field": "HPM3", + "idl_key": "type()" + }, + { + "csr": "mcounteren", + "field": "HPM3", + "idl_key": "reset_value()" + }, + { + "csr": "mcounteren", + "field": "HPM4", + "idl_key": "type()" + }, + { + "csr": "mcounteren", + "field": "HPM4", + "idl_key": "reset_value()" + }, + { + "csr": "mcounteren", + "field": "HPM5", + "idl_key": "type()" + }, + { + "csr": "mcounteren", + "field": "HPM5", + "idl_key": "reset_value()" + }, + { + "csr": "mcounteren", + "field": "HPM6", + "idl_key": "type()" + }, + { + "csr": "mcounteren", + "field": "HPM6", + "idl_key": "reset_value()" + }, + { + "csr": "mcounteren", + "field": "HPM7", + "idl_key": "type()" + }, + { + "csr": "mcounteren", + "field": "HPM7", + "idl_key": "reset_value()" + }, + { + "csr": "mcounteren", + "field": "HPM8", + "idl_key": "type()" + }, + { + "csr": "mcounteren", + "field": "HPM8", + "idl_key": "reset_value()" + }, + { + "csr": "mcounteren", + "field": "HPM9", + "idl_key": "type()" + }, + { + "csr": "mcounteren", + "field": "HPM9", + "idl_key": "reset_value()" + }, + { + "csr": "mcounteren", + "field": "HPM10", + "idl_key": "type()" + }, + { + "csr": "mcounteren", + "field": "HPM10", + "idl_key": "reset_value()" + }, + { + "csr": "mcounteren", + "field": "HPM11", + "idl_key": "type()" + }, + { + "csr": "mcounteren", + "field": "HPM11", + "idl_key": "reset_value()" + }, + { + "csr": "mcounteren", + "field": "HPM12", + "idl_key": "type()" + }, + { + "csr": "mcounteren", + "field": "HPM12", + "idl_key": "reset_value()" + }, + { + "csr": "mcounteren", + "field": "HPM13", + "idl_key": "type()" + }, + { + "csr": "mcounteren", + "field": "HPM13", + "idl_key": "reset_value()" + }, + { + "csr": "mcounteren", + "field": "HPM14", + "idl_key": "type()" + }, + { + "csr": "mcounteren", + "field": "HPM14", + "idl_key": "reset_value()" + }, + { + "csr": "mcounteren", + "field": "HPM15", + "idl_key": "type()" + }, + { + "csr": "mcounteren", + "field": "HPM15", + "idl_key": "reset_value()" + }, + { + "csr": "mcounteren", + "field": "HPM16", + "idl_key": "type()" + }, + { + "csr": "mcounteren", + "field": "HPM16", + "idl_key": "reset_value()" + }, + { + "csr": "mcounteren", + "field": "HPM17", + "idl_key": "type()" + }, + { + "csr": "mcounteren", + "field": "HPM17", + "idl_key": "reset_value()" + }, + { + "csr": "mcounteren", + "field": "HPM18", + "idl_key": "type()" + }, + { + "csr": "mcounteren", + "field": "HPM18", + "idl_key": "reset_value()" + }, + { + "csr": "mcounteren", + "field": "HPM19", + "idl_key": "type()" + }, + { + "csr": "mcounteren", + "field": "HPM19", + "idl_key": "reset_value()" + }, + { + "csr": "mcounteren", + "field": "HPM20", + "idl_key": "type()" + }, + { + "csr": "mcounteren", + "field": "HPM20", + "idl_key": "reset_value()" + }, + { + "csr": "mcounteren", + "field": "HPM21", + "idl_key": "type()" + }, + { + "csr": "mcounteren", + "field": "HPM21", + "idl_key": "reset_value()" + }, + { + "csr": "mcounteren", + "field": "HPM22", + "idl_key": "type()" + }, + { + "csr": "mcounteren", + "field": "HPM22", + "idl_key": "reset_value()" + }, + { + "csr": "mcounteren", + "field": "HPM23", + "idl_key": "type()" + }, + { + "csr": "mcounteren", + "field": "HPM23", + "idl_key": "reset_value()" + }, + { + "csr": "mcounteren", + "field": "HPM24", + "idl_key": "type()" + }, + { + "csr": "mcounteren", + "field": "HPM24", + "idl_key": "reset_value()" + }, + { + "csr": "mcounteren", + "field": "HPM25", + "idl_key": "type()" + }, + { + "csr": "mcounteren", + "field": "HPM25", + "idl_key": "reset_value()" + }, + { + "csr": "mcounteren", + "field": "HPM26", + "idl_key": "type()" + }, + { + "csr": "mcounteren", + "field": "HPM26", + "idl_key": "reset_value()" + }, + { + "csr": "mcounteren", + "field": "HPM27", + "idl_key": "type()" + }, + { + "csr": "mcounteren", + "field": "HPM27", + "idl_key": "reset_value()" + }, + { + "csr": "mcounteren", + "field": "HPM28", + "idl_key": "type()" + }, + { + "csr": "mcounteren", + "field": "HPM28", + "idl_key": "reset_value()" + }, + { + "csr": "mcounteren", + "field": "HPM29", + "idl_key": "type()" + }, + { + "csr": "mcounteren", + "field": "HPM29", + "idl_key": "reset_value()" + }, + { + "csr": "mcounteren", + "field": "HPM30", + "idl_key": "type()" + }, + { + "csr": "mcounteren", + "field": "HPM30", + "idl_key": "reset_value()" + }, + { + "csr": "mcounteren", + "field": "HPM31", + "idl_key": "type()" + }, + { + "csr": "mcounteren", + "field": "HPM31", + "idl_key": "reset_value()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of mcounteren.CY", + "source_file": "spec/std/isa/param/MCOUNTENABLE_EN.yaml" + }, + { + "name": "MIMPID_IMPLEMENTED", + "long_name": "Whether or not the `mimpid` CSR is implemented.", + "description": "* false: `mimpid` is not implemented, and must be read-only-0\n* true: `mimpid` is implemented, and the value is determined by `IMP_ID_VALUE`", + "defined_by": { + "extensions": [ + "Sm" + ], + "params": [], + "raw": { + "extension": { + "name": "Sm" + } + }, + "summary": "ext:Sm" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Feature/CSR existence parameter ('IMPLEMENTED' suffix)", + "source_file": "spec/std/isa/param/MIMPID_IMPLEMENTED.yaml" + }, + { + "name": "MISALIGNED_AMO", + "long_name": "TODO", + "description": "whether or not the implementation supports misaligned atomics in main memory", + "defined_by": { + "extensions": [ + "Zaamo" + ], + "params": [], + "raw": { + "extension": { + "name": "Zaamo" + } + }, + "summary": "ext:Zaamo" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "medium", + "classification_reasoning": "Misaligned access behavior parameter", + "source_file": "spec/std/isa/param/MISALIGNED_AMO.yaml" + }, + { + "name": "MISALIGNED_LDST", + "long_name": "Support for misaligned loads and stores to main memory.", + "description": "Does the implementation perform non-atomic misaligned loads and stores to main memory\n(does *not* affect misaligned support to device memory)?\nIf not, the implementation always throws a misaligned exception.", + "defined_by": { + "extensions": [ + "Sm" + ], + "params": [], + "raw": { + "extension": { + "name": "Sm" + } + }, + "summary": "ext:Sm" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "medium", + "classification_reasoning": "Misaligned access behavior parameter", + "source_file": "spec/std/isa/param/MISALIGNED_LDST.yaml" + }, + { + "name": "MISALIGNED_LDST_EXCEPTION_PRIORITY", + "long_name": "The relative priority of a load/store/AMO exception vs. load/store/AMO page-fault\nor access-fault exceptions.", + "description": "The relative priority of a load/store/AMO exception vs. load/store/AMO page-fault\nor access-fault exceptions.\n\nMay be one of:\n\n[separator=\"!\"]\n!===\n! low ! Misaligned load/store/AMO exceptions are always lower priority than load/store/AMO page-fault and access-fault exceptions.\n! high ! Misaligned load/store/AMO exceptions are always higher priority than load/store/AMO page-fault and access-fault exceptions.\n!===\n\nMISALIGNED_LDST_EXCEPTION_PRIORITY cannot be \"high\" when MISALIGNED_MAX_ATOMICITY_GRANULE_SIZE\nis non-zero, since the atomicity of an access cannot be determined in that case until after\naddress translation.", + "defined_by": { + "extensions": [ + "Sm" + ], + "params": [], + "raw": { + "extension": { + "name": "Sm" + } + }, + "summary": "ext:Sm" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + "low", + "high" + ] + } + }, + "has_requirements": true, + "requirements_summary": "MISALIGNED_LDST_EXCEPTION_PRIORITY cannot be \"high\" when MISALIGNED_MAX_ATOMICITY_GRANULE_SIZE is non-zero, since the atomicity of an access cannot be determined in that case until after address translation.", + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "medium", + "classification_reasoning": "Misaligned access behavior parameter", + "source_file": "spec/std/isa/param/MISALIGNED_LDST_EXCEPTION_PRIORITY.yaml" + }, + { + "name": "MISALIGNED_MAX_ATOMICITY_GRANULE_SIZE", + "long_name": "The maximum granule size, in bytes, that the hart can atomically perform a\nmisaligned load/store/AMO without raising a Misaligned exception", + "description": "When MISALIGNED_MAX_ATOMICITY_GRANULE_SIZE is 0, the hart\ncannot atomically perform a misaligned load/store/AMO. When a power of two, the hart can\natomically load/store/AMO a misaligned access that is fully contained in a\nMISALIGNED_MAX_ATOMICITY_GRANULE_SIZE-aligned region.\n\n[NOTE]\nEven if the hart is capable of performing a misaligned load/store/AMO atomically,\na misaligned exception may still occur if the access does not have the appropriate\nMisaligned Atomicity Granule PMA set.", + "defined_by": { + "extensions": [ + "Sm" + ], + "params": [ + { + "name": "MISALIGNED_LDST", + "condition": { + "equal": true + } + } + ], + "raw": { + "allOf": [ + { + "extension": { + "name": "Sm" + } + }, + { + "param": { + "name": "MISALIGNED_LDST", + "equal": true, + "reason": "Granule size is only relevant when misaligned load/stores might execute without an exception." + } + } + ] + }, + "summary": "ext:Sm AND param:MISALIGNED_LDST(equal=True)" + }, + "value_type": { + "type": "enum", + "details": { + "values": [ + 0, + 2, + 4, + 8, + 16, + 32, + 64, + 128, + 256, + 512, + 1024, + 2048, + 4096 + ] + } + }, + "has_requirements": true, + "requirements_summary": "MISALIGNED_LDST_EXCEPTION_PRIORITY cannot be \"high\" when MISALIGNED_MAX_ATOMICITY_GRANULE_SIZE is non-zero, since the atomicity of an access cannot be determined in that case until after address translation.", + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "medium", + "classification_reasoning": "Misaligned access behavior parameter", + "source_file": "spec/std/isa/param/MISALIGNED_MAX_ATOMICITY_GRANULE_SIZE.yaml" + }, + { + "name": "MISALIGNED_SPLIT_STRATEGY", + "long_name": "The *order* the implementation appears\nto process a non-atomic misaligned load/store, which determines how/which\nexceptions will be reported.", + "description": "Options:\n\n * sequential_bytes: The load/store appears to be broken into byte-sized accesses that processed sequentially from smallest address to largest address\n * custom: Something else. Will result in a call to unpredictable() in the execution", + "defined_by": { + "extensions": [ + "Sm" + ], + "params": [ + { + "name": "MISALIGNED_LDST", + "condition": { + "equal": true + } + } + ], + "raw": { + "allOf": [ + { + "extension": { + "name": "Sm" + } + }, + { + "param": { + "name": "MISALIGNED_LDST", + "equal": true, + "reason": "Granule size is only relevant when misaligned load/stores might execute without an exception." + } + } + ] + }, + "summary": "ext:Sm AND param:MISALIGNED_LDST(equal=True)" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + "sequential_bytes", + "custom" + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "medium", + "classification_reasoning": "Misaligned access behavior parameter", + "source_file": "spec/std/isa/param/MISALIGNED_SPLIT_STRATEGY.yaml" + }, + { + "name": "MISA_CSR_IMPLEMENTED", + "long_name": "Whether or not the `misa` CSR is implemented", + "description": "Options:\n\n true::\n The `misa` CSR returns a non-zero value.\n\n false::\n The `misa` CSR is read-only-0.", + "defined_by": { + "extensions": [ + "Sm" + ], + "params": [], + "raw": { + "extension": { + "name": "Sm" + } + }, + "summary": "ext:Sm" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "mstatus", + "field": "FS", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "mstatus", + "field": "FS", + "idl_key": "type()" + }, + { + "csr": "mstatus", + "field": "VS", + "idl_key": "type()" + } + ], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Feature/CSR existence parameter ('IMPLEMENTED' suffix)", + "source_file": "spec/std/isa/param/MISA_CSR_IMPLEMENTED.yaml" + }, + { + "name": "MSTATEEN_AIA_TYPE", + "long_name": "TODO", + "description": "Behavior of the mstateen0.AIA bit:\n\n * 'rw': read-write\n * 'read-only-0': read-only, fixed to 0\n * 'read-only-1': read-only, fixed to 1", + "defined_by": { + "extensions": [ + "Smstateen", + "Ssaia" + ], + "params": [], + "raw": { + "extension": { + "allOf": [ + { + "name": "Ssaia" + }, + { + "name": "Smstateen", + "version": "~> 1.0" + } + ] + } + }, + "summary": "ext:Ssaia AND ext:Smstateen(~> 1.0)" + }, + "value_type": { + "type": "enum", + "details": { + "values": [ + "rw", + "read-only-0", + "read-only-1" + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_CSR_RW", + "classification_confidence": "low", + "classification_reasoning": "CSR field type control parameter for 'mstateen' (determines RO/RW behavior)", + "source_file": "spec/std/isa/param/MSTATEEN_AIA_TYPE.yaml" + }, + { + "name": "MSTATEEN_CONTEXT_TYPE", + "long_name": "TODO", + "description": "Behavior of the mstateen0.CONTEXT bit:\n\n * 'rw': read-write\n * 'read-only-0': read-only, fixed to 0\n * 'read-only-1': read-only, fixed to 1", + "defined_by": { + "extensions": [ + "Sdtrig", + "Smstateen" + ], + "params": [], + "raw": { + "extension": { + "allOf": [ + { + "name": "Sdtrig" + }, + { + "name": "Smstateen" + } + ] + } + }, + "summary": "ext:Sdtrig AND ext:Smstateen" + }, + "value_type": { + "type": "enum", + "details": { + "values": [ + "rw", + "read-only-0", + "read-only-1" + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_CSR_RW", + "classification_confidence": "low", + "classification_reasoning": "CSR field type control parameter for 'mstateen' (determines RO/RW behavior)", + "source_file": "spec/std/isa/param/MSTATEEN_CONTEXT_TYPE.yaml" + }, + { + "name": "MSTATEEN_CSRIND_TYPE", + "long_name": "TODO", + "description": "Behavior of the mstateen0.CSRIND bit:\n\n * 'rw': read-write\n * 'read-only-0': read-only, fixed to 0\n * 'read-only-1': read-only, fixed to 1", + "defined_by": { + "extensions": [ + "Smstateen", + "Sscsrind" + ], + "params": [], + "raw": { + "extension": { + "allOf": [ + { + "name": "Sscsrind" + }, + { + "name": "Smstateen" + } + ] + } + }, + "summary": "ext:Sscsrind AND ext:Smstateen" + }, + "value_type": { + "type": "enum", + "details": { + "values": [ + "rw", + "read-only-0", + "read-only-1" + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_CSR_RW", + "classification_confidence": "low", + "classification_reasoning": "CSR field type control parameter for 'mstateen' (determines RO/RW behavior)", + "source_file": "spec/std/isa/param/MSTATEEN_CSRIND_TYPE.yaml" + }, + { + "name": "MSTATEEN_ENVCFG_TYPE", + "long_name": "TODO", + "description": "Behavior of the mstateen0.ENVCFG bit:\n\n * 'rw': read-write\n * 'read-only-0': read-only, fixed to 0\n * 'read-only-1': read-only, fixed to 1", + "defined_by": { + "extensions": [ + "S", + "Smstateen" + ], + "params": [], + "raw": { + "extension": { + "allOf": [ + { + "name": "S" + }, + { + "name": "Smstateen" + } + ] + } + }, + "summary": "ext:S AND ext:Smstateen" + }, + "value_type": { + "type": "enum", + "details": { + "values": [ + "rw", + "read-only-0", + "read-only-1" + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_CSR_RW", + "classification_confidence": "low", + "classification_reasoning": "CSR field type control parameter for 'mstateen' (determines RO/RW behavior)", + "source_file": "spec/std/isa/param/MSTATEEN_ENVCFG_TYPE.yaml" + }, + { + "name": "MSTATEEN_IMSIC_TYPE", + "long_name": "TODO", + "description": "Behavior of the mstateen0.IMSIC bit:\n\n * 'rw': read-write\n * 'read-only-0': read-only, fixed to 0\n * 'read-only-1': read-only, fixed to 1", + "defined_by": { + "extensions": [ + "Smstateen", + "Ssaia" + ], + "params": [], + "raw": { + "extension": { + "allOf": [ + { + "name": "Ssaia" + }, + { + "name": "Smstateen", + "version": "~> 1.0" + } + ] + } + }, + "summary": "ext:Ssaia AND ext:Smstateen(~> 1.0)" + }, + "value_type": { + "type": "enum", + "details": { + "values": [ + "rw", + "read-only-0", + "read-only-1" + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_CSR_RW", + "classification_confidence": "low", + "classification_reasoning": "CSR field type control parameter for 'mstateen' (determines RO/RW behavior)", + "source_file": "spec/std/isa/param/MSTATEEN_IMSIC_TYPE.yaml" + }, + { + "name": "MSTATEEN_JVT_TYPE", + "long_name": "TODO", + "description": "Behavior of the mstateen0.JVT bit:\n\n * 'rw': read-write\n * 'read-only-0': read-only, fixed to 0\n * 'read-only-1': read-only, fixed to 1", + "defined_by": { + "extensions": [ + "Smstateen", + "Zcmt" + ], + "params": [], + "raw": { + "extension": { + "allOf": [ + { + "name": "Zcmt" + }, + { + "name": "Smstateen", + "version": "~> 1.0" + } + ] + } + }, + "summary": "ext:Zcmt AND ext:Smstateen(~> 1.0)" + }, + "value_type": { + "type": "enum", + "details": { + "values": [ + "rw", + "read-only-0", + "read-only-1" + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_CSR_RW", + "classification_confidence": "low", + "classification_reasoning": "CSR field type control parameter for 'mstateen' (determines RO/RW behavior)", + "source_file": "spec/std/isa/param/MSTATEEN_JVT_TYPE.yaml" + }, + { + "name": "MSTATUS_FS_LEGAL_VALUES", + "long_name": "TODO", + "description": "The set of values that mstatus.FS supports.", + "defined_by": { + "extensions": [ + "F", + "S" + ], + "params": [], + "raw": { + "extension": { + "anyOf": [ + { + "name": "F" + }, + { + "name": "S" + } + ] + } + }, + "summary": "(ext:F OR ext:S)" + }, + "value_type": { + "type": "set", + "details": { + "universe": [ + 0, + 1, + 2, + 3 + ], + "min_items": 1, + "max_items": 4 + } + }, + "has_requirements": true, + "requirements_summary": "If there is a hardware update to mstatus.FS, then the Dirty state must be supported", + "csr_references": [ + { + "csr": "mstatus", + "field": "FS", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "mstatus", + "field": "FS", + "idl_key": "type()" + }, + { + "csr": "mstatus", + "field": "FS", + "idl_key": "reset_value()" + } + ], + "classification": "NORM_CSR_WARL", + "classification_confidence": "high", + "classification_reasoning": "Referenced in sw_write() of mstatus.FS", + "source_file": "spec/std/isa/param/MSTATUS_FS_LEGAL_VALUES.yaml" + }, + { + "name": "MSTATUS_TVM_IMPLEMENTED", + "long_name": "TODO", + "description": "Whether or not mstatus.TVM is implemented.\n\nWhen not implemented mstatus.TVM will be read-only-zero.", + "defined_by": { + "extensions": [ + "S" + ], + "params": [], + "raw": { + "extension": { + "name": "S" + } + }, + "summary": "ext:S" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "mstatus", + "field": "TVM", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "mstatus", + "field": "TVM", + "idl_key": "reset_value()" + } + ], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Feature/CSR existence parameter ('IMPLEMENTED' suffix)", + "source_file": "spec/std/isa/param/MSTATUS_TVM_IMPLEMENTED.yaml" + }, + { + "name": "MSTATUS_VS_LEGAL_VALUES", + "long_name": "TODO", + "description": "The set of values that mstatus.VS will accept from a software write.", + "defined_by": { + "extensions": [ + "S", + "V" + ], + "params": [], + "raw": { + "extension": { + "anyOf": [ + { + "name": "V" + }, + { + "name": "S" + } + ] + } + }, + "summary": "(ext:V OR ext:S)" + }, + "value_type": { + "type": "set", + "details": { + "universe": [ + 0, + 1, + 2, + 3 + ], + "min_items": 1, + "max_items": 4 + } + }, + "has_requirements": true, + "requirements_summary": "If V is supported, both Off (0) and Dirty (3) must be supported\n\nIf there is a hardware update to mstatus.VS, then the Dirty state must be supported\n", + "csr_references": [ + { + "csr": "mstatus", + "field": "VS", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "mstatus", + "field": "VS", + "idl_key": "type()" + }, + { + "csr": "mstatus", + "field": "VS", + "idl_key": "reset_value()" + } + ], + "classification": "NORM_CSR_WARL", + "classification_confidence": "high", + "classification_reasoning": "Referenced in sw_write() of mstatus.VS", + "source_file": "spec/std/isa/param/MSTATUS_VS_LEGAL_VALUES.yaml" + }, + { + "name": "MTVAL_WIDTH", + "long_name": "Width of the `mtval` CSR", + "description": "The number of implemented bits in the `mtval` CSR.\nThis is the CSR that may be written when a trap is taken into M-mode with exception-specific information to\nassist software in handling the trap (e.g., address associated with exception).\n\nMust be greater than or equal to _max_(`PHYS_ADDR_WIDTH`, `VA_SIZE`)", + "defined_by": { + "extensions": [ + "Sm" + ], + "params": [], + "raw": { + "extension": { + "name": "Sm" + } + }, + "summary": "ext:Sm" + }, + "value_type": { + "type": "conditional", + "details": { + "branches": [ + { + "condition": "MXLEN == 32", + "inner_type": { + "type": "range", + "details": { + "minimum": 0, + "maximum": 32 + } + } + }, + { + "condition": "MXLEN == 64", + "inner_type": { + "type": "range", + "details": { + "minimum": 0, + "maximum": 64 + } + } + } + ] + } + }, + "has_requirements": true, + "requirements_summary": "`mtval` must be able to hold physical and/or virtual addresses\n", + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "medium", + "classification_reasoning": "Trap value reporting parameter", + "source_file": "spec/std/isa/param/MTVAL_WIDTH.yaml" + }, + { + "name": "MTVEC_ACCESS", + "long_name": "Acess type of the `mtvec` CSR (read-only or read-write).", + "description": "Options:\n\n ro::\n `mtvec` is read-only.\n\n rw::\n `mtvec` is read-write, but may not accept all values.", + "defined_by": { + "extensions": [ + "Sm" + ], + "params": [], + "raw": { + "extension": { + "name": "Sm" + } + }, + "summary": "ext:Sm" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + "ro", + "rw" + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "mtvec", + "field": "BASE", + "idl_key": "type()" + }, + { + "csr": "mtvec", + "field": "MODE", + "idl_key": "type()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of mtvec.BASE", + "source_file": "spec/std/isa/param/MTVEC_ACCESS.yaml" + }, + { + "name": "MTVEC_BASE_ALIGNMENT_DIRECT", + "long_name": "Minumum alignment of `mtvec.BASE` when `mtvec.MODE` is 0 (direct)", + "description": "Minimum alignment of the base pointer. Because `mtvec` excludes the two least-significant bits of\nthe base, the minimum alignment cannot be less than 4.", + "defined_by": { + "extensions": [ + "Sm" + ], + "params": [ + { + "name": "MTVEC_MODES", + "condition": { + "includes": 0 + } + }, + { + "name": "MTVEC_ACCESS", + "condition": { + "equal": "rw" + } + } + ], + "raw": { + "allOf": [ + { + "extension": { + "name": "Sm" + } + }, + { + "param": { + "allOf": [ + { + "name": "MTVEC_MODES", + "includes": 0, + "reason": "Only relevant when direct mode is supported" + }, + { + "name": "MTVEC_ACCESS", + "equal": "rw", + "reason": "Base address is hard-coded when MTVEC_ACCESS is read-only" + } + ] + } + } + ] + }, + "summary": "ext:Sm AND {'param': {'allOf': [{'name': 'MTVEC_MODES', 'includes': 0, 'reason': 'Only rele" + }, + "value_type": { + "type": "conditional", + "details": { + "branches": [ + { + "condition": "MXLEN == 32", + "inner_type": { + "type": "enum", + "details": { + "values": [ + 4, + 8, + 16, + 32, + 64, + 128, + 256, + 512, + 1024, + 2048, + 4095, + 8192, + 16384, + 32768, + 65536, + 131072, + 262144, + 524288, + 1048576, + 2097152, + 4194304, + 8388608, + 16777216, + 33554432, + 67108864, + 134217728, + 268435456, + 536870912, + 1073741824, + 2147483648 + ] + } + } + }, + { + "condition": "MXLEN == 64", + "inner_type": { + "type": "enum", + "details": { + "values": [ + 4, + 8, + 16, + 32, + 64, + 128, + 256, + 512, + 1024, + 2048, + 4095, + 8192, + 16384, + 32768, + 65536, + 131072, + 262144, + 524288, + 1048576, + 2097152, + 4194304, + 8388608, + 16777216, + 33554432, + 67108864, + 134217728, + 268435456, + 536870912, + 1073741824, + 2147483648, + 4294967296, + 8589934592, + 17179869184, + 34359738368, + 68719476736, + 137438953472, + 274877906944, + 549755813888, + 1099511627776, + 2199023255552, + 4398046511104, + 8796093022208, + 17592186044416, + 35184372088832, + 70368744177664, + 140737488355328, + 281474976710656, + 562949953421312, + 1125899906842624, + 2251799813685248, + 4503599627370496, + 9007199254740992, + 18014398509481984, + 36028797018963968, + 72057594037927936, + 144115188075855872, + 288230376151711744, + 576460752303423488, + 1152921504606846976, + 2305843009213693952, + 4611686018427387904, + 9223372036854775808 + ] + } + } + } + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_CSR_WARL", + "classification_confidence": "low", + "classification_reasoning": "Name pattern suggests CSR 'mtvec' association, but no IDL cross-reference found", + "source_file": "spec/std/isa/param/MTVEC_BASE_ALIGNMENT_DIRECT.yaml" + }, + { + "name": "MTVEC_BASE_ALIGNMENT_VECTORED", + "long_name": "Minumum alignment of `mtvec.BASE` when `mtvec.MODE` is 1 (vectored)", + "description": "Because `mtvec` excludes the two least-significant bits of\nthe base, the minimum alignment cannot be less than 4.", + "defined_by": { + "extensions": [ + "Sm" + ], + "params": [ + { + "name": "MTVEC_MODES", + "condition": { + "includes": 1 + } + }, + { + "name": "MTVEC_ACCESS", + "condition": { + "equal": "rw" + } + } + ], + "raw": { + "allOf": [ + { + "extension": { + "name": "Sm" + } + }, + { + "param": { + "allOf": [ + { + "name": "MTVEC_MODES", + "includes": 1, + "reason": "Only relevant when vectored mode is supported" + }, + { + "name": "MTVEC_ACCESS", + "equal": "rw", + "reason": "Base address is hard-coded when MTVEC_ACCESS is read-only" + } + ] + } + } + ] + }, + "summary": "ext:Sm AND {'param': {'allOf': [{'name': 'MTVEC_MODES', 'includes': 1, 'reason': 'Only rele" + }, + "value_type": { + "type": "conditional", + "details": { + "branches": [ + { + "condition": "MXLEN == 32", + "inner_type": { + "type": "enum", + "details": { + "values": [ + 4, + 8, + 16, + 32, + 64, + 128, + 256, + 512, + 1024, + 2048, + 4095, + 8192, + 16384, + 32768, + 65536, + 131072, + 262144, + 524288, + 1048576, + 2097152, + 4194304, + 8388608, + 16777216, + 33554432, + 67108864, + 134217728, + 268435456, + 536870912, + 1073741824, + 2147483648 + ] + } + } + }, + { + "condition": "MXLEN == 64", + "inner_type": { + "type": "enum", + "details": { + "values": [ + 4, + 8, + 16, + 32, + 64, + 128, + 256, + 512, + 1024, + 2048, + 4095, + 8192, + 16384, + 32768, + 65536, + 131072, + 262144, + 524288, + 1048576, + 2097152, + 4194304, + 8388608, + 16777216, + 33554432, + 67108864, + 134217728, + 268435456, + 536870912, + 1073741824, + 2147483648, + 4294967296, + 8589934592, + 17179869184, + 34359738368, + 68719476736, + 137438953472, + 274877906944, + 549755813888, + 1099511627776, + 2199023255552, + 4398046511104, + 8796093022208, + 17592186044416, + 35184372088832, + 70368744177664, + 140737488355328, + 281474976710656, + 562949953421312, + 1125899906842624, + 2251799813685248, + 4503599627370496, + 9007199254740992, + 18014398509481984, + 36028797018963968, + 72057594037927936, + 144115188075855872, + 288230376151711744, + 576460752303423488, + 1152921504606846976, + 2305843009213693952, + 4611686018427387904, + 9223372036854775808 + ] + } + } + } + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_CSR_WARL", + "classification_confidence": "low", + "classification_reasoning": "Name pattern suggests CSR 'mtvec' association, but no IDL cross-reference found", + "source_file": "spec/std/isa/param/MTVEC_BASE_ALIGNMENT_VECTORED.yaml" + }, + { + "name": "MTVEC_ILLEGAL_WRITE_BEHAVIOR", + "long_name": "What happens when `mtvec` is written with an illegal value", + "description": "Options:\n\n retain::\n When either `mtvec.MODE` or `mtvec.BASE` is illegal, `mtvec` will retain its current value\n\n custom::\n When either `mtvec.MODE` or `mtvec.BASE` is illegal, `mtvec` will obtain an unpredictable value\n\nOther values may be added over time once other common behaviors are identified.", + "defined_by": { + "extensions": [ + "Sm" + ], + "params": [], + "raw": { + "extension": { + "name": "Sm" + } + }, + "summary": "ext:Sm" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + "retain", + "custom" + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "mtvec", + "field": "BASE", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "mtvec", + "field": "MODE", + "idl_key": "sw_write(csr_value)" + } + ], + "classification": "NORM_CSR_WARL", + "classification_confidence": "high", + "classification_reasoning": "Referenced in sw_write() of mtvec.BASE", + "source_file": "spec/std/isa/param/MTVEC_ILLEGAL_WRITE_BEHAVIOR.yaml" + }, + { + "name": "MTVEC_MODES", + "long_name": "Modes supported by `mtvec.MODE`", + "description": "Options:\n\n 0::\n Direct; All traps set `pc` to `mtvec.BASE`\n 1::\n Vectored; Asynchronous interrupts set `pc` to `mtvec.BASE` + 4 x cause.\n\nIf only one mode is given, `mtvec.MODE` is assumed to be read-only with that value.\nOtherwise, `mtvec.MODE` is read-write.", + "defined_by": { + "extensions": [ + "Sm" + ], + "params": [], + "raw": { + "extension": { + "name": "Sm" + } + }, + "summary": "ext:Sm" + }, + "value_type": { + "type": "set", + "details": { + "universe": [ + 0, + 1 + ], + "min_items": 1, + "max_items": 2 + } + }, + "has_requirements": true, + "requirements_summary": "If `mtvec` is read-only, the mode cannot be changed.", + "csr_references": [ + { + "csr": "mtvec", + "field": "BASE", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "mtvec", + "field": "MODE", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "mtvec", + "field": "MODE", + "idl_key": "type()" + }, + { + "csr": "mtvec", + "field": "MODE", + "idl_key": "reset_value()" + } + ], + "classification": "NORM_CSR_WARL", + "classification_confidence": "high", + "classification_reasoning": "Referenced in sw_write() of mtvec.BASE", + "source_file": "spec/std/isa/param/MTVEC_MODES.yaml" + }, + { + "name": "MUTABLE_MISA_A", + "long_name": "TODO", + "description": "When the `A` extensions is supported, indicates whether or not\nthe extension can be disabled in the `misa.A` bit.", + "defined_by": { + "extensions": [ + "A" + ], + "params": [], + "raw": { + "extension": { + "name": "A" + } + }, + "summary": "ext:A" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "misa", + "field": "A", + "idl_key": "type()" + }, + { + "csr": "misa", + "field": "G", + "idl_key": "type()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of misa.A", + "source_file": "spec/std/isa/param/MUTABLE_MISA_A.yaml" + }, + { + "name": "MUTABLE_MISA_B", + "long_name": "TODO", + "description": "Indicates whether or not the `B` extension can be disabled with the `misa.B` bit.", + "defined_by": { + "extensions": [ + "B" + ], + "params": [], + "raw": { + "extension": { + "name": "B" + } + }, + "summary": "ext:B" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "misa", + "field": "B", + "idl_key": "type()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of misa.B", + "source_file": "spec/std/isa/param/MUTABLE_MISA_B.yaml" + }, + { + "name": "MUTABLE_MISA_C", + "long_name": "TODO", + "description": "Indicates whether or not the `C` extension can be disabled with the `misa.C` bit.", + "defined_by": { + "extensions": [ + "C" + ], + "params": [], + "raw": { + "extension": { + "name": "C" + } + }, + "summary": "ext:C" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "misa", + "field": "C", + "idl_key": "type()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of misa.C", + "source_file": "spec/std/isa/param/MUTABLE_MISA_C.yaml" + }, + { + "name": "MUTABLE_MISA_D", + "long_name": "TODO", + "description": "Indicates whether or not the `D` extension can be disabled with the `misa.D` bit.", + "defined_by": { + "extensions": [ + "D" + ], + "params": [], + "raw": { + "extension": { + "name": "D" + } + }, + "summary": "ext:D" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "misa", + "field": "D", + "idl_key": "type()" + }, + { + "csr": "misa", + "field": "G", + "idl_key": "type()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of misa.D", + "source_file": "spec/std/isa/param/MUTABLE_MISA_D.yaml" + }, + { + "name": "MUTABLE_MISA_F", + "long_name": "TODO", + "description": "Indicates whether or not the `F` extension can be disabled with the `misa.F` bit.", + "defined_by": { + "extensions": [ + "F" + ], + "params": [], + "raw": { + "extension": { + "name": "F" + } + }, + "summary": "ext:F" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "misa", + "field": "F", + "idl_key": "type()" + }, + { + "csr": "misa", + "field": "G", + "idl_key": "type()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of misa.F", + "source_file": "spec/std/isa/param/MUTABLE_MISA_F.yaml" + }, + { + "name": "MUTABLE_MISA_H", + "long_name": "TODO", + "description": "Indicates whether or not the `H` extension can be disabled with the `misa.H` bit.", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": true, + "requirements_summary": "If S mode can be disabled, then H mode must also be disabled since you can't be in H mode\nwithout S mode (and thus MUTABLE_MISA_H is not an option -- it's always true)\n", + "csr_references": [ + { + "csr": "misa", + "field": "H", + "idl_key": "type()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of misa.H", + "source_file": "spec/std/isa/param/MUTABLE_MISA_H.yaml" + }, + { + "name": "MUTABLE_MISA_M", + "long_name": "TODO", + "description": "Indicates whether or not the `M` extension can be disabled with the `misa.M` bit.", + "defined_by": { + "extensions": [ + "M" + ], + "params": [], + "raw": { + "extension": { + "name": "M" + } + }, + "summary": "ext:M" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "misa", + "field": "G", + "idl_key": "type()" + }, + { + "csr": "misa", + "field": "M", + "idl_key": "type()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of misa.G", + "source_file": "spec/std/isa/param/MUTABLE_MISA_M.yaml" + }, + { + "name": "MUTABLE_MISA_Q", + "long_name": "TODO", + "description": "Indicates whether or not the `Q` extension can be disabled with the `misa.Q` bit.", + "defined_by": { + "extensions": [ + "Q" + ], + "params": [], + "raw": { + "extension": { + "name": "Q" + } + }, + "summary": "ext:Q" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "misa", + "field": "Q", + "idl_key": "type()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of misa.Q", + "source_file": "spec/std/isa/param/MUTABLE_MISA_Q.yaml" + }, + { + "name": "MUTABLE_MISA_S", + "long_name": "TODO", + "description": "Indicates whether or not the `S` extension can be disabled with the `misa.S` bit.", + "defined_by": { + "extensions": [ + "S" + ], + "params": [], + "raw": { + "extension": { + "name": "S" + } + }, + "summary": "ext:S" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": true, + "requirements_summary": "If U-mode can be disabled, then S must also be disabled since S cannot exist without U (and thus there is no option for MUTABLE_MISA_S).", + "csr_references": [ + { + "csr": "misa", + "field": "S", + "idl_key": "type()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of misa.S", + "source_file": "spec/std/isa/param/MUTABLE_MISA_S.yaml" + }, + { + "name": "MUTABLE_MISA_U", + "long_name": "TODO", + "description": "Indicates whether or not the `U` extension can be disabled with the `misa.U` bit.", + "defined_by": { + "extensions": [ + "U" + ], + "params": [], + "raw": { + "extension": { + "name": "U" + } + }, + "summary": "ext:U" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "misa", + "field": "U", + "idl_key": "type()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of misa.U", + "source_file": "spec/std/isa/param/MUTABLE_MISA_U.yaml" + }, + { + "name": "MUTABLE_MISA_V", + "long_name": "TODO", + "description": "Indicates whether or not the `V` extension can be disabled with the `misa.V` bit.", + "defined_by": { + "extensions": [ + "V" + ], + "params": [], + "raw": { + "extension": { + "name": "V" + } + }, + "summary": "ext:V" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "misa", + "field": "V", + "idl_key": "type()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of misa.V", + "source_file": "spec/std/isa/param/MUTABLE_MISA_V.yaml" + }, + { + "name": "MXLEN", + "long_name": "XLEN in machine mode", + "description": "XLEN in machine mode, specified in bits", + "defined_by": { + "extensions": [ + "Sm" + ], + "params": [], + "raw": { + "extension": { + "name": "Sm" + } + }, + "summary": "ext:Sm" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + 32, + 64 + ] + } + }, + "has_requirements": true, + "requirements_summary": "# if M-mode is rv32, then every mode must be rv32\nMXLEN == 32 -> xlen() == 32;\n\n# can't get in to rv64 anywhere unless MXLEN is 64\nxlen() == 64 -> MXLEN == 64;\n\n# if it's just M-mode, then xlen is alw", + "csr_references": [ + { + "csr": "satp", + "field": "ASID", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "mconfigptr", + "field": "ADDRESS", + "idl_key": "legal?(csr_value)" + }, + { + "csr": "misa", + "field": "MXL", + "idl_key": "reset_value()" + }, + { + "csr": "hcontext", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr32", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr24", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr49", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr4", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr28", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr53", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr12", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr8", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr45", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr44", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr9", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr13", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr52", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr29", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr5", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr48", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr25", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr33", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr38", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr55", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr14", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr43", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr34", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr63", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr22", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr59", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr18", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr2", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr3", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr19", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr58", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr23", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr62", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr35", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr42", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr15", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr54", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr39", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr41", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr16", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr57", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr0", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr20", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr61", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr36", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr37", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr60", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr21", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr1", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr56", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr17", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr40", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr6", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr26", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr30", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr47", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr10", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr51", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr50", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr11", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr46", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr31", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr27", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr7", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "vsatp", + "field": "ASID", + "idl_key": "sw_write(csr_value)" + } + ], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Well-known architectural parameter 'MXLEN'", + "source_file": "spec/std/isa/param/MXLEN.yaml" + }, + { + "name": "M_MODE_ENDIANNESS", + "long_name": "Endianness of data in M-mode", + "description": "Options:\n\n[separator=\"!\"]\n!===\nh! little ! M-mode data is always little endian\nh! big ! M-mode data is always big endian\nh! dynamic ! M-mode data can be either little or big endian,\n depending on the CSR field `mstatus.MBE`\n!===", + "defined_by": { + "extensions": [ + "Sm" + ], + "params": [], + "raw": { + "extension": { + "name": "Sm" + } + }, + "summary": "ext:Sm" + }, + "value_type": { + "type": "enum", + "details": { + "values": [ + "little", + "big", + "dynamic" + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "mstatus", + "field": "MBE", + "idl_key": "type()" + }, + { + "csr": "mstatus", + "field": "MBE", + "idl_key": "reset_value()" + }, + { + "csr": "mstatush", + "field": "MBE", + "idl_key": "type()" + }, + { + "csr": "mstatush", + "field": "MBE", + "idl_key": "reset_value()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of mstatus.MBE", + "source_file": "spec/std/isa/param/M_MODE_ENDIANNESS.yaml" + }, + { + "name": "NUM_EXTERNAL_GUEST_INTERRUPTS", + "long_name": "TODO", + "description": "Number of supported virtualized guest interrupts\n\nCorresponds to the `GEILEN` parameter in the RVI specs", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "conditional", + "details": { + "branches": [ + { + "condition": "MXLEN == 32", + "inner_type": { + "type": "range", + "details": { + "minimum": 1, + "maximum": 31 + } + } + }, + { + "condition": "MXLEN == 64", + "inner_type": { + "type": "range", + "details": { + "minimum": 1, + "maximum": 63 + } + } + } + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "hstatus", + "field": "VGEIN", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "hstatus", + "field": "VGEIN", + "idl_key": "type()" + }, + { + "csr": "hstatus", + "field": "VGEIN", + "idl_key": "legal?(csr_value)" + } + ], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Well-known architectural parameter 'NUM_EXTERNAL_GUEST_INTERRUPTS'", + "source_file": "spec/std/isa/param/NUM_EXTERNAL_GUEST_INTERRUPTS.yaml" + }, + { + "name": "NUM_PMP_ENTRIES", + "long_name": "TODO", + "description": "Number of implemented PMP entries. Can be any value between 0-64, inclusive.\n\nThe architecture mandates that the number of implemented PMP registers\nmust appear to be 0, 16, or 64.\n\nTherefore, pmp registers will behave as follows according to NUN_PMP_ENTRIES:\n\n[separator=\"!\"]\n!===\n! NUM_PMP_ENTRIES ! pmpaddr<0-15> / pmpcfg<0-3> ! pmpaddr<16-63> / pmpcfg<4-15>\n! 0 ! N ! N\n! 1-16 ! Y ! N\n! 17-64 ! Y ! Y\n!===\n\n** N = Not implemented; access will cause `IllegalInstruction`\n if TRAP_ON_UNIMPLEMENTED_CSR is true\n** Y = Implemented; access will not cause an exception (from M-mode), but register\n may be read-only-zero if NUM_PMP_ENTRIES is less than the corresponding register\n\n[NOTE]\n`pmpcfgN` for an odd N never exists when XLEN == 64\n\nWhen NUM_PMP_ENTRIES is not exactly 0, 16, or 64, some extant pmp registers,\nand associated pmpNcfg, will be read-only zero (but will never cause an exception).", + "defined_by": { + "extensions": [ + "Smpmp" + ], + "params": [], + "raw": { + "extension": { + "name": "Smpmp" + } + }, + "summary": "ext:Smpmp" + }, + "value_type": { + "type": "range", + "details": { + "minimum": 0, + "maximum": 64 + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "pmpaddr32", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr32", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpcfg14", + "field": "pmp56cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg14", + "field": "pmp57cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg14", + "field": "pmp58cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg14", + "field": "pmp59cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg14", + "field": "pmp60cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg14", + "field": "pmp61cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg14", + "field": "pmp62cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg14", + "field": "pmp63cfg", + "idl_key": "type()" + }, + { + "csr": "pmpaddr24", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr24", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpcfg4", + "field": "pmp16cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg4", + "field": "pmp17cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg4", + "field": "pmp18cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg4", + "field": "pmp19cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg4", + "field": "pmp20cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg4", + "field": "pmp21cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg4", + "field": "pmp22cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg4", + "field": "pmp23cfg", + "idl_key": "type()" + }, + { + "csr": "pmpaddr49", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr49", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr4", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr4", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr28", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr28", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr53", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr53", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpcfg8", + "field": "pmp32cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg8", + "field": "pmp33cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg8", + "field": "pmp34cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg8", + "field": "pmp35cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg8", + "field": "pmp36cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg8", + "field": "pmp37cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg8", + "field": "pmp38cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg8", + "field": "pmp39cfg", + "idl_key": "type()" + }, + { + "csr": "pmpaddr12", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr12", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr8", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr8", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr45", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr45", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr44", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr44", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr9", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr9", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpcfg9", + "field": "pmp36cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg9", + "field": "pmp37cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg9", + "field": "pmp38cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg9", + "field": "pmp39cfg", + "idl_key": "type()" + }, + { + "csr": "pmpaddr13", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr13", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr52", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr52", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr29", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr29", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr5", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr5", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr48", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr48", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpcfg5", + "field": "pmp20cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg5", + "field": "pmp21cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg5", + "field": "pmp22cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg5", + "field": "pmp23cfg", + "idl_key": "type()" + }, + { + "csr": "pmpaddr25", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr25", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpcfg15", + "field": "pmp60cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg15", + "field": "pmp61cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg15", + "field": "pmp62cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg15", + "field": "pmp63cfg", + "idl_key": "type()" + }, + { + "csr": "pmpaddr33", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr33", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr38", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr38", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr55", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr55", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr14", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr14", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr43", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr43", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr34", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr34", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr63", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr63", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpcfg12", + "field": "pmp48cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg12", + "field": "pmp49cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg12", + "field": "pmp50cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg12", + "field": "pmp51cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg12", + "field": "pmp52cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg12", + "field": "pmp53cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg12", + "field": "pmp54cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg12", + "field": "pmp55cfg", + "idl_key": "type()" + }, + { + "csr": "pmpaddr22", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr22", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr59", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr59", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpcfg2", + "field": "pmp8cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg2", + "field": "pmp9cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg2", + "field": "pmp10cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg2", + "field": "pmp11cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg2", + "field": "pmp12cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg2", + "field": "pmp13cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg2", + "field": "pmp14cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg2", + "field": "pmp15cfg", + "idl_key": "type()" + }, + { + "csr": "pmpaddr18", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr18", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr2", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr2", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr3", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr3", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpcfg3", + "field": "pmp12cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg3", + "field": "pmp13cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg3", + "field": "pmp14cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg3", + "field": "pmp15cfg", + "idl_key": "type()" + }, + { + "csr": "pmpaddr19", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr19", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr58", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr58", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr23", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr23", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpcfg13", + "field": "pmp52cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg13", + "field": "pmp53cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg13", + "field": "pmp54cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg13", + "field": "pmp55cfg", + "idl_key": "type()" + }, + { + "csr": "pmpaddr62", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr62", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr35", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr35", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr42", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr42", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr15", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr15", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr54", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr54", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr39", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr39", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr41", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr41", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr16", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr16", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr57", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr57", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr0", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr0", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpcfg0", + "field": "pmp0cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg0", + "field": "pmp1cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg0", + "field": "pmp2cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg0", + "field": "pmp3cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg0", + "field": "pmp4cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg0", + "field": "pmp5cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg0", + "field": "pmp6cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg0", + "field": "pmp7cfg", + "idl_key": "type()" + }, + { + "csr": "pmpaddr20", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr20", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpcfg10", + "field": "pmp40cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg10", + "field": "pmp41cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg10", + "field": "pmp42cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg10", + "field": "pmp43cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg10", + "field": "pmp44cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg10", + "field": "pmp45cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg10", + "field": "pmp46cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg10", + "field": "pmp47cfg", + "idl_key": "type()" + }, + { + "csr": "pmpaddr61", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr61", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr36", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr36", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr37", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr37", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr60", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr60", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpcfg11", + "field": "pmp44cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg11", + "field": "pmp45cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg11", + "field": "pmp46cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg11", + "field": "pmp47cfg", + "idl_key": "type()" + }, + { + "csr": "pmpaddr21", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr21", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpcfg1", + "field": "pmp4cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg1", + "field": "pmp5cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg1", + "field": "pmp6cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg1", + "field": "pmp7cfg", + "idl_key": "type()" + }, + { + "csr": "pmpaddr1", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr1", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr56", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr56", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr17", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr17", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr40", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr40", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr6", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr6", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpcfg6", + "field": "pmp24cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg6", + "field": "pmp25cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg6", + "field": "pmp26cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg6", + "field": "pmp27cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg6", + "field": "pmp28cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg6", + "field": "pmp29cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg6", + "field": "pmp30cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg6", + "field": "pmp31cfg", + "idl_key": "type()" + }, + { + "csr": "pmpaddr26", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr26", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr30", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr30", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr47", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr47", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr10", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr10", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr51", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr51", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr50", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr50", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr11", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr11", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr46", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr46", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr31", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr31", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpaddr27", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr27", + "field": "ADDR", + "idl_key": "type()" + }, + { + "csr": "pmpcfg7", + "field": "pmp28cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg7", + "field": "pmp29cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg7", + "field": "pmp30cfg", + "idl_key": "type()" + }, + { + "csr": "pmpcfg7", + "field": "pmp31cfg", + "idl_key": "type()" + }, + { + "csr": "pmpaddr7", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr7", + "field": "ADDR", + "idl_key": "type()" + } + ], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Well-known architectural parameter 'NUM_PMP_ENTRIES'", + "source_file": "spec/std/isa/param/NUM_PMP_ENTRIES.yaml" + }, + { + "name": "PHYS_ADDR_WIDTH", + "long_name": "Number of bits in a physical address", + "description": "Implementation-defined size of the physical address space.", + "defined_by": { + "extensions": [ + "Sm" + ], + "params": [], + "raw": { + "extension": { + "name": "Sm" + } + }, + "summary": "ext:Sm" + }, + "value_type": { + "type": "conditional", + "details": { + "branches": [ + { + "condition": "MXLEN == 32", + "inner_type": { + "type": "range", + "details": { + "minimum": 1, + "maximum": 34 + } + } + }, + { + "condition": "MXLEN == 64", + "inner_type": { + "type": "range", + "details": { + "minimum": 1, + "maximum": 64 + } + } + } + ] + } + }, + "has_requirements": true, + "requirements_summary": "without Sv32 translation, there is no way to create an address > 32 bits", + "csr_references": [ + { + "csr": "pmpaddr32", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr32", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr24", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr24", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr49", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr49", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr4", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr4", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr28", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr28", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr53", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr53", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr12", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr12", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr8", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr8", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr45", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr45", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr44", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr44", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr9", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr9", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr13", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr13", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr52", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr52", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr29", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr29", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr5", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr5", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr48", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr48", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr25", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr25", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr33", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr33", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr38", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr38", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr55", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr55", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr14", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr14", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr43", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr43", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr34", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr34", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr63", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr63", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr22", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr22", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr59", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr59", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr18", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr18", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr2", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr2", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr3", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr3", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr19", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr19", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr58", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr58", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr23", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr23", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr62", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr62", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr35", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr35", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr42", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr42", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr15", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr15", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr54", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr54", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr39", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr39", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr41", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr41", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr16", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr16", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr57", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr57", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr0", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr0", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr20", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr20", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr61", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr61", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr36", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr36", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr37", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr37", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr60", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr60", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr21", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr21", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr1", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr1", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr56", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr56", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr17", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr17", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr40", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr40", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr6", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr6", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr26", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr26", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr30", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr30", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr47", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr47", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr10", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr10", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr51", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr51", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr50", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr50", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr11", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr11", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr46", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr46", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr31", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr31", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr27", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr27", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr7", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr7", + "field": "ADDR", + "idl_key": "sw_write(csr_value)" + } + ], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Well-known architectural parameter 'PHYS_ADDR_WIDTH'", + "source_file": "spec/std/isa/param/PHYS_ADDR_WIDTH.yaml" + }, + { + "name": "PMA_GRANULARITY", + "long_name": "log2 of the smallest supported PMA region", + "description": "Generally, for systems with an MMU, should not be smaller than 12,\nas that would preclude caching PMA results in the TLB along with\nvirtual memory translations", + "defined_by": { + "extensions": [ + "Sm" + ], + "params": [], + "raw": { + "extension": { + "name": "Sm" + } + }, + "summary": "ext:Sm" + }, + "value_type": { + "type": "range", + "details": { + "minimum": 2, + "maximum": 66 + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Well-known architectural parameter 'PMA_GRANULARITY'", + "source_file": "spec/std/isa/param/PMA_GRANULARITY.yaml" + }, + { + "name": "PMLEN", + "long_name": "TODO", + "description": "The number of high-order bits of an address that are masked by the\npointer masking facility.", + "defined_by": { + "extensions": [ + "Smmpm", + "Smnpm", + "Ssnpm" + ], + "params": [], + "raw": { + "extension": { + "anyOf": [ + { + "name": "Smmpm" + }, + { + "name": "Smnpm" + }, + { + "name": "Ssnpm" + } + ] + } + }, + "summary": "(ext:Smmpm OR ext:Smnpm OR ext:Ssnpm)" + }, + "value_type": { + "type": "value", + "details": { + "base": "integer" + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Well-known architectural parameter 'PMLEN'", + "source_file": "spec/std/isa/param/PMLEN.yaml" + }, + { + "name": "PMP_GRANULARITY", + "long_name": "TODO", + "description": "log2 of the smallest supported PMP region.\n\nGenerally, for systems with an MMU, should not be smaller than 12,\nas that would preclude caching PMP results in the TLB along with\nvirtual memory translations\n\nNote that PMP_GRANULARITY is equal to G+2 (not G) as described in\nthe privileged architecture.", + "defined_by": { + "extensions": [ + "Smpmp" + ], + "params": [], + "raw": { + "extension": { + "name": "Smpmp" + } + }, + "summary": "ext:Smpmp" + }, + "value_type": { + "type": "range", + "details": { + "minimum": 2, + "maximum": 66 + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "pmpaddr32", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpcfg14", + "field": "pmp56cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg14", + "field": "pmp57cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg14", + "field": "pmp58cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg14", + "field": "pmp59cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg14", + "field": "pmp60cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg14", + "field": "pmp61cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg14", + "field": "pmp62cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg14", + "field": "pmp63cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr24", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpcfg4", + "field": "pmp16cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg4", + "field": "pmp17cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg4", + "field": "pmp18cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg4", + "field": "pmp19cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg4", + "field": "pmp20cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg4", + "field": "pmp21cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg4", + "field": "pmp22cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg4", + "field": "pmp23cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr49", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr4", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr28", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr53", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpcfg8", + "field": "pmp32cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg8", + "field": "pmp33cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg8", + "field": "pmp34cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg8", + "field": "pmp35cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg8", + "field": "pmp36cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg8", + "field": "pmp37cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg8", + "field": "pmp38cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg8", + "field": "pmp39cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr12", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr8", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr45", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr44", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr9", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpcfg9", + "field": "pmp36cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg9", + "field": "pmp37cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg9", + "field": "pmp38cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg9", + "field": "pmp39cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr13", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr52", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr29", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr5", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr48", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpcfg5", + "field": "pmp20cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg5", + "field": "pmp21cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg5", + "field": "pmp22cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg5", + "field": "pmp23cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr25", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpcfg15", + "field": "pmp60cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg15", + "field": "pmp61cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg15", + "field": "pmp62cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg15", + "field": "pmp63cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr33", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr38", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr55", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr14", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr43", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr34", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr63", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpcfg12", + "field": "pmp48cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg12", + "field": "pmp49cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg12", + "field": "pmp50cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg12", + "field": "pmp51cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg12", + "field": "pmp52cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg12", + "field": "pmp53cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg12", + "field": "pmp54cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg12", + "field": "pmp55cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr22", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr59", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpcfg2", + "field": "pmp8cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg2", + "field": "pmp9cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg2", + "field": "pmp10cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg2", + "field": "pmp11cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg2", + "field": "pmp12cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg2", + "field": "pmp13cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg2", + "field": "pmp14cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg2", + "field": "pmp15cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr18", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr2", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr3", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpcfg3", + "field": "pmp12cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg3", + "field": "pmp13cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg3", + "field": "pmp14cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg3", + "field": "pmp15cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr19", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr58", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr23", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpcfg13", + "field": "pmp52cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg13", + "field": "pmp53cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg13", + "field": "pmp54cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg13", + "field": "pmp55cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr62", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr35", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr42", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr15", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr54", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr39", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr41", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr16", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr57", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr0", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpcfg0", + "field": "pmp0cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg0", + "field": "pmp1cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg0", + "field": "pmp2cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg0", + "field": "pmp3cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg0", + "field": "pmp4cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg0", + "field": "pmp5cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg0", + "field": "pmp6cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg0", + "field": "pmp7cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr20", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpcfg10", + "field": "pmp40cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg10", + "field": "pmp41cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg10", + "field": "pmp42cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg10", + "field": "pmp43cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg10", + "field": "pmp44cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg10", + "field": "pmp45cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg10", + "field": "pmp46cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg10", + "field": "pmp47cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr61", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr36", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr37", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr60", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpcfg11", + "field": "pmp44cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg11", + "field": "pmp45cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg11", + "field": "pmp46cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg11", + "field": "pmp47cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr21", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpcfg1", + "field": "pmp4cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg1", + "field": "pmp5cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg1", + "field": "pmp6cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg1", + "field": "pmp7cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr1", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr56", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr17", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr40", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr6", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpcfg6", + "field": "pmp24cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg6", + "field": "pmp25cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg6", + "field": "pmp26cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg6", + "field": "pmp27cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg6", + "field": "pmp28cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg6", + "field": "pmp29cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg6", + "field": "pmp30cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg6", + "field": "pmp31cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr26", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr30", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr47", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr10", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr51", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr50", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr11", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr46", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr31", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpaddr27", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "pmpcfg7", + "field": "pmp28cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg7", + "field": "pmp29cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg7", + "field": "pmp30cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpcfg7", + "field": "pmp31cfg", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "pmpaddr7", + "field": "(csr-level)", + "idl_key": "sw_read()" + } + ], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Well-known architectural parameter 'PMP_GRANULARITY'", + "source_file": "spec/std/isa/param/PMP_GRANULARITY.yaml" + }, + { + "name": "PRECISE_SYNCHRONOUS_EXCEPTIONS", + "long_name": "Whether or not all synchronous exceptions are precise.", + "description": "If false, any exception not otherwise mandated to precise (e.g., PMP violation)\nwill cause execution to enter an unpredictable state.", + "defined_by": { + "extensions": [ + "Sm" + ], + "params": [], + "raw": { + "extension": { + "name": "Sm" + } + }, + "summary": "ext:Sm" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^PRECISE_)", + "source_file": "spec/std/isa/param/PRECISE_SYNCHRONOUS_EXCEPTIONS.yaml" + }, + { + "name": "RCID_WIDTH", + "long_name": "TODO", + "description": "Number of bits used for the Resource Control ID field (RCID).\nDefault is 12.", + "defined_by": { + "extensions": [ + "Ssqosid" + ], + "params": [], + "raw": { + "extension": { + "name": "Ssqosid" + } + }, + "summary": "ext:Ssqosid" + }, + "value_type": { + "type": "range", + "details": { + "minimum": 1, + "maximum": 12 + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "srmcfg", + "field": "RCID", + "idl_key": "sw_write(csr_value)" + } + ], + "classification": "NORM_CSR_WARL", + "classification_confidence": "high", + "classification_reasoning": "Referenced in sw_write() of srmcfg.RCID", + "source_file": "spec/std/isa/param/RCID_WIDTH.yaml" + }, + { + "name": "REPORT_CAUSE_IN_MTVAL_ON_LANDING_PAD_SOFTWARE_CHECK", + "long_name": "TODO", + "description": "When true, `mtval` is written with the shadow stack cause (code=18) when a SoftwareCheck exception is raised into M-mode due to a landing pad error.\n\nWhen false, `mtval` is written with 0.", + "defined_by": { + "extensions": [ + "Zicfilp" + ], + "params": [], + "raw": { + "extension": { + "name": "Zicfilp" + } + }, + "summary": "ext:Zicfilp" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_CAUSE_IN_MTVAL_ON_LANDING_PAD_SOFTWARE_CHECK.yaml" + }, + { + "name": "REPORT_CAUSE_IN_MTVAL_ON_SHADOW_STACK_SOFTWARE_CHECK", + "long_name": "TODO", + "description": "When true, `mtval` is written with the shadow stack cause (code=3) when a SoftwareCheck exception is raised into M-mode due to a shadow stack pop check instruction.\n\nWhen false, `mtval` is written with 0.", + "defined_by": { + "extensions": [ + "Zicfiss" + ], + "params": [], + "raw": { + "extension": { + "name": "Zicfiss" + } + }, + "summary": "ext:Zicfiss" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_CAUSE_IN_MTVAL_ON_SHADOW_STACK_SOFTWARE_CHECK.yaml" + }, + { + "name": "REPORT_CAUSE_IN_STVAL_ON_LANDING_PAD_SOFTWARE_CHECK", + "long_name": "TODO", + "description": "When true, `stval` is written with the shadow stack cause (code=18) when a SoftwareCheck exception is raised into S-mode due to a landing pad error.\n\nWhen false, `stval` is written with 0.", + "defined_by": { + "extensions": [ + "Zicfilp" + ], + "params": [], + "raw": { + "extension": { + "name": "Zicfilp" + } + }, + "summary": "ext:Zicfilp" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_CAUSE_IN_STVAL_ON_LANDING_PAD_SOFTWARE_CHECK.yaml" + }, + { + "name": "REPORT_CAUSE_IN_STVAL_ON_SHADOW_STACK_SOFTWARE_CHECK", + "long_name": "TODO", + "description": "When true, `stval` is written with the shadow stack cause (code=3) when a SoftwareCheck exception is raised into S-mode due to a shadow stack pop check instruction.\n\nWhen false, `stval` is written with 0.", + "defined_by": { + "extensions": [ + "Zicfiss" + ], + "params": [], + "raw": { + "extension": { + "name": "Zicfiss" + } + }, + "summary": "ext:Zicfiss" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_CAUSE_IN_STVAL_ON_SHADOW_STACK_SOFTWARE_CHECK.yaml" + }, + { + "name": "REPORT_CAUSE_IN_VSTVAL_ON_LANDING_PAD_SOFTWARE_CHECK", + "long_name": "TODO", + "description": "When true, `vstval` is written with the shadow stack cause (code=18) when a SoftwareCheck exception is raised into VS-mode due to a landing pad error.\n\nWhen false, `vstval` is written with 0.", + "defined_by": { + "extensions": [ + "Zicfilp" + ], + "params": [], + "raw": { + "extension": { + "name": "Zicfilp" + } + }, + "summary": "ext:Zicfilp" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_CAUSE_IN_VSTVAL_ON_LANDING_PAD_SOFTWARE_CHECK.yaml" + }, + { + "name": "REPORT_CAUSE_IN_VSTVAL_ON_SHADOW_STACK_SOFTWARE_CHECK", + "long_name": "TODO", + "description": "When true, `vstval` is written with the shadow stack cause (code=3) when a SoftwareCheck exception is raised into VS-mode due to a shadow stack pop check instruction.\n\nWhen false, `vstval` is written with 0.", + "defined_by": { + "extensions": [ + "Zicfiss" + ], + "params": [], + "raw": { + "extension": { + "name": "Zicfiss" + } + }, + "summary": "ext:Zicfiss" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_CAUSE_IN_VSTVAL_ON_SHADOW_STACK_SOFTWARE_CHECK.yaml" + }, + { + "name": "REPORT_ENCODING_IN_MTVAL_ON_ILLEGAL_INSTRUCTION", + "long_name": "Whether or not `mtval` is written with the encoding of an instruction causing an IllegalInstruction exception", + "description": "Options:\n\n * true: `mtval` is written with the encoding of an instruction causing an IllegalInstruction exception\n * false: `mtval` is written with 0 when an instruction causes an IllegalInstruction exception.", + "defined_by": { + "extensions": [ + "Sm" + ], + "params": [], + "raw": { + "extension": { + "name": "Sm" + } + }, + "summary": "ext:Sm" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_ENCODING_IN_MTVAL_ON_ILLEGAL_INSTRUCTION.yaml" + }, + { + "name": "REPORT_ENCODING_IN_STVAL_ON_ILLEGAL_INSTRUCTION", + "long_name": "TODO", + "description": "When true, `stval` is written with the encoding of an instruction that causes an\n`IllegalInstruction` exception.\n\nWhen false `stval` is written with 0 when an `IllegalInstruction` exception occurs.", + "defined_by": { + "extensions": [ + "S" + ], + "params": [], + "raw": { + "extension": { + "name": "S" + } + }, + "summary": "ext:S" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_ENCODING_IN_STVAL_ON_ILLEGAL_INSTRUCTION.yaml" + }, + { + "name": "REPORT_ENCODING_IN_VSTVAL_ON_ILLEGAL_INSTRUCTION", + "long_name": "TODO", + "description": "When true, `vstval` is written with the encoding of an instruction that causes an\n`IllegalInstruction` exception.\n\nWhen false `vstval` is written with 0 when an `IllegalInstruction` exception occurs.", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_ENCODING_IN_VSTVAL_ON_ILLEGAL_INSTRUCTION.yaml" + }, + { + "name": "REPORT_ENCODING_IN_VSTVAL_ON_VIRTUAL_INSTRUCTION", + "long_name": "TODO", + "description": "When true, `vstval` is written with the encoding of an instruction that causes an\n`VirualInstruction` exception.\n\nWhen false `vstval` is written with 0 when an `VirtualInstruction` exception occurs.", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_ENCODING_IN_VSTVAL_ON_VIRTUAL_INSTRUCTION.yaml" + }, + { + "name": "REPORT_GPA_IN_HTVAL_ON_GUEST_PAGE_FAULT", + "long_name": "TODO", + "description": "When true, `htval` is written with the Guest Physical Address, shifted right by 2, that\ncaused a `GuestPageFault` exception.\n\nWhen false, `htval` is written with 0 when a `GuestPageFault` exception occurs.", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_GPA_IN_HTVAL_ON_GUEST_PAGE_FAULT.yaml" + }, + { + "name": "REPORT_GPA_IN_TVAL_ON_INSTRUCTION_GUEST_PAGE_FAULT", + "long_name": "TODO", + "description": "Whether or not GPA >> 2 is written into htval/mtval2 when an instruction guest page fault occurs.\n\nIf false, 0 will be written into htval/mtval2 on an instruction guest page fault.", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "htval", + "field": "VALUE", + "idl_key": "type()" + }, + { + "csr": "mtval2", + "field": "VALUE", + "idl_key": "type()" + } + ], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_GPA_IN_TVAL_ON_INSTRUCTION_GUEST_PAGE_FAULT.yaml" + }, + { + "name": "REPORT_GPA_IN_TVAL_ON_INTERMEDIATE_GUEST_PAGE_FAULT", + "long_name": "TODO", + "description": "Whether or not GPA >> 2 is written into htval/mtval2 when a guest page fault occurs while\nwalking a VS-mode page table.\n\nIf false, 0 will be written into htval/mtval2 on an intermediate guest page fault.", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "htval", + "field": "VALUE", + "idl_key": "type()" + }, + { + "csr": "mtval2", + "field": "VALUE", + "idl_key": "type()" + } + ], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_GPA_IN_TVAL_ON_INTERMEDIATE_GUEST_PAGE_FAULT.yaml" + }, + { + "name": "REPORT_GPA_IN_TVAL_ON_LOAD_GUEST_PAGE_FAULT", + "long_name": "TODO", + "description": "Whether or not GPA >> 2 is written into htval/mtval2 when a load guest page fault occurs.\n\nIf false, 0 will be written into htval/mtval2 on a load guest page fault.", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "htval", + "field": "VALUE", + "idl_key": "type()" + }, + { + "csr": "mtval2", + "field": "VALUE", + "idl_key": "type()" + } + ], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_GPA_IN_TVAL_ON_LOAD_GUEST_PAGE_FAULT.yaml" + }, + { + "name": "REPORT_GPA_IN_TVAL_ON_STORE_AMO_GUEST_PAGE_FAULT", + "long_name": "TODO", + "description": "Whether or not GPA >> 2 is written into htval/mtval2 when a store/amo guest page fault occurs.\n\nIf false, 0 will be written into htval/mtval2 on a store/amo guest page fault.", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "htval", + "field": "VALUE", + "idl_key": "type()" + }, + { + "csr": "mtval2", + "field": "VALUE", + "idl_key": "type()" + } + ], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_GPA_IN_TVAL_ON_STORE_AMO_GUEST_PAGE_FAULT.yaml" + }, + { + "name": "REPORT_VA_IN_MTVAL_ON_BREAKPOINT", + "long_name": "Whether or not `mtval` is written with the virtual PC of an EBREAK instruction.", + "description": "Options:\n\n * true: `mtval` is written with the virtual PC of an EBREAK instruction (same information as `mepc`).\n * false: `mtval` is written with 0 on an EBREAK instruction.\n\nRegardless, `mtval` is always written with a virtual PC when an external breakpoint is generated", + "defined_by": { + "extensions": [ + "Sm" + ], + "params": [], + "raw": { + "extension": { + "name": "Sm" + } + }, + "summary": "ext:Sm" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_VA_IN_MTVAL_ON_BREAKPOINT.yaml" + }, + { + "name": "REPORT_VA_IN_MTVAL_ON_INSTRUCTION_ACCESS_FAULT", + "long_name": "Whether or not `mtval` is written with the virtual address of a fetch causing an access fault", + "description": "Options:\n\n * true: `mtval` is written with the virtual address of a fetch causing the access fault\n * false: `mtval` is written with 0 when a fetch causes an access fault", + "defined_by": { + "extensions": [ + "Sm" + ], + "params": [], + "raw": { + "extension": { + "name": "Sm" + } + }, + "summary": "ext:Sm" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_VA_IN_MTVAL_ON_INSTRUCTION_ACCESS_FAULT.yaml" + }, + { + "name": "REPORT_VA_IN_MTVAL_ON_INSTRUCTION_MISALIGNED", + "long_name": "Whether or not `mtval` is written with the virtual address of a misaligned fetch", + "description": "Options:\n\n * true: `mtval` is written with the virtual address of a trapping misaligned fetch\n * false: `mtval` is written with 0 when a misaligned fetch traps", + "defined_by": { + "extensions": [ + "Sm" + ], + "params": [], + "raw": { + "extension": { + "name": "Sm" + } + }, + "summary": "ext:Sm" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_VA_IN_MTVAL_ON_INSTRUCTION_MISALIGNED.yaml" + }, + { + "name": "REPORT_VA_IN_MTVAL_ON_INSTRUCTION_PAGE_FAULT", + "long_name": "TODO", + "description": "When true, `mtval` is written with the virtual PC of an instructino when fetch causes an\n`InstructionPageFault`.\n\nWHen false, `mtval` is written with 0 when an instruction fetch causes an\n`InstructionPageFault`.", + "defined_by": { + "extensions": [ + "S" + ], + "params": [], + "raw": { + "extension": { + "name": "S" + } + }, + "summary": "ext:S" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_VA_IN_MTVAL_ON_INSTRUCTION_PAGE_FAULT.yaml" + }, + { + "name": "REPORT_VA_IN_MTVAL_ON_LOAD_ACCESS_FAULT", + "long_name": "Whether or not `mtval` is written with the virtual address of a load causing an access fault", + "description": "Options:\n\n * true: `mtval` is written with the virtual address of a load causing the access fault\n * false: `mtval` is written with 0 when a load causes an access fault", + "defined_by": { + "extensions": [ + "Sm" + ], + "params": [], + "raw": { + "extension": { + "name": "Sm" + } + }, + "summary": "ext:Sm" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_VA_IN_MTVAL_ON_LOAD_ACCESS_FAULT.yaml" + }, + { + "name": "REPORT_VA_IN_MTVAL_ON_LOAD_MISALIGNED", + "long_name": "Whether or not `mtval` is written with the virtual address of a misaligned load", + "description": "Options:\n\n * true: `mtval` is written with the virtual address of a trapping misaligned load.\n * false: `mtval` is written with 0 when a misaligned load traps.", + "defined_by": { + "extensions": [ + "Sm" + ], + "params": [], + "raw": { + "extension": { + "name": "Sm" + } + }, + "summary": "ext:Sm" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_VA_IN_MTVAL_ON_LOAD_MISALIGNED.yaml" + }, + { + "name": "REPORT_VA_IN_MTVAL_ON_LOAD_PAGE_FAULT", + "long_name": "TODO", + "description": "When true, `mtval` is written with the virtual address of a load when it causes a\n`LoadPageFault`.\n\nWHen false, `mtval` is written with 0 when a load causes a `LoadPageFault`.", + "defined_by": { + "extensions": [ + "S" + ], + "params": [], + "raw": { + "extension": { + "name": "S" + } + }, + "summary": "ext:S" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_VA_IN_MTVAL_ON_LOAD_PAGE_FAULT.yaml" + }, + { + "name": "REPORT_VA_IN_MTVAL_ON_STORE_AMO_ACCESS_FAULT", + "long_name": "Whether or not `mtval` is written with the virtual address of a store or AMO causing an access fault", + "description": "Options:\n\n * true: `mtval` is written with the virtual address of a store or AMO causing the access fault\n * false: `mtval` is written with 0 when a store or AMO causes an access fault", + "defined_by": { + "extensions": [ + "Sm" + ], + "params": [], + "raw": { + "extension": { + "name": "Sm" + } + }, + "summary": "ext:Sm" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_VA_IN_MTVAL_ON_STORE_AMO_ACCESS_FAULT.yaml" + }, + { + "name": "REPORT_VA_IN_MTVAL_ON_STORE_AMO_MISALIGNED", + "long_name": "Whether or not `mtval` is written with the virtual address of a misaligned store or AMO", + "description": "Options:\n\n * true: `mtval` is written with the virtual address of a trapping misaligned store or AMO.\n * false: `mtval` is written with 0 when a misaligned store or AMO traps.", + "defined_by": { + "extensions": [ + "Sm" + ], + "params": [], + "raw": { + "extension": { + "name": "Sm" + } + }, + "summary": "ext:Sm" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_VA_IN_MTVAL_ON_STORE_AMO_MISALIGNED.yaml" + }, + { + "name": "REPORT_VA_IN_MTVAL_ON_STORE_AMO_PAGE_FAULT", + "long_name": "TODO", + "description": "When true, `mtval` is written with the virtual address of a store when it causes a\n`StoreAmoPageFault`.\n\nWHen false, `mtval` is written with 0 when a store causes a `StoreAmoPageFault`.", + "defined_by": { + "extensions": [ + "S" + ], + "params": [], + "raw": { + "extension": { + "name": "S" + } + }, + "summary": "ext:S" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_VA_IN_MTVAL_ON_STORE_AMO_PAGE_FAULT.yaml" + }, + { + "name": "REPORT_VA_IN_STVAL_ON_BREAKPOINT", + "long_name": "TODO", + "description": "When true, `stval` is written with the virtual PC of the EBREAK instruction (same information as `mepc`).\n\nWhen false, `stval` is written with 0 on an EBREAK instruction.\n\nRegardless, `stval` is always written with a virtual PC when an external breakpoint is generated", + "defined_by": { + "extensions": [ + "S" + ], + "params": [], + "raw": { + "extension": { + "name": "S" + } + }, + "summary": "ext:S" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_VA_IN_STVAL_ON_BREAKPOINT.yaml" + }, + { + "name": "REPORT_VA_IN_STVAL_ON_INSTRUCTION_ACCESS_FAULT", + "long_name": "TODO", + "description": "When true, `stval` is written with the virtual PC of an instructino when fetch causes an\n`InstructionAccessFault`.\n\nWHen false, `stval` is written with 0 when an instruction fetch causes an\n`InstructionAccessFault`.", + "defined_by": { + "extensions": [ + "S" + ], + "params": [], + "raw": { + "extension": { + "name": "S" + } + }, + "summary": "ext:S" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_VA_IN_STVAL_ON_INSTRUCTION_ACCESS_FAULT.yaml" + }, + { + "name": "REPORT_VA_IN_STVAL_ON_INSTRUCTION_MISALIGNED", + "long_name": "TODO", + "description": "When true, `stval` is written with the virtual PC when an instruction fetch is misaligned.\n\nWhen false, `stval` is written with 0 when an instruction fetch is misaligned.\n\nNote that when IALIGN=16 (i.e., when the `C` or one of the `Zc*` extensions are implemented),\nit is impossible to generate a misaligned fetch, and so this parameter has no effect.", + "defined_by": { + "extensions": [ + "S" + ], + "params": [], + "raw": { + "extension": { + "name": "S" + } + }, + "summary": "ext:S" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_VA_IN_STVAL_ON_INSTRUCTION_MISALIGNED.yaml" + }, + { + "name": "REPORT_VA_IN_STVAL_ON_INSTRUCTION_PAGE_FAULT", + "long_name": "TODO", + "description": "When true, `stval` is written with the virtual PC of an instructino when fetch causes an\n`InstructionPageFault`.\n\nWHen false, `stval` is written with 0 when an instruction fetch causes an\n`InstructionPageFault`.", + "defined_by": { + "extensions": [ + "S" + ], + "params": [], + "raw": { + "extension": { + "name": "S" + } + }, + "summary": "ext:S" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_VA_IN_STVAL_ON_INSTRUCTION_PAGE_FAULT.yaml" + }, + { + "name": "REPORT_VA_IN_STVAL_ON_LOAD_ACCESS_FAULT", + "long_name": "TODO", + "description": "When true, `stval` is written with the virtual address of a load when it causes a\n`LoadAccessFault`.\n\nWHen false, `stval` is written with 0 when a load causes a `LoadAccessFault`.", + "defined_by": { + "extensions": [ + "S" + ], + "params": [], + "raw": { + "extension": { + "name": "S" + } + }, + "summary": "ext:S" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_VA_IN_STVAL_ON_LOAD_ACCESS_FAULT.yaml" + }, + { + "name": "REPORT_VA_IN_STVAL_ON_LOAD_MISALIGNED", + "long_name": "TODO", + "description": "When true, `stval` is written with the virtual address of a load instruction when the\naddress is misaligned and MISALIGNED_LDST is false.\n\nWhen false, `stval` is written with 0 when a load address is misaligned and\nMISALIGNED_LDST is false.", + "defined_by": { + "extensions": [ + "S" + ], + "params": [], + "raw": { + "extension": { + "name": "S" + } + }, + "summary": "ext:S" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_VA_IN_STVAL_ON_LOAD_MISALIGNED.yaml" + }, + { + "name": "REPORT_VA_IN_STVAL_ON_LOAD_PAGE_FAULT", + "long_name": "TODO", + "description": "When true, `stval` is written with the virtual address of a load when it causes a\n`LoadPageFault`.\n\nWHen false, `stval` is written with 0 when a load causes a `LoadPageFault`.", + "defined_by": { + "extensions": [ + "S" + ], + "params": [], + "raw": { + "extension": { + "name": "S" + } + }, + "summary": "ext:S" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_VA_IN_STVAL_ON_LOAD_PAGE_FAULT.yaml" + }, + { + "name": "REPORT_VA_IN_STVAL_ON_STORE_AMO_ACCESS_FAULT", + "long_name": "TODO", + "description": "When true, `stval` is written with the virtual address of a store when it causes a\n`StoreAmoAccessFault`.\n\nWHen false, `stval` is written with 0 when a store causes a `StoreAmoAccessFault`.", + "defined_by": { + "extensions": [ + "S" + ], + "params": [], + "raw": { + "extension": { + "name": "S" + } + }, + "summary": "ext:S" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_VA_IN_STVAL_ON_STORE_AMO_ACCESS_FAULT.yaml" + }, + { + "name": "REPORT_VA_IN_STVAL_ON_STORE_AMO_MISALIGNED", + "long_name": "TODO", + "description": "When true, `stval` is written with the virtual address of a store instruction when the\naddress is misaligned and MISALIGNED_LDST is false.\n\nWhen false, `stval` is written with 0 when a store address is misaligned and\nMISALIGNED_LDST is false.", + "defined_by": { + "extensions": [ + "S" + ], + "params": [], + "raw": { + "extension": { + "name": "S" + } + }, + "summary": "ext:S" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_VA_IN_STVAL_ON_STORE_AMO_MISALIGNED.yaml" + }, + { + "name": "REPORT_VA_IN_STVAL_ON_STORE_AMO_PAGE_FAULT", + "long_name": "TODO", + "description": "When true, `stval` is written with the virtual address of a store when it causes a\n`StoreAmoPageFault`.\n\nWHen false, `stval` is written with 0 when a store causes a `StoreAmoPageFault`.", + "defined_by": { + "extensions": [ + "S" + ], + "params": [], + "raw": { + "extension": { + "name": "S" + } + }, + "summary": "ext:S" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_VA_IN_STVAL_ON_STORE_AMO_PAGE_FAULT.yaml" + }, + { + "name": "REPORT_VA_IN_VSTVAL_ON_BREAKPOINT", + "long_name": "TODO", + "description": "When true, `vstval` is written with the virtual PC of the EBREAK instruction (same information as `mepc`).\n\nWhen false, `vstval` is written with 0 on an EBREAK instruction.\n\nRegardless, `vstval` is always written with a virtual PC when an external breakpoint is generated.", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_VA_IN_VSTVAL_ON_BREAKPOINT.yaml" + }, + { + "name": "REPORT_VA_IN_VSTVAL_ON_INSTRUCTION_ACCESS_FAULT", + "long_name": "TODO", + "description": "When true, `vstval` is written with the virtual PC of an instructino when fetch causes an\n`InstructionAccessFault`.\n\nWHen false, `vstval` is written with 0 when an instruction fetch causes an\n`InstructionAccessFault`.", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_VA_IN_VSTVAL_ON_INSTRUCTION_ACCESS_FAULT.yaml" + }, + { + "name": "REPORT_VA_IN_VSTVAL_ON_INSTRUCTION_MISALIGNED", + "long_name": "TODO", + "description": "When true, `vstval` is written with the virtual PC when an instruction fetch is misaligned.\n\nWhen false, `vstval` is written with 0 when an instruction fetch is misaligned.\n\nNote that when IALIGN=16 (i.e., when the `C` or one of the `Zc*` extensions are implemented),\nit is impossible to generate a misaligned fetch, and so this parameter has no effect.", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_VA_IN_VSTVAL_ON_INSTRUCTION_MISALIGNED.yaml" + }, + { + "name": "REPORT_VA_IN_VSTVAL_ON_INSTRUCTION_PAGE_FAULT", + "long_name": "TODO", + "description": "When true, `vstval` is written with the virtual PC of an instructino when fetch causes an\n`InstructionPageFault`.\n\nWHen false, `vstval` is written with 0 when an instruction fetch causes an\n`InstructionPageFault`.", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_VA_IN_VSTVAL_ON_INSTRUCTION_PAGE_FAULT.yaml" + }, + { + "name": "REPORT_VA_IN_VSTVAL_ON_LOAD_ACCESS_FAULT", + "long_name": "TODO", + "description": "When true, `vstval` is written with the virtual address of a load when it causes a\n`LoadAccessFault`.\n\nWHen false, `vstval` is written with 0 when a load causes a `LoadAccessFault`.", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_VA_IN_VSTVAL_ON_LOAD_ACCESS_FAULT.yaml" + }, + { + "name": "REPORT_VA_IN_VSTVAL_ON_LOAD_MISALIGNED", + "long_name": "TODO", + "description": "When true, `vstval` is written with the virtual address of a load instruction when the\naddress is misaligned and MISALIGNED_LDST is false.\n\nWhen false, `vstval` is written with 0 when a load address is misaligned and\nMISALIGNED_LDST is false.", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_VA_IN_VSTVAL_ON_LOAD_MISALIGNED.yaml" + }, + { + "name": "REPORT_VA_IN_VSTVAL_ON_LOAD_PAGE_FAULT", + "long_name": "TODO", + "description": "When true, `vstval` is written with the virtual address of a load when it causes a\n`LoadPageFault`.\n\nWHen false, `vstval` is written with 0 when a load causes a `LoadPageFault`.", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_VA_IN_VSTVAL_ON_LOAD_PAGE_FAULT.yaml" + }, + { + "name": "REPORT_VA_IN_VSTVAL_ON_STORE_AMO_ACCESS_FAULT", + "long_name": "TODO", + "description": "When true, `vstval` is written with the virtual address of a store when it causes a\n`StoreAmoAccessFault`.\n\nWHen false, `vstval` is written with 0 when a store causes a `StoreAmoAccessFault`.", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_VA_IN_VSTVAL_ON_STORE_AMO_ACCESS_FAULT.yaml" + }, + { + "name": "REPORT_VA_IN_VSTVAL_ON_STORE_AMO_MISALIGNED", + "long_name": "TODO", + "description": "When true, `vstval` is written with the virtual address of a store instruction when the\naddress is misaligned and MISALIGNED_LDST is false.\n\nWhen false, `vstval` is written with 0 when a store address is misaligned and\nMISALIGNED_LDST is false.", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_VA_IN_VSTVAL_ON_STORE_AMO_MISALIGNED.yaml" + }, + { + "name": "REPORT_VA_IN_VSTVAL_ON_STORE_AMO_PAGE_FAULT", + "long_name": "TODO", + "description": "When true, `vstval` is written with the virtual address of a store when it causes a\n`StoreAmoPageFault`.\n\nWHen false, `vstval` is written with 0 when a store causes a `StoreAmoPageFault`.", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^REPORT_)", + "source_file": "spec/std/isa/param/REPORT_VA_IN_VSTVAL_ON_STORE_AMO_PAGE_FAULT.yaml" + }, + { + "name": "RVV_VL_WHEN_AVL_LT_DOUBLE_VLMAX", + "long_name": "TODO", + "description": "The value assigned to VL when AVL < 2*VLMAX.", + "defined_by": { + "extensions": [ + "V" + ], + "params": [], + "raw": { + "extension": { + "name": "V" + } + }, + "summary": "ext:V" + }, + "value_type": { + "type": "enum", + "details": { + "values": [ + "ceil(AVL/2)", + "VLMAX", + "custom" + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "low", + "classification_reasoning": "No strong signals; defaulting to direct normative parameter", + "source_file": "spec/std/isa/param/RVV_VL_WHEN_AVL_LT_DOUBLE_VLMAX.yaml" + }, + { + "name": "SATP_MODE_BARE", + "long_name": "TODO", + "description": "Whether or not satp.MODE == Bare is supported.", + "defined_by": { + "extensions": [ + "S" + ], + "params": [], + "raw": { + "extension": { + "name": "S" + } + }, + "summary": "ext:S" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "satp", + "field": "MODE", + "idl_key": "sw_write(csr_value)" + } + ], + "classification": "NORM_CSR_WARL", + "classification_confidence": "high", + "classification_reasoning": "Referenced in sw_write() of satp.MODE", + "source_file": "spec/std/isa/param/SATP_MODE_BARE.yaml" + }, + { + "name": "SCOUNTENABLE_EN", + "long_name": "TODO", + "description": "Indicates which counters can delegated via `scounteren`\n\nAn unimplemented counter cannot be specified, i.e., if\nHPM_COUNTER_EN[3] is false, it would be illegal to set\nSCOUNTENABLE_EN[3] to true.\n\nSCOUNTENABLE_EN[0:2] must all be false if `Zicntr` is not implemented.\nSCOUNTENABLE_EN[3:31] must all be false if `Zihpm` is not implemented.", + "defined_by": { + "extensions": [ + "S", + "Zicntr", + "Zihpm" + ], + "params": [], + "raw": { + "extension": { + "allOf": [ + { + "name": "S" + }, + { + "anyOf": [ + { + "name": "Zicntr" + }, + { + "name": "Zihpm" + } + ] + } + ] + } + }, + "summary": "ext:S AND (ext:Zicntr OR ext:Zihpm)" + }, + "value_type": { + "type": "bitmask", + "details": { + "length": 32 + } + }, + "has_requirements": true, + "requirements_summary": "Counters 0-2 are defined by Zicntr\n\nCounters 3..31 are defined by Zihpm\n\nWhen mhpmcounter[i] does not exist, it cannot be enabled.\n", + "csr_references": [ + { + "csr": "scounteren", + "field": "CY", + "idl_key": "type()" + }, + { + "csr": "scounteren", + "field": "CY", + "idl_key": "reset_value()" + }, + { + "csr": "scounteren", + "field": "TM", + "idl_key": "type()" + }, + { + "csr": "scounteren", + "field": "TM", + "idl_key": "reset_value()" + }, + { + "csr": "scounteren", + "field": "IR", + "idl_key": "type()" + }, + { + "csr": "scounteren", + "field": "IR", + "idl_key": "reset_value()" + }, + { + "csr": "scounteren", + "field": "HPM3", + "idl_key": "type()" + }, + { + "csr": "scounteren", + "field": "HPM3", + "idl_key": "reset_value()" + }, + { + "csr": "scounteren", + "field": "HPM4", + "idl_key": "type()" + }, + { + "csr": "scounteren", + "field": "HPM4", + "idl_key": "reset_value()" + }, + { + "csr": "scounteren", + "field": "HPM5", + "idl_key": "type()" + }, + { + "csr": "scounteren", + "field": "HPM5", + "idl_key": "reset_value()" + }, + { + "csr": "scounteren", + "field": "HPM6", + "idl_key": "type()" + }, + { + "csr": "scounteren", + "field": "HPM6", + "idl_key": "reset_value()" + }, + { + "csr": "scounteren", + "field": "HPM7", + "idl_key": "type()" + }, + { + "csr": "scounteren", + "field": "HPM7", + "idl_key": "reset_value()" + }, + { + "csr": "scounteren", + "field": "HPM8", + "idl_key": "type()" + }, + { + "csr": "scounteren", + "field": "HPM8", + "idl_key": "reset_value()" + }, + { + "csr": "scounteren", + "field": "HPM9", + "idl_key": "type()" + }, + { + "csr": "scounteren", + "field": "HPM9", + "idl_key": "reset_value()" + }, + { + "csr": "scounteren", + "field": "HPM10", + "idl_key": "type()" + }, + { + "csr": "scounteren", + "field": "HPM10", + "idl_key": "reset_value()" + }, + { + "csr": "scounteren", + "field": "HPM11", + "idl_key": "type()" + }, + { + "csr": "scounteren", + "field": "HPM11", + "idl_key": "reset_value()" + }, + { + "csr": "scounteren", + "field": "HPM12", + "idl_key": "type()" + }, + { + "csr": "scounteren", + "field": "HPM12", + "idl_key": "reset_value()" + }, + { + "csr": "scounteren", + "field": "HPM13", + "idl_key": "type()" + }, + { + "csr": "scounteren", + "field": "HPM13", + "idl_key": "reset_value()" + }, + { + "csr": "scounteren", + "field": "HPM14", + "idl_key": "type()" + }, + { + "csr": "scounteren", + "field": "HPM14", + "idl_key": "reset_value()" + }, + { + "csr": "scounteren", + "field": "HPM15", + "idl_key": "type()" + }, + { + "csr": "scounteren", + "field": "HPM15", + "idl_key": "reset_value()" + }, + { + "csr": "scounteren", + "field": "HPM16", + "idl_key": "type()" + }, + { + "csr": "scounteren", + "field": "HPM16", + "idl_key": "reset_value()" + }, + { + "csr": "scounteren", + "field": "HPM17", + "idl_key": "type()" + }, + { + "csr": "scounteren", + "field": "HPM17", + "idl_key": "reset_value()" + }, + { + "csr": "scounteren", + "field": "HPM18", + "idl_key": "type()" + }, + { + "csr": "scounteren", + "field": "HPM18", + "idl_key": "reset_value()" + }, + { + "csr": "scounteren", + "field": "HPM19", + "idl_key": "type()" + }, + { + "csr": "scounteren", + "field": "HPM19", + "idl_key": "reset_value()" + }, + { + "csr": "scounteren", + "field": "HPM20", + "idl_key": "type()" + }, + { + "csr": "scounteren", + "field": "HPM20", + "idl_key": "reset_value()" + }, + { + "csr": "scounteren", + "field": "HPM21", + "idl_key": "type()" + }, + { + "csr": "scounteren", + "field": "HPM21", + "idl_key": "reset_value()" + }, + { + "csr": "scounteren", + "field": "HPM22", + "idl_key": "type()" + }, + { + "csr": "scounteren", + "field": "HPM22", + "idl_key": "reset_value()" + }, + { + "csr": "scounteren", + "field": "HPM23", + "idl_key": "type()" + }, + { + "csr": "scounteren", + "field": "HPM23", + "idl_key": "reset_value()" + }, + { + "csr": "scounteren", + "field": "HPM24", + "idl_key": "type()" + }, + { + "csr": "scounteren", + "field": "HPM24", + "idl_key": "reset_value()" + }, + { + "csr": "scounteren", + "field": "HPM25", + "idl_key": "type()" + }, + { + "csr": "scounteren", + "field": "HPM25", + "idl_key": "reset_value()" + }, + { + "csr": "scounteren", + "field": "HPM26", + "idl_key": "type()" + }, + { + "csr": "scounteren", + "field": "HPM26", + "idl_key": "reset_value()" + }, + { + "csr": "scounteren", + "field": "HPM27", + "idl_key": "type()" + }, + { + "csr": "scounteren", + "field": "HPM27", + "idl_key": "reset_value()" + }, + { + "csr": "scounteren", + "field": "HPM28", + "idl_key": "type()" + }, + { + "csr": "scounteren", + "field": "HPM28", + "idl_key": "reset_value()" + }, + { + "csr": "scounteren", + "field": "HPM29", + "idl_key": "type()" + }, + { + "csr": "scounteren", + "field": "HPM29", + "idl_key": "reset_value()" + }, + { + "csr": "scounteren", + "field": "HPM30", + "idl_key": "type()" + }, + { + "csr": "scounteren", + "field": "HPM30", + "idl_key": "reset_value()" + }, + { + "csr": "scounteren", + "field": "HPM31", + "idl_key": "type()" + }, + { + "csr": "scounteren", + "field": "HPM31", + "idl_key": "reset_value()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of scounteren.CY", + "source_file": "spec/std/isa/param/SCOUNTENABLE_EN.yaml" + }, + { + "name": "SSTATEEN_JVT_TYPE", + "long_name": "TODO", + "description": "Behavior of the sstateen0.JVT bit:\n\n * 'rw': read-write\n * 'read-only-0': read-only, fixed to 0\n * 'read-only-1': read-only, fixed to 1", + "defined_by": { + "extensions": [ + "Ssstateen", + "Zcmt" + ], + "params": [], + "raw": { + "extension": { + "allOf": [ + { + "name": "Zcmt" + }, + { + "name": "Ssstateen" + } + ] + } + }, + "summary": "ext:Zcmt AND ext:Ssstateen" + }, + "value_type": { + "type": "enum", + "details": { + "values": [ + "rw", + "read-only-0", + "read-only-1" + ] + } + }, + "has_requirements": true, + "requirements_summary": "SSTATEEN cannot have more options that MSTATEEN\n\nSSTATEEN cannot have more options that HSTATEEN\n", + "csr_references": [], + "classification": "NORM_CSR_RW", + "classification_confidence": "low", + "classification_reasoning": "CSR field type control parameter for 'sstateen' (determines RO/RW behavior)", + "source_file": "spec/std/isa/param/SSTATEEN_JVT_TYPE.yaml" + }, + { + "name": "STVAL_WIDTH", + "long_name": "TODO", + "description": "The number of implemented bits in `stval`.\n\nMust be greater than or equal to _max_(`PHYS_ADDR_WIDTH`, `VA_SIZE`)", + "defined_by": { + "extensions": [ + "S" + ], + "params": [], + "raw": { + "extension": { + "name": "S" + } + }, + "summary": "ext:S" + }, + "value_type": { + "type": "range", + "details": { + "minimum": null, + "maximum": 18446744073709551615 + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "medium", + "classification_reasoning": "Trap value reporting parameter", + "source_file": "spec/std/isa/param/STVAL_WIDTH.yaml" + }, + { + "name": "STVEC_MODE_DIRECT", + "long_name": "TODO", + "description": "Whether or not `stvec.MODE` supports Direct (0).", + "defined_by": { + "extensions": [ + "S" + ], + "params": [], + "raw": { + "extension": { + "name": "S" + } + }, + "summary": "ext:S" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": true, + "requirements_summary": "stvec must support at least one mode", + "csr_references": [ + { + "csr": "stvec", + "field": "MODE", + "idl_key": "sw_write(csr_value)" + } + ], + "classification": "NORM_CSR_WARL", + "classification_confidence": "high", + "classification_reasoning": "Referenced in sw_write() of stvec.MODE", + "source_file": "spec/std/isa/param/STVEC_MODE_DIRECT.yaml" + }, + { + "name": "STVEC_MODE_VECTORED", + "long_name": "TODO", + "description": "Whether or not `stvec.MODE` supports Vectored (1).", + "defined_by": { + "extensions": [ + "S" + ], + "params": [], + "raw": { + "extension": { + "name": "S" + } + }, + "summary": "ext:S" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": true, + "requirements_summary": "stvec must support at least one mode", + "csr_references": [ + { + "csr": "stvec", + "field": "MODE", + "idl_key": "sw_write(csr_value)" + } + ], + "classification": "NORM_CSR_WARL", + "classification_confidence": "high", + "classification_reasoning": "Referenced in sw_write() of stvec.MODE", + "source_file": "spec/std/isa/param/STVEC_MODE_VECTORED.yaml" + }, + { + "name": "SV32X4_TRANSLATION", + "long_name": "TODO", + "description": "Whether or not Sv32x4 translation mode is supported.", + "defined_by": { + "extensions": [ + "H" + ], + "params": [ + { + "name": "SXLEN", + "condition": { + "includes": 32 + } + } + ], + "raw": { + "allOf": [ + { + "extension": { + "name": "H" + } + }, + { + "param": { + "name": "SXLEN", + "includes": 32 + } + } + ] + }, + "summary": "ext:H AND param:SXLEN(includes=32)" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": true, + "requirements_summary": "at least one of Bare, Sv32x4 must be supported", + "csr_references": [ + { + "csr": "hgatp", + "field": "MODE", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "hgatp", + "field": "PPN", + "idl_key": "type()" + }, + { + "csr": "hgatp", + "field": "PPN", + "idl_key": "reset_value()" + } + ], + "classification": "NORM_CSR_WARL", + "classification_confidence": "high", + "classification_reasoning": "Referenced in sw_write() of hgatp.MODE", + "source_file": "spec/std/isa/param/SV32X4_TRANSLATION.yaml" + }, + { + "name": "SV32_VSMODE_TRANSLATION", + "long_name": "TODO", + "description": "Whether or not Sv32 translation is supported in first-stage (VS-stage)\ntranslation.", + "defined_by": { + "extensions": [ + "H" + ], + "params": [ + { + "name": "VSXLEN", + "condition": { + "includes": 32 + } + } + ], + "raw": { + "allOf": [ + { + "extension": { + "name": "H" + } + }, + { + "param": { + "name": "VSXLEN", + "includes": 32 + } + } + ] + }, + "summary": "ext:H AND param:VSXLEN(includes=32)" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": true, + "requirements_summary": "at least one of Bare, Sv32 must be supported", + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "medium", + "classification_reasoning": "Translation/mode parameter", + "source_file": "spec/std/isa/param/SV32_VSMODE_TRANSLATION.yaml" + }, + { + "name": "SV39X4_TRANSLATION", + "long_name": "TODO", + "description": "Whether or not Sv39x4 translation mode is supported.", + "defined_by": { + "extensions": [ + "H" + ], + "params": [ + { + "name": "SXLEN", + "condition": { + "includes": 64 + } + } + ], + "raw": { + "allOf": [ + { + "extension": { + "name": "H" + } + }, + { + "param": { + "name": "SXLEN", + "includes": 64 + } + } + ] + }, + "summary": "ext:H AND param:SXLEN(includes=64)" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": true, + "requirements_summary": "Sv39x4 is only valid if S-mode can get into RV64 mode", + "csr_references": [ + { + "csr": "hgatp", + "field": "MODE", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "hgatp", + "field": "PPN", + "idl_key": "type()" + }, + { + "csr": "hgatp", + "field": "PPN", + "idl_key": "reset_value()" + } + ], + "classification": "NORM_CSR_WARL", + "classification_confidence": "high", + "classification_reasoning": "Referenced in sw_write() of hgatp.MODE", + "source_file": "spec/std/isa/param/SV39X4_TRANSLATION.yaml" + }, + { + "name": "SV39_VSMODE_TRANSLATION", + "long_name": "TODO", + "description": "Whether or not Sv39 translation is supported in first-stage (VS-stage)\ntranslation.", + "defined_by": { + "extensions": [ + "H" + ], + "params": [ + { + "name": "VSXLEN", + "condition": { + "includes": 64 + } + } + ], + "raw": { + "allOf": [ + { + "extension": { + "name": "H" + } + }, + { + "param": { + "name": "VSXLEN", + "includes": 64 + } + } + ] + }, + "summary": "ext:H AND param:VSXLEN(includes=64)" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": true, + "requirements_summary": "at least one of Bare, SvQQX4 must be supported", + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "medium", + "classification_reasoning": "Translation/mode parameter", + "source_file": "spec/std/isa/param/SV39_VSMODE_TRANSLATION.yaml" + }, + { + "name": "SV48X4_TRANSLATION", + "long_name": "TODO", + "description": "Whether or not Sv48x4 translation mode is supported.", + "defined_by": { + "extensions": [ + "H" + ], + "params": [ + { + "name": "SXLEN", + "condition": { + "includes": 64 + } + } + ], + "raw": { + "allOf": [ + { + "extension": { + "name": "H" + } + }, + { + "param": { + "name": "SXLEN", + "includes": 64 + } + } + ] + }, + "summary": "ext:H AND param:SXLEN(includes=64)" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": true, + "requirements_summary": "at least one of Bare, SvQQx4 must be supported", + "csr_references": [ + { + "csr": "hgatp", + "field": "MODE", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "hgatp", + "field": "PPN", + "idl_key": "type()" + }, + { + "csr": "hgatp", + "field": "PPN", + "idl_key": "reset_value()" + } + ], + "classification": "NORM_CSR_WARL", + "classification_confidence": "high", + "classification_reasoning": "Referenced in sw_write() of hgatp.MODE", + "source_file": "spec/std/isa/param/SV48X4_TRANSLATION.yaml" + }, + { + "name": "SV48_VSMODE_TRANSLATION", + "long_name": "TODO", + "description": "Whether or not Sv48 translation is supported in first-stage (VS-stage)\ntranslation.", + "defined_by": { + "extensions": [ + "H" + ], + "params": [ + { + "name": "VSXLEN", + "condition": { + "includes": 64 + } + } + ], + "raw": { + "allOf": [ + { + "extension": { + "name": "H" + } + }, + { + "param": { + "name": "VSXLEN", + "includes": 64 + } + } + ] + }, + "summary": "ext:H AND param:VSXLEN(includes=64)" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": true, + "requirements_summary": "at least one of Bare, SvQQX4 must be supported", + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "medium", + "classification_reasoning": "Translation/mode parameter", + "source_file": "spec/std/isa/param/SV48_VSMODE_TRANSLATION.yaml" + }, + { + "name": "SV57X4_TRANSLATION", + "long_name": "TODO", + "description": "Whether or not Sv57x4 translation mode is supported.", + "defined_by": { + "extensions": [ + "H" + ], + "params": [ + { + "name": "SXLEN", + "condition": { + "includes": 64 + } + } + ], + "raw": { + "allOf": [ + { + "extension": { + "name": "H" + } + }, + { + "param": { + "name": "SXLEN", + "includes": 64 + } + } + ] + }, + "summary": "ext:H AND param:SXLEN(includes=64)" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": true, + "requirements_summary": "at least one of Bare, SvQQx4 must be supported", + "csr_references": [ + { + "csr": "hgatp", + "field": "MODE", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "hgatp", + "field": "PPN", + "idl_key": "type()" + }, + { + "csr": "hgatp", + "field": "PPN", + "idl_key": "reset_value()" + } + ], + "classification": "NORM_CSR_WARL", + "classification_confidence": "high", + "classification_reasoning": "Referenced in sw_write() of hgatp.MODE", + "source_file": "spec/std/isa/param/SV57X4_TRANSLATION.yaml" + }, + { + "name": "SV57_VSMODE_TRANSLATION", + "long_name": "TODO", + "description": "Whether or not Sv57 translation is supported in first-stage (VS-stage)\ntranslation.", + "defined_by": { + "extensions": [ + "H" + ], + "params": [ + { + "name": "VSXLEN", + "condition": { + "includes": 64 + } + } + ], + "raw": { + "allOf": [ + { + "extension": { + "name": "H" + } + }, + { + "param": { + "name": "VSXLEN", + "includes": 64 + } + } + ] + }, + "summary": "ext:H AND param:VSXLEN(includes=64)" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": true, + "requirements_summary": "at least one of Bare, SvQQX4 must be supported", + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "medium", + "classification_reasoning": "Translation/mode parameter", + "source_file": "spec/std/isa/param/SV57_VSMODE_TRANSLATION.yaml" + }, + { + "name": "SXLEN", + "long_name": "TODO", + "description": "Set of XLENs supported in S-mode. Can be one of:\n\n * 32: SXLEN is always 32\n * 64: SXLEN is always 64\n * [32, 64]: SXLEN can be changed (via mstatus.SXL) between 32 and 64", + "defined_by": { + "extensions": [ + "S" + ], + "params": [], + "raw": { + "extension": { + "name": "S" + } + }, + "summary": "ext:S" + }, + "value_type": { + "type": "set", + "details": { + "universe": [ + 32, + 64 + ], + "min_items": 1, + "max_items": 2 + } + }, + "has_requirements": true, + "requirements_summary": "XLEN in S-mode can never be larger than XLEN in M-mode", + "csr_references": [ + { + "csr": "mstatus", + "field": "SXL", + "idl_key": "type()" + }, + { + "csr": "mstatus", + "field": "SXL", + "idl_key": "reset_value()" + }, + { + "csr": "hstatus", + "field": "VSXL", + "idl_key": "sw_write(csr_value)" + } + ], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Well-known architectural parameter 'SXLEN'", + "source_file": "spec/std/isa/param/SXLEN.yaml" + }, + { + "name": "S_MODE_ENDIANNESS", + "long_name": "TODO", + "description": "Endianness of data in S-mode. Can be one of:\n\n * little: S-mode data is always little endian\n * big: S-mode data is always big endian\n * dynamic: S-mode data can be either little or big endian,\n depending on the CSR field `mstatus.SBE`", + "defined_by": { + "extensions": [ + "S" + ], + "params": [], + "raw": { + "extension": { + "name": "S" + } + }, + "summary": "ext:S" + }, + "value_type": { + "type": "enum", + "details": { + "values": [ + "little", + "big", + "dynamic" + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "mstatus", + "field": "SBE", + "idl_key": "type()" + }, + { + "csr": "mstatus", + "field": "SBE", + "idl_key": "reset_value()" + }, + { + "csr": "mstatush", + "field": "SBE", + "idl_key": "type()" + }, + { + "csr": "mstatush", + "field": "SBE", + "idl_key": "reset_value()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of mstatus.SBE", + "source_file": "spec/std/isa/param/S_MODE_ENDIANNESS.yaml" + }, + { + "name": "TIME_CSR_IMPLEMENTED", + "long_name": "TODO", + "description": "Whether or not a real hardware `time` CSR exists. Implementations can either provide a real\nCSR or emulate access at M-mode.\n\nPossible values:\n\ntrue::\n `time`/`timeh` exists, and accessing it will not cause an IllegalInstruction trap\n\nfalse::\n `time`/`timeh` does not exist.\n Accessing the CSR will cause an IllegalInstruction trap or enter an unpredictable state,\n depending on TRAP_ON_UNIMPLEMENTED_CSR.\n Privileged software may emulate the `time` CSR, or may pass the exception to a lower level.", + "defined_by": { + "extensions": [ + "Zicntr" + ], + "params": [], + "raw": { + "extension": { + "name": "Zicntr" + } + }, + "summary": "ext:Zicntr" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "timeh", + "field": "(csr-level)", + "idl_key": "sw_read()" + }, + { + "csr": "time", + "field": "(csr-level)", + "idl_key": "sw_read()" + } + ], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Feature/CSR existence parameter ('IMPLEMENTED' suffix)", + "source_file": "spec/std/isa/param/TIME_CSR_IMPLEMENTED.yaml" + }, + { + "name": "TINST_VALUE_ON_BREAKPOINT", + "long_name": "TODO", + "description": "Value written into htinst/mtinst on a Breakpoint exception from VU/VS-mode.\n\nPossible values:\n * \"always zero\": Always write the value zero\n * \"custom\": Write a custom value, which results in UNPREDICTABLE", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + "always zero", + "custom" + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "htinst", + "field": "VALUE", + "idl_key": "type()" + }, + { + "csr": "mtinst", + "field": "VALUE", + "idl_key": "type()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of htinst.VALUE", + "source_file": "spec/std/isa/param/TINST_VALUE_ON_BREAKPOINT.yaml" + }, + { + "name": "TINST_VALUE_ON_FINAL_INSTRUCTION_GUEST_PAGE_FAULT", + "long_name": "TODO", + "description": "Value to write into htval/mtval2 when there is a guest page fault on a final translation.\n\nPossible values:\n * \"always zero\": Always write the value zero\n * \"always pseudoinstruction\": Always write the pseudoinstruction", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + "always zero", + "always pseudoinstruction" + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "htinst", + "field": "VALUE", + "idl_key": "type()" + }, + { + "csr": "mtinst", + "field": "VALUE", + "idl_key": "type()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of htinst.VALUE", + "source_file": "spec/std/isa/param/TINST_VALUE_ON_FINAL_INSTRUCTION_GUEST_PAGE_FAULT.yaml" + }, + { + "name": "TINST_VALUE_ON_FINAL_LOAD_GUEST_PAGE_FAULT", + "long_name": "TODO", + "description": "Value to write into htval/mtval2 when there is a guest page fault on a final translation.\n\nPossible values:\n * \"always zero\": Always write the value zero\n * \"always pseudoinstruction\": Always write the pseudoinstruction\n * \"always transformed standard instruction\": Always write the transformation of the standard instruction encoding\n * \"custom\": A custom value, which will cause an UNPREDICTABLE event.", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "enum", + "details": { + "values": [ + "always zero", + "always pseudoinstruction", + "always transformed standard instruction", + "custom" + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "htinst", + "field": "VALUE", + "idl_key": "type()" + }, + { + "csr": "mtinst", + "field": "VALUE", + "idl_key": "type()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of htinst.VALUE", + "source_file": "spec/std/isa/param/TINST_VALUE_ON_FINAL_LOAD_GUEST_PAGE_FAULT.yaml" + }, + { + "name": "TINST_VALUE_ON_FINAL_STORE_AMO_GUEST_PAGE_FAULT", + "long_name": "TODO", + "description": "Value to write into htval/mtval2 when there is a guest page fault on a final translation.\n\nPossible values:\n * \"always zero\": Always write the value zero\n * \"always pseudoinstruction\": Always write the pseudoinstruction\n * \"always transformed standard instruction\": Always write the transformation of the standard instruction encoding\n * \"custom\": A custom value, which will cause an UNPREDICTABLE event.", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "enum", + "details": { + "values": [ + "always zero", + "always pseudoinstruction", + "always transformed standard instruction", + "custom" + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "htinst", + "field": "VALUE", + "idl_key": "type()" + }, + { + "csr": "mtinst", + "field": "VALUE", + "idl_key": "type()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of htinst.VALUE", + "source_file": "spec/std/isa/param/TINST_VALUE_ON_FINAL_STORE_AMO_GUEST_PAGE_FAULT.yaml" + }, + { + "name": "TINST_VALUE_ON_INSTRUCTION_ADDRESS_MISALIGNED", + "long_name": "TODO", + "description": "Value written into htinst/mtinst when there is an instruction address misaligned exception.\n\nPossible values:\n * \"always zero\": Always write the value zero\n * \"custom\": Write a custom value, which results in UNPREDICTABLE", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + "always zero", + "custom" + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "htinst", + "field": "VALUE", + "idl_key": "type()" + }, + { + "csr": "mtinst", + "field": "VALUE", + "idl_key": "type()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of htinst.VALUE", + "source_file": "spec/std/isa/param/TINST_VALUE_ON_INSTRUCTION_ADDRESS_MISALIGNED.yaml" + }, + { + "name": "TINST_VALUE_ON_LOAD_ACCESS_FAULT", + "long_name": "TODO", + "description": "Value written into htinst/mtinst on an AccessFault exception from VU/VS-mode.\n\nPossible values:\n * \"always zero\": Always write the value zero\n * \"always transformed standard instruction\": Always write a transformed standard instruction as defined by H\n * \"custom\": Write a custom value, which results in UNPREDICTABLE", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "enum", + "details": { + "values": [ + "always zero", + "always transformed standard instruction", + "custom" + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "htinst", + "field": "VALUE", + "idl_key": "type()" + }, + { + "csr": "mtinst", + "field": "VALUE", + "idl_key": "type()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of htinst.VALUE", + "source_file": "spec/std/isa/param/TINST_VALUE_ON_LOAD_ACCESS_FAULT.yaml" + }, + { + "name": "TINST_VALUE_ON_LOAD_ADDRESS_MISALIGNED", + "long_name": "TODO", + "description": "Value written into htinst/mtinst on a VirtualInstruction exception from VU/VS-mode.\n\nPossible values:\n * \"always zero\": Always write the value zero\n * \"always transformed standard instruction\": Always write a transformed standard instruction as defined by H\n * \"custom\": Write a custom value, which results in UNPREDICTABLE", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "enum", + "details": { + "values": [ + "always zero", + "always transformed standard instruction", + "custom" + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "htinst", + "field": "VALUE", + "idl_key": "type()" + }, + { + "csr": "mtinst", + "field": "VALUE", + "idl_key": "type()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of htinst.VALUE", + "source_file": "spec/std/isa/param/TINST_VALUE_ON_LOAD_ADDRESS_MISALIGNED.yaml" + }, + { + "name": "TINST_VALUE_ON_LOAD_PAGE_FAULT", + "long_name": "TODO", + "description": "Value written into htinst/mtinst on a LoadPageFault exception from VU/VS-mode.\n\nPossible values:\n * \"always zero\": Always write the value zero\n * \"always transformed standard instruction\": Always write a transformed standard instruction as defined by H\n * \"custom\": Write a custom value, which results in UNPREDICTABLE", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "enum", + "details": { + "values": [ + "always zero", + "always transformed standard instruction", + "custom" + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "htinst", + "field": "VALUE", + "idl_key": "type()" + }, + { + "csr": "mtinst", + "field": "VALUE", + "idl_key": "type()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of htinst.VALUE", + "source_file": "spec/std/isa/param/TINST_VALUE_ON_LOAD_PAGE_FAULT.yaml" + }, + { + "name": "TINST_VALUE_ON_MCALL", + "long_name": "TODO", + "description": "Value written into htinst/mtinst on a MCall exception from VU/VS-mode.\n\nPossible values:\n * \"always zero\": Always write the value zero\n * \"custom\": Write a custom value, which results in UNPREDICTABLE", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + "always zero", + "custom" + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "htinst", + "field": "VALUE", + "idl_key": "type()" + }, + { + "csr": "mtinst", + "field": "VALUE", + "idl_key": "type()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of htinst.VALUE", + "source_file": "spec/std/isa/param/TINST_VALUE_ON_MCALL.yaml" + }, + { + "name": "TINST_VALUE_ON_SCALL", + "long_name": "TODO", + "description": "Value written into htinst/mtinst on a SCall exception from VU/VS-mode.\n\nPossible values:\n * \"always zero\": Always write the value zero\n * \"custom\": Write a custom value, which results in UNPREDICTABLE", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + "always zero", + "custom" + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "htinst", + "field": "VALUE", + "idl_key": "type()" + }, + { + "csr": "mtinst", + "field": "VALUE", + "idl_key": "type()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of htinst.VALUE", + "source_file": "spec/std/isa/param/TINST_VALUE_ON_SCALL.yaml" + }, + { + "name": "TINST_VALUE_ON_STORE_AMO_ACCESS_FAULT", + "long_name": "TODO", + "description": "Value written into htinst/mtinst on an AccessFault exception from VU/VS-mode.\n\nPossible values:\n * \"always zero\": Always write the value zero\n * \"always transformed standard instruction\": Always write a transformed standard instruction as defined by H\n * \"custom\": Write a custom value, which results in UNPREDICTABLE", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "enum", + "details": { + "values": [ + "always zero", + "always transformed standard instruction", + "custom" + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "htinst", + "field": "VALUE", + "idl_key": "type()" + }, + { + "csr": "mtinst", + "field": "VALUE", + "idl_key": "type()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of htinst.VALUE", + "source_file": "spec/std/isa/param/TINST_VALUE_ON_STORE_AMO_ACCESS_FAULT.yaml" + }, + { + "name": "TINST_VALUE_ON_STORE_AMO_ADDRESS_MISALIGNED", + "long_name": "TODO", + "description": "Value written into htinst/mtinst on a VirtualInstruction exception from VU/VS-mode.\n\nPossible values:\n * \"always zero\": Always write the value zero\n * \"always transformed standard instruction\": Always write a transformed standard instruction as defined by H\n * \"custom\": Write a custom value, which results in UNPREDICTABLE", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "enum", + "details": { + "values": [ + "always zero", + "always transformed standard instruction", + "custom" + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "htinst", + "field": "VALUE", + "idl_key": "type()" + }, + { + "csr": "mtinst", + "field": "VALUE", + "idl_key": "type()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of htinst.VALUE", + "source_file": "spec/std/isa/param/TINST_VALUE_ON_STORE_AMO_ADDRESS_MISALIGNED.yaml" + }, + { + "name": "TINST_VALUE_ON_STORE_AMO_PAGE_FAULT", + "long_name": "TODO", + "description": "Value written into htinst/mtinst on a StoreAmoPageFault exception from VU/VS-mode.\n\nPossible values:\n * \"always zero\": Always write the value zero\n * \"always transformed standard instruction\": Always write a transformed standard instruction as defined by H\n * \"custom\": Write a custom value, which results in UNPREDICTABLE", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "enum", + "details": { + "values": [ + "always zero", + "always transformed standard instruction", + "custom" + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "htinst", + "field": "VALUE", + "idl_key": "type()" + }, + { + "csr": "mtinst", + "field": "VALUE", + "idl_key": "type()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of htinst.VALUE", + "source_file": "spec/std/isa/param/TINST_VALUE_ON_STORE_AMO_PAGE_FAULT.yaml" + }, + { + "name": "TINST_VALUE_ON_UCALL", + "long_name": "TODO", + "description": "Value written into htinst/mtinst on a UCall exception from VU/VS-mode.\n\nPossible values:\n * \"always zero\": Always write the value zero\n * \"custom\": Write a custom value, which results in UNPREDICTABLE", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + "always zero", + "custom" + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "htinst", + "field": "VALUE", + "idl_key": "type()" + }, + { + "csr": "mtinst", + "field": "VALUE", + "idl_key": "type()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of htinst.VALUE", + "source_file": "spec/std/isa/param/TINST_VALUE_ON_UCALL.yaml" + }, + { + "name": "TINST_VALUE_ON_VIRTUAL_INSTRUCTION", + "long_name": "TODO", + "description": "Value written into htinst/mtinst on a VirtualInstruction exception from VU/VS-mode.\n\nPossible values:\n * \"always zero\": Always write the value zero\n * \"custom\": Write a custom value, which results in UNPREDICTABLE", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + "always zero", + "custom" + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "htinst", + "field": "VALUE", + "idl_key": "type()" + }, + { + "csr": "mtinst", + "field": "VALUE", + "idl_key": "type()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of htinst.VALUE", + "source_file": "spec/std/isa/param/TINST_VALUE_ON_VIRTUAL_INSTRUCTION.yaml" + }, + { + "name": "TINST_VALUE_ON_VSCALL", + "long_name": "TODO", + "description": "Value written into htinst/mtinst on a VSCall exception from VU/VS-mode.\n\nPossible values:\n * \"always zero\": Always write the value zero\n * \"custom\": Write a custom value, which results in UNPREDICTABLE", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + "always zero", + "custom" + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "htinst", + "field": "VALUE", + "idl_key": "type()" + }, + { + "csr": "mtinst", + "field": "VALUE", + "idl_key": "type()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of htinst.VALUE", + "source_file": "spec/std/isa/param/TINST_VALUE_ON_VSCALL.yaml" + }, + { + "name": "TRAP_ON_EBREAK", + "long_name": "Whether or not an EBREAK causes a synchronous exception.", + "description": "The spec states that implementations may handle EBREAKs transparently\nwithout raising a trap, in which case the EEI must provide a builtin.", + "defined_by": { + "extensions": [ + "Sm" + ], + "params": [], + "raw": { + "extension": { + "name": "Sm" + } + }, + "summary": "ext:Sm" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^TRAP_ON_)", + "source_file": "spec/std/isa/param/TRAP_ON_EBREAK.yaml" + }, + { + "name": "TRAP_ON_ECALL_FROM_M", + "long_name": "Whether or not an ECALL-from-M-mode causes a synchronous exception.", + "description": "The spec states that implementations may handle ECALLs transparently\nwithout raising a trap, in which case the EEI must provide a builtin.", + "defined_by": { + "extensions": [ + "Sm" + ], + "params": [], + "raw": { + "extension": { + "name": "Sm" + } + }, + "summary": "ext:Sm" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^TRAP_ON_)", + "source_file": "spec/std/isa/param/TRAP_ON_ECALL_FROM_M.yaml" + }, + { + "name": "TRAP_ON_ECALL_FROM_S", + "long_name": "TODO", + "description": "Whether or not an ECALL-from-S-mode causes a synchronous exception.\n\nThe spec states that implementations may handle ECALLs transparently\nwithout raising a trap, in which case the EEI must provide a builtin.", + "defined_by": { + "extensions": [ + "S" + ], + "params": [], + "raw": { + "extension": { + "name": "S" + } + }, + "summary": "ext:S" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^TRAP_ON_)", + "source_file": "spec/std/isa/param/TRAP_ON_ECALL_FROM_S.yaml" + }, + { + "name": "TRAP_ON_ECALL_FROM_U", + "long_name": "TODO", + "description": "Whether or not an ECALL-from-U-mode causes a synchronous exception.\n\nThe spec states that implementations may handle ECALLs transparently\nwithout raising a trap, in which case the EEI must provide a builtin.", + "defined_by": { + "extensions": [ + "U" + ], + "params": [], + "raw": { + "extension": { + "name": "U" + } + }, + "summary": "ext:U" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^TRAP_ON_)", + "source_file": "spec/std/isa/param/TRAP_ON_ECALL_FROM_U.yaml" + }, + { + "name": "TRAP_ON_ECALL_FROM_VS", + "long_name": "TODO", + "description": "Whether or not an ECALL-from-VS-mode causes a synchronous exception.\n\nThe spec states that implementations may handle ECALLs transparently\nwithout raising a trap, in which case the EEI must provide a builtin.", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^TRAP_ON_)", + "source_file": "spec/std/isa/param/TRAP_ON_ECALL_FROM_VS.yaml" + }, + { + "name": "TRAP_ON_ILLEGAL_WLRL", + "long_name": "Whether or not writing an illegal value to a WLRL CSR field causes a trap.", + "description": "Options:\n\n * true: Writing an illegal value to a WLRL CSR field will cause an IllegalInstruction exception.\n * false: Writing an illegal value to a WLRL CSR field causes unpredictable behavior.", + "defined_by": { + "extensions": [ + "Sm" + ], + "params": [], + "raw": { + "extension": { + "name": "Sm" + } + }, + "summary": "ext:Sm" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^TRAP_ON_)", + "source_file": "spec/std/isa/param/TRAP_ON_ILLEGAL_WLRL.yaml" + }, + { + "name": "TRAP_ON_RESERVED_INSTRUCTION", + "long_name": "Whether or not fetching an unimplemented standard instruction and/or an undefined standard\ninstruction from the standard/reserved opcode space causes a trap", + "description": "Options:\n\n * true: Fetching an unimplemented and/or undefined instruction from the standard/reserved opcode space will cause an IllegalInstruction exception.\n * false: Fetching an unimplemented and/or undefined instruction from the standard/reserved opcose space causes unpredictable behavior.\n\nTRAP_ON_RESERVED_INSTRUCTION may be false while TRAP_ON_UNIMPLEMENTED_INSTRUCTION is true\nwhen a custom instruction is implemented in the standard/reserved opcode space.", + "defined_by": { + "extensions": [ + "Sm" + ], + "params": [], + "raw": { + "extension": { + "name": "Sm" + } + }, + "summary": "ext:Sm" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^TRAP_ON_)", + "source_file": "spec/std/isa/param/TRAP_ON_RESERVED_INSTRUCTION.yaml" + }, + { + "name": "TRAP_ON_SFENCE_VMA_WHEN_SATP_MODE_IS_READ_ONLY", + "long_name": "TODO", + "description": "For implementations that make `satp`.MODE read-only zero\n(always Bare, _i.e._, no virtual translation is implemented),\nattempts to execute an SFENCE.VMA instruction might raise an\nillegal-instruction exception.\n\nTRAP_ON_SFENCE_VMA_WHEN_SATP_MODE_IS_READ_ONLY indicates whether\nor not that exception occurs.\n\nTRAP_ON_SFENCE_VMA_WHEN_SATP_MODE_IS_READ_ONLY has no effect when\nsome virtual translation mode is supported.", + "defined_by": { + "extensions": [ + "S", + "Sv32", + "Sv39", + "Sv48", + "Sv57" + ], + "params": [], + "raw": { + "extension": { + "allOf": [ + { + "name": "S" + }, + { + "noneOf": [ + { + "name": "Sv32" + }, + { + "name": "Sv39" + }, + { + "name": "Sv48" + }, + { + "name": "Sv57" + } + ] + } + ] + } + }, + "summary": "ext:S AND NONE(ext:Sv32, ext:Sv39, ext:Sv48, ext:Sv57)" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^TRAP_ON_)", + "source_file": "spec/std/isa/param/TRAP_ON_SFENCE_VMA_WHEN_SATP_MODE_IS_READ_ONLY.yaml" + }, + { + "name": "TRAP_ON_UNIMPLEMENTED_CSR", + "long_name": "Whether or not fetching an unimplemented instruction causes a trap", + "description": "Options:\n\n * true: Accessing an unimplemented CSR (via a `Zicsr` instruction) will cause an IllegalInstruction exception.\n * false: Accessing an unimplemented CSR (via a `Zicsr` instruction) will cause unpredictable behavior.", + "defined_by": { + "extensions": [ + "Sm" + ], + "params": [], + "raw": { + "extension": { + "name": "Sm" + } + }, + "summary": "ext:Sm" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^TRAP_ON_)", + "source_file": "spec/std/isa/param/TRAP_ON_UNIMPLEMENTED_CSR.yaml" + }, + { + "name": "TRAP_ON_UNIMPLEMENTED_INSTRUCTION", + "long_name": "Whether or not fetching an unimplemented instruction causes a trap", + "description": "Options:\n\n * true: Fetching an unimplemented instruction will cause an IllegalInstruction exception.\n * false: Fetching an unimplemented instruction causes unpredictable behavior.\n\nAn unimplemented instruction is any instruction encoding that is not defined by the implementation.\nCustom instructions are considered implemented.", + "defined_by": { + "extensions": [ + "Sm" + ], + "params": [], + "raw": { + "extension": { + "name": "Sm" + } + }, + "summary": "ext:Sm" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Trap/report behavior parameter (matches ^TRAP_ON_)", + "source_file": "spec/std/isa/param/TRAP_ON_UNIMPLEMENTED_INSTRUCTION.yaml" + }, + { + "name": "UXLEN", + "long_name": "TODO", + "description": "Set of XLENs supported in U-mode. When both 32 and 64 are supported, SXLEN can be changed,\nvia mstatus.UXL, between 32 and 64.", + "defined_by": { + "extensions": [ + "U" + ], + "params": [], + "raw": { + "extension": { + "name": "U" + } + }, + "summary": "ext:U" + }, + "value_type": { + "type": "set", + "details": { + "universe": [ + 32, + 64 + ], + "min_items": 1, + "max_items": 2 + } + }, + "has_requirements": true, + "requirements_summary": "# XLEN in U-mode can never be larger than XLEN in M-mode\nMXLEN == 32 -> !$array_includes?(UXLEN, 64);\n\n# If S-mode supports RV32, then U mode must also support it.\n$array_includes?(SXLEN, 32) -> $arra", + "csr_references": [ + { + "csr": "mstatus", + "field": "UXL", + "idl_key": "type()" + }, + { + "csr": "mstatus", + "field": "UXL", + "idl_key": "reset_value()" + } + ], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Well-known architectural parameter 'UXLEN'", + "source_file": "spec/std/isa/param/UXLEN.yaml" + }, + { + "name": "U_MODE_ENDIANNESS", + "long_name": "TODO", + "description": "Endianness of data in U-mode. Can be one of:\n\n * little: U-mode data is always little endian\n * big: U-mode data is always big endian\n * dynamic: U-mode data can be either little or big endian,\n depending on the CSR field `mstatus.UBE`", + "defined_by": { + "extensions": [ + "U" + ], + "params": [], + "raw": { + "extension": { + "name": "U" + } + }, + "summary": "ext:U" + }, + "value_type": { + "type": "enum", + "details": { + "values": [ + "little", + "big", + "dynamic" + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "mstatus", + "field": "UBE", + "idl_key": "type()" + }, + { + "csr": "mstatus", + "field": "UBE", + "idl_key": "reset_value()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of mstatus.UBE", + "source_file": "spec/std/isa/param/U_MODE_ENDIANNESS.yaml" + }, + { + "name": "VENDOR_ID_BANK", + "long_name": "JEDEC Vendor ID bank, for `mvendorid`.", + "description": "Encodes the number of one-byte continuation codes in the Bank field of `mvendorid`.\n\niN JEDEC’s parlance, the bank number is one greater than the number of continuation codes; hence, the mvendorid Bank field encodes a value that is one less than the JEDEC bank number.", + "defined_by": { + "extensions": [ + "Sm" + ], + "params": [], + "raw": { + "extension": { + "name": "Sm" + } + }, + "summary": "ext:Sm" + }, + "value_type": { + "type": "range", + "details": { + "minimum": 0, + "maximum": 33554431 + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "mvendorid", + "field": "Bank", + "idl_key": "reset_value()" + } + ], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Well-known architectural parameter 'VENDOR_ID_BANK'", + "source_file": "spec/std/isa/param/VENDOR_ID_BANK.yaml" + }, + { + "name": "VENDOR_ID_OFFSET", + "long_name": "JEDEC Vendor ID offset, for `mvendorid`.", + "description": "Encodes the final byte of a JEDEC manufactor ID, discarding the parity bit.", + "defined_by": { + "extensions": [ + "Sm" + ], + "params": [], + "raw": { + "extension": { + "name": "Sm" + } + }, + "summary": "ext:Sm" + }, + "value_type": { + "type": "range", + "details": { + "minimum": 0, + "maximum": 127 + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "mvendorid", + "field": "Offset", + "idl_key": "reset_value()" + } + ], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Well-known architectural parameter 'VENDOR_ID_OFFSET'", + "source_file": "spec/std/isa/param/VENDOR_ID_OFFSET.yaml" + }, + { + "name": "VLEN", + "long_name": "TODO", + "description": "The number of bits in a single vector register.", + "defined_by": { + "extensions": [ + "V" + ], + "params": [], + "raw": { + "extension": { + "name": "V" + } + }, + "summary": "ext:V" + }, + "value_type": { + "type": "value", + "details": { + "base": "integer" + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "vlenb", + "field": "VALUE", + "idl_key": "reset_value()" + }, + { + "csr": "vstart", + "field": "VALUE", + "idl_key": "sw_write(csr_value)" + } + ], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Well-known architectural parameter 'VLEN'", + "source_file": "spec/std/isa/param/VLEN.yaml" + }, + { + "name": "VMID_WIDTH", + "long_name": "TODO", + "description": "Number of bits supported in `hgatp.VMID` (i.e., the supported width of a virtual machine ID).", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "conditional", + "details": { + "branches": [ + { + "condition": "MXLEN == 32", + "inner_type": { + "type": "range", + "details": { + "minimum": 0, + "maximum": 7 + } + } + }, + { + "condition": "MXLEN == 64", + "inner_type": { + "type": "range", + "details": { + "minimum": 0, + "maximum": 14 + } + } + } + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "hgatp", + "field": "VMID", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "hgatp", + "field": "VMID", + "idl_key": "type()" + }, + { + "csr": "hgatp", + "field": "VMID", + "idl_key": "reset_value()" + } + ], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Well-known architectural parameter 'VMID_WIDTH'", + "source_file": "spec/std/isa/param/VMID_WIDTH.yaml" + }, + { + "name": "VSSTAGE_MODE_BARE", + "long_name": "TODO", + "description": "Whether or not writing mode=Bare is supported in the `vsatp` register.", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": true, + "requirements_summary": "# if guest is 32 bit, then one of Bare or SV32_VSMODE_TRANSLATION must be supported\n$array_includes?(VSXLEN, 32) && !SV32_VSMODE_TRANSLATION\n -> VSSTAGE_MODE_BARE;\n\n# if guest is 64 bit, then one of ", + "csr_references": [], + "classification": "NORM_DIRECT", + "classification_confidence": "medium", + "classification_reasoning": "Translation/mode parameter", + "source_file": "spec/std/isa/param/VSSTAGE_MODE_BARE.yaml" + }, + { + "name": "VSTVEC_MODE_DIRECT", + "long_name": "TODO", + "description": "Whether or not `vstvec.MODE` supports Direct (0).", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": true, + "requirements_summary": "At least one vstvec mode must be supported", + "csr_references": [ + { + "csr": "vstvec", + "field": "MODE", + "idl_key": "sw_write(csr_value)" + } + ], + "classification": "NORM_CSR_WARL", + "classification_confidence": "high", + "classification_reasoning": "Referenced in sw_write() of vstvec.MODE", + "source_file": "spec/std/isa/param/VSTVEC_MODE_DIRECT.yaml" + }, + { + "name": "VSTVEC_MODE_VECTORED", + "long_name": "TODO", + "description": "Whether or not `stvec.MODE` supports Vectored (1).", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "binary", + "details": { + "choices": [ + true, + false + ] + } + }, + "has_requirements": true, + "requirements_summary": "At least one vstvec mode must be supported", + "csr_references": [ + { + "csr": "vstvec", + "field": "MODE", + "idl_key": "sw_write(csr_value)" + } + ], + "classification": "NORM_CSR_WARL", + "classification_confidence": "high", + "classification_reasoning": "Referenced in sw_write() of vstvec.MODE", + "source_file": "spec/std/isa/param/VSTVEC_MODE_VECTORED.yaml" + }, + { + "name": "VSXLEN", + "long_name": "TODO", + "description": "Set of XLENs supported in VS-mode. Can be one of:\n\n * [32]: VSXLEN is always 32\n * [64]: VSXLEN is always 64\n * [32, 64]: VSXLEN can be changed (via `hstatus.VSXL`) between 32 and 64", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "set", + "details": { + "universe": [ + 32, + 64 + ], + "min_items": 1, + "max_items": 2 + } + }, + "has_requirements": true, + "requirements_summary": "XLEN in VS-mode can never be larger than XLEN in S-mode\n(and, transitively, cannot be larger than XLEN in M-mode).\n", + "csr_references": [ + { + "csr": "hstatus", + "field": "VSXL", + "idl_key": "sw_write(csr_value)" + }, + { + "csr": "hstatus", + "field": "VSXL", + "idl_key": "type()" + }, + { + "csr": "hstatus", + "field": "VSXL", + "idl_key": "reset_value()" + } + ], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Well-known architectural parameter 'VSXLEN'", + "source_file": "spec/std/isa/param/VSXLEN.yaml" + }, + { + "name": "VS_MODE_ENDIANNESS", + "long_name": "TODO", + "description": "Endianness of data in VS-mode. Can be one of:\n\n * little: VS-mode data is always little endian\n * big: VS-mode data is always big endian\n * dynamic: VS-mode data can be either little or big endian,\n depending on the CSR field `hstatus.VSBE`", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "enum", + "details": { + "values": [ + "little", + "big", + "dynamic" + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "hstatus", + "field": "VSBE", + "idl_key": "type()" + }, + { + "csr": "hstatus", + "field": "VSBE", + "idl_key": "reset_value()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of hstatus.VSBE", + "source_file": "spec/std/isa/param/VS_MODE_ENDIANNESS.yaml" + }, + { + "name": "VUXLEN", + "long_name": "TODO", + "description": "Set of XLENs supported in VU-mode. When both 32 and 64 are supported, VUXLEN can be changed\nvia `vsstatus.UXL`.", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "set", + "details": { + "universe": [ + 32, + 64 + ], + "min_items": 1, + "max_items": 2 + } + }, + "has_requirements": true, + "requirements_summary": "XLEN in VU-mode can never be larger than XLEN in VS-mode\n(and, transitively, cannot be larger than XLEN in S-mode or M-mode).\n", + "csr_references": [ + { + "csr": "vsstatus", + "field": "UXL", + "idl_key": "type()" + }, + { + "csr": "vsstatus", + "field": "UXL", + "idl_key": "reset_value()" + } + ], + "classification": "NORM_DIRECT", + "classification_confidence": "high", + "classification_reasoning": "Well-known architectural parameter 'VUXLEN'", + "source_file": "spec/std/isa/param/VUXLEN.yaml" + }, + { + "name": "VU_MODE_ENDIANNESS", + "long_name": "TODO", + "description": "Endianness of data in VU-mode. Can be one of:\n\n * little: VU-mode data is always little endian\n * big: VU-mode data is always big endian\n * dynamic: VU-mode data can be either little or big endian,\n depending on the CSR field `vsstatus.UBE`", + "defined_by": { + "extensions": [ + "H" + ], + "params": [], + "raw": { + "extension": { + "name": "H" + } + }, + "summary": "ext:H" + }, + "value_type": { + "type": "enum", + "details": { + "values": [ + "little", + "big", + "dynamic" + ] + } + }, + "has_requirements": false, + "requirements_summary": null, + "csr_references": [ + { + "csr": "vsstatus", + "field": "UBE", + "idl_key": "type()" + }, + { + "csr": "vsstatus", + "field": "UBE", + "idl_key": "reset_value()" + } + ], + "classification": "NORM_CSR_RW", + "classification_confidence": "high", + "classification_reasoning": "Controls type (RO/RW) of vsstatus.UBE", + "source_file": "spec/std/isa/param/VU_MODE_ENDIANNESS.yaml" + } + ] +} \ No newline at end of file diff --git a/param_extraction/data/parameters_catalog.csv b/param_extraction/data/parameters_catalog.csv new file mode 100644 index 0000000000..41ff49ce0c --- /dev/null +++ b/param_extraction/data/parameters_catalog.csv @@ -0,0 +1,723 @@ +parameter_name,long_name,classification,classification_confidence,classification_reasoning,value_type,value_details,defined_by_extensions,defined_by_summary,has_requirements,num_csr_references,csr_names,spec_file,spec_line,spec_score,spec_is_normative,spec_in_note,spec_text,description +ARCH_ID_VALUE,Vendor-specific architecture ID in `marchid`,NORM_DIRECT,high,Well-known architectural parameter 'ARCH_ID_VALUE',conditional,2 conditional branches,Sm,ext:Sm AND param:MARCHID_IMPLEMENTED(equal=True),False,1,marchid,machine.adoc,297,8,False,False,==== Machine Architecture ID (`marchid`) Register,"The value of `marchid` +The combination of mvendorid and marchid should uniquely identify the type of hart microarchitecture that is implemented." +ASID_WIDTH,TODO,NORM_DIRECT,high,Well-known architectural parameter 'ASID_WIDTH',conditional,2 conditional branches,S,ext:S,False,0,,supervisor.adoc,1373,5,True,False,"[#norm:sfence-vma-asid_effect]#Likewise, changes to `satp`.ASID take effect immediately.#","Number of implemented ASID bits. Maximum is 16 for XLEN==64, and 9 for XLEN==32" +CACHE_BLOCK_SIZE,TODO,NORM_DIRECT,high,Well-known architectural parameter 'CACHE_BLOCK_SIZE',range,[1..18446744073709551615],"Zicbom, Zicbop, Zicboz",(ext:Zicbom OR ext:Zicbop OR ext:Zicboz),False,0,,cmo.adoc,973,5,True,False,[#norm:cbo-zero_unaligned]#It is not required that _rs1_ is aligned to the size of a cache block.# On,"The observable size of a cache block, in bytes" +CONFIG_PTR_ADDRESS,Physical address in `mconfigptr`,NORM_DIRECT,high,Well-known architectural parameter 'CONFIG_PTR_ADDRESS',conditional,2 conditional branches,Sm,ext:Sm(>= 1.12.0),True,1,mconfigptr,machine.adoc,2136,6,False,False,==== Machine Configuration Pointer (`mconfigptr`) Register,The value returned from `mconfigptr` +COUNTINHIBIT_EN,TODO,NORM_CSR_RW,high,Controls type (RO/RW) of mcountinhibit.CY,bitmask,32-bit mask,Sm,ext:Sm,False,62,mcountinhibit,machine.adoc,1669,13,True,False,[#norm:mcountinhibit_sz_warl_op1]#The counter-inhibit register `mcountinhibit` is a 32-bit,"Indicates which hardware performance monitor counters can be disabled from `mcountinhibit`. + +An unimplemented counter cannot be specified, i.e., if HPM_COUNTER_EN[3] is false, +it would be illegal to set COUNTINHIBIT_EN[3] to true. + +COUNTINHIBIT_EN[1] can never be true, since it corresponds to `mcoun" +DBG_HCONTEXT_WIDTH,TODO,NORM_CSR_WARL,high,Referenced in sw_write() of hcontext.HCONTEXT,range,[0..14],Sdtrig,ext:Sdtrig,False,2,"hcontext, mcontext",smstateen.adoc,287,8,False,False,`hcontext` CSRs provided by the Sdtrig extension. The CONTEXT bit in,Specifies the size of HCONTEXT +DBG_SCONTEXT_WIDTH,TODO,NORM_CSR_WARL,high,Referenced in sw_write() of scontext.DATA,range,[0..32],Sdtrig,ext:Sdtrig,False,1,scontext,hypervisor.adoc,146,6,False,False,"Some standard supervisor CSRs (`senvcfg`, `scounteren`, and `scontext`,",Specifies the size of SCONTEXT +DCSR_MPRVEN_TYPE,TODO,NORM_CSR_RW,high,Controls type (RO/RW) of dcsr.MPRVEN,enum,"values: ['read-only-0', 'read-only-1', 'rw']",Sdtrig,ext:Sdtrig,False,2,dcsr,priv-cfi.adoc,87,4,False,False,"transition to Debug Mode, a `pelp` bit is defined in the `dcsr` register.#","Implementation of dcsr.MPRVEN is optional. +It may be tied to either 0 or 1. + +Behavior of the dcsr.MPRVEN bit: + * 'read-only-0': tied to 0 + * 'read-only-1': tied to 1 + * 'rw': read-write" +DCSR_STEPIE_TYPE,TODO,NORM_CSR_RW,high,Controls type (RO/RW) of dcsr.STEPIE,enum,"values: ['read-only-0', 'read-only-1', 'rw']",Sdtrig,ext:Sdtrig,False,2,dcsr,priv-cfi.adoc,87,4,False,False,"transition to Debug Mode, a `pelp` bit is defined in the `dcsr` register.#","Implementation of dcsr.STEPIE is optional. +It may be tied to either 0 or 1. + +Behavior of the dcsr.STEPIE bit: + * 'read-only-0': tied to 0 + * 'read-only-1': tied to 1 + * 'rw': read-write" +DCSR_STOPCOUNT_TYPE,TODO,NORM_CSR_RW,high,Controls type (RO/RW) of dcsr.STOPCOUNT,enum,"values: ['read-only-0', 'read-only-1', 'rw']",Sdtrig,ext:Sdtrig,False,2,dcsr,priv-cfi.adoc,87,4,False,False,"transition to Debug Mode, a `pelp` bit is defined in the `dcsr` register.#","Implementation of dcsr.STOPCOUNT is optional. +It may be tied to either 0 or 1. + +Behavior of the dcsr.STOPCOUNT bit: + * 'read-only-0': tied to 0 + * 'read-only-1': tied to 1 + * 'rw': read-write" +DCSR_STOPTIME_TYPE,TODO,NORM_CSR_RW,high,Controls type (RO/RW) of dcsr.STOPTIME,enum,"values: ['read-only-0', 'read-only-1', 'rw']",Sdtrig,ext:Sdtrig,False,2,dcsr,priv-cfi.adoc,87,4,False,False,"transition to Debug Mode, a `pelp` bit is defined in the `dcsr` register.#","Implementation of dcsr.STOPTIME is optional. +It may be tied to either 0 or 1. + +Behavior of the dcsr.STOPTIME bit: + * 'read-only-0': tied to 0 + * 'read-only-1': tied to 1 + * 'rw': read-write" +ELEN,TODO,NORM_DIRECT,high,Well-known architectural parameter 'ELEN',value,{'base': 'integer'},V,ext:V,False,0,,v-st-ext.adoc,24,9,True,False,". [#norm:vlen_param]#The number of bits in a single vector register, _VLEN_ {ge} ELEN, which must be a power of 2, and must be no greater than 2^16^.#",The maximum size in bits of a vector element that any operation can produce or consume. +FOLLOW_VTYPE_RESET_RECOMMENDATION,TODO,NORM_DIRECT,medium,Implementation behavioral choice parameter,binary,"choices: [True, False]",V,ext:V,False,6,"vl, vtype",v-st-ext.adoc,169,14,True,False,"NOTE: [#norm:vill_implicit_encoding_param]#A small implementation supporting ELEN=32 requires only seven bits of state in `vtype`: two bits for `ma` and `ta`, two bits for `vsew[1:0]` and three bits f","It is recommended that at reset, vtype.vill is set, the remaining bits in vtype are zero, and vl is set to zero. +If this parameter is set to true, this recommendation is followed. If it is false, at reset the respective fields +will be UNDEFINED_LEGAL." +FORCE_UPGRADE_CBO_INVAL_TO_FLUSH,TODO,NORM_CSR_WARL,high,Referenced in sw_write() of menvcfg.CBIE,binary,"choices: [True, False]",Zicbom,ext:Zicbom,False,1,menvcfg,supervisor.adoc,913,20,False,False,"implemented, `CBIE` is read-only zero. Execution of `CBO.INVAL` in U-mode is","When true, an implementation prohibits setting `menvcfg.CBIE` == `11` such that all `cbo.inval` +instructions either trap (when `menvcfg.CBIE` == '00') or flush (when `menvcfg.CBIE` == '01'). + +When false, an implementation allows a true INVAL operation for `cbo.inval`, and thus supports +the setting `" +GSTAGE_MODE_BARE,TODO,NORM_CSR_WARL,high,Referenced in sw_write() of hgatp.MODE,binary,"choices: [True, False]",H,ext:H,True,1,hgatp,hypervisor.adoc,1075,11,False,False,"is for `satp`. Instead, the fields of `hgatp` are *WARL* in the normal way,",Whether or not writing mode=Bare is supported in the `hgatp` register. +HCONTEXT_AVAILABLE,TODO,NORM_DIRECT,high,Feature/CSR existence parameter ('AVAILABLE' suffix),binary,"choices: [True, False]",Sdtrig,ext:Sdtrig,True,2,hcontext,smstateen.adoc,287,8,False,False,`hcontext` CSRs provided by the Sdtrig extension. The CONTEXT bit in,Specifies if HCONTEXT is available +HCOUNTENABLE_EN,TODO,NORM_CSR_RW,high,Controls type (RO/RW) of hcounteren.CY,bitmask,32-bit mask,H,ext:H,False,64,hcounteren,hypervisor.adoc,857,12,False,False,"When the CY, TM, IR, or HPM__n__ bit in the `hcounteren` register is","Indicates which counters can delegated via `hcounteren` + +An unimplemented counter cannot be specified, i.e., if +HPM_COUNTER_EN[3] is false, it would be illegal to set +HCOUNTENABLE_EN[3] to true. + +HCOUNTENABLE_EN[0:2] must all be false if `Zicntr` is not implemented. +HCOUNTENABLE_EN[3:31] must all be" +HPM_COUNTER_EN,TODO,NORM_CSR_RW,high,Controls type (RO/RW) of scountovf.OF3,bitmask,32-bit mask,Smhpm,ext:Smhpm,False,1044,"mhpmcounter10, mhpmcounter10h, mhpmcounter11, mhpmcounter11h, mhpmcounter12, mhpmcounter12h, mhpmcounter13, mhpmcounter13h, mhpmcounter14, mhpmcounter14h, mhpmcounter15, mhpmcounter15h, mhpmcounter16, mhpmcounter16h, mhpmcounter17, mhpmcounter17h, mhpmcounter18, mhpmcounter18h, mhpmcounter19, mhpmcounter19h, mhpmcounter20, mhpmcounter20h, mhpmcounter21, mhpmcounter21h, mhpmcounter22, mhpmcounter22h, mhpmcounter23, mhpmcounter23h, mhpmcounter24, mhpmcounter24h, mhpmcounter25, mhpmcounter25h, mhpmcounter26, mhpmcounter26h, mhpmcounter27, mhpmcounter27h, mhpmcounter28, mhpmcounter28h, mhpmcounter29, mhpmcounter29h, mhpmcounter3, mhpmcounter30, mhpmcounter30h, mhpmcounter31, mhpmcounter31h, mhpmcounter3h, mhpmcounter4, mhpmcounter4h, mhpmcounter5, mhpmcounter5h, mhpmcounter6, mhpmcounter6h, mhpmcounter7, mhpmcounter7h, mhpmcounter8, mhpmcounter8h, mhpmcounter9, mhpmcounter9h, mhpmevent10, mhpmevent10h, mhpmevent11, mhpmevent11h, mhpmevent12, mhpmevent12h, mhpmevent13, mhpmevent13h, mhpmevent14, mhpmevent14h, mhpmevent15, mhpmevent15h, mhpmevent16, mhpmevent16h, mhpmevent17, mhpmevent17h, mhpmevent18, mhpmevent18h, mhpmevent19, mhpmevent19h, mhpmevent20, mhpmevent20h, mhpmevent21, mhpmevent21h, mhpmevent22, mhpmevent22h, mhpmevent23, mhpmevent23h, mhpmevent24, mhpmevent24h, mhpmevent25, mhpmevent25h, mhpmevent26, mhpmevent26h, mhpmevent27, mhpmevent27h, mhpmevent28, mhpmevent28h, mhpmevent29, mhpmevent29h, mhpmevent3, mhpmevent30, mhpmevent30h, mhpmevent31, mhpmevent31h, mhpmevent3h, mhpmevent4, mhpmevent4h, mhpmevent5, mhpmevent5h, mhpmevent6, mhpmevent6h, mhpmevent7, mhpmevent7h, mhpmevent8, mhpmevent8h, mhpmevent9, mhpmevent9h, scountovf",machine.adoc,1615,8,True,False,"[#norm:mcounteren_clr_ill_inst_exc]#When the CY, TM, IR, or HPM__n__ bit in the `mcounteren` register is","List of HPM counters that are enabled. +There is one entry for each hpmcounter. + +The first three entries *must* be false (as they correspond to CY, IR, TM in, _e.g._ `mhmpcountinhibit`) +Index 3 in HPM_COUNTER_EN corresponds to hpmcounter3. +Index 31 in HPM_COUNTER_EN corresponds to hpmcounter31." +HPM_EVENTS,TODO,NORM_CSR_WARL,high,Referenced in sw_write() of mhpmevent14.EVENT,set,set of integer,Smhpm,ext:Smhpm,False,29,"mhpmevent10, mhpmevent11, mhpmevent12, mhpmevent13, mhpmevent14, mhpmevent15, mhpmevent16, mhpmevent17, mhpmevent18, mhpmevent19, mhpmevent20, mhpmevent21, mhpmevent22, mhpmevent23, mhpmevent24, mhpmevent25, mhpmevent26, mhpmevent27, mhpmevent28, mhpmevent29, mhpmevent3, mhpmevent30, mhpmevent31, mhpmevent4, mhpmevent5, mhpmevent6, mhpmevent7, mhpmevent8, mhpmevent9",machine.adoc,1581,8,False,False,"`mhpmevent3`-`mhpmevent31`, are 64-bit *WARL* registers that control which",List of defined event numbers that can be written into hpmeventN +HSTATEEN_AIA_TYPE,TODO,NORM_CSR_RW,low,CSR field type control parameter for 'hstateen' (determines RO/RW behavior),enum,"values: ['rw', 'read-only-0', 'read-only-1']","H, Ssaia, Ssstateen",ext:Ssaia AND ext:H AND ext:Ssstateen,True,0,,,,0,,,,"Behavior of the hstateen0.AIA bit: + + * 'rw': read-write + * 'read-only-0': read-only, fixed to 0 + * 'read-only-1': read-only, fixed to 1" +HSTATEEN_CONTEXT_TYPE,TODO,NORM_CSR_RW,low,CSR field type control parameter for 'hstateen' (determines RO/RW behavior),enum,"values: ['rw', 'read-only-0', 'read-only-1']","H, Sdtrig, Ssstateen",ext:Sdtrig AND ext:H AND ext:Ssstateen,True,0,,smctr.adoc,652,5,True,False,"[#norm:ccounter_reset]#The CtrCycleCounter is reset on writes to `__x__ctrctl`, and on execution of SCTRCLR, to ensure that any accumulated cycle counts do not persist across a context switch.#","Behavior of the hstateen0.CONTEXT bit: + + * 'rw': read-write + * 'read-only-0': read-only, fixed to 0 + * 'read-only-1': read-only, fixed to 1" +HSTATEEN_CSRIND_TYPE,TODO,NORM_CSR_RW,low,CSR field type control parameter for 'hstateen' (determines RO/RW behavior),enum,"values: ['rw', 'read-only-0', 'read-only-1']","H, Sscsrind, Ssstateen",ext:Sscsrind AND ext:H AND ext:Ssstateen,True,0,,smstateen.adoc,191,3,False,False,"{bits: 1, name: 'CSRIND'},","Behavior of the hstateen0.CSRIND bit: + + * 'rw': read-write + * 'read-only-0': read-only, fixed to 0 + * 'read-only-1': read-only, fixed to 1" +HSTATEEN_ENVCFG_TYPE,TODO,NORM_CSR_RW,low,CSR field type control parameter for 'hstateen' (determines RO/RW behavior),enum,"values: ['rw', 'read-only-0', 'read-only-1']","H, Ssstateen",ext:H(~> 1.0) AND ext:Ssstateen(~> 1.0),True,0,,priv-cfi.adoc,134,3,False,False,*__x__*`envcfg.SSE` fields. The conditions are specified as follows:,"Behavior of the hstateen0.ENVCFG bit: + + * 'rw': read-write + * 'read-only-0': read-only, fixed to 0 + * 'read-only-1': read-only, fixed to 1" +HSTATEEN_IMSIC_TYPE,TODO,NORM_CSR_RW,low,CSR field type control parameter for 'hstateen' (determines RO/RW behavior),enum,"values: ['rw', 'read-only-0', 'read-only-1']","H, Ssaia, Ssstateen",ext:Ssaia AND ext:H AND ext:Ssstateen,True,0,,smstateen.adoc,189,3,False,False,"{bits: 1, name: 'IMSIC'},","Behavior of the hstateen0.IMSIC bit: + + * 'rw': read-write + * 'read-only-0': read-only, fixed to 0 + * 'read-only-1': read-only, fixed to 1" +HSTATEEN_JVT_TYPE,TODO,NORM_CSR_RW,low,CSR field type control parameter for 'hstateen' (determines RO/RW behavior),enum,"values: ['rw', 'read-only-0', 'read-only-1']","H, Ssstateen, Zcmt",ext:Zcmt AND ext:H AND ext:Ssstateen,True,0,,zc.adoc,2341,4,True,False,"[#norm:Zcmt_entry_sz]#The base of the table is in the jvt CSR (see <>), each table entry is XLEN bits.#","Behavior of the hstateen0.JVT bit: + + * 'rw': read-write + * 'read-only-0': read-only, fixed to 0 + * 'read-only-1': read-only, fixed to 1" +HW_MSTATUS_FS_DIRTY_UPDATE,TODO,SW_RULE,medium,Hardware update behavior (HW_ prefix) — software-deterministic with correct fencing,enum,"values: ['never', 'precise', 'imprecise']",F,ext:F,False,1,mstatus,v-st-ext.adoc,3313,26,True,False,[#norm:mstatus-FS_off_V_fp_ill]#If the floating-point unit status field `mstatus.FS` is `Off` then any,"Indicates whether or not hardware will write to `mstatus.FS` + +Values are: +[separator=""!""] +!=== +h! never ! Hardware never writes `mstatus.FS` +h! precise ! Hardware writes `mstatus.FS` to the Dirty (3) state precisely when F registers are modified +h! imprecise ! Hardware writes `mstatus.FS` imprecis" +HW_MSTATUS_VS_DIRTY_UPDATE,TODO,SW_RULE,medium,Hardware update behavior (HW_ prefix) — software-deterministic with correct fencing,enum,"values: ['never', 'precise', 'imprecise']",V,ext:V,False,1,mstatus,v-st-ext.adoc,107,27,False,False,"If `mstatus.VS` is Dirty, `mstatus.SD` is 1;","Indicates whether or not hardware will write to `mstatus.VS` + +Values are: +[separator=""!""] +!=== +h! never ! Hardware never writes `mstatus.VS` +h! precise ! Hardware writes `mstatus.VS` to the Dirty (3) state precisely when V registers are modified +h! imprecise ! Hardware writes `mstatus.VS` imprecis" +IGNORE_INVALID_VSATP_MODE_WRITES_WHEN_V_EQ_ZERO,TODO,NORM_CSR_WARL,high,Referenced in sw_write() of vsatp.MODE,binary,"choices: [True, False]",H,ext:H,False,3,vsatp,hypervisor.adoc,1416,9,False,False,"ignored as it is for `satp`, or the fields of `vsatp` are treated as *WARL* in","Whether writes from M-mode, U-mode, or S-mode to vsatp with an illegal mode setting are +ignored (as they are with satp), or if they are treated as WARL, leading to undpredictable +behavior." +IMP_ID_VALUE,Vendor-specific implementation ID in `mimpid`,NORM_DIRECT,high,Well-known architectural parameter 'IMP_ID_VALUE',conditional,2 conditional branches,Sm,ext:Sm AND param:MIMPID_IMPLEMENTED(equal=True),False,1,mimpid,machine.adoc,335,5,False,False,==== Machine Implementation ID (`mimpid`) Register,A unique encoding of the version of the processor implementation. +JVT_BASE_MASK,Mask representing the implemented bits of jvt.BASE,NORM_CSR_WARL,high,Referenced in sw_write() of jvt.BASE,range,[64..576460752303423487],Zcmt,ext:Zcmt AND param:JVT_BASE_TYPE(equal=mask),True,1,jvt,c-st-ext.adoc,466,8,True,False,"instructions. [#norm:Zca_offsets_mul2]#As with base RVI instructions, the offsets of all RVC","Mask representing the implemented bits of jvt.BASE. +Includes the implicitly-zero bits of jvt.BASE, so JVT_BASE_MASK[5:0] must always be 0." +JVT_BASE_TYPE,Type of the jvt.BASE CSR field,NORM_CSR_WARL,high,Referenced in sw_write() of jvt.BASE,binary,"choices: ['mask', 'custom']",Zcmt,ext:Zcmt,False,1,jvt,c-st-ext.adoc,466,10,True,False,"instructions. [#norm:Zca_offsets_mul2]#As with base RVI instructions, the offsets of all RVC","Type of the jvt.BASE CSR field. One of: + +* mask: jvt.BASE contains one or more implemented bits, which are indicated by JVT_BASE_MASK. +* custom: Custom behavior. Will cause hart to enter 'unpredictable' state on a write to jvt.BASE." +JVT_READ_ONLY,Whether or not the JVT CSR is read-only,NORM_CSR_WARL,high,Referenced in sw_write() of jvt.MODE,binary,"choices: [True, False]",Zcmt,ext:Zcmt,False,3,jvt,zc.adoc,2341,6,True,False,"[#norm:Zcmt_entry_sz]#The base of the table is in the jvt CSR (see <>), each table entry is XLEN bits.#","If Zcmt is implemented, JVT is implemented, but can contain a read-only value" +LRSC_FAIL_ON_NON_EXACT_LRSC,TODO,NORM_DIRECT,medium,Load-reserved/store-conditional behavior parameter,binary,"choices: [True, False]",Zalrsc,ext:Zalrsc,False,0,,a-st-ext.adoc,169,3,False,False,The SC must fail if the address is not within the reservation set of the,"Whether or not a Store Conditional fails if its physical address and size do not +exactly match the physical address and size of the last Load Reserved in program order +(independent of whether or not the SC is in the current reservation set)" +LRSC_FAIL_ON_VA_SYNONYM,TODO,NORM_DIRECT,medium,Load-reserved/store-conditional behavior parameter,binary,"choices: [True, False]",Zalrsc,ext:Zalrsc,False,0,,a-st-ext.adoc,76,7,False,False,SC.W instruction invalidates any reservation held by this hart. LR.D and,"Whether or not an `sc.l`/`sc.d` will fail if its VA does not match the VA of the prior +`lr.l`/`lr.d`, even if the physical address of the SC and LR are the same" +LRSC_MISALIGNED_BEHAVIOR,TODO,NORM_DIRECT,medium,Load-reserved/store-conditional behavior parameter,enum,"values: ['always raise misaligned exception', 'always raise access fault', 'custom']",Zalrsc,ext:Zalrsc,False,0,,a-st-ext.adoc,59,12,False,False,are performed with the load-reserved (LR) and store-conditional (SC),"What to do when an LR/SC address is misaligned and MISALIGNED_AMO == false. + + * 'always raise misaligned exception': self-explainitory + * 'always raise access fault': self-explainitory + * 'custom': Custom behavior; misaligned LR/SC may sometimes raise a misaligned exception and sometimes raise a " +LRSC_RESERVATION_STRATEGY,TODO,NORM_DIRECT,medium,Load-reserved/store-conditional behavior parameter,enum,"values: ['reserve naturally-aligned 64-byte region', 'reserve naturally-aligned 128-byte region', 'reserve exactly enough to cover the access', 'custom']",Zalrsc,ext:Zalrsc,False,0,,a-st-ext.adoc,76,19,False,False,SC.W instruction invalidates any reservation held by this hart. LR.D and,"Strategy used to handle reservation sets. + + * ""reserve naturally-aligned 64-byte region"": Always reserve the 64-byte block containing the LR/SC address + * ""reserve naturally-aligned 128-byte region"": Always reserve the 128-byte block containing the LR/SC address + * ""reserve exactly enough to cove" +MARCHID_IMPLEMENTED,Whether or not the `marchid` CSR is implemented.,NORM_DIRECT,high,Feature/CSR existence parameter ('IMPLEMENTED' suffix),binary,"choices: [True, False]",Sm,ext:Sm,False,0,,machine.adoc,303,10,False,False,The combination of `mvendorid` and `marchid` should uniquely identify the type of hart microarchitecture that is implemented.,"* false: `marchid` is not implemented, and must be read-only-0 +* true: `marchid` is implemented, and the value is determined by `ARCH_ID_VALUE`" +MCID_WIDTH,TODO,NORM_CSR_WARL,high,Referenced in sw_write() of srmcfg.MCID,range,[1..12],Ssqosid,ext:Ssqosid,False,1,srmcfg,supervisor.adoc,2586,8,False,False,The `RCID` and `MCID` configured in the `srmcfg` CSR apply to all privilege,"Number of bits used for the Monitoring Counter ID field (MCID). +Default is 12." +MCONTEXT_AVAILABLE,TODO,NORM_DIRECT,high,Feature/CSR existence parameter ('AVAILABLE' suffix),binary,"choices: [True, False]",Sdtrig,ext:Sdtrig,False,2,mcontext,priv-csrs.adoc,1019,6,False,False,`mcontext`,Specifies if MCONTEXT is available +MCOUNTENABLE_EN,TODO,NORM_CSR_RW,high,Controls type (RO/RW) of mcounteren.CY,bitmask,32-bit mask,U,ext:U,True,62,mcounteren,machine.adoc,1656,13,True,False,"[#norm:mcounteren_flds_mandatory_warl]#In harts with U-mode, the `mcounteren` must be","Indicates which counters can be delegated via `mcounteren`. + +An unimplemented counter cannot be specified, i.e., if +HPM_COUNTER_EN[3] is false, it would be illegal to set +MCOUNTENABLE_EN[3] to true. + +MCOUNTENABLE_EN[0:2] must all be false if `Zicntr` is not implemented. +MCOUNTENABLE_EN[3:31] must al" +MIMPID_IMPLEMENTED,Whether or not the `mimpid` CSR is implemented.,NORM_DIRECT,high,Feature/CSR existence parameter ('IMPLEMENTED' suffix),binary,"choices: [True, False]",Sm,ext:Sm,False,0,,machine.adoc,337,9,True,False,[#norm:mimpid_op]#The `mimpid` CSR provides a unique encoding of the version of the,"* false: `mimpid` is not implemented, and must be read-only-0 +* true: `mimpid` is implemented, and the value is determined by `IMP_ID_VALUE`" +MISALIGNED_AMO,TODO,NORM_DIRECT,medium,Misaligned access behavior parameter,binary,"choices: [True, False]",Zaamo,ext:Zaamo,False,0,,machine.adoc,1976,5,True,False,[#norm:mcause_exccode_pri2]#Load/store/AMO address-misaligned exceptions may have either higher or,whether or not the implementation supports misaligned atomics in main memory +MISALIGNED_LDST,Support for misaligned loads and stores to main memory.,NORM_DIRECT,medium,Misaligned access behavior parameter,binary,"choices: [True, False]",Sm,ext:Sm,False,0,,machine.adoc,1976,5,True,False,[#norm:mcause_exccode_pri2]#Load/store/AMO address-misaligned exceptions may have either higher or,"Does the implementation perform non-atomic misaligned loads and stores to main memory +(does *not* affect misaligned support to device memory)? +If not, the implementation always throws a misaligned exception." +MISALIGNED_LDST_EXCEPTION_PRIORITY,"The relative priority of a load/store/AMO exception vs. load/store/AMO page-fault +or access-fault exceptions.",NORM_DIRECT,medium,Misaligned access behavior parameter,binary,"choices: ['low', 'high']",Sm,ext:Sm,True,0,,rv32.adoc,139,6,True,False,[#norm:taken_cti_misaligned_exc]#An instruction-address-misaligned exception is generated on a taken branch,"The relative priority of a load/store/AMO exception vs. load/store/AMO page-fault +or access-fault exceptions. + +May be one of: + +[separator=""!""] +!=== +! low ! Misaligned load/store/AMO exceptions are always lower priority than load/store/AMO page-fault and access-fault exceptions. +! high ! Misaligned " +MISALIGNED_MAX_ATOMICITY_GRANULE_SIZE,"The maximum granule size, in bytes, that the hart can atomically perform a +misaligned load/store/AMO without raising a Misaligned exception",NORM_DIRECT,medium,Misaligned access behavior parameter,enum,13 values,Sm,ext:Sm AND param:MISALIGNED_LDST(equal=True),True,0,,a-st-ext.adoc,385,7,False,False,"The misaligned atomicity granule PMA, defined in Volume II of this manual,","When MISALIGNED_MAX_ATOMICITY_GRANULE_SIZE is 0, the hart +cannot atomically perform a misaligned load/store/AMO. When a power of two, the hart can +atomically load/store/AMO a misaligned access that is fully contained in a +MISALIGNED_MAX_ATOMICITY_GRANULE_SIZE-aligned region. + +[NOTE] +Even if the hart" +MISALIGNED_SPLIT_STRATEGY,"The *order* the implementation appears +to process a non-atomic misaligned load/store, which determines how/which +exceptions will be reported.",NORM_DIRECT,medium,Misaligned access behavior parameter,binary,"choices: ['sequential_bytes', 'custom']",Sm,ext:Sm AND param:MISALIGNED_LDST(equal=True),False,0,,machine.adoc,1976,5,True,False,[#norm:mcause_exccode_pri2]#Load/store/AMO address-misaligned exceptions may have either higher or,"Options: + + * sequential_bytes: The load/store appears to be broken into byte-sized accesses that processed sequentially from smallest address to largest address + * custom: Something else. Will result in a call to unpredictable() in the execution" +MISA_CSR_IMPLEMENTED,Whether or not the `misa` CSR is implemented,NORM_DIRECT,high,Feature/CSR existence parameter ('IMPLEMENTED' suffix),binary,"choices: [True, False]",Sm,ext:Sm,False,3,mstatus,machine.adoc,23,12,True,False,"but [#norm:misa_csr_implemented]#a value of zero can be returned to indicate the `misa` register has not been implemented#, requiring that CPU capabilities be determined through a separate non-standar","Options: + + true:: + The `misa` CSR returns a non-zero value. + + false:: + The `misa` CSR is read-only-0." +MSTATEEN_AIA_TYPE,TODO,NORM_CSR_RW,low,CSR field type control parameter for 'mstateen' (determines RO/RW behavior),enum,"values: ['rw', 'read-only-0', 'read-only-1']","Smstateen, Ssaia",ext:Ssaia AND ext:Smstateen(~> 1.0),False,0,,,,0,,,,"Behavior of the mstateen0.AIA bit: + + * 'rw': read-write + * 'read-only-0': read-only, fixed to 0 + * 'read-only-1': read-only, fixed to 1" +MSTATEEN_CONTEXT_TYPE,TODO,NORM_CSR_RW,low,CSR field type control parameter for 'mstateen' (determines RO/RW behavior),enum,"values: ['rw', 'read-only-0', 'read-only-1']","Sdtrig, Smstateen",ext:Sdtrig AND ext:Smstateen,False,0,,smctr.adoc,652,5,True,False,"[#norm:ccounter_reset]#The CtrCycleCounter is reset on writes to `__x__ctrctl`, and on execution of SCTRCLR, to ensure that any accumulated cycle counts do not persist across a context switch.#","Behavior of the mstateen0.CONTEXT bit: + + * 'rw': read-write + * 'read-only-0': read-only, fixed to 0 + * 'read-only-1': read-only, fixed to 1" +MSTATEEN_CSRIND_TYPE,TODO,NORM_CSR_RW,low,CSR field type control parameter for 'mstateen' (determines RO/RW behavior),enum,"values: ['rw', 'read-only-0', 'read-only-1']","Smstateen, Sscsrind",ext:Sscsrind AND ext:Smstateen,False,0,,smstateen.adoc,191,3,False,False,"{bits: 1, name: 'CSRIND'},","Behavior of the mstateen0.CSRIND bit: + + * 'rw': read-write + * 'read-only-0': read-only, fixed to 0 + * 'read-only-1': read-only, fixed to 1" +MSTATEEN_ENVCFG_TYPE,TODO,NORM_CSR_RW,low,CSR field type control parameter for 'mstateen' (determines RO/RW behavior),enum,"values: ['rw', 'read-only-0', 'read-only-1']","S, Smstateen",ext:S AND ext:Smstateen,False,0,,priv-cfi.adoc,134,3,False,False,*__x__*`envcfg.SSE` fields. The conditions are specified as follows:,"Behavior of the mstateen0.ENVCFG bit: + + * 'rw': read-write + * 'read-only-0': read-only, fixed to 0 + * 'read-only-1': read-only, fixed to 1" +MSTATEEN_IMSIC_TYPE,TODO,NORM_CSR_RW,low,CSR field type control parameter for 'mstateen' (determines RO/RW behavior),enum,"values: ['rw', 'read-only-0', 'read-only-1']","Smstateen, Ssaia",ext:Ssaia AND ext:Smstateen(~> 1.0),False,0,,smstateen.adoc,189,3,False,False,"{bits: 1, name: 'IMSIC'},","Behavior of the mstateen0.IMSIC bit: + + * 'rw': read-write + * 'read-only-0': read-only, fixed to 0 + * 'read-only-1': read-only, fixed to 1" +MSTATEEN_JVT_TYPE,TODO,NORM_CSR_RW,low,CSR field type control parameter for 'mstateen' (determines RO/RW behavior),enum,"values: ['rw', 'read-only-0', 'read-only-1']","Smstateen, Zcmt",ext:Zcmt AND ext:Smstateen(~> 1.0),False,0,,zc.adoc,2341,4,True,False,"[#norm:Zcmt_entry_sz]#The base of the table is in the jvt CSR (see <>), each table entry is XLEN bits.#","Behavior of the mstateen0.JVT bit: + + * 'rw': read-write + * 'read-only-0': read-only, fixed to 0 + * 'read-only-1': read-only, fixed to 1" +MSTATUS_FS_LEGAL_VALUES,TODO,NORM_CSR_WARL,high,Referenced in sw_write() of mstatus.FS,set,"subset of [0, 1, 2, 3]","F, S",(ext:F OR ext:S),True,3,mstatus,machine.adoc,679,11,True,False,"[#norm:mstatus_mstatush_xbe_warl]#The MBE, SBE, and UBE bits in `mstatus` and `mstatush` are *WARL* fields# that",The set of values that mstatus.FS supports. +MSTATUS_TVM_IMPLEMENTED,TODO,NORM_DIRECT,high,Feature/CSR existence parameter ('IMPLEMENTED' suffix),binary,"choices: [True, False]",S,ext:S,False,2,mstatus,hypervisor.adoc,999,12,True,False,"addresses. [#norm:hgatp_tvm_illegal]#When `mstatus`.TVM=1, attempts to read or write `hgatp` while","Whether or not mstatus.TVM is implemented. + +When not implemented mstatus.TVM will be read-only-zero." +MSTATUS_VS_LEGAL_VALUES,TODO,NORM_CSR_WARL,high,Referenced in sw_write() of mstatus.VS,set,"subset of [0, 1, 2, 3]","S, V",(ext:V OR ext:S),True,3,mstatus,machine.adoc,679,11,True,False,"[#norm:mstatus_mstatush_xbe_warl]#The MBE, SBE, and UBE bits in `mstatus` and `mstatush` are *WARL* fields# that",The set of values that mstatus.VS will accept from a software write. +MTVAL_WIDTH,Width of the `mtval` CSR,NORM_DIRECT,medium,Trap value reporting parameter,conditional,2 conditional branches,Sm,ext:Sm,True,0,,hypervisor.adoc,25,6,True,False,"registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and","The number of implemented bits in the `mtval` CSR. +This is the CSR that may be written when a trap is taken into M-mode with exception-specific information to +assist software in handling the trap (e.g., address associated with exception). + +Must be greater than or equal to _max_(`PHYS_ADDR_WIDTH`, `V" +MTVEC_ACCESS,Acess type of the `mtvec` CSR (read-only or read-write).,NORM_CSR_RW,high,Controls type (RO/RW) of mtvec.BASE,binary,"choices: ['ro', 'rw']",Sm,ext:Sm,False,2,mtvec,machine.adoc,1209,17,True,False,[#norm:mtvec_sz_warl_acc]#The `mtvec` register is an MXLEN-bit *WARL* read/write register that holds,"Options: + + ro:: + `mtvec` is read-only. + + rw:: + `mtvec` is read-write, but may not accept all values." +MTVEC_BASE_ALIGNMENT_DIRECT,Minumum alignment of `mtvec.BASE` when `mtvec.MODE` is 0 (direct),NORM_CSR_WARL,low,"Name pattern suggests CSR 'mtvec' association, but no IDL cross-reference found",conditional,2 conditional branches,Sm,"ext:Sm AND {'param': {'allOf': [{'name': 'MTVEC_MODES', 'includes': 0, 'reason': 'Only rele",False,0,,machine.adoc,1209,6,True,False,[#norm:mtvec_sz_warl_acc]#The `mtvec` register is an MXLEN-bit *WARL* read/write register that holds,"Minimum alignment of the base pointer. Because `mtvec` excludes the two least-significant bits of +the base, the minimum alignment cannot be less than 4." +MTVEC_BASE_ALIGNMENT_VECTORED,Minumum alignment of `mtvec.BASE` when `mtvec.MODE` is 1 (vectored),NORM_CSR_WARL,low,"Name pattern suggests CSR 'mtvec' association, but no IDL cross-reference found",conditional,2 conditional branches,Sm,"ext:Sm AND {'param': {'allOf': [{'name': 'MTVEC_MODES', 'includes': 1, 'reason': 'Only rele",False,0,,priv-preface.adoc,540,7,False,False,* Optional vectored interrupt support has been added to the `mtvec` and,"Because `mtvec` excludes the two least-significant bits of +the base, the minimum alignment cannot be less than 4." +MTVEC_ILLEGAL_WRITE_BEHAVIOR,What happens when `mtvec` is written with an illegal value,NORM_CSR_WARL,high,Referenced in sw_write() of mtvec.BASE,binary,"choices: ['retain', 'custom']",Sm,ext:Sm,False,2,mtvec,machine.adoc,1209,18,True,False,[#norm:mtvec_sz_warl_acc]#The `mtvec` register is an MXLEN-bit *WARL* read/write register that holds,"Options: + + retain:: + When either `mtvec.MODE` or `mtvec.BASE` is illegal, `mtvec` will retain its current value + + custom:: + When either `mtvec.MODE` or `mtvec.BASE` is illegal, `mtvec` will obtain an unpredictable value + +Other values may be added over time once other common behaviors are ide" +MTVEC_MODES,Modes supported by `mtvec.MODE`,NORM_CSR_WARL,high,Referenced in sw_write() of mtvec.BASE,set,"subset of [0, 1]",Sm,ext:Sm,True,4,mtvec,machine.adoc,1255,18,False,False,machine mode cause the `pc` to be set to the address in the BASE field.#,"Options: + + 0:: + Direct; All traps set `pc` to `mtvec.BASE` + 1:: + Vectored; Asynchronous interrupts set `pc` to `mtvec.BASE` + 4 x cause. + +If only one mode is given, `mtvec.MODE` is assumed to be read-only with that value. +Otherwise, `mtvec.MODE` is read-write." +MUTABLE_MISA_A,TODO,NORM_CSR_RW,high,Controls type (RO/RW) of misa.A,binary,"choices: [True, False]",A,ext:A,False,2,misa,machine.adoc,21,16,True,False,[#norm:misa_acc]#The `misa` CSR is a *WARL* read-write register# reporting the ISA supported by the hart.,"When the `A` extensions is supported, indicates whether or not +the extension can be disabled in the `misa.A` bit." +MUTABLE_MISA_B,TODO,NORM_CSR_RW,high,Controls type (RO/RW) of misa.B,binary,"choices: [True, False]",B,ext:B,False,1,misa,machine.adoc,21,11,True,False,[#norm:misa_acc]#The `misa` CSR is a *WARL* read-write register# reporting the ISA supported by the hart.,Indicates whether or not the `B` extension can be disabled with the `misa.B` bit. +MUTABLE_MISA_C,TODO,NORM_CSR_RW,high,Controls type (RO/RW) of misa.C,binary,"choices: [True, False]",C,ext:C,False,1,misa,machine.adoc,21,11,True,False,[#norm:misa_acc]#The `misa` CSR is a *WARL* read-write register# reporting the ISA supported by the hart.,Indicates whether or not the `C` extension can be disabled with the `misa.C` bit. +MUTABLE_MISA_D,TODO,NORM_CSR_RW,high,Controls type (RO/RW) of misa.D,binary,"choices: [True, False]",D,ext:D,False,2,misa,machine.adoc,21,11,True,False,[#norm:misa_acc]#The `misa` CSR is a *WARL* read-write register# reporting the ISA supported by the hart.,Indicates whether or not the `D` extension can be disabled with the `misa.D` bit. +MUTABLE_MISA_F,TODO,NORM_CSR_RW,high,Controls type (RO/RW) of misa.F,binary,"choices: [True, False]",F,ext:F,False,2,misa,machine.adoc,21,11,True,False,[#norm:misa_acc]#The `misa` CSR is a *WARL* read-write register# reporting the ISA supported by the hart.,Indicates whether or not the `F` extension can be disabled with the `misa.F` bit. +MUTABLE_MISA_H,TODO,NORM_CSR_RW,high,Controls type (RO/RW) of misa.H,binary,"choices: [True, False]",H,ext:H,True,1,misa,machine.adoc,21,11,True,False,[#norm:misa_acc]#The `misa` CSR is a *WARL* read-write register# reporting the ISA supported by the hart.,Indicates whether or not the `H` extension can be disabled with the `misa.H` bit. +MUTABLE_MISA_M,TODO,NORM_CSR_RW,high,Controls type (RO/RW) of misa.G,binary,"choices: [True, False]",M,ext:M,False,2,misa,machine.adoc,21,11,True,False,[#norm:misa_acc]#The `misa` CSR is a *WARL* read-write register# reporting the ISA supported by the hart.,Indicates whether or not the `M` extension can be disabled with the `misa.M` bit. +MUTABLE_MISA_Q,TODO,NORM_CSR_RW,high,Controls type (RO/RW) of misa.Q,binary,"choices: [True, False]",Q,ext:Q,False,1,misa,machine.adoc,21,11,True,False,[#norm:misa_acc]#The `misa` CSR is a *WARL* read-write register# reporting the ISA supported by the hart.,Indicates whether or not the `Q` extension can be disabled with the `misa.Q` bit. +MUTABLE_MISA_S,TODO,NORM_CSR_RW,high,Controls type (RO/RW) of misa.S,binary,"choices: [True, False]",S,ext:S,True,1,misa,machine.adoc,21,11,True,False,[#norm:misa_acc]#The `misa` CSR is a *WARL* read-write register# reporting the ISA supported by the hart.,Indicates whether or not the `S` extension can be disabled with the `misa.S` bit. +MUTABLE_MISA_U,TODO,NORM_CSR_RW,high,Controls type (RO/RW) of misa.U,binary,"choices: [True, False]",U,ext:U,False,1,misa,machine.adoc,21,11,True,False,[#norm:misa_acc]#The `misa` CSR is a *WARL* read-write register# reporting the ISA supported by the hart.,Indicates whether or not the `U` extension can be disabled with the `misa.U` bit. +MUTABLE_MISA_V,TODO,NORM_CSR_RW,high,Controls type (RO/RW) of misa.V,binary,"choices: [True, False]",V,ext:V,False,1,misa,v-st-ext.adoc,5161,14,True,False,[#norm:misa-V_op]#The `misa.v` bit is set for implementations providing `misa` and,Indicates whether or not the `V` extension can be disabled with the `misa.V` bit. +MXLEN,XLEN in machine mode,NORM_DIRECT,high,Well-known architectural parameter 'MXLEN',binary,"choices: [32, 64]",Sm,ext:Sm,True,69,"hcontext, mconfigptr, misa, pmpaddr0, pmpaddr1, pmpaddr10, pmpaddr11, pmpaddr12, pmpaddr13, pmpaddr14, pmpaddr15, pmpaddr16, pmpaddr17, pmpaddr18, pmpaddr19, pmpaddr2, pmpaddr20, pmpaddr21, pmpaddr22, pmpaddr23, pmpaddr24, pmpaddr25, pmpaddr26, pmpaddr27, pmpaddr28, pmpaddr29, pmpaddr3, pmpaddr30, pmpaddr31, pmpaddr32, pmpaddr33, pmpaddr34, pmpaddr35, pmpaddr36, pmpaddr37, pmpaddr38, pmpaddr39, pmpaddr4, pmpaddr40, pmpaddr41, pmpaddr42, pmpaddr43, pmpaddr44, pmpaddr45, pmpaddr46, pmpaddr47, pmpaddr48, pmpaddr49, pmpaddr5, pmpaddr50, pmpaddr51, pmpaddr52, pmpaddr53, pmpaddr54, pmpaddr55, pmpaddr56, pmpaddr57, pmpaddr58, pmpaddr59, pmpaddr6, pmpaddr60, pmpaddr61, pmpaddr62, pmpaddr63, pmpaddr7, pmpaddr8, pmpaddr9, satp, vsatp",machine.adoc,50,12,True,False,[#norm:misa_sz]#The `misa` CSR is MXLEN bits wide.#,"XLEN in machine mode, specified in bits" +M_MODE_ENDIANNESS,Endianness of data in M-mode,NORM_CSR_RW,high,Controls type (RO/RW) of mstatus.MBE,enum,"values: ['little', 'big', 'dynamic']",Sm,ext:Sm,False,4,"mstatus, mstatush",machine.adoc,679,22,True,False,"[#norm:mstatus_mstatush_xbe_warl]#The MBE, SBE, and UBE bits in `mstatus` and `mstatush` are *WARL* fields# that","Options: + +[separator=""!""] +!=== +h! little ! M-mode data is always little endian +h! big ! M-mode data is always big endian +h! dynamic ! M-mode data can be either little or big endian, + depending on the CSR field `mstatus.MBE` +!===" +NUM_EXTERNAL_GUEST_INTERRUPTS,TODO,NORM_DIRECT,high,Well-known architectural parameter 'NUM_EXTERNAL_GUEST_INTERRUPTS',conditional,2 conditional branches,H,ext:H,False,3,hstatus,hypervisor.adoc,259,9,False,False,"VS-level external interrupts. GEILEN may be zero, in which case VGEIN","Number of supported virtualized guest interrupts + +Corresponds to the `GEILEN` parameter in the RVI specs" +NUM_PMP_ENTRIES,TODO,NORM_DIRECT,high,Well-known architectural parameter 'NUM_PMP_ENTRIES',range,[0..64],Smpmp,ext:Smpmp,False,224,"pmpaddr0, pmpaddr1, pmpaddr10, pmpaddr11, pmpaddr12, pmpaddr13, pmpaddr14, pmpaddr15, pmpaddr16, pmpaddr17, pmpaddr18, pmpaddr19, pmpaddr2, pmpaddr20, pmpaddr21, pmpaddr22, pmpaddr23, pmpaddr24, pmpaddr25, pmpaddr26, pmpaddr27, pmpaddr28, pmpaddr29, pmpaddr3, pmpaddr30, pmpaddr31, pmpaddr32, pmpaddr33, pmpaddr34, pmpaddr35, pmpaddr36, pmpaddr37, pmpaddr38, pmpaddr39, pmpaddr4, pmpaddr40, pmpaddr41, pmpaddr42, pmpaddr43, pmpaddr44, pmpaddr45, pmpaddr46, pmpaddr47, pmpaddr48, pmpaddr49, pmpaddr5, pmpaddr50, pmpaddr51, pmpaddr52, pmpaddr53, pmpaddr54, pmpaddr55, pmpaddr56, pmpaddr57, pmpaddr58, pmpaddr59, pmpaddr6, pmpaddr60, pmpaddr61, pmpaddr62, pmpaddr63, pmpaddr7, pmpaddr8, pmpaddr9, pmpcfg0, pmpcfg1, pmpcfg10, pmpcfg11, pmpcfg12, pmpcfg13, pmpcfg14, pmpcfg15, pmpcfg2, pmpcfg3, pmpcfg4, pmpcfg5, pmpcfg6, pmpcfg7, pmpcfg8, pmpcfg9",machine.adoc,668,4,True,False,"Note that, [#norm:mstatus_sum_op_mprv_mpp]#while SUM is ordinarily ignored when not","Number of implemented PMP entries. Can be any value between 0-64, inclusive. + +The architecture mandates that the number of implemented PMP registers +must appear to be 0, 16, or 64. + +Therefore, pmp registers will behave as follows according to NUN_PMP_ENTRIES: + +[separator=""!""] +!=== +! NUM_PMP_ENTRIES " +PHYS_ADDR_WIDTH,Number of bits in a physical address,NORM_DIRECT,high,Well-known architectural parameter 'PHYS_ADDR_WIDTH',conditional,2 conditional branches,Sm,ext:Sm,True,128,"pmpaddr0, pmpaddr1, pmpaddr10, pmpaddr11, pmpaddr12, pmpaddr13, pmpaddr14, pmpaddr15, pmpaddr16, pmpaddr17, pmpaddr18, pmpaddr19, pmpaddr2, pmpaddr20, pmpaddr21, pmpaddr22, pmpaddr23, pmpaddr24, pmpaddr25, pmpaddr26, pmpaddr27, pmpaddr28, pmpaddr29, pmpaddr3, pmpaddr30, pmpaddr31, pmpaddr32, pmpaddr33, pmpaddr34, pmpaddr35, pmpaddr36, pmpaddr37, pmpaddr38, pmpaddr39, pmpaddr4, pmpaddr40, pmpaddr41, pmpaddr42, pmpaddr43, pmpaddr44, pmpaddr45, pmpaddr46, pmpaddr47, pmpaddr48, pmpaddr49, pmpaddr5, pmpaddr50, pmpaddr51, pmpaddr52, pmpaddr53, pmpaddr54, pmpaddr55, pmpaddr56, pmpaddr57, pmpaddr58, pmpaddr59, pmpaddr6, pmpaddr60, pmpaddr61, pmpaddr62, pmpaddr63, pmpaddr7, pmpaddr8, pmpaddr9",hypervisor.adoc,1027,3,False,False,<>.,Implementation-defined size of the physical address space. +PMA_GRANULARITY,log2 of the smallest supported PMA region,NORM_DIRECT,high,Well-known architectural parameter 'PMA_GRANULARITY',range,[2..66],Sm,ext:Sm,False,0,,cmo.adoc,754,3,False,False,"granularity and atomicity, including individual bytes.","Generally, for systems with an MMU, should not be smaller than 12, +as that would preclude caching PMA results in the TLB along with +virtual memory translations" +PMLEN,TODO,NORM_DIRECT,high,Well-known architectural parameter 'PMLEN',value,{'base': 'integer'},"Smmpm, Smnpm, Ssnpm",(ext:Smmpm OR ext:Smnpm OR ext:Ssnpm),False,0,,hypervisor.adoc,807,7,False,False,|00|Pointer masking is disabled (PMLEN = 0),"The number of high-order bits of an address that are masked by the +pointer masking facility." +PMP_GRANULARITY,TODO,NORM_DIRECT,high,Well-known architectural parameter 'PMP_GRANULARITY',range,[2..66],Smpmp,ext:Smpmp,False,160,"pmpaddr0, pmpaddr1, pmpaddr10, pmpaddr11, pmpaddr12, pmpaddr13, pmpaddr14, pmpaddr15, pmpaddr16, pmpaddr17, pmpaddr18, pmpaddr19, pmpaddr2, pmpaddr20, pmpaddr21, pmpaddr22, pmpaddr23, pmpaddr24, pmpaddr25, pmpaddr26, pmpaddr27, pmpaddr28, pmpaddr29, pmpaddr3, pmpaddr30, pmpaddr31, pmpaddr32, pmpaddr33, pmpaddr34, pmpaddr35, pmpaddr36, pmpaddr37, pmpaddr38, pmpaddr39, pmpaddr4, pmpaddr40, pmpaddr41, pmpaddr42, pmpaddr43, pmpaddr44, pmpaddr45, pmpaddr46, pmpaddr47, pmpaddr48, pmpaddr49, pmpaddr5, pmpaddr50, pmpaddr51, pmpaddr52, pmpaddr53, pmpaddr54, pmpaddr55, pmpaddr56, pmpaddr57, pmpaddr58, pmpaddr59, pmpaddr6, pmpaddr60, pmpaddr61, pmpaddr62, pmpaddr63, pmpaddr7, pmpaddr8, pmpaddr9, pmpcfg0, pmpcfg1, pmpcfg10, pmpcfg11, pmpcfg12, pmpcfg13, pmpcfg14, pmpcfg15, pmpcfg2, pmpcfg3, pmpcfg4, pmpcfg5, pmpcfg6, pmpcfg7, pmpcfg8, pmpcfg9",cmo.adoc,754,3,False,False,"granularity and atomicity, including individual bytes.","log2 of the smallest supported PMP region. + +Generally, for systems with an MMU, should not be smaller than 12, +as that would preclude caching PMP results in the TLB along with +virtual memory translations + +Note that PMP_GRANULARITY is equal to G+2 (not G) as described in +the privileged architecture." +PRECISE_SYNCHRONOUS_EXCEPTIONS,Whether or not all synchronous exceptions are precise.,NORM_DIRECT,high,Trap/report behavior parameter (matches ^PRECISE_),binary,"choices: [True, False]",Sm,ext:Sm,False,0,,machine.adoc,1256,4,True,False,"[#norm:mtvec_mode_vectored_op]#When MODE=Vectored, all synchronous exceptions into machine mode cause","If false, any exception not otherwise mandated to precise (e.g., PMP violation) +will cause execution to enter an unpredictable state." +RCID_WIDTH,TODO,NORM_CSR_WARL,high,Referenced in sw_write() of srmcfg.RCID,range,[1..12],Ssqosid,ext:Ssqosid,False,1,srmcfg,supervisor.adoc,2586,8,False,False,The `RCID` and `MCID` configured in the `srmcfg` CSR apply to all privilege,"Number of bits used for the Resource Control ID field (RCID). +Default is 12." +REPORT_CAUSE_IN_MTVAL_ON_LANDING_PAD_SOFTWARE_CHECK,TODO,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",Zicfilp,ext:Zicfilp,False,0,,hypervisor.adoc,25,10,True,False,"registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and","When true, `mtval` is written with the shadow stack cause (code=18) when a SoftwareCheck exception is raised into M-mode due to a landing pad error. + +When false, `mtval` is written with 0." +REPORT_CAUSE_IN_MTVAL_ON_SHADOW_STACK_SOFTWARE_CHECK,TODO,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",Zicfiss,ext:Zicfiss,False,0,,hypervisor.adoc,25,10,True,False,"registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and","When true, `mtval` is written with the shadow stack cause (code=3) when a SoftwareCheck exception is raised into M-mode due to a shadow stack pop check instruction. + +When false, `mtval` is written with 0." +REPORT_CAUSE_IN_STVAL_ON_LANDING_PAD_SOFTWARE_CHECK,TODO,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",Zicfilp,ext:Zicfilp,False,0,,supervisor.adoc,707,9,True,False,[[norm:stval]],"When true, `stval` is written with the shadow stack cause (code=18) when a SoftwareCheck exception is raised into S-mode due to a landing pad error. + +When false, `stval` is written with 0." +REPORT_CAUSE_IN_STVAL_ON_SHADOW_STACK_SOFTWARE_CHECK,TODO,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",Zicfiss,ext:Zicfiss,False,0,,supervisor.adoc,707,9,True,False,[[norm:stval]],"When true, `stval` is written with the shadow stack cause (code=3) when a SoftwareCheck exception is raised into S-mode due to a shadow stack pop check instruction. + +When false, `stval` is written with 0." +REPORT_CAUSE_IN_VSTVAL_ON_LANDING_PAD_SOFTWARE_CHECK,TODO,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",Zicfilp,ext:Zicfilp,False,0,,hypervisor.adoc,1364,7,False,False,==== Virtual Supervisor Trap Value (`vstval`) Register,"When true, `vstval` is written with the shadow stack cause (code=18) when a SoftwareCheck exception is raised into VS-mode due to a landing pad error. + +When false, `vstval` is written with 0." +REPORT_CAUSE_IN_VSTVAL_ON_SHADOW_STACK_SOFTWARE_CHECK,TODO,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",Zicfiss,ext:Zicfiss,False,0,,hypervisor.adoc,1364,7,False,False,==== Virtual Supervisor Trap Value (`vstval`) Register,"When true, `vstval` is written with the shadow stack cause (code=3) when a SoftwareCheck exception is raised into VS-mode due to a shadow stack pop check instruction. + +When false, `vstval` is written with 0." +REPORT_ENCODING_IN_MTVAL_ON_ILLEGAL_INSTRUCTION,Whether or not `mtval` is written with the encoding of an instruction causing an IllegalInstruction exception,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",Sm,ext:Sm,False,0,,machine.adoc,2082,11,False,False,"nonzero value when an illegal-instruction exception occurs, then `mtval`","Options: + + * true: `mtval` is written with the encoding of an instruction causing an IllegalInstruction exception + * false: `mtval` is written with 0 when an instruction causes an IllegalInstruction exception." +REPORT_ENCODING_IN_STVAL_ON_ILLEGAL_INSTRUCTION,TODO,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",S,ext:S,False,0,,supervisor.adoc,751,11,False,False,"nonzero value when an illegal-instruction exception occurs, then `stval`","When true, `stval` is written with the encoding of an instruction that causes an +`IllegalInstruction` exception. + +When false `stval` is written with 0 when an `IllegalInstruction` exception occurs." +REPORT_ENCODING_IN_VSTVAL_ON_ILLEGAL_INSTRUCTION,TODO,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",H,ext:H,False,0,,hypervisor.adoc,1364,7,False,False,==== Virtual Supervisor Trap Value (`vstval`) Register,"When true, `vstval` is written with the encoding of an instruction that causes an +`IllegalInstruction` exception. + +When false `vstval` is written with 0 when an `IllegalInstruction` exception occurs." +REPORT_ENCODING_IN_VSTVAL_ON_VIRTUAL_INSTRUCTION,TODO,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",H,ext:H,False,0,,hypervisor.adoc,1364,8,False,False,==== Virtual Supervisor Trap Value (`vstval`) Register,"When true, `vstval` is written with the encoding of an instruction that causes an +`VirualInstruction` exception. + +When false `vstval` is written with 0 when an `VirtualInstruction` exception occurs." +REPORT_GPA_IN_HTVAL_ON_GUEST_PAGE_FAULT,TODO,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",H,ext:H,False,0,,hypervisor.adoc,917,9,False,False,"When a guest-page-fault trap is taken into HS-mode, `htval` is written","When true, `htval` is written with the Guest Physical Address, shifted right by 2, that +caused a `GuestPageFault` exception. + +When false, `htval` is written with 0 when a `GuestPageFault` exception occurs." +REPORT_GPA_IN_TVAL_ON_INSTRUCTION_GUEST_PAGE_FAULT,TODO,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",H,ext:H,False,2,"htval, mtval2",hypervisor.adoc,2832,8,False,False,"`mtval2` or `htval`. If both conditions are met, the value written to","Whether or not GPA >> 2 is written into htval/mtval2 when an instruction guest page fault occurs. + +If false, 0 will be written into htval/mtval2 on an instruction guest page fault." +REPORT_GPA_IN_TVAL_ON_INTERMEDIATE_GUEST_PAGE_FAULT,TODO,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",H,ext:H,False,2,"htval, mtval2",hypervisor.adoc,2832,8,False,False,"`mtval2` or `htval`. If both conditions are met, the value written to","Whether or not GPA >> 2 is written into htval/mtval2 when a guest page fault occurs while +walking a VS-mode page table. + +If false, 0 will be written into htval/mtval2 on an intermediate guest page fault." +REPORT_GPA_IN_TVAL_ON_LOAD_GUEST_PAGE_FAULT,TODO,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",H,ext:H,False,2,"htval, mtval2",hypervisor.adoc,2832,8,False,False,"`mtval2` or `htval`. If both conditions are met, the value written to","Whether or not GPA >> 2 is written into htval/mtval2 when a load guest page fault occurs. + +If false, 0 will be written into htval/mtval2 on a load guest page fault." +REPORT_GPA_IN_TVAL_ON_STORE_AMO_GUEST_PAGE_FAULT,TODO,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",H,ext:H,False,2,"htval, mtval2",hypervisor.adoc,2832,8,False,False,"`mtval2` or `htval`. If both conditions are met, the value written to","Whether or not GPA >> 2 is written into htval/mtval2 when a store/amo guest page fault occurs. + +If false, 0 will be written into htval/mtval2 on a store/amo guest page fault." +REPORT_VA_IN_MTVAL_ON_BREAKPOINT,Whether or not `mtval` is written with the virtual PC of an EBREAK instruction.,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",Sm,ext:Sm,False,0,,machine.adoc,2049,17,False,False,"On a breakpoint exception raised by an EBREAK or C.EBREAK instruction, `mtval`","Options: + + * true: `mtval` is written with the virtual PC of an EBREAK instruction (same information as `mepc`). + * false: `mtval` is written with 0 on an EBREAK instruction. + +Regardless, `mtval` is always written with a virtual PC when an external breakpoint is generated" +REPORT_VA_IN_MTVAL_ON_INSTRUCTION_ACCESS_FAULT,Whether or not `mtval` is written with the virtual address of a fetch causing an access fault,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",Sm,ext:Sm,False,0,,hypervisor.adoc,25,10,True,False,"registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and","Options: + + * true: `mtval` is written with the virtual address of a fetch causing the access fault + * false: `mtval` is written with 0 when a fetch causes an access fault" +REPORT_VA_IN_MTVAL_ON_INSTRUCTION_MISALIGNED,Whether or not `mtval` is written with the virtual address of a misaligned fetch,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",Sm,ext:Sm,False,0,,hypervisor.adoc,25,10,True,False,"registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and","Options: + + * true: `mtval` is written with the virtual address of a trapping misaligned fetch + * false: `mtval` is written with 0 when a misaligned fetch traps" +REPORT_VA_IN_MTVAL_ON_INSTRUCTION_PAGE_FAULT,TODO,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",S,ext:S,False,0,,hypervisor.adoc,25,10,True,False,"registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and","When true, `mtval` is written with the virtual PC of an instructino when fetch causes an +`InstructionPageFault`. + +WHen false, `mtval` is written with 0 when an instruction fetch causes an +`InstructionPageFault`." +REPORT_VA_IN_MTVAL_ON_LOAD_ACCESS_FAULT,Whether or not `mtval` is written with the virtual address of a load causing an access fault,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",Sm,ext:Sm,False,0,,hypervisor.adoc,25,10,True,False,"registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and","Options: + + * true: `mtval` is written with the virtual address of a load causing the access fault + * false: `mtval` is written with 0 when a load causes an access fault" +REPORT_VA_IN_MTVAL_ON_LOAD_MISALIGNED,Whether or not `mtval` is written with the virtual address of a misaligned load,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",Sm,ext:Sm,False,0,,machine.adoc,2067,11,False,False,If `mtval` is written with a nonzero value when a misaligned load or,"Options: + + * true: `mtval` is written with the virtual address of a trapping misaligned load. + * false: `mtval` is written with 0 when a misaligned load traps." +REPORT_VA_IN_MTVAL_ON_LOAD_PAGE_FAULT,TODO,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",S,ext:S,False,0,,hypervisor.adoc,25,10,True,False,"registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and","When true, `mtval` is written with the virtual address of a load when it causes a +`LoadPageFault`. + +WHen false, `mtval` is written with 0 when a load causes a `LoadPageFault`." +REPORT_VA_IN_MTVAL_ON_STORE_AMO_ACCESS_FAULT,Whether or not `mtval` is written with the virtual address of a store or AMO causing an access fault,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",Sm,ext:Sm,False,0,,hypervisor.adoc,25,10,True,False,"registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and","Options: + + * true: `mtval` is written with the virtual address of a store or AMO causing the access fault + * false: `mtval` is written with 0 when a store or AMO causes an access fault" +REPORT_VA_IN_MTVAL_ON_STORE_AMO_MISALIGNED,Whether or not `mtval` is written with the virtual address of a misaligned store or AMO,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",Sm,ext:Sm,False,0,,hypervisor.adoc,25,10,True,False,"registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and","Options: + + * true: `mtval` is written with the virtual address of a trapping misaligned store or AMO. + * false: `mtval` is written with 0 when a misaligned store or AMO traps." +REPORT_VA_IN_MTVAL_ON_STORE_AMO_PAGE_FAULT,TODO,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",S,ext:S,False,0,,hypervisor.adoc,25,10,True,False,"registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and","When true, `mtval` is written with the virtual address of a store when it causes a +`StoreAmoPageFault`. + +WHen false, `mtval` is written with 0 when a store causes a `StoreAmoPageFault`." +REPORT_VA_IN_STVAL_ON_BREAKPOINT,TODO,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",S,ext:S,False,0,,supervisor.adoc,726,17,False,False,"On a breakpoint exception raised by an EBREAK or C.EBREAK instruction, `stval`","When true, `stval` is written with the virtual PC of the EBREAK instruction (same information as `mepc`). + +When false, `stval` is written with 0 on an EBREAK instruction. + +Regardless, `stval` is always written with a virtual PC when an external breakpoint is generated" +REPORT_VA_IN_STVAL_ON_INSTRUCTION_ACCESS_FAULT,TODO,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",S,ext:S,False,0,,hypervisor.adoc,936,10,False,False,the instruction as indicated by the virtual address in `stval`.,"When true, `stval` is written with the virtual PC of an instructino when fetch causes an +`InstructionAccessFault`. + +WHen false, `stval` is written with 0 when an instruction fetch causes an +`InstructionAccessFault`." +REPORT_VA_IN_STVAL_ON_INSTRUCTION_MISALIGNED,TODO,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",S,ext:S,False,0,,supervisor.adoc,726,13,False,False,"On a breakpoint exception raised by an EBREAK or C.EBREAK instruction, `stval`","When true, `stval` is written with the virtual PC when an instruction fetch is misaligned. + +When false, `stval` is written with 0 when an instruction fetch is misaligned. + +Note that when IALIGN=16 (i.e., when the `C` or one of the `Zc*` extensions are implemented), +it is impossible to generate a mis" +REPORT_VA_IN_STVAL_ON_INSTRUCTION_PAGE_FAULT,TODO,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",S,ext:S,False,0,,hypervisor.adoc,936,10,False,False,the instruction as indicated by the virtual address in `stval`.,"When true, `stval` is written with the virtual PC of an instructino when fetch causes an +`InstructionPageFault`. + +WHen false, `stval` is written with 0 when an instruction fetch causes an +`InstructionPageFault`." +REPORT_VA_IN_STVAL_ON_LOAD_ACCESS_FAULT,TODO,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",S,ext:S,False,0,,supervisor.adoc,707,9,True,False,[[norm:stval]],"When true, `stval` is written with the virtual address of a load when it causes a +`LoadAccessFault`. + +WHen false, `stval` is written with 0 when a load causes a `LoadAccessFault`." +REPORT_VA_IN_STVAL_ON_LOAD_MISALIGNED,TODO,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",S,ext:S,False,0,,supervisor.adoc,734,11,False,False,If `stval` is written with a nonzero value when a misaligned load or,"When true, `stval` is written with the virtual address of a load instruction when the +address is misaligned and MISALIGNED_LDST is false. + +When false, `stval` is written with 0 when a load address is misaligned and +MISALIGNED_LDST is false." +REPORT_VA_IN_STVAL_ON_LOAD_PAGE_FAULT,TODO,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",S,ext:S,False,0,,hypervisor.adoc,2046,9,False,False,"modes. On a guest-page fault, CSR `mtval` or `stval` is written with the","When true, `stval` is written with the virtual address of a load when it causes a +`LoadPageFault`. + +WHen false, `stval` is written with 0 when a load causes a `LoadPageFault`." +REPORT_VA_IN_STVAL_ON_STORE_AMO_ACCESS_FAULT,TODO,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",S,ext:S,False,0,,supervisor.adoc,707,9,True,False,[[norm:stval]],"When true, `stval` is written with the virtual address of a store when it causes a +`StoreAmoAccessFault`. + +WHen false, `stval` is written with 0 when a store causes a `StoreAmoAccessFault`." +REPORT_VA_IN_STVAL_ON_STORE_AMO_MISALIGNED,TODO,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",S,ext:S,False,0,,supervisor.adoc,734,10,False,False,If `stval` is written with a nonzero value when a misaligned load or,"When true, `stval` is written with the virtual address of a store instruction when the +address is misaligned and MISALIGNED_LDST is false. + +When false, `stval` is written with 0 when a store address is misaligned and +MISALIGNED_LDST is false." +REPORT_VA_IN_STVAL_ON_STORE_AMO_PAGE_FAULT,TODO,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",S,ext:S,False,0,,hypervisor.adoc,2046,9,False,False,"modes. On a guest-page fault, CSR `mtval` or `stval` is written with the","When true, `stval` is written with the virtual address of a store when it causes a +`StoreAmoPageFault`. + +WHen false, `stval` is written with 0 when a store causes a `StoreAmoPageFault`." +REPORT_VA_IN_VSTVAL_ON_BREAKPOINT,TODO,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",H,ext:H,False,0,,hypervisor.adoc,1364,10,False,False,==== Virtual Supervisor Trap Value (`vstval`) Register,"When true, `vstval` is written with the virtual PC of the EBREAK instruction (same information as `mepc`). + +When false, `vstval` is written with 0 on an EBREAK instruction. + +Regardless, `vstval` is always written with a virtual PC when an external breakpoint is generated." +REPORT_VA_IN_VSTVAL_ON_INSTRUCTION_ACCESS_FAULT,TODO,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",H,ext:H,False,0,,zc.adoc,1183,9,True,False,"[#norm:Zcmp_trap]#If a trap occurs during the sequence then _xEPC_ is updated with the PC of the instruction, _xTVAL_ (if not read-only-zero) updated with the bad address if it was an access fault and","When true, `vstval` is written with the virtual PC of an instructino when fetch causes an +`InstructionAccessFault`. + +WHen false, `vstval` is written with 0 when an instruction fetch causes an +`InstructionAccessFault`." +REPORT_VA_IN_VSTVAL_ON_INSTRUCTION_MISALIGNED,TODO,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",H,ext:H,False,0,,c-st-ext.adoc,310,8,True,False,[#norm:c-ldsp_op]#C.LDSP is an RV64C-only instruction that loads a 64-bit value,"When true, `vstval` is written with the virtual PC when an instruction fetch is misaligned. + +When false, `vstval` is written with 0 when an instruction fetch is misaligned. + +Note that when IALIGN=16 (i.e., when the `C` or one of the `Zc*` extensions are implemented), +it is impossible to generate a m" +REPORT_VA_IN_VSTVAL_ON_INSTRUCTION_PAGE_FAULT,TODO,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",H,ext:H,False,0,,zc.adoc,1183,8,True,False,"[#norm:Zcmp_trap]#If a trap occurs during the sequence then _xEPC_ is updated with the PC of the instruction, _xTVAL_ (if not read-only-zero) updated with the bad address if it was an access fault and","When true, `vstval` is written with the virtual PC of an instructino when fetch causes an +`InstructionPageFault`. + +WHen false, `vstval` is written with 0 when an instruction fetch causes an +`InstructionPageFault`." +REPORT_VA_IN_VSTVAL_ON_LOAD_ACCESS_FAULT,TODO,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",H,ext:H,False,0,,hypervisor.adoc,1371,8,False,False,"actually access `vstval` instead. When V=0, `vstval` does not directly","When true, `vstval` is written with the virtual address of a load when it causes a +`LoadAccessFault`. + +WHen false, `vstval` is written with 0 when a load causes a `LoadAccessFault`." +REPORT_VA_IN_VSTVAL_ON_LOAD_MISALIGNED,TODO,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",H,ext:H,False,0,,hypervisor.adoc,1364,7,False,False,==== Virtual Supervisor Trap Value (`vstval`) Register,"When true, `vstval` is written with the virtual address of a load instruction when the +address is misaligned and MISALIGNED_LDST is false. + +When false, `vstval` is written with 0 when a load address is misaligned and +MISALIGNED_LDST is false." +REPORT_VA_IN_VSTVAL_ON_LOAD_PAGE_FAULT,TODO,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",H,ext:H,False,0,,hypervisor.adoc,1364,7,False,False,==== Virtual Supervisor Trap Value (`vstval`) Register,"When true, `vstval` is written with the virtual address of a load when it causes a +`LoadPageFault`. + +WHen false, `vstval` is written with 0 when a load causes a `LoadPageFault`." +REPORT_VA_IN_VSTVAL_ON_STORE_AMO_ACCESS_FAULT,TODO,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",H,ext:H,False,0,,hypervisor.adoc,1371,8,False,False,"actually access `vstval` instead. When V=0, `vstval` does not directly","When true, `vstval` is written with the virtual address of a store when it causes a +`StoreAmoAccessFault`. + +WHen false, `vstval` is written with 0 when a store causes a `StoreAmoAccessFault`." +REPORT_VA_IN_VSTVAL_ON_STORE_AMO_MISALIGNED,TODO,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",H,ext:H,False,0,,hypervisor.adoc,1364,7,False,False,==== Virtual Supervisor Trap Value (`vstval`) Register,"When true, `vstval` is written with the virtual address of a store instruction when the +address is misaligned and MISALIGNED_LDST is false. + +When false, `vstval` is written with 0 when a store address is misaligned and +MISALIGNED_LDST is false." +REPORT_VA_IN_VSTVAL_ON_STORE_AMO_PAGE_FAULT,TODO,NORM_DIRECT,high,Trap/report behavior parameter (matches ^REPORT_),binary,"choices: [True, False]",H,ext:H,False,0,,hypervisor.adoc,1364,7,False,False,==== Virtual Supervisor Trap Value (`vstval`) Register,"When true, `vstval` is written with the virtual address of a store when it causes a +`StoreAmoPageFault`. + +WHen false, `vstval` is written with 0 when a store causes a `StoreAmoPageFault`." +RVV_VL_WHEN_AVL_LT_DOUBLE_VLMAX,TODO,NORM_DIRECT,low,No strong signals; defaulting to direct normative parameter,enum,"values: ['ceil(AVL/2)', 'VLMAX', 'custom']",V,ext:V,False,0,,v-st-ext.adoc,1279,9,True,False,"[#norm:vsetvl_op_rs1_x0_rd_x0]#When _rs1_=`x0` and _rd_=`x0`, the instructions operate as if the current vector length in `vl` is used as the AVL, and the resulting value is written to `vl`, but not t",The value assigned to VL when AVL < 2*VLMAX. +SATP_MODE_BARE,TODO,NORM_CSR_WARL,high,Referenced in sw_write() of satp.MODE,binary,"choices: [True, False]",S,ext:S,False,1,satp,machine.adoc,670,11,True,False,[#norm:mstatus_sum_rdonly0]#SUM is read-only 0 if S-mode is not supported or if `satp`.MODE is read-only 0.#,Whether or not satp.MODE == Bare is supported. +SCOUNTENABLE_EN,TODO,NORM_CSR_RW,high,Controls type (RO/RW) of scounteren.CY,bitmask,32-bit mask,"S, Zicntr, Zihpm",ext:S AND (ext:Zicntr OR ext:Zihpm),True,64,scounteren,supervisor.adoc,511,12,False,False,"When the CY, TM, IR, or HPM__n__ bit in the `scounteren` register is","Indicates which counters can delegated via `scounteren` + +An unimplemented counter cannot be specified, i.e., if +HPM_COUNTER_EN[3] is false, it would be illegal to set +SCOUNTENABLE_EN[3] to true. + +SCOUNTENABLE_EN[0:2] must all be false if `Zicntr` is not implemented. +SCOUNTENABLE_EN[3:31] must all be" +SSTATEEN_JVT_TYPE,TODO,NORM_CSR_RW,low,CSR field type control parameter for 'sstateen' (determines RO/RW behavior),enum,"values: ['rw', 'read-only-0', 'read-only-1']","Ssstateen, Zcmt",ext:Zcmt AND ext:Ssstateen,True,0,,zc.adoc,2341,4,True,False,"[#norm:Zcmt_entry_sz]#The base of the table is in the jvt CSR (see <>), each table entry is XLEN bits.#","Behavior of the sstateen0.JVT bit: + + * 'rw': read-write + * 'read-only-0': read-only, fixed to 0 + * 'read-only-1': read-only, fixed to 1" +STVAL_WIDTH,TODO,NORM_DIRECT,medium,Trap value reporting parameter,range,[None..18446744073709551615],S,ext:S,False,0,,supervisor.adoc,707,6,True,False,[[norm:stval]],"The number of implemented bits in `stval`. + +Must be greater than or equal to _max_(`PHYS_ADDR_WIDTH`, `VA_SIZE`)" +STVEC_MODE_DIRECT,TODO,NORM_CSR_WARL,high,Referenced in sw_write() of stvec.MODE,binary,"choices: [True, False]",S,ext:S,True,1,stvec,hypervisor.adoc,1304,8,False,False,"VS-mode’s version of supervisor register `stvec`, formatted as shown in",Whether or not `stvec.MODE` supports Direct (0). +STVEC_MODE_VECTORED,TODO,NORM_CSR_WARL,high,Referenced in sw_write() of stvec.MODE,binary,"choices: [True, False]",S,ext:S,True,1,stvec,machine.adoc,1256,9,True,False,"[#norm:mtvec_mode_vectored_op]#When MODE=Vectored, all synchronous exceptions into machine mode cause",Whether or not `stvec.MODE` supports Vectored (1). +SV32X4_TRANSLATION,TODO,NORM_CSR_WARL,high,Referenced in sw_write() of hgatp.MODE,binary,"choices: [True, False]",H,ext:H AND param:SXLEN(includes=32),True,3,hgatp,hypervisor.adoc,1915,9,False,False,"When `hgatp`.MODE specifies a translation scheme of Sv32x4, Sv39x4,",Whether or not Sv32x4 translation mode is supported. +SV32_VSMODE_TRANSLATION,TODO,NORM_DIRECT,medium,Translation/mode parameter,binary,"choices: [True, False]",H,ext:H AND param:VSXLEN(includes=32),True,0,,cmo.adoc,365,5,True,False,"otherwise.# [#norm:cbm_unperm_translate]#During address translation, the instruction also checks the accessed","Whether or not Sv32 translation is supported in first-stage (VS-stage) +translation." +SV39X4_TRANSLATION,TODO,NORM_CSR_WARL,high,Referenced in sw_write() of hgatp.MODE,binary,"choices: [True, False]",H,ext:H AND param:SXLEN(includes=64),True,3,hgatp,hypervisor.adoc,1007,9,False,False,".Hypervisor guest address translation and protection register `hgatp` when HSXLEN=64 for MODE values Bare, Sv39x4, Sv48x4, and Sv57x4.",Whether or not Sv39x4 translation mode is supported. +SV39_VSMODE_TRANSLATION,TODO,NORM_DIRECT,medium,Translation/mode parameter,binary,"choices: [True, False]",H,ext:H AND param:VSXLEN(includes=64),True,0,,cmo.adoc,365,5,True,False,"otherwise.# [#norm:cbm_unperm_translate]#During address translation, the instruction also checks the accessed","Whether or not Sv39 translation is supported in first-stage (VS-stage) +translation." +SV48X4_TRANSLATION,TODO,NORM_CSR_WARL,high,Referenced in sw_write() of hgatp.MODE,binary,"choices: [True, False]",H,ext:H AND param:SXLEN(includes=64),True,3,hgatp,hypervisor.adoc,1007,9,False,False,".Hypervisor guest address translation and protection register `hgatp` when HSXLEN=64 for MODE values Bare, Sv39x4, Sv48x4, and Sv57x4.",Whether or not Sv48x4 translation mode is supported. +SV48_VSMODE_TRANSLATION,TODO,NORM_DIRECT,medium,Translation/mode parameter,binary,"choices: [True, False]",H,ext:H AND param:VSXLEN(includes=64),True,0,,cmo.adoc,365,5,True,False,"otherwise.# [#norm:cbm_unperm_translate]#During address translation, the instruction also checks the accessed","Whether or not Sv48 translation is supported in first-stage (VS-stage) +translation." +SV57X4_TRANSLATION,TODO,NORM_CSR_WARL,high,Referenced in sw_write() of hgatp.MODE,binary,"choices: [True, False]",H,ext:H AND param:SXLEN(includes=64),True,3,hgatp,hypervisor.adoc,1007,9,False,False,".Hypervisor guest address translation and protection register `hgatp` when HSXLEN=64 for MODE values Bare, Sv39x4, Sv48x4, and Sv57x4.",Whether or not Sv57x4 translation mode is supported. +SV57_VSMODE_TRANSLATION,TODO,NORM_DIRECT,medium,Translation/mode parameter,binary,"choices: [True, False]",H,ext:H AND param:VSXLEN(includes=64),True,0,,cmo.adoc,365,5,True,False,"otherwise.# [#norm:cbm_unperm_translate]#During address translation, the instruction also checks the accessed","Whether or not Sv57 translation is supported in first-stage (VS-stage) +translation." +SXLEN,TODO,NORM_DIRECT,high,Well-known architectural parameter 'SXLEN',set,"subset of [32, 64]",S,ext:S,True,3,"hstatus, mstatus",machine.adoc,575,11,False,False,"When MXLEN=32, the SXL and UXL fields do not exist, and SXLEN=32 and UXLEN=32.","Set of XLENs supported in S-mode. Can be one of: + + * 32: SXLEN is always 32 + * 64: SXLEN is always 64 + * [32, 64]: SXLEN can be changed (via mstatus.SXL) between 32 and 64" +S_MODE_ENDIANNESS,TODO,NORM_CSR_RW,high,Controls type (RO/RW) of mstatus.SBE,enum,"values: ['little', 'big', 'dynamic']",S,ext:S,False,4,"mstatus, mstatush",machine.adoc,679,22,True,False,"[#norm:mstatus_mstatush_xbe_warl]#The MBE, SBE, and UBE bits in `mstatus` and `mstatush` are *WARL* fields# that","Endianness of data in S-mode. Can be one of: + + * little: S-mode data is always little endian + * big: S-mode data is always big endian + * dynamic: S-mode data can be either little or big endian, + depending on the CSR field `mstatus.SBE`" +TIME_CSR_IMPLEMENTED,TODO,NORM_DIRECT,high,Feature/CSR existence parameter ('IMPLEMENTED' suffix),binary,"choices: [True, False]",Zicntr,ext:Zicntr,False,2,"time, timeh",machine.adoc,2621,25,False,False,"When `mtime` changes, it is guaranteed to be reflected in `time` and `timeh`","Whether or not a real hardware `time` CSR exists. Implementations can either provide a real +CSR or emulate access at M-mode. + +Possible values: + +true:: + `time`/`timeh` exists, and accessing it will not cause an IllegalInstruction trap + +false:: + `time`/`timeh` does not exist. + Accessing the CSR wil" +TINST_VALUE_ON_BREAKPOINT,TODO,NORM_CSR_RW,high,Controls type (RO/RW) of htinst.VALUE,binary,"choices: ['always zero', 'custom']",H,ext:H,False,2,"htinst, mtinst",hypervisor.adoc,983,8,False,False,`htinst` is a *WARL* register that need only be able to hold the values that,"Value written into htinst/mtinst on a Breakpoint exception from VU/VS-mode. + +Possible values: + * ""always zero"": Always write the value zero + * ""custom"": Write a custom value, which results in UNPREDICTABLE" +TINST_VALUE_ON_FINAL_INSTRUCTION_GUEST_PAGE_FAULT,TODO,NORM_CSR_RW,high,Controls type (RO/RW) of htinst.VALUE,binary,"choices: ['always zero', 'always pseudoinstruction']",H,ext:H,False,2,"htinst, mtinst",hypervisor.adoc,2567,9,False,False,==== Transformed Instruction or Pseudoinstruction for `mtinst` or `htinst`,"Value to write into htval/mtval2 when there is a guest page fault on a final translation. + +Possible values: + * ""always zero"": Always write the value zero + * ""always pseudoinstruction"": Always write the pseudoinstruction" +TINST_VALUE_ON_FINAL_LOAD_GUEST_PAGE_FAULT,TODO,NORM_CSR_RW,high,Controls type (RO/RW) of htinst.VALUE,enum,"values: ['always zero', 'always pseudoinstruction', 'always transformed standard instruction', 'custom']",H,ext:H,False,2,"htinst, mtinst",hypervisor.adoc,983,8,False,False,`htinst` is a *WARL* register that need only be able to hold the values that,"Value to write into htval/mtval2 when there is a guest page fault on a final translation. + +Possible values: + * ""always zero"": Always write the value zero + * ""always pseudoinstruction"": Always write the pseudoinstruction + * ""always transformed standard instruction"": Always write the transformation" +TINST_VALUE_ON_FINAL_STORE_AMO_GUEST_PAGE_FAULT,TODO,NORM_CSR_RW,high,Controls type (RO/RW) of htinst.VALUE,enum,"values: ['always zero', 'always pseudoinstruction', 'always transformed standard instruction', 'custom']",H,ext:H,False,2,"htinst, mtinst",hypervisor.adoc,983,8,False,False,`htinst` is a *WARL* register that need only be able to hold the values that,"Value to write into htval/mtval2 when there is a guest page fault on a final translation. + +Possible values: + * ""always zero"": Always write the value zero + * ""always pseudoinstruction"": Always write the pseudoinstruction + * ""always transformed standard instruction"": Always write the transformation" +TINST_VALUE_ON_INSTRUCTION_ADDRESS_MISALIGNED,TODO,NORM_CSR_RW,high,Controls type (RO/RW) of htinst.VALUE,binary,"choices: ['always zero', 'custom']",H,ext:H,False,2,"htinst, mtinst",hypervisor.adoc,2567,9,False,False,==== Transformed Instruction or Pseudoinstruction for `mtinst` or `htinst`,"Value written into htinst/mtinst when there is an instruction address misaligned exception. + +Possible values: + * ""always zero"": Always write the value zero + * ""custom"": Write a custom value, which results in UNPREDICTABLE" +TINST_VALUE_ON_LOAD_ACCESS_FAULT,TODO,NORM_CSR_RW,high,Controls type (RO/RW) of htinst.VALUE,enum,"values: ['always zero', 'always transformed standard instruction', 'custom']",H,ext:H,False,2,"htinst, mtinst",hypervisor.adoc,983,8,False,False,`htinst` is a *WARL* register that need only be able to hold the values that,"Value written into htinst/mtinst on an AccessFault exception from VU/VS-mode. + +Possible values: + * ""always zero"": Always write the value zero + * ""always transformed standard instruction"": Always write a transformed standard instruction as defined by H + * ""custom"": Write a custom value, which resu" +TINST_VALUE_ON_LOAD_ADDRESS_MISALIGNED,TODO,NORM_CSR_RW,high,Controls type (RO/RW) of htinst.VALUE,enum,"values: ['always zero', 'always transformed standard instruction', 'custom']",H,ext:H,False,2,"htinst, mtinst",hypervisor.adoc,983,8,False,False,`htinst` is a *WARL* register that need only be able to hold the values that,"Value written into htinst/mtinst on a VirtualInstruction exception from VU/VS-mode. + +Possible values: + * ""always zero"": Always write the value zero + * ""always transformed standard instruction"": Always write a transformed standard instruction as defined by H + * ""custom"": Write a custom value, whic" +TINST_VALUE_ON_LOAD_PAGE_FAULT,TODO,NORM_CSR_RW,high,Controls type (RO/RW) of htinst.VALUE,enum,"values: ['always zero', 'always transformed standard instruction', 'custom']",H,ext:H,False,2,"htinst, mtinst",hypervisor.adoc,983,8,False,False,`htinst` is a *WARL* register that need only be able to hold the values that,"Value written into htinst/mtinst on a LoadPageFault exception from VU/VS-mode. + +Possible values: + * ""always zero"": Always write the value zero + * ""always transformed standard instruction"": Always write a transformed standard instruction as defined by H + * ""custom"": Write a custom value, which res" +TINST_VALUE_ON_MCALL,TODO,NORM_CSR_RW,high,Controls type (RO/RW) of htinst.VALUE,binary,"choices: ['always zero', 'custom']",H,ext:H,False,2,"htinst, mtinst",hypervisor.adoc,983,8,False,False,`htinst` is a *WARL* register that need only be able to hold the values that,"Value written into htinst/mtinst on a MCall exception from VU/VS-mode. + +Possible values: + * ""always zero"": Always write the value zero + * ""custom"": Write a custom value, which results in UNPREDICTABLE" +TINST_VALUE_ON_SCALL,TODO,NORM_CSR_RW,high,Controls type (RO/RW) of htinst.VALUE,binary,"choices: ['always zero', 'custom']",H,ext:H,False,2,"htinst, mtinst",hypervisor.adoc,983,8,False,False,`htinst` is a *WARL* register that need only be able to hold the values that,"Value written into htinst/mtinst on a SCall exception from VU/VS-mode. + +Possible values: + * ""always zero"": Always write the value zero + * ""custom"": Write a custom value, which results in UNPREDICTABLE" +TINST_VALUE_ON_STORE_AMO_ACCESS_FAULT,TODO,NORM_CSR_RW,high,Controls type (RO/RW) of htinst.VALUE,enum,"values: ['always zero', 'always transformed standard instruction', 'custom']",H,ext:H,False,2,"htinst, mtinst",hypervisor.adoc,983,8,False,False,`htinst` is a *WARL* register that need only be able to hold the values that,"Value written into htinst/mtinst on an AccessFault exception from VU/VS-mode. + +Possible values: + * ""always zero"": Always write the value zero + * ""always transformed standard instruction"": Always write a transformed standard instruction as defined by H + * ""custom"": Write a custom value, which resu" +TINST_VALUE_ON_STORE_AMO_ADDRESS_MISALIGNED,TODO,NORM_CSR_RW,high,Controls type (RO/RW) of htinst.VALUE,enum,"values: ['always zero', 'always transformed standard instruction', 'custom']",H,ext:H,False,2,"htinst, mtinst",hypervisor.adoc,983,8,False,False,`htinst` is a *WARL* register that need only be able to hold the values that,"Value written into htinst/mtinst on a VirtualInstruction exception from VU/VS-mode. + +Possible values: + * ""always zero"": Always write the value zero + * ""always transformed standard instruction"": Always write a transformed standard instruction as defined by H + * ""custom"": Write a custom value, whic" +TINST_VALUE_ON_STORE_AMO_PAGE_FAULT,TODO,NORM_CSR_RW,high,Controls type (RO/RW) of htinst.VALUE,enum,"values: ['always zero', 'always transformed standard instruction', 'custom']",H,ext:H,False,2,"htinst, mtinst",hypervisor.adoc,983,8,False,False,`htinst` is a *WARL* register that need only be able to hold the values that,"Value written into htinst/mtinst on a StoreAmoPageFault exception from VU/VS-mode. + +Possible values: + * ""always zero"": Always write the value zero + * ""always transformed standard instruction"": Always write a transformed standard instruction as defined by H + * ""custom"": Write a custom value, which" +TINST_VALUE_ON_UCALL,TODO,NORM_CSR_RW,high,Controls type (RO/RW) of htinst.VALUE,binary,"choices: ['always zero', 'custom']",H,ext:H,False,2,"htinst, mtinst",hypervisor.adoc,983,8,False,False,`htinst` is a *WARL* register that need only be able to hold the values that,"Value written into htinst/mtinst on a UCall exception from VU/VS-mode. + +Possible values: + * ""always zero"": Always write the value zero + * ""custom"": Write a custom value, which results in UNPREDICTABLE" +TINST_VALUE_ON_VIRTUAL_INSTRUCTION,TODO,NORM_CSR_RW,high,Controls type (RO/RW) of htinst.VALUE,binary,"choices: ['always zero', 'custom']",H,ext:H,False,2,"htinst, mtinst",smctr.adoc,218,10,True,False,"[#norm:sctrdepth_mode]#Attempts to access `sctrdepth` from VS-mode or VU-mode raise a virtual-instruction exception, unless CTR state enable access restrictions apply.# See <>. In particular, an implementation may make UXL be a read-only copy of field VSXL of `hstatus`, forcing VU-mode XLEN=VSXLEN.","Set of XLENs supported in VS-mode. Can be one of: + + * [32]: VSXLEN is always 32 + * [64]: VSXLEN is always 64 + * [32, 64]: VSXLEN can be changed (via `hstatus.VSXL`) between 32 and 64" +VS_MODE_ENDIANNESS,TODO,NORM_CSR_RW,high,Controls type (RO/RW) of hstatus.VSBE,enum,"values: ['little', 'big', 'dynamic']",H,ext:H,False,2,hstatus,hypervisor.adoc,339,14,False,False,"accesses made from VS-mode are little-endian, and if VSBE=1, they are","Endianness of data in VS-mode. Can be one of: + + * little: VS-mode data is always little endian + * big: VS-mode data is always big endian + * dynamic: VS-mode data can be either little or big endian, + depending on the CSR field `hstatus.VSBE`" +VUXLEN,TODO,NORM_DIRECT,high,Well-known architectural parameter 'VUXLEN',set,"subset of [32, 64]",H,ext:H,True,2,vsstatus,hypervisor.adoc,1181,6,False,False,"The UXL field controls the effective XLEN for VU-mode, which may differ","Set of XLENs supported in VU-mode. When both 32 and 64 are supported, VUXLEN can be changed +via `vsstatus.UXL`." +VU_MODE_ENDIANNESS,TODO,NORM_CSR_RW,high,Controls type (RO/RW) of vsstatus.UBE,enum,"values: ['little', 'big', 'dynamic']",H,ext:H,False,2,vsstatus,hypervisor.adoc,2359,10,True,False,"* [#norm:H_virtinst_vu_nonhighctr_h0_s0_m1]#in VU-mode, attempts to access a non-high-half counter CSR when the","Endianness of data in VU-mode. Can be one of: + + * little: VU-mode data is always little endian + * big: VU-mode data is always big endian + * dynamic: VU-mode data can be either little or big endian, + depending on the CSR field `vsstatus.UBE`" diff --git a/param_extraction/data/phase1_report.txt b/param_extraction/data/phase1_report.txt new file mode 100644 index 0000000000..9abffb697f --- /dev/null +++ b/param_extraction/data/phase1_report.txt @@ -0,0 +1,821 @@ +======================================================================== +PHASE 1 REPORT: UDB Parameter Ground Truth +RISC-V Architectural Parameter Extraction Project +======================================================================== + +1. OVERVIEW +---------------------------------------- + Total real parameters in UDB: 185 + Spec files searched: 74 + Total spec lines: 52602 + Parameters with spec matches: 183 (98%) + Parameters with strong matches: 161 (87%) + +2. CLASSIFICATION BREAKDOWN +---------------------------------------- + NORM_CSR_RW 55 (29%) + NORM_CSR_WARL 26 (14%) + NORM_DIRECT 102 (55%) + SW_RULE 2 ( 1%) + + Classification descriptions: + NORM_DIRECT = Normative, directly configurable (not CSR-controlled) + NORM_CSR_WARL = Normative, legal values of a WARL CSR field + NORM_CSR_RW = Normative, controls whether CSR field is RO/RW + SW_RULE = Software-deterministic (impl-defined but deterministic w/ correct SW) + +3. VALUE TYPE BREAKDOWN +---------------------------------------- + binary 111 (60%) + bitmask 5 ( 2%) + conditional 10 ( 5%) + enum 36 (19%) + range 12 ( 6%) + set 8 ( 4%) + value 3 ( 1%) + + Value type descriptions: + binary = Exactly 2 choices (boolean or 2-value enum) + enum = Finite set of 3+ discrete values + range = Continuous integer range with min/max bounds + set = Subset selection from a fixed universe of values + bitmask = Fixed-length boolean array (one bit per feature) + conditional = Schema varies based on another parameter (e.g., MXLEN) + value = Single unconstrained value + +4. CLASSIFICATION CONFIDENCE +---------------------------------------- + high 150 (81%) + low 16 ( 8%) + medium 19 (10%) + +5. DEFINING EXTENSIONS (Top 15) +---------------------------------------- + H 61 + Sm 38 + S 29 + Sdtrig 10 + V 7 + Ssstateen 7 + Zcmt 6 + Smstateen 6 + U 5 + Ssaia 4 + Zalrsc 4 + F 3 + Zicfilp 3 + Zicfiss 3 + Zicbom 2 + +6. PARAMETER LISTING BY CLASSIFICATION +---------------------------------------- + + --- NORM_DIRECT (102 parameters) --- + ARCH_ID_VALUE + Type: conditional | Exts: ext:Sm AND param:MARCHID_IMPLEMENTED(equal=True) CSRs: marchid + Spec: -> machine.adoc:297 + Conf: high | Well-known architectural parameter 'ARCH_ID_VALUE' + ASID_WIDTH + Type: conditional | Exts: ext:S + Spec: -> supervisor.adoc:1373 [NORM] + Conf: high | Well-known architectural parameter 'ASID_WIDTH' + CACHE_BLOCK_SIZE + Type: range | Exts: (ext:Zicbom OR ext:Zicbop OR ext:Zicboz) + Spec: -> cmo.adoc:973 [NORM] + Conf: high | Well-known architectural parameter 'CACHE_BLOCK_SIZE' + CONFIG_PTR_ADDRESS + Type: conditional | Exts: ext:Sm(>= 1.12.0) CSRs: mconfigptr + Spec: -> machine.adoc:2136 + Conf: high | Well-known architectural parameter 'CONFIG_PTR_ADDRESS' + ELEN + Type: value | Exts: ext:V + Spec: -> v-st-ext.adoc:24 [NORM] + Conf: high | Well-known architectural parameter 'ELEN' + FOLLOW_VTYPE_RESET_RECOMMENDATION + Type: binary([True, False]) | Exts: ext:V CSRs: vl, vtype + Spec: -> v-st-ext.adoc:169 [NORM] + Conf: medium | Implementation behavioral choice parameter + HCONTEXT_AVAILABLE + Type: binary([True, False]) | Exts: ext:Sdtrig CSRs: hcontext + Spec: -> smstateen.adoc:287 + Conf: high | Feature/CSR existence parameter ('AVAILABLE' suffix) + IMP_ID_VALUE + Type: conditional | Exts: ext:Sm AND param:MIMPID_IMPLEMENTED(equal=True) CSRs: mimpid + Spec: -> machine.adoc:335 + Conf: high | Well-known architectural parameter 'IMP_ID_VALUE' + LRSC_FAIL_ON_NON_EXACT_LRSC + Type: binary([True, False]) | Exts: ext:Zalrsc + Spec: -> a-st-ext.adoc:169 + Conf: medium | Load-reserved/store-conditional behavior parameter + LRSC_FAIL_ON_VA_SYNONYM + Type: binary([True, False]) | Exts: ext:Zalrsc + Spec: -> a-st-ext.adoc:76 + Conf: medium | Load-reserved/store-conditional behavior parameter + LRSC_MISALIGNED_BEHAVIOR + Type: enum(3 vals) | Exts: ext:Zalrsc + Spec: -> a-st-ext.adoc:59 + Conf: medium | Load-reserved/store-conditional behavior parameter + LRSC_RESERVATION_STRATEGY + Type: enum(4 vals) | Exts: ext:Zalrsc + Spec: -> a-st-ext.adoc:76 + Conf: medium | Load-reserved/store-conditional behavior parameter + MARCHID_IMPLEMENTED + Type: binary([True, False]) | Exts: ext:Sm + Spec: -> machine.adoc:303 + Conf: high | Feature/CSR existence parameter ('IMPLEMENTED' suffix) + MCONTEXT_AVAILABLE + Type: binary([True, False]) | Exts: ext:Sdtrig CSRs: mcontext + Spec: -> priv-csrs.adoc:1019 + Conf: high | Feature/CSR existence parameter ('AVAILABLE' suffix) + MIMPID_IMPLEMENTED + Type: binary([True, False]) | Exts: ext:Sm + Spec: -> machine.adoc:337 [NORM] + Conf: high | Feature/CSR existence parameter ('IMPLEMENTED' suffix) + MISALIGNED_AMO + Type: binary([True, False]) | Exts: ext:Zaamo + Spec: -> machine.adoc:1976 [NORM] + Conf: medium | Misaligned access behavior parameter + MISALIGNED_LDST + Type: binary([True, False]) | Exts: ext:Sm + Spec: -> machine.adoc:1976 [NORM] + Conf: medium | Misaligned access behavior parameter + MISALIGNED_LDST_EXCEPTION_PRIORITY + Type: binary(['low', 'high']) | Exts: ext:Sm + Spec: -> rv32.adoc:139 [NORM] + Conf: medium | Misaligned access behavior parameter + MISALIGNED_MAX_ATOMICITY_GRANULE_SIZE + Type: enum(13 vals) | Exts: ext:Sm AND param:MISALIGNED_LDST(equal=True) + Spec: -> a-st-ext.adoc:385 + Conf: medium | Misaligned access behavior parameter + MISALIGNED_SPLIT_STRATEGY + Type: binary(['sequential_bytes', 'custom']) | Exts: ext:Sm AND param:MISALIGNED_LDST(equal=True) + Spec: -> machine.adoc:1976 [NORM] + Conf: medium | Misaligned access behavior parameter + MISA_CSR_IMPLEMENTED + Type: binary([True, False]) | Exts: ext:Sm CSRs: mstatus + Spec: -> machine.adoc:23 [NORM] + Conf: high | Feature/CSR existence parameter ('IMPLEMENTED' suffix) + MSTATUS_TVM_IMPLEMENTED + Type: binary([True, False]) | Exts: ext:S CSRs: mstatus + Spec: -> hypervisor.adoc:999 [NORM] + Conf: high | Feature/CSR existence parameter ('IMPLEMENTED' suffix) + MTVAL_WIDTH + Type: conditional | Exts: ext:Sm + Spec: -> hypervisor.adoc:25 [NORM] + Conf: medium | Trap value reporting parameter + MXLEN + Type: binary([32, 64]) | Exts: ext:Sm CSRs: hcontext, mconfigptr, misa + Spec: -> machine.adoc:50 [NORM] + Conf: high | Well-known architectural parameter 'MXLEN' + NUM_EXTERNAL_GUEST_INTERRUPTS + Type: conditional | Exts: ext:H CSRs: hstatus + Spec: -> hypervisor.adoc:259 + Conf: high | Well-known architectural parameter 'NUM_EXTERNAL_GUEST_INTERRUPTS' + NUM_PMP_ENTRIES + Type: range | Exts: ext:Smpmp CSRs: pmpaddr0, pmpaddr1, pmpaddr10 + Spec: -> machine.adoc:668 [NORM] + Conf: high | Well-known architectural parameter 'NUM_PMP_ENTRIES' + PHYS_ADDR_WIDTH + Type: conditional | Exts: ext:Sm CSRs: pmpaddr0, pmpaddr1, pmpaddr10 + Spec: -> hypervisor.adoc:1027 + Conf: high | Well-known architectural parameter 'PHYS_ADDR_WIDTH' + PMA_GRANULARITY + Type: range | Exts: ext:Sm + Spec: -> cmo.adoc:754 + Conf: high | Well-known architectural parameter 'PMA_GRANULARITY' + PMLEN + Type: value | Exts: (ext:Smmpm OR ext:Smnpm OR ext:Ssnpm) + Spec: -> hypervisor.adoc:807 + Conf: high | Well-known architectural parameter 'PMLEN' + PMP_GRANULARITY + Type: range | Exts: ext:Smpmp CSRs: pmpaddr0, pmpaddr1, pmpaddr10 + Spec: -> cmo.adoc:754 + Conf: high | Well-known architectural parameter 'PMP_GRANULARITY' + PRECISE_SYNCHRONOUS_EXCEPTIONS + Type: binary([True, False]) | Exts: ext:Sm + Spec: -> machine.adoc:1256 [NORM] + Conf: high | Trap/report behavior parameter (matches ^PRECISE_) + REPORT_CAUSE_IN_MTVAL_ON_LANDING_PAD_SOFTWARE_CHECK + Type: binary([True, False]) | Exts: ext:Zicfilp + Spec: -> hypervisor.adoc:25 [NORM] + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_CAUSE_IN_MTVAL_ON_SHADOW_STACK_SOFTWARE_CHECK + Type: binary([True, False]) | Exts: ext:Zicfiss + Spec: -> hypervisor.adoc:25 [NORM] + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_CAUSE_IN_STVAL_ON_LANDING_PAD_SOFTWARE_CHECK + Type: binary([True, False]) | Exts: ext:Zicfilp + Spec: -> supervisor.adoc:707 [NORM] + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_CAUSE_IN_STVAL_ON_SHADOW_STACK_SOFTWARE_CHECK + Type: binary([True, False]) | Exts: ext:Zicfiss + Spec: -> supervisor.adoc:707 [NORM] + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_CAUSE_IN_VSTVAL_ON_LANDING_PAD_SOFTWARE_CHECK + Type: binary([True, False]) | Exts: ext:Zicfilp + Spec: -> hypervisor.adoc:1364 + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_CAUSE_IN_VSTVAL_ON_SHADOW_STACK_SOFTWARE_CHECK + Type: binary([True, False]) | Exts: ext:Zicfiss + Spec: -> hypervisor.adoc:1364 + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_ENCODING_IN_MTVAL_ON_ILLEGAL_INSTRUCTION + Type: binary([True, False]) | Exts: ext:Sm + Spec: -> machine.adoc:2082 + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_ENCODING_IN_STVAL_ON_ILLEGAL_INSTRUCTION + Type: binary([True, False]) | Exts: ext:S + Spec: -> supervisor.adoc:751 + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_ENCODING_IN_VSTVAL_ON_ILLEGAL_INSTRUCTION + Type: binary([True, False]) | Exts: ext:H + Spec: -> hypervisor.adoc:1364 + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_ENCODING_IN_VSTVAL_ON_VIRTUAL_INSTRUCTION + Type: binary([True, False]) | Exts: ext:H + Spec: -> hypervisor.adoc:1364 + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_GPA_IN_HTVAL_ON_GUEST_PAGE_FAULT + Type: binary([True, False]) | Exts: ext:H + Spec: -> hypervisor.adoc:917 + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_GPA_IN_TVAL_ON_INSTRUCTION_GUEST_PAGE_FAULT + Type: binary([True, False]) | Exts: ext:H CSRs: htval, mtval2 + Spec: -> hypervisor.adoc:2832 + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_GPA_IN_TVAL_ON_INTERMEDIATE_GUEST_PAGE_FAULT + Type: binary([True, False]) | Exts: ext:H CSRs: htval, mtval2 + Spec: -> hypervisor.adoc:2832 + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_GPA_IN_TVAL_ON_LOAD_GUEST_PAGE_FAULT + Type: binary([True, False]) | Exts: ext:H CSRs: htval, mtval2 + Spec: -> hypervisor.adoc:2832 + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_GPA_IN_TVAL_ON_STORE_AMO_GUEST_PAGE_FAULT + Type: binary([True, False]) | Exts: ext:H CSRs: htval, mtval2 + Spec: -> hypervisor.adoc:2832 + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_VA_IN_MTVAL_ON_BREAKPOINT + Type: binary([True, False]) | Exts: ext:Sm + Spec: -> machine.adoc:2049 + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_VA_IN_MTVAL_ON_INSTRUCTION_ACCESS_FAULT + Type: binary([True, False]) | Exts: ext:Sm + Spec: -> hypervisor.adoc:25 [NORM] + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_VA_IN_MTVAL_ON_INSTRUCTION_MISALIGNED + Type: binary([True, False]) | Exts: ext:Sm + Spec: -> hypervisor.adoc:25 [NORM] + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_VA_IN_MTVAL_ON_INSTRUCTION_PAGE_FAULT + Type: binary([True, False]) | Exts: ext:S + Spec: -> hypervisor.adoc:25 [NORM] + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_VA_IN_MTVAL_ON_LOAD_ACCESS_FAULT + Type: binary([True, False]) | Exts: ext:Sm + Spec: -> hypervisor.adoc:25 [NORM] + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_VA_IN_MTVAL_ON_LOAD_MISALIGNED + Type: binary([True, False]) | Exts: ext:Sm + Spec: -> machine.adoc:2067 + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_VA_IN_MTVAL_ON_LOAD_PAGE_FAULT + Type: binary([True, False]) | Exts: ext:S + Spec: -> hypervisor.adoc:25 [NORM] + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_VA_IN_MTVAL_ON_STORE_AMO_ACCESS_FAULT + Type: binary([True, False]) | Exts: ext:Sm + Spec: -> hypervisor.adoc:25 [NORM] + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_VA_IN_MTVAL_ON_STORE_AMO_MISALIGNED + Type: binary([True, False]) | Exts: ext:Sm + Spec: -> hypervisor.adoc:25 [NORM] + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_VA_IN_MTVAL_ON_STORE_AMO_PAGE_FAULT + Type: binary([True, False]) | Exts: ext:S + Spec: -> hypervisor.adoc:25 [NORM] + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_VA_IN_STVAL_ON_BREAKPOINT + Type: binary([True, False]) | Exts: ext:S + Spec: -> supervisor.adoc:726 + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_VA_IN_STVAL_ON_INSTRUCTION_ACCESS_FAULT + Type: binary([True, False]) | Exts: ext:S + Spec: -> hypervisor.adoc:936 + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_VA_IN_STVAL_ON_INSTRUCTION_MISALIGNED + Type: binary([True, False]) | Exts: ext:S + Spec: -> supervisor.adoc:726 + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_VA_IN_STVAL_ON_INSTRUCTION_PAGE_FAULT + Type: binary([True, False]) | Exts: ext:S + Spec: -> hypervisor.adoc:936 + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_VA_IN_STVAL_ON_LOAD_ACCESS_FAULT + Type: binary([True, False]) | Exts: ext:S + Spec: -> supervisor.adoc:707 [NORM] + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_VA_IN_STVAL_ON_LOAD_MISALIGNED + Type: binary([True, False]) | Exts: ext:S + Spec: -> supervisor.adoc:734 + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_VA_IN_STVAL_ON_LOAD_PAGE_FAULT + Type: binary([True, False]) | Exts: ext:S + Spec: -> hypervisor.adoc:2046 + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_VA_IN_STVAL_ON_STORE_AMO_ACCESS_FAULT + Type: binary([True, False]) | Exts: ext:S + Spec: -> supervisor.adoc:707 [NORM] + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_VA_IN_STVAL_ON_STORE_AMO_MISALIGNED + Type: binary([True, False]) | Exts: ext:S + Spec: -> supervisor.adoc:734 + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_VA_IN_STVAL_ON_STORE_AMO_PAGE_FAULT + Type: binary([True, False]) | Exts: ext:S + Spec: -> hypervisor.adoc:2046 + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_VA_IN_VSTVAL_ON_BREAKPOINT + Type: binary([True, False]) | Exts: ext:H + Spec: -> hypervisor.adoc:1364 + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_VA_IN_VSTVAL_ON_INSTRUCTION_ACCESS_FAULT + Type: binary([True, False]) | Exts: ext:H + Spec: -> zc.adoc:1183 [NORM] + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_VA_IN_VSTVAL_ON_INSTRUCTION_MISALIGNED + Type: binary([True, False]) | Exts: ext:H + Spec: -> c-st-ext.adoc:310 [NORM] + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_VA_IN_VSTVAL_ON_INSTRUCTION_PAGE_FAULT + Type: binary([True, False]) | Exts: ext:H + Spec: -> zc.adoc:1183 [NORM] + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_VA_IN_VSTVAL_ON_LOAD_ACCESS_FAULT + Type: binary([True, False]) | Exts: ext:H + Spec: -> hypervisor.adoc:1371 + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_VA_IN_VSTVAL_ON_LOAD_MISALIGNED + Type: binary([True, False]) | Exts: ext:H + Spec: -> hypervisor.adoc:1364 + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_VA_IN_VSTVAL_ON_LOAD_PAGE_FAULT + Type: binary([True, False]) | Exts: ext:H + Spec: -> hypervisor.adoc:1364 + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_VA_IN_VSTVAL_ON_STORE_AMO_ACCESS_FAULT + Type: binary([True, False]) | Exts: ext:H + Spec: -> hypervisor.adoc:1371 + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_VA_IN_VSTVAL_ON_STORE_AMO_MISALIGNED + Type: binary([True, False]) | Exts: ext:H + Spec: -> hypervisor.adoc:1364 + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + REPORT_VA_IN_VSTVAL_ON_STORE_AMO_PAGE_FAULT + Type: binary([True, False]) | Exts: ext:H + Spec: -> hypervisor.adoc:1364 + Conf: high | Trap/report behavior parameter (matches ^REPORT_) + RVV_VL_WHEN_AVL_LT_DOUBLE_VLMAX + Type: enum(3 vals) | Exts: ext:V + Spec: -> v-st-ext.adoc:1279 [NORM] + Conf: low | No strong signals; defaulting to direct normative parameter + STVAL_WIDTH + Type: range | Exts: ext:S + Spec: -> supervisor.adoc:707 [NORM] + Conf: medium | Trap value reporting parameter + SV32_VSMODE_TRANSLATION + Type: binary([True, False]) | Exts: ext:H AND param:VSXLEN(includes=32) + Spec: -> cmo.adoc:365 [NORM] + Conf: medium | Translation/mode parameter + SV39_VSMODE_TRANSLATION + Type: binary([True, False]) | Exts: ext:H AND param:VSXLEN(includes=64) + Spec: -> cmo.adoc:365 [NORM] + Conf: medium | Translation/mode parameter + SV48_VSMODE_TRANSLATION + Type: binary([True, False]) | Exts: ext:H AND param:VSXLEN(includes=64) + Spec: -> cmo.adoc:365 [NORM] + Conf: medium | Translation/mode parameter + SV57_VSMODE_TRANSLATION + Type: binary([True, False]) | Exts: ext:H AND param:VSXLEN(includes=64) + Spec: -> cmo.adoc:365 [NORM] + Conf: medium | Translation/mode parameter + SXLEN + Type: set | Exts: ext:S CSRs: hstatus, mstatus + Spec: -> machine.adoc:575 + Conf: high | Well-known architectural parameter 'SXLEN' + TIME_CSR_IMPLEMENTED + Type: binary([True, False]) | Exts: ext:Zicntr CSRs: time, timeh + Spec: -> machine.adoc:2621 + Conf: high | Feature/CSR existence parameter ('IMPLEMENTED' suffix) + TRAP_ON_EBREAK + Type: binary([True, False]) | Exts: ext:Sm + Spec: -> rv32.adoc:684 [NORM] + Conf: high | Trap/report behavior parameter (matches ^TRAP_ON_) + TRAP_ON_ECALL_FROM_M + Type: binary([True, False]) | Exts: ext:Sm + Spec: -> rv32.adoc:684 [NORM] + Conf: high | Trap/report behavior parameter (matches ^TRAP_ON_) + TRAP_ON_ECALL_FROM_S + Type: binary([True, False]) | Exts: ext:S + Spec: -> rv32.adoc:925 [NORM] + Conf: high | Trap/report behavior parameter (matches ^TRAP_ON_) + TRAP_ON_ECALL_FROM_U + Type: binary([True, False]) | Exts: ext:U + Spec: -> rv32.adoc:925 [NORM] + Conf: high | Trap/report behavior parameter (matches ^TRAP_ON_) + TRAP_ON_ECALL_FROM_VS + Type: binary([True, False]) | Exts: ext:H + Spec: -> machine.adoc:932 [NORM] + Conf: high | Trap/report behavior parameter (matches ^TRAP_ON_) + TRAP_ON_ILLEGAL_WLRL + Type: binary([True, False]) | Exts: ext:Sm + Spec: -> hypervisor.adoc:25 [NORM] + Conf: high | Trap/report behavior parameter (matches ^TRAP_ON_) + TRAP_ON_RESERVED_INSTRUCTION + Type: binary([True, False]) | Exts: ext:Sm + Spec: -> c-st-ext.adoc:756 [NORM] + Conf: high | Trap/report behavior parameter (matches ^TRAP_ON_) + TRAP_ON_SFENCE_VMA_WHEN_SATP_MODE_IS_READ_ONLY + Type: binary([True, False]) | Exts: ext:S AND NONE(ext:Sv32, ext:Sv39, ext:Sv48, ext:Sv57) + Spec: -> hypervisor.adoc:250 + Conf: high | Trap/report behavior parameter (matches ^TRAP_ON_) + TRAP_ON_UNIMPLEMENTED_CSR + Type: binary([True, False]) | Exts: ext:Sm + Spec: -> v-st-ext.adoc:5140 [NORM] + Conf: high | Trap/report behavior parameter (matches ^TRAP_ON_) + TRAP_ON_UNIMPLEMENTED_INSTRUCTION + Type: binary([True, False]) | Exts: ext:Sm + Spec: -> c-st-ext.adoc:310 [NORM] + Conf: high | Trap/report behavior parameter (matches ^TRAP_ON_) + UXLEN + Type: set | Exts: ext:U CSRs: mstatus + Spec: -> machine.adoc:575 + Conf: high | Well-known architectural parameter 'UXLEN' + VENDOR_ID_BANK + Type: range | Exts: ext:Sm CSRs: mvendorid + Spec: -> machine.adoc:263 [NORM] + Conf: high | Well-known architectural parameter 'VENDOR_ID_BANK' + VENDOR_ID_OFFSET + Type: range | Exts: ext:Sm CSRs: mvendorid + Spec: -> machine.adoc:263 [NORM] + Conf: high | Well-known architectural parameter 'VENDOR_ID_OFFSET' + VLEN + Type: value | Exts: ext:V CSRs: vlenb, vstart + Spec: -> v-st-ext.adoc:511 + Conf: high | Well-known architectural parameter 'VLEN' + VMID_WIDTH + Type: conditional | Exts: ext:H CSRs: hgatp + Spec: -> hypervisor.adoc:1089 + Conf: high | Well-known architectural parameter 'VMID_WIDTH' + VSSTAGE_MODE_BARE + Type: binary([True, False]) | Exts: ext:H + Spec: -> priv-cfi.adoc:216 [NORM] + Conf: medium | Translation/mode parameter + VSXLEN + Type: set | Exts: ext:H CSRs: hstatus + Spec: -> hypervisor.adoc:1184 + Conf: high | Well-known architectural parameter 'VSXLEN' + VUXLEN + Type: set | Exts: ext:H CSRs: vsstatus + Spec: -> hypervisor.adoc:1181 + Conf: high | Well-known architectural parameter 'VUXLEN' + + --- NORM_CSR_WARL (26 parameters) --- + DBG_HCONTEXT_WIDTH + Type: range | Exts: ext:Sdtrig CSRs: hcontext, mcontext + Spec: -> smstateen.adoc:287 + Conf: high | Referenced in sw_write() of hcontext.HCONTEXT + DBG_SCONTEXT_WIDTH + Type: range | Exts: ext:Sdtrig CSRs: scontext + Spec: -> hypervisor.adoc:146 + Conf: high | Referenced in sw_write() of scontext.DATA + FORCE_UPGRADE_CBO_INVAL_TO_FLUSH + Type: binary([True, False]) | Exts: ext:Zicbom CSRs: menvcfg + Spec: -> supervisor.adoc:913 + Conf: high | Referenced in sw_write() of menvcfg.CBIE + GSTAGE_MODE_BARE + Type: binary([True, False]) | Exts: ext:H CSRs: hgatp + Spec: -> hypervisor.adoc:1075 + Conf: high | Referenced in sw_write() of hgatp.MODE + HPM_EVENTS + Type: set | Exts: ext:Smhpm CSRs: mhpmevent10, mhpmevent11, mhpmevent12 + Spec: -> machine.adoc:1581 + Conf: high | Referenced in sw_write() of mhpmevent14.EVENT + IGNORE_INVALID_VSATP_MODE_WRITES_WHEN_V_EQ_ZERO + Type: binary([True, False]) | Exts: ext:H CSRs: vsatp + Spec: -> hypervisor.adoc:1416 + Conf: high | Referenced in sw_write() of vsatp.MODE + JVT_BASE_MASK + Type: range | Exts: ext:Zcmt AND param:JVT_BASE_TYPE(equal=mask) CSRs: jvt + Spec: -> c-st-ext.adoc:466 [NORM] + Conf: high | Referenced in sw_write() of jvt.BASE + JVT_BASE_TYPE + Type: binary(['mask', 'custom']) | Exts: ext:Zcmt CSRs: jvt + Spec: -> c-st-ext.adoc:466 [NORM] + Conf: high | Referenced in sw_write() of jvt.BASE + JVT_READ_ONLY + Type: binary([True, False]) | Exts: ext:Zcmt CSRs: jvt + Spec: -> zc.adoc:2341 [NORM] + Conf: high | Referenced in sw_write() of jvt.MODE + MCID_WIDTH + Type: range | Exts: ext:Ssqosid CSRs: srmcfg + Spec: -> supervisor.adoc:2586 + Conf: high | Referenced in sw_write() of srmcfg.MCID + MSTATUS_FS_LEGAL_VALUES + Type: set | Exts: (ext:F OR ext:S) CSRs: mstatus + Spec: -> machine.adoc:679 [NORM] + Conf: high | Referenced in sw_write() of mstatus.FS + MSTATUS_VS_LEGAL_VALUES + Type: set | Exts: (ext:V OR ext:S) CSRs: mstatus + Spec: -> machine.adoc:679 [NORM] + Conf: high | Referenced in sw_write() of mstatus.VS + MTVEC_BASE_ALIGNMENT_DIRECT + Type: conditional | Exts: ext:Sm AND {'param': {'allOf': [{'name': 'MTVEC_MODES', 'includes': 0, 'reason': 'Only rele + Spec: -> machine.adoc:1209 [NORM] + Conf: low | Name pattern suggests CSR 'mtvec' association, but no IDL cross-reference found + MTVEC_BASE_ALIGNMENT_VECTORED + Type: conditional | Exts: ext:Sm AND {'param': {'allOf': [{'name': 'MTVEC_MODES', 'includes': 1, 'reason': 'Only rele + Spec: -> priv-preface.adoc:540 + Conf: low | Name pattern suggests CSR 'mtvec' association, but no IDL cross-reference found + MTVEC_ILLEGAL_WRITE_BEHAVIOR + Type: binary(['retain', 'custom']) | Exts: ext:Sm CSRs: mtvec + Spec: -> machine.adoc:1209 [NORM] + Conf: high | Referenced in sw_write() of mtvec.BASE + MTVEC_MODES + Type: set | Exts: ext:Sm CSRs: mtvec + Spec: -> machine.adoc:1255 + Conf: high | Referenced in sw_write() of mtvec.BASE + RCID_WIDTH + Type: range | Exts: ext:Ssqosid CSRs: srmcfg + Spec: -> supervisor.adoc:2586 + Conf: high | Referenced in sw_write() of srmcfg.RCID + SATP_MODE_BARE + Type: binary([True, False]) | Exts: ext:S CSRs: satp + Spec: -> machine.adoc:670 [NORM] + Conf: high | Referenced in sw_write() of satp.MODE + STVEC_MODE_DIRECT + Type: binary([True, False]) | Exts: ext:S CSRs: stvec + Spec: -> hypervisor.adoc:1304 + Conf: high | Referenced in sw_write() of stvec.MODE + STVEC_MODE_VECTORED + Type: binary([True, False]) | Exts: ext:S CSRs: stvec + Spec: -> machine.adoc:1256 [NORM] + Conf: high | Referenced in sw_write() of stvec.MODE + SV32X4_TRANSLATION + Type: binary([True, False]) | Exts: ext:H AND param:SXLEN(includes=32) CSRs: hgatp + Spec: -> hypervisor.adoc:1915 + Conf: high | Referenced in sw_write() of hgatp.MODE + SV39X4_TRANSLATION + Type: binary([True, False]) | Exts: ext:H AND param:SXLEN(includes=64) CSRs: hgatp + Spec: -> hypervisor.adoc:1007 + Conf: high | Referenced in sw_write() of hgatp.MODE + SV48X4_TRANSLATION + Type: binary([True, False]) | Exts: ext:H AND param:SXLEN(includes=64) CSRs: hgatp + Spec: -> hypervisor.adoc:1007 + Conf: high | Referenced in sw_write() of hgatp.MODE + SV57X4_TRANSLATION + Type: binary([True, False]) | Exts: ext:H AND param:SXLEN(includes=64) CSRs: hgatp + Spec: -> hypervisor.adoc:1007 + Conf: high | Referenced in sw_write() of hgatp.MODE + VSTVEC_MODE_DIRECT + Type: binary([True, False]) | Exts: ext:H CSRs: vstvec + Spec: -> machine.adoc:423 [NORM] + Conf: high | Referenced in sw_write() of vstvec.MODE + VSTVEC_MODE_VECTORED + Type: binary([True, False]) | Exts: ext:H CSRs: vstvec + Spec: -> machine.adoc:1256 [NORM] + Conf: high | Referenced in sw_write() of vstvec.MODE + + --- NORM_CSR_RW (55 parameters) --- + COUNTINHIBIT_EN + Type: bitmask | Exts: ext:Sm CSRs: mcountinhibit + Spec: -> machine.adoc:1669 [NORM] + Conf: high | Controls type (RO/RW) of mcountinhibit.CY + DCSR_MPRVEN_TYPE + Type: enum(3 vals) | Exts: ext:Sdtrig CSRs: dcsr + Spec: -> priv-cfi.adoc:87 + Conf: high | Controls type (RO/RW) of dcsr.MPRVEN + DCSR_STEPIE_TYPE + Type: enum(3 vals) | Exts: ext:Sdtrig CSRs: dcsr + Spec: -> priv-cfi.adoc:87 + Conf: high | Controls type (RO/RW) of dcsr.STEPIE + DCSR_STOPCOUNT_TYPE + Type: enum(3 vals) | Exts: ext:Sdtrig CSRs: dcsr + Spec: -> priv-cfi.adoc:87 + Conf: high | Controls type (RO/RW) of dcsr.STOPCOUNT + DCSR_STOPTIME_TYPE + Type: enum(3 vals) | Exts: ext:Sdtrig CSRs: dcsr + Spec: -> priv-cfi.adoc:87 + Conf: high | Controls type (RO/RW) of dcsr.STOPTIME + HCOUNTENABLE_EN + Type: bitmask | Exts: ext:H CSRs: hcounteren + Spec: -> hypervisor.adoc:857 + Conf: high | Controls type (RO/RW) of hcounteren.CY + HPM_COUNTER_EN + Type: bitmask | Exts: ext:Smhpm CSRs: mhpmcounter10, mhpmcounter10h, mhpmcounter11 + Spec: -> machine.adoc:1615 [NORM] + Conf: high | Controls type (RO/RW) of scountovf.OF3 + HSTATEEN_AIA_TYPE + Type: enum(3 vals) | Exts: ext:Ssaia AND ext:H AND ext:Ssstateen + Conf: low | CSR field type control parameter for 'hstateen' (determines RO/RW behavior) + HSTATEEN_CONTEXT_TYPE + Type: enum(3 vals) | Exts: ext:Sdtrig AND ext:H AND ext:Ssstateen + Spec: -> smctr.adoc:652 [NORM] + Conf: low | CSR field type control parameter for 'hstateen' (determines RO/RW behavior) + HSTATEEN_CSRIND_TYPE + Type: enum(3 vals) | Exts: ext:Sscsrind AND ext:H AND ext:Ssstateen + Spec: -> smstateen.adoc:191 + Conf: low | CSR field type control parameter for 'hstateen' (determines RO/RW behavior) + HSTATEEN_ENVCFG_TYPE + Type: enum(3 vals) | Exts: ext:H(~> 1.0) AND ext:Ssstateen(~> 1.0) + Spec: -> priv-cfi.adoc:134 + Conf: low | CSR field type control parameter for 'hstateen' (determines RO/RW behavior) + HSTATEEN_IMSIC_TYPE + Type: enum(3 vals) | Exts: ext:Ssaia AND ext:H AND ext:Ssstateen + Spec: -> smstateen.adoc:189 + Conf: low | CSR field type control parameter for 'hstateen' (determines RO/RW behavior) + HSTATEEN_JVT_TYPE + Type: enum(3 vals) | Exts: ext:Zcmt AND ext:H AND ext:Ssstateen + Spec: -> zc.adoc:2341 [NORM] + Conf: low | CSR field type control parameter for 'hstateen' (determines RO/RW behavior) + MCOUNTENABLE_EN + Type: bitmask | Exts: ext:U CSRs: mcounteren + Spec: -> machine.adoc:1656 [NORM] + Conf: high | Controls type (RO/RW) of mcounteren.CY + MSTATEEN_AIA_TYPE + Type: enum(3 vals) | Exts: ext:Ssaia AND ext:Smstateen(~> 1.0) + Conf: low | CSR field type control parameter for 'mstateen' (determines RO/RW behavior) + MSTATEEN_CONTEXT_TYPE + Type: enum(3 vals) | Exts: ext:Sdtrig AND ext:Smstateen + Spec: -> smctr.adoc:652 [NORM] + Conf: low | CSR field type control parameter for 'mstateen' (determines RO/RW behavior) + MSTATEEN_CSRIND_TYPE + Type: enum(3 vals) | Exts: ext:Sscsrind AND ext:Smstateen + Spec: -> smstateen.adoc:191 + Conf: low | CSR field type control parameter for 'mstateen' (determines RO/RW behavior) + MSTATEEN_ENVCFG_TYPE + Type: enum(3 vals) | Exts: ext:S AND ext:Smstateen + Spec: -> priv-cfi.adoc:134 + Conf: low | CSR field type control parameter for 'mstateen' (determines RO/RW behavior) + MSTATEEN_IMSIC_TYPE + Type: enum(3 vals) | Exts: ext:Ssaia AND ext:Smstateen(~> 1.0) + Spec: -> smstateen.adoc:189 + Conf: low | CSR field type control parameter for 'mstateen' (determines RO/RW behavior) + MSTATEEN_JVT_TYPE + Type: enum(3 vals) | Exts: ext:Zcmt AND ext:Smstateen(~> 1.0) + Spec: -> zc.adoc:2341 [NORM] + Conf: low | CSR field type control parameter for 'mstateen' (determines RO/RW behavior) + MTVEC_ACCESS + Type: binary(['ro', 'rw']) | Exts: ext:Sm CSRs: mtvec + Spec: -> machine.adoc:1209 [NORM] + Conf: high | Controls type (RO/RW) of mtvec.BASE + MUTABLE_MISA_A + Type: binary([True, False]) | Exts: ext:A CSRs: misa + Spec: -> machine.adoc:21 [NORM] + Conf: high | Controls type (RO/RW) of misa.A + MUTABLE_MISA_B + Type: binary([True, False]) | Exts: ext:B CSRs: misa + Spec: -> machine.adoc:21 [NORM] + Conf: high | Controls type (RO/RW) of misa.B + MUTABLE_MISA_C + Type: binary([True, False]) | Exts: ext:C CSRs: misa + Spec: -> machine.adoc:21 [NORM] + Conf: high | Controls type (RO/RW) of misa.C + MUTABLE_MISA_D + Type: binary([True, False]) | Exts: ext:D CSRs: misa + Spec: -> machine.adoc:21 [NORM] + Conf: high | Controls type (RO/RW) of misa.D + MUTABLE_MISA_F + Type: binary([True, False]) | Exts: ext:F CSRs: misa + Spec: -> machine.adoc:21 [NORM] + Conf: high | Controls type (RO/RW) of misa.F + MUTABLE_MISA_H + Type: binary([True, False]) | Exts: ext:H CSRs: misa + Spec: -> machine.adoc:21 [NORM] + Conf: high | Controls type (RO/RW) of misa.H + MUTABLE_MISA_M + Type: binary([True, False]) | Exts: ext:M CSRs: misa + Spec: -> machine.adoc:21 [NORM] + Conf: high | Controls type (RO/RW) of misa.G + MUTABLE_MISA_Q + Type: binary([True, False]) | Exts: ext:Q CSRs: misa + Spec: -> machine.adoc:21 [NORM] + Conf: high | Controls type (RO/RW) of misa.Q + MUTABLE_MISA_S + Type: binary([True, False]) | Exts: ext:S CSRs: misa + Spec: -> machine.adoc:21 [NORM] + Conf: high | Controls type (RO/RW) of misa.S + MUTABLE_MISA_U + Type: binary([True, False]) | Exts: ext:U CSRs: misa + Spec: -> machine.adoc:21 [NORM] + Conf: high | Controls type (RO/RW) of misa.U + MUTABLE_MISA_V + Type: binary([True, False]) | Exts: ext:V CSRs: misa + Spec: -> v-st-ext.adoc:5161 [NORM] + Conf: high | Controls type (RO/RW) of misa.V + M_MODE_ENDIANNESS + Type: enum(3 vals) | Exts: ext:Sm CSRs: mstatus, mstatush + Spec: -> machine.adoc:679 [NORM] + Conf: high | Controls type (RO/RW) of mstatus.MBE + SCOUNTENABLE_EN + Type: bitmask | Exts: ext:S AND (ext:Zicntr OR ext:Zihpm) CSRs: scounteren + Spec: -> supervisor.adoc:511 + Conf: high | Controls type (RO/RW) of scounteren.CY + SSTATEEN_JVT_TYPE + Type: enum(3 vals) | Exts: ext:Zcmt AND ext:Ssstateen + Spec: -> zc.adoc:2341 [NORM] + Conf: low | CSR field type control parameter for 'sstateen' (determines RO/RW behavior) + S_MODE_ENDIANNESS + Type: enum(3 vals) | Exts: ext:S CSRs: mstatus, mstatush + Spec: -> machine.adoc:679 [NORM] + Conf: high | Controls type (RO/RW) of mstatus.SBE + TINST_VALUE_ON_BREAKPOINT + Type: binary(['always zero', 'custom']) | Exts: ext:H CSRs: htinst, mtinst + Spec: -> hypervisor.adoc:983 + Conf: high | Controls type (RO/RW) of htinst.VALUE + TINST_VALUE_ON_FINAL_INSTRUCTION_GUEST_PAGE_FAULT + Type: binary(['always zero', 'always pseudoinstruction']) | Exts: ext:H CSRs: htinst, mtinst + Spec: -> hypervisor.adoc:2567 + Conf: high | Controls type (RO/RW) of htinst.VALUE + TINST_VALUE_ON_FINAL_LOAD_GUEST_PAGE_FAULT + Type: enum(4 vals) | Exts: ext:H CSRs: htinst, mtinst + Spec: -> hypervisor.adoc:983 + Conf: high | Controls type (RO/RW) of htinst.VALUE + TINST_VALUE_ON_FINAL_STORE_AMO_GUEST_PAGE_FAULT + Type: enum(4 vals) | Exts: ext:H CSRs: htinst, mtinst + Spec: -> hypervisor.adoc:983 + Conf: high | Controls type (RO/RW) of htinst.VALUE + TINST_VALUE_ON_INSTRUCTION_ADDRESS_MISALIGNED + Type: binary(['always zero', 'custom']) | Exts: ext:H CSRs: htinst, mtinst + Spec: -> hypervisor.adoc:2567 + Conf: high | Controls type (RO/RW) of htinst.VALUE + TINST_VALUE_ON_LOAD_ACCESS_FAULT + Type: enum(3 vals) | Exts: ext:H CSRs: htinst, mtinst + Spec: -> hypervisor.adoc:983 + Conf: high | Controls type (RO/RW) of htinst.VALUE + TINST_VALUE_ON_LOAD_ADDRESS_MISALIGNED + Type: enum(3 vals) | Exts: ext:H CSRs: htinst, mtinst + Spec: -> hypervisor.adoc:983 + Conf: high | Controls type (RO/RW) of htinst.VALUE + TINST_VALUE_ON_LOAD_PAGE_FAULT + Type: enum(3 vals) | Exts: ext:H CSRs: htinst, mtinst + Spec: -> hypervisor.adoc:983 + Conf: high | Controls type (RO/RW) of htinst.VALUE + TINST_VALUE_ON_MCALL + Type: binary(['always zero', 'custom']) | Exts: ext:H CSRs: htinst, mtinst + Spec: -> hypervisor.adoc:983 + Conf: high | Controls type (RO/RW) of htinst.VALUE + TINST_VALUE_ON_SCALL + Type: binary(['always zero', 'custom']) | Exts: ext:H CSRs: htinst, mtinst + Spec: -> hypervisor.adoc:983 + Conf: high | Controls type (RO/RW) of htinst.VALUE + TINST_VALUE_ON_STORE_AMO_ACCESS_FAULT + Type: enum(3 vals) | Exts: ext:H CSRs: htinst, mtinst + Spec: -> hypervisor.adoc:983 + Conf: high | Controls type (RO/RW) of htinst.VALUE + TINST_VALUE_ON_STORE_AMO_ADDRESS_MISALIGNED + Type: enum(3 vals) | Exts: ext:H CSRs: htinst, mtinst + Spec: -> hypervisor.adoc:983 + Conf: high | Controls type (RO/RW) of htinst.VALUE + TINST_VALUE_ON_STORE_AMO_PAGE_FAULT + Type: enum(3 vals) | Exts: ext:H CSRs: htinst, mtinst + Spec: -> hypervisor.adoc:983 + Conf: high | Controls type (RO/RW) of htinst.VALUE + TINST_VALUE_ON_UCALL + Type: binary(['always zero', 'custom']) | Exts: ext:H CSRs: htinst, mtinst + Spec: -> hypervisor.adoc:983 + Conf: high | Controls type (RO/RW) of htinst.VALUE + TINST_VALUE_ON_VIRTUAL_INSTRUCTION + Type: binary(['always zero', 'custom']) | Exts: ext:H CSRs: htinst, mtinst + Spec: -> smctr.adoc:218 [NORM] + Conf: high | Controls type (RO/RW) of htinst.VALUE + TINST_VALUE_ON_VSCALL + Type: binary(['always zero', 'custom']) | Exts: ext:H CSRs: htinst, mtinst + Spec: -> hypervisor.adoc:983 + Conf: high | Controls type (RO/RW) of htinst.VALUE + U_MODE_ENDIANNESS + Type: enum(3 vals) | Exts: ext:U CSRs: mstatus + Spec: -> machine.adoc:679 [NORM] + Conf: high | Controls type (RO/RW) of mstatus.UBE + VS_MODE_ENDIANNESS + Type: enum(3 vals) | Exts: ext:H CSRs: hstatus + Spec: -> hypervisor.adoc:339 + Conf: high | Controls type (RO/RW) of hstatus.VSBE + VU_MODE_ENDIANNESS + Type: enum(3 vals) | Exts: ext:H CSRs: vsstatus + Spec: -> hypervisor.adoc:2359 [NORM] + Conf: high | Controls type (RO/RW) of vsstatus.UBE + + --- SW_RULE (2 parameters) --- + HW_MSTATUS_FS_DIRTY_UPDATE + Type: enum(3 vals) | Exts: ext:F CSRs: mstatus + Spec: -> v-st-ext.adoc:3313 [NORM] + Conf: medium | Hardware update behavior (HW_ prefix) — software-deterministic with correct fencing + HW_MSTATUS_VS_DIRTY_UPDATE + Type: enum(3 vals) | Exts: ext:V CSRs: mstatus + Spec: -> v-st-ext.adoc:107 + Conf: medium | Hardware update behavior (HW_ prefix) — software-deterministic with correct fencing + +======================================================================== +END OF REPORT +======================================================================== \ No newline at end of file diff --git a/param_extraction/data/spec_mappings.json b/param_extraction/data/spec_mappings.json new file mode 100644 index 0000000000..695250ae3c --- /dev/null +++ b/param_extraction/data/spec_mappings.json @@ -0,0 +1,13975 @@ +{ + "metadata": { + "total_parameters": 185, + "params_with_matches": 183, + "params_with_strong_matches": 161, + "spec_files_searched": 74, + "total_spec_lines": 52602 + }, + "mappings": [ + { + "parameter_name": "ARCH_ID_VALUE", + "classification": "NORM_DIRECT", + "value_type": "conditional", + "num_candidates": 7, + "best_score": 8, + "candidates": [ + { + "score": 8, + "reasons": [ + "Description keyword 'marchid'", + "CSR field name 'Architecture'", + "CSR name 'marchid' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 297, + "line_text": "==== Machine Architecture ID (`marchid`) Register", + "context": " 295| ====\n 296| \n>>> 297| ==== Machine Architecture ID (`marchid`) Register\n 298| \n 299| [#norm:marchid_sz_acc_op]#The `marchid` CSR is an MXLEN-bit read-only register encoding the base" + }, + { + "score": 8, + "reasons": [ + "Description keyword 'marchid'", + "CSR name 'marchid' in backticks" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 299, + "line_text": "[#norm:marchid_sz_acc_op]#The `marchid` CSR is an MXLEN-bit read-only register encoding the base", + "context": " 297| ==== Machine Architecture ID (`marchid`) Register\n 298| \n>>> 299| [#norm:marchid_sz_acc_op]#The `marchid` CSR is an MXLEN-bit read-only register encoding the base\n 300| microarchitecture of the hart.#\n 301| [#norm:marchid_always_rd]#This register must be readable in any" + }, + { + "score": 8, + "reasons": [ + "Description keyword 'marchid'", + "CSR field name 'Architecture'", + "CSR name 'marchid' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 305, + "line_text": ".Machine Architecture ID (`marchid`) register", + "context": " 303| The combination of `mvendorid` and `marchid` should uniquely identify the type of hart microarchitecture that is implemented.\n 304| \n>>> 305| .Machine Architecture ID (`marchid`) register\n 306| include::images/bytefield/marchid.edn[]\n 307| " + }, + { + "score": 6, + "reasons": [ + "Description keyword 'marchid'", + "CSR name 'marchid' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 303, + "line_text": "The combination of `mvendorid` and `marchid` should uniquely identify the type of hart microarchitecture that is implemented.", + "context": " 301| [#norm:marchid_always_rd]#This register must be readable in any\n 302| implementation, but a value of 0 can be returned to indicate the field is not implemented.#\n>>> 303| The combination of `mvendorid` and `marchid` should uniquely identify the type of hart microarchitecture that is implemented.\n 304| \n 305| .Machine Architecture ID (`marchid`) register" + }, + { + "score": 6, + "reasons": [ + "Description keyword 'marchid'", + "CSR name 'marchid' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "priv-csrs.adoc", + "line_number": 650, + "line_text": "`marchid` +", + "context": " 648| MRO\n 649| |`mvendorid` +\n>>> 650| `marchid` +\n 651| `mimpid` +\n 652| `mhartid` +" + } + ] + }, + { + "parameter_name": "ASID_WIDTH", + "classification": "NORM_DIRECT", + "value_type": "conditional", + "num_candidates": 10, + "best_score": 5, + "candidates": [ + { + "score": 5, + "reasons": [ + "Description keyword 'ASID'", + "Name segment 'ASID'" + ], + "is_normative": true, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 1373, + "line_text": "[#norm:sfence-vma-asid_effect]#Likewise, changes to `satp`.ASID take effect immediately.#", + "context": " 1371| `satp`.MODE from Bare to other modes and vice versa also takes effect\n 1372| immediately, without the need to execute an SFENCE.VMA instruction.#\n>>> 1373| [#norm:sfence-vma-asid_effect]#Likewise, changes to `satp`.ASID take effect immediately.#\n 1374| \n 1375| [NOTE]" + }, + { + "score": 3, + "reasons": [ + "Description keyword 'ASID'", + "Name segment 'ASID'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1559, + "line_text": "at the time HFENCE.VVMA executed. If operand __rs1__≠`x0`, it specifies a single guest virtual address, and if operand __rs2__≠`x0`, it specifies a single guest address-space identifier (ASID).", + "context": " 1557| [[norm:hfence-vvma_limits]]\n 1558| Implicit reads need not be ordered when `hgatp`.VMID is different than\n>>> 1559| at the time HFENCE.VVMA executed. If operand __rs1__≠`x0`, it specifies a single guest virtual address, and if operand __rs2__≠`x0`, it specifies a single guest address-space identifier (ASID).\n 1560| \n 1561| [NOTE]" + }, + { + "score": 3, + "reasons": [ + "Description keyword 'ASID'", + "Name segment 'ASID'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2075, + "line_text": "HS-level virtual address, and the ASID argument is an HS-level ASID. The", + "context": " 2073| The behavior of the SFENCE.VMA instruction is affected by the current\n 2074| virtualization mode V. When V=0, the virtual-address argument is an\n>>> 2075| HS-level virtual address, and the ASID argument is an HS-level ASID. The\n 2076| instruction orders stores only to HS-level address-translation\n 2077| structures with subsequent HS-level address translations." + }, + { + "score": 3, + "reasons": [ + "Description keyword 'ASID'", + "Name segment 'ASID'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2081, + "line_text": "address within the current virtual machine, and the ASID argument is a", + "context": " 2079| [[norm:sfence-vma_v1]]\n 2080| When V=1, the virtual-address argument to SFENCE.VMA is a guest virtual\n>>> 2081| address within the current virtual machine, and the ASID argument is a\n 2082| VS-level ASID within the current virtual machine. The current virtual\n 2083| machine is identified by the VMID field of CSR `hgatp`, and the" + }, + { + "score": 3, + "reasons": [ + "Description keyword 'ASID'", + "Name segment 'ASID'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2082, + "line_text": "VS-level ASID within the current virtual machine. The current virtual", + "context": " 2080| When V=1, the virtual-address argument to SFENCE.VMA is a guest virtual\n 2081| address within the current virtual machine, and the ASID argument is a\n>>> 2082| VS-level ASID within the current virtual machine. The current virtual\n 2083| machine is identified by the VMID field of CSR `hgatp`, and the\n 2084| effective ASID can be considered to be the combination of this VMID with" + } + ] + }, + { + "parameter_name": "CACHE_BLOCK_SIZE", + "classification": "NORM_DIRECT", + "value_type": "range", + "num_candidates": 10, + "best_score": 5, + "candidates": [ + { + "score": 5, + "reasons": [ + "Name segment 'BLOCK'", + "Name segment 'SIZE'", + "Name segment 'CACHE'" + ], + "is_normative": true, + "in_note": false, + "file": "cmo.adoc", + "line_number": 973, + "line_text": "[#norm:cbo-zero_unaligned]#It is not required that _rs1_ is aligned to the size of a cache block.# On", + "context": " 971| [#norm:cbo-zero_op]#A *cbo.zero* instruction performs stores of zeros to the full set of bytes\n 972| corresponding to the cache block that contains the address specified in _rs1_.#\n>>> 973| [#norm:cbo-zero_unaligned]#It is not required that _rs1_ is aligned to the size of a cache block.# On\n 974| faults, the faulting virtual address is considered to be the value in rs1,\n 975| rather than the base address of the cache block. An implementation may or" + }, + { + "score": 4, + "reasons": [ + "Name segment 'BLOCK'", + "Name segment 'CACHE'" + ], + "is_normative": true, + "in_note": false, + "file": "cmo.adoc", + "line_number": 327, + "line_text": "* [#norm:PMA_same]#The PMAs shall be the same for _all_ physical addresses in the cache block,", + "context": " 325| bits, read permission shall also be granted#\n 326| \n>>> 327| * [#norm:PMA_same]#The PMAs shall be the same for _all_ physical addresses in the cache block,\n 328| and if write permission is granted by the supported access type PMAs, read\n 329| permission shall also be granted#" + }, + { + "score": 4, + "reasons": [ + "Name segment 'BLOCK'", + "Name segment 'CACHE'" + ], + "is_normative": true, + "in_note": false, + "file": "cmo.adoc", + "line_number": 356, + "line_text": "[#norm:cbm_access]#A cache-block management instruction is permitted to access the specified cache", + "context": " 354| whether accesses by cache-block zero instructions are supported.\n 355| \n>>> 356| [#norm:cbm_access]#A cache-block management instruction is permitted to access the specified cache\n 357| block whenever a load instruction or store instruction is permitted to access\n 358| the corresponding physical addresses.# If neither a load instruction nor store" + }, + { + "score": 4, + "reasons": [ + "Name segment 'BLOCK'", + "Name segment 'CACHE'" + ], + "is_normative": true, + "in_note": false, + "file": "cmo.adoc", + "line_number": 361, + "line_text": "management instruction is permitted to access the cache block is UNSPECIFIED. [#norm:cbm_unperm_fault]#If", + "context": " 359| instruction is permitted to access the physical addresses, but an instruction\n 360| fetch is permitted to access the physical addresses, whether a cache-block\n>>> 361| management instruction is permitted to access the cache block is UNSPECIFIED. [#norm:cbm_unperm_fault]#If\n 362| access to the cache block is not permitted, a cache-block management instruction\n 363| raises a store page-fault or store guest-page-fault exception if address" + }, + { + "score": 4, + "reasons": [ + "Name segment 'BLOCK'", + "Name segment 'CACHE'" + ], + "is_normative": true, + "in_note": false, + "file": "cmo.adoc", + "line_number": 377, + "line_text": "[#norm:cbz_access]#A cache-block zero instruction is permitted to access the specified cache block", + "context": " 375| ====\n 376| \n>>> 377| [#norm:cbz_access]#A cache-block zero instruction is permitted to access the specified cache block\n 378| whenever a store instruction is permitted to access the corresponding physical\n 379| addresses and when the PMAs indicate that cache-block zero instructions are a" + } + ] + }, + { + "parameter_name": "CONFIG_PTR_ADDRESS", + "classification": "NORM_DIRECT", + "value_type": "conditional", + "num_candidates": 10, + "best_score": 6, + "candidates": [ + { + "score": 6, + "reasons": [ + "CSR name 'mconfigptr' in backticks", + "Description keyword 'mconfigptr'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 2136, + "line_text": "==== Machine Configuration Pointer (`mconfigptr`) Register", + "context": " 2134| _N_ is the smaller of MXLEN and ILEN.\n 2135| \n>>> 2136| ==== Machine Configuration Pointer (`mconfigptr`) Register\n 2137| \n 2138| The `mconfigptr` register is an MXLEN-bit read-only CSR, formatted as shown in" + }, + { + "score": 6, + "reasons": [ + "CSR name 'mconfigptr' in backticks", + "Description keyword 'mconfigptr'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 2138, + "line_text": "The `mconfigptr` register is an MXLEN-bit read-only CSR, formatted as shown in", + "context": " 2136| ==== Machine Configuration Pointer (`mconfigptr`) Register\n 2137| \n>>> 2138| The `mconfigptr` register is an MXLEN-bit read-only CSR, formatted as shown in\n 2139| <>, that holds the physical\n 2140| address of a configuration data structure. Software can traverse this" + }, + { + "score": 6, + "reasons": [ + "CSR name 'mconfigptr' in backticks", + "Description keyword 'mconfigptr'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 2145, + "line_text": ".Machine Configuration Pointer (`mconfigptr`) register.", + "context": " 2143| \n 2144| [[mconfigptrreg]]\n>>> 2145| .Machine Configuration Pointer (`mconfigptr`) register.\n 2146| include::images/bytefield/mconfigptrreg.edn[]\n 2147| " + }, + { + "score": 6, + "reasons": [ + "CSR name 'mconfigptr' in backticks", + "Description keyword 'mconfigptr'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 2151, + "line_text": "8{times}__n__, then `mconfigptr`[log~2n~-1:0]", + "context": " 2149| The pointer alignment in bits must be no smaller than MXLEN:\n 2150| i.e., if MXLEN is\n>>> 2151| 8{times}__n__, then `mconfigptr`[log~2n~-1:0]\n 2152| must be zero.\n 2153| " + }, + { + "score": 6, + "reasons": [ + "CSR name 'mconfigptr' in backticks", + "Description keyword 'mconfigptr'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 2154, + "line_text": "The `mconfigptr` register must be implemented, but it may be zero to indicate the", + "context": " 2152| must be zero.\n 2153| \n>>> 2154| The `mconfigptr` register must be implemented, but it may be zero to indicate the\n 2155| configuration data structure does not exist or that an alternative\n 2156| mechanism must be used to locate it." + } + ] + }, + { + "parameter_name": "COUNTINHIBIT_EN", + "classification": "NORM_CSR_RW", + "value_type": "bitmask", + "num_candidates": 10, + "best_score": 13, + "candidates": [ + { + "score": 13, + "reasons": [ + "CSR name 'mcountinhibit' in backticks", + "Description keyword 'mcountinhibit'", + "WARL + CSR 'mcountinhibit'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1669, + "line_text": "[#norm:mcountinhibit_sz_warl_op1]#The counter-inhibit register `mcountinhibit` is a 32-bit", + "context": " 1667| include::images/bytefield/counterinh.edn[]\n 1668| \n>>> 1669| [#norm:mcountinhibit_sz_warl_op1]#The counter-inhibit register `mcountinhibit` is a 32-bit\n 1670| *WARL* register that controls which of the hardware performance-monitoring counters increment.#\n 1671| [#norm:mcountinhibit_only_inc]#The settings in this register only control whether the" + }, + { + "score": 12, + "reasons": [ + "CSR name 'mcountinhibit' in backticks", + "CSR field name 'IR'", + "CSR field name 'CY'", + "Description keyword 'mcountinhibit'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1675, + "line_text": "[#norm:mcountinhibit_op2]#When the CY, IR, or HPM__n__ bit in the `mcountinhibit` register is clear,", + "context": " 1673| of this register.#\n 1674| \n>>> 1675| [#norm:mcountinhibit_op2]#When the CY, IR, or HPM__n__ bit in the `mcountinhibit` register is clear,\n 1676| the `mcycle`, `minstret`, or `mhpmcountern` register increments as usual.\n 1677| When the CY, IR, or HPM__n__ bit is set, the corresponding counter does" + }, + { + "score": 8, + "reasons": [ + "Description keyword 'TM'", + "CSR field name 'IR'", + "CSR field name 'CY'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1615, + "line_text": "[#norm:mcounteren_clr_ill_inst_exc]#When the CY, TM, IR, or HPM__n__ bit in the `mcounteren` register is", + "context": " 1613| counters, which continue to increment even when not accessible.#\n 1614| \n>>> 1615| [#norm:mcounteren_clr_ill_inst_exc]#When the CY, TM, IR, or HPM__n__ bit in the `mcounteren` register is\n 1616| clear, attempts to read the `cycle`, `time`, `instret`, or\n 1617| `hpmcountern` register while executing in S-mode or U-mode will cause an" + }, + { + "score": 8, + "reasons": [ + "CSR name 'mcountinhibit' in backticks", + "Description keyword 'mcountinhibit'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1684, + "line_text": "[#norm:mcountinhibit_not_impl]#If the `mcountinhibit` register is not implemented, the implementation", + "context": " 1682| and so writes to `mcountinhibit.CY` will be visible to those harts.#\n 1683| \n>>> 1684| [#norm:mcountinhibit_not_impl]#If the `mcountinhibit` register is not implemented, the implementation\n 1685| behaves as though the register were set to zero.#\n 1686| " + }, + { + "score": 6, + "reasons": [ + "Description keyword 'TM'", + "CSR field name 'IR'", + "CSR field name 'CY'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 857, + "line_text": "When the CY, TM, IR, or HPM__n__ bit in the `hcounteren` register is", + "context": " 855| \n 856| [[norm:hcounteren_op]]\n>>> 857| When the CY, TM, IR, or HPM__n__ bit in the `hcounteren` register is\n 858| clear, attempts to read the `cycle`, `time`, `instret`, or\n 859| `hpmcounter` _n_ register while V=1 will cause a virtual-instruction" + } + ] + }, + { + "parameter_name": "DBG_HCONTEXT_WIDTH", + "classification": "NORM_CSR_WARL", + "value_type": "range", + "num_candidates": 2, + "best_score": 8, + "candidates": [ + { + "score": 8, + "reasons": [ + "Description keyword 'HCONTEXT'", + "CSR field name 'HCONTEXT'", + "Name segment 'HCONTEXT'", + "CSR name 'hcontext' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "smstateen.adoc", + "line_number": 287, + "line_text": "`hcontext` CSRs provided by the Sdtrig extension. The CONTEXT bit in", + "context": " 285| \n 286| The CONTEXT bit in `mstateen0` controls access to the `scontext` and\n>>> 287| `hcontext` CSRs provided by the Sdtrig extension. The CONTEXT bit in\n 288| `hstateen0` controls access to the `scontext` CSR provided by the Sdtrig\n 289| extension." + }, + { + "score": 3, + "reasons": [ + "CSR name 'mcontext' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "priv-csrs.adoc", + "line_number": 1019, + "line_text": "`mcontext`", + "context": " 1017| `tdata2` +\n 1018| `tdata3` +\n>>> 1019| `mcontext`\n 1020| \n 1021| |Debug/Trace trigger register select. +" + } + ] + }, + { + "parameter_name": "DBG_SCONTEXT_WIDTH", + "classification": "NORM_CSR_WARL", + "value_type": "range", + "num_candidates": 10, + "best_score": 6, + "candidates": [ + { + "score": 6, + "reasons": [ + "Description keyword 'SCONTEXT'", + "Name segment 'SCONTEXT'", + "CSR name 'scontext' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 146, + "line_text": "Some standard supervisor CSRs (`senvcfg`, `scounteren`, and `scontext`,", + "context": " 144| \n 145| [[norm:H_scsrs_nomatch]]\n>>> 146| Some standard supervisor CSRs (`senvcfg`, `scounteren`, and `scontext`,\n 147| possibly others) have no matching VS CSR. These supervisor CSRs continue\n 148| to have their usual function and accessibility even when V=1, except" + }, + { + "score": 6, + "reasons": [ + "Description keyword 'SCONTEXT'", + "Name segment 'SCONTEXT'", + "CSR name 'scontext' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "smstateen.adoc", + "line_number": 286, + "line_text": "The CONTEXT bit in `mstateen0` controls access to the `scontext` and", + "context": " 284| bits of `hstateen0`.\n 285| \n>>> 286| The CONTEXT bit in `mstateen0` controls access to the `scontext` and\n 287| `hcontext` CSRs provided by the Sdtrig extension. The CONTEXT bit in\n 288| `hstateen0` controls access to the `scontext` CSR provided by the Sdtrig" + }, + { + "score": 6, + "reasons": [ + "Description keyword 'SCONTEXT'", + "Name segment 'SCONTEXT'", + "CSR name 'scontext' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "smstateen.adoc", + "line_number": 288, + "line_text": "`hstateen0` controls access to the `scontext` CSR provided by the Sdtrig", + "context": " 286| The CONTEXT bit in `mstateen0` controls access to the `scontext` and\n 287| `hcontext` CSRs provided by the Sdtrig extension. The CONTEXT bit in\n>>> 288| `hstateen0` controls access to the `scontext` CSR provided by the Sdtrig\n 289| extension.\n 290| " + }, + { + "score": 4, + "reasons": [ + "CSR field name 'DATA'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 698, + "line_text": "[#norm:mstatus_sbe_implicit]#For _implicit_ accesses to supervisor-level memory management data", + "context": " 696| little-endian (UBE=0) or big-endian (UBE=1).\n 697| \n>>> 698| [#norm:mstatus_sbe_implicit]#For _implicit_ accesses to supervisor-level memory management data\n 699| structures, such as page tables, endianness is always controlled by SBE.#\n 700| [#norm:mstatus_sbe_change_fence]#Since changing SBE alters the implementation’s interpretation of these" + }, + { + "score": 4, + "reasons": [ + "CSR field name 'DATA'" + ], + "is_normative": true, + "in_note": false, + "file": "smctr.adoc", + "line_number": 294, + "line_text": "[#norm:ctrsource_op]#The `ctrsource` register contains the source program counter, which is the `pc` of the recorded control transfer instruction, or the epc of the recorded trap.# [#norm:ctrsource_ctrtartget_ctrdata_Vbit]#The valid (V) bit is set by the hardware when a transfer is recorded in the selected CTR buffer entry, and implies that data in `ctrsource`, `ctrtarget`, and `ctrdata` is valid for this entry.#", + "context": " 292| ==== Control Transfer Record Source Register (`ctrsource`)\n 293| \n>>> 294| [#norm:ctrsource_op]#The `ctrsource` register contains the source program counter, which is the `pc` of the recorded control transfer instruction, or the epc of the recorded trap.# [#norm:ctrsource_ctrtartget_ctrdata_Vbit]#The valid (V) bit is set by the hardware when a transfer is recorded in the selected CTR buffer entry, and implies that data in `ctrsource`, `ctrtarget`, and `ctrdata` is valid for this entry.#\n 295| \n 296| [#norm:Ssctr_ctrsource_sz_acc_op]#`ctrsource` is an MXLEN-bit WARL register that must be able to hold all valid virtual or physical addresses that can serve as a `pc`. It need not be able to hold any invalid addresses; implementations may convert an invalid address into a valid address that the register is capable of holding. When XLEN < MXLEN, both explicit writes (by software) and implicit writes (for recorded transfers) will be zero-extended.#" + } + ] + }, + { + "parameter_name": "DCSR_MPRVEN_TYPE", + "classification": "NORM_CSR_RW", + "value_type": "enum", + "num_candidates": 4, + "best_score": 4, + "candidates": [ + { + "score": 4, + "reasons": [ + "Name segment 'DCSR'", + "CSR name 'dcsr' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "priv-cfi.adoc", + "line_number": 87, + "line_text": "transition to Debug Mode, a `pelp` bit is defined in the `dcsr` register.#", + "context": " 85| the previous `ELP` state on traps to VS-mode, a `SPELP` bit is defined in the\n 86| `vsstatus` (VS-modes version of `sstatus`).# [#norm:dcsr-pelp_op]#To store the previous `ELP` state on\n>>> 87| transition to Debug Mode, a `pelp` bit is defined in the `dcsr` register.#\n 88| \n 89| [[norm:zicflip_pelp_trap]]" + }, + { + "score": 4, + "reasons": [ + "Name segment 'DCSR'", + "CSR name 'dcsr' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "priv-cfi.adoc", + "line_number": 101, + "line_text": "Upon entry into Debug Mode, the `pelp` bit in `dcsr` is updated with the `ELP`", + "context": " 99| \n 100| [[norm:zicflip_pelp_debug_mode]]\n>>> 101| Upon entry into Debug Mode, the `pelp` bit in `dcsr` is updated with the `ELP`\n 102| at the privilege level the hart was previously in, and the `ELP` is set to\n 103| `NO_LP_EXPECTED`. When a hart resumes from Debug Mode, if the new privilege mode" + }, + { + "score": 4, + "reasons": [ + "Name segment 'DCSR'", + "CSR name 'dcsr' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "priv-csrs.adoc", + "line_number": 1037, + "line_text": "|`dcsr` +", + "context": " 1035| DRW +\n 1036| DRW +\n>>> 1037| |`dcsr` +\n 1038| `dpc` +\n 1039| `dscratch0` +" + }, + { + "score": 3, + "reasons": [ + "Name segment 'DCSR'" + ], + "is_normative": true, + "in_note": false, + "file": "priv-cfi.adoc", + "line_number": 86, + "line_text": "`vsstatus` (VS-modes version of `sstatus`).# [#norm:dcsr-pelp_op]#To store the previous `ELP` state on", + "context": " 84| `SPELP` bit in `mstatus` can be accessed through the `sstatus` CSR.# [#norm:vsstatus-spelp_op2]#To store\n 85| the previous `ELP` state on traps to VS-mode, a `SPELP` bit is defined in the\n>>> 86| `vsstatus` (VS-modes version of `sstatus`).# [#norm:dcsr-pelp_op]#To store the previous `ELP` state on\n 87| transition to Debug Mode, a `pelp` bit is defined in the `dcsr` register.#\n 88| " + } + ] + }, + { + "parameter_name": "DCSR_STEPIE_TYPE", + "classification": "NORM_CSR_RW", + "value_type": "enum", + "num_candidates": 4, + "best_score": 4, + "candidates": [ + { + "score": 4, + "reasons": [ + "Name segment 'DCSR'", + "CSR name 'dcsr' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "priv-cfi.adoc", + "line_number": 87, + "line_text": "transition to Debug Mode, a `pelp` bit is defined in the `dcsr` register.#", + "context": " 85| the previous `ELP` state on traps to VS-mode, a `SPELP` bit is defined in the\n 86| `vsstatus` (VS-modes version of `sstatus`).# [#norm:dcsr-pelp_op]#To store the previous `ELP` state on\n>>> 87| transition to Debug Mode, a `pelp` bit is defined in the `dcsr` register.#\n 88| \n 89| [[norm:zicflip_pelp_trap]]" + }, + { + "score": 4, + "reasons": [ + "Name segment 'DCSR'", + "CSR name 'dcsr' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "priv-cfi.adoc", + "line_number": 101, + "line_text": "Upon entry into Debug Mode, the `pelp` bit in `dcsr` is updated with the `ELP`", + "context": " 99| \n 100| [[norm:zicflip_pelp_debug_mode]]\n>>> 101| Upon entry into Debug Mode, the `pelp` bit in `dcsr` is updated with the `ELP`\n 102| at the privilege level the hart was previously in, and the `ELP` is set to\n 103| `NO_LP_EXPECTED`. When a hart resumes from Debug Mode, if the new privilege mode" + }, + { + "score": 4, + "reasons": [ + "Name segment 'DCSR'", + "CSR name 'dcsr' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "priv-csrs.adoc", + "line_number": 1037, + "line_text": "|`dcsr` +", + "context": " 1035| DRW +\n 1036| DRW +\n>>> 1037| |`dcsr` +\n 1038| `dpc` +\n 1039| `dscratch0` +" + }, + { + "score": 3, + "reasons": [ + "Name segment 'DCSR'" + ], + "is_normative": true, + "in_note": false, + "file": "priv-cfi.adoc", + "line_number": 86, + "line_text": "`vsstatus` (VS-modes version of `sstatus`).# [#norm:dcsr-pelp_op]#To store the previous `ELP` state on", + "context": " 84| `SPELP` bit in `mstatus` can be accessed through the `sstatus` CSR.# [#norm:vsstatus-spelp_op2]#To store\n 85| the previous `ELP` state on traps to VS-mode, a `SPELP` bit is defined in the\n>>> 86| `vsstatus` (VS-modes version of `sstatus`).# [#norm:dcsr-pelp_op]#To store the previous `ELP` state on\n 87| transition to Debug Mode, a `pelp` bit is defined in the `dcsr` register.#\n 88| " + } + ] + }, + { + "parameter_name": "DCSR_STOPCOUNT_TYPE", + "classification": "NORM_CSR_RW", + "value_type": "enum", + "num_candidates": 4, + "best_score": 4, + "candidates": [ + { + "score": 4, + "reasons": [ + "Name segment 'DCSR'", + "CSR name 'dcsr' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "priv-cfi.adoc", + "line_number": 87, + "line_text": "transition to Debug Mode, a `pelp` bit is defined in the `dcsr` register.#", + "context": " 85| the previous `ELP` state on traps to VS-mode, a `SPELP` bit is defined in the\n 86| `vsstatus` (VS-modes version of `sstatus`).# [#norm:dcsr-pelp_op]#To store the previous `ELP` state on\n>>> 87| transition to Debug Mode, a `pelp` bit is defined in the `dcsr` register.#\n 88| \n 89| [[norm:zicflip_pelp_trap]]" + }, + { + "score": 4, + "reasons": [ + "Name segment 'DCSR'", + "CSR name 'dcsr' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "priv-cfi.adoc", + "line_number": 101, + "line_text": "Upon entry into Debug Mode, the `pelp` bit in `dcsr` is updated with the `ELP`", + "context": " 99| \n 100| [[norm:zicflip_pelp_debug_mode]]\n>>> 101| Upon entry into Debug Mode, the `pelp` bit in `dcsr` is updated with the `ELP`\n 102| at the privilege level the hart was previously in, and the `ELP` is set to\n 103| `NO_LP_EXPECTED`. When a hart resumes from Debug Mode, if the new privilege mode" + }, + { + "score": 4, + "reasons": [ + "Name segment 'DCSR'", + "CSR name 'dcsr' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "priv-csrs.adoc", + "line_number": 1037, + "line_text": "|`dcsr` +", + "context": " 1035| DRW +\n 1036| DRW +\n>>> 1037| |`dcsr` +\n 1038| `dpc` +\n 1039| `dscratch0` +" + }, + { + "score": 3, + "reasons": [ + "Name segment 'DCSR'" + ], + "is_normative": true, + "in_note": false, + "file": "priv-cfi.adoc", + "line_number": 86, + "line_text": "`vsstatus` (VS-modes version of `sstatus`).# [#norm:dcsr-pelp_op]#To store the previous `ELP` state on", + "context": " 84| `SPELP` bit in `mstatus` can be accessed through the `sstatus` CSR.# [#norm:vsstatus-spelp_op2]#To store\n 85| the previous `ELP` state on traps to VS-mode, a `SPELP` bit is defined in the\n>>> 86| `vsstatus` (VS-modes version of `sstatus`).# [#norm:dcsr-pelp_op]#To store the previous `ELP` state on\n 87| transition to Debug Mode, a `pelp` bit is defined in the `dcsr` register.#\n 88| " + } + ] + }, + { + "parameter_name": "DCSR_STOPTIME_TYPE", + "classification": "NORM_CSR_RW", + "value_type": "enum", + "num_candidates": 4, + "best_score": 4, + "candidates": [ + { + "score": 4, + "reasons": [ + "Name segment 'DCSR'", + "CSR name 'dcsr' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "priv-cfi.adoc", + "line_number": 87, + "line_text": "transition to Debug Mode, a `pelp` bit is defined in the `dcsr` register.#", + "context": " 85| the previous `ELP` state on traps to VS-mode, a `SPELP` bit is defined in the\n 86| `vsstatus` (VS-modes version of `sstatus`).# [#norm:dcsr-pelp_op]#To store the previous `ELP` state on\n>>> 87| transition to Debug Mode, a `pelp` bit is defined in the `dcsr` register.#\n 88| \n 89| [[norm:zicflip_pelp_trap]]" + }, + { + "score": 4, + "reasons": [ + "Name segment 'DCSR'", + "CSR name 'dcsr' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "priv-cfi.adoc", + "line_number": 101, + "line_text": "Upon entry into Debug Mode, the `pelp` bit in `dcsr` is updated with the `ELP`", + "context": " 99| \n 100| [[norm:zicflip_pelp_debug_mode]]\n>>> 101| Upon entry into Debug Mode, the `pelp` bit in `dcsr` is updated with the `ELP`\n 102| at the privilege level the hart was previously in, and the `ELP` is set to\n 103| `NO_LP_EXPECTED`. When a hart resumes from Debug Mode, if the new privilege mode" + }, + { + "score": 4, + "reasons": [ + "Name segment 'DCSR'", + "CSR name 'dcsr' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "priv-csrs.adoc", + "line_number": 1037, + "line_text": "|`dcsr` +", + "context": " 1035| DRW +\n 1036| DRW +\n>>> 1037| |`dcsr` +\n 1038| `dpc` +\n 1039| `dscratch0` +" + }, + { + "score": 3, + "reasons": [ + "Name segment 'DCSR'" + ], + "is_normative": true, + "in_note": false, + "file": "priv-cfi.adoc", + "line_number": 86, + "line_text": "`vsstatus` (VS-modes version of `sstatus`).# [#norm:dcsr-pelp_op]#To store the previous `ELP` state on", + "context": " 84| `SPELP` bit in `mstatus` can be accessed through the `sstatus` CSR.# [#norm:vsstatus-spelp_op2]#To store\n 85| the previous `ELP` state on traps to VS-mode, a `SPELP` bit is defined in the\n>>> 86| `vsstatus` (VS-modes version of `sstatus`).# [#norm:dcsr-pelp_op]#To store the previous `ELP` state on\n 87| transition to Debug Mode, a `pelp` bit is defined in the `dcsr` register.#\n 88| " + } + ] + }, + { + "parameter_name": "ELEN", + "classification": "NORM_DIRECT", + "value_type": "value", + "num_candidates": 10, + "best_score": 9, + "candidates": [ + { + "score": 9, + "reasons": [ + "Exact parameter name 'ELEN'", + "Name segment 'ELEN'" + ], + "is_normative": true, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 24, + "line_text": ". [#norm:vlen_param]#The number of bits in a single vector register, _VLEN_ {ge} ELEN, which must be a power of 2, and must be no greater than 2^16^.#", + "context": " 22| . [#norm:elen_param]#The maximum size in bits of a vector element that any operation can produce or consume, _ELEN_ {ge} 8, which\n 23| must be a power of 2.#\n>>> 24| . [#norm:vlen_param]#The number of bits in a single vector register, _VLEN_ {ge} ELEN, which must be a power of 2, and must be no greater than 2^16^.#\n 25| \n 26| Standard vector extensions (<>) and" + }, + { + "score": 9, + "reasons": [ + "Exact parameter name 'ELEN'", + "Name segment 'ELEN'" + ], + "is_normative": true, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 169, + "line_text": "NOTE: [#norm:vill_implicit_encoding_param]#A small implementation supporting ELEN=32 requires only seven bits of state in `vtype`: two bits for `ma` and `ta`, two bits for `vsew[1:0]` and three bits for `vlmul[2:0]`. The illegal value represented by `vill` can be internally encoded using the illegal 64-bit combination in `vsew[1:0]` without requiring an additional storage", + "context": " 167| \n 168| \n>>> 169| NOTE: [#norm:vill_implicit_encoding_param]#A small implementation supporting ELEN=32 requires only seven bits of state in `vtype`: two bits for `ma` and `ta`, two bits for `vsew[1:0]` and three bits for `vlmul[2:0]`. The illegal value represented by `vill` can be internally encoded using the illegal 64-bit combination in `vsew[1:0]` without requiring an additional storage\n 170| bit to hold `vill`.#\n 171| " + }, + { + "score": 8, + "reasons": [ + "Parameter name in emphasis '_ELEN_'" + ], + "is_normative": true, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 22, + "line_text": ". [#norm:elen_param]#The maximum size in bits of a vector element that any operation can produce or consume, _ELEN_ {ge} 8, which", + "context": " 20| Each hart supporting a vector extension defines two parameters:\n 21| \n>>> 22| . [#norm:elen_param]#The maximum size in bits of a vector element that any operation can produce or consume, _ELEN_ {ge} 8, which\n 23| must be a power of 2.#\n 24| . [#norm:vlen_param]#The number of bits in a single vector register, _VLEN_ {ge} ELEN, which must be a power of 2, and must be no greater than 2^16^.#" + }, + { + "score": 7, + "reasons": [ + "Exact parameter name 'ELEN'", + "Name segment 'ELEN'" + ], + "is_normative": false, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 29, + "line_text": "NOTE: Future extensions may allow ELEN {gt} VLEN by holding one", + "context": " 27| architecture profiles may set further constraints on _ELEN_ and _VLEN_.\n 28| \n>>> 29| NOTE: Future extensions may allow ELEN {gt} VLEN by holding one\n 30| element using bits from multiple vector registers, but this\n 31| extension does not include this option." + }, + { + "score": 7, + "reasons": [ + "Exact parameter name 'ELEN'", + "Name segment 'ELEN'" + ], + "is_normative": false, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 50, + "line_text": "VLEN or ELEN parameters.", + "context": " 48| NOTE: In general, thread contexts with active vector state cannot be\n 49| migrated during execution between harts that have any difference in\n>>> 50| VLEN or ELEN parameters.\n 51| \n 52| === Vector Extension Programmer's Model" + } + ] + }, + { + "parameter_name": "FOLLOW_VTYPE_RESET_RECOMMENDATION", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 14, + "candidates": [ + { + "score": 14, + "reasons": [ + "Name segment 'VTYPE'", + "CSR field name 'VALUE'", + "CSR name 'vtype' in backticks", + "CSR field name 'VLMUL'", + "CSR field name 'VSEW'", + "CSR field name 'VILL'" + ], + "is_normative": true, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 169, + "line_text": "NOTE: [#norm:vill_implicit_encoding_param]#A small implementation supporting ELEN=32 requires only seven bits of state in `vtype`: two bits for `ma` and `ta`, two bits for `vsew[1:0]` and three bits for `vlmul[2:0]`. The illegal value represented by `vill` can be internally encoded using the illegal 64-bit combination in `vsew[1:0]` without requiring an additional storage", + "context": " 167| \n 168| \n>>> 169| NOTE: [#norm:vill_implicit_encoding_param]#A small implementation supporting ELEN=32 requires only seven bits of state in `vtype`: two bits for `ma` and `ta`, two bits for `vsew[1:0]` and three bits for `vlmul[2:0]`. The illegal value represented by `vill` can be internally encoded using the illegal 64-bit combination in `vsew[1:0]` without requiring an additional storage\n 170| bit to hold `vill`.#\n 171| " + }, + { + "score": 10, + "reasons": [ + "Name segment 'VTYPE'", + "CSR name 'vtype' in backticks", + "CSR field name 'VTA'", + "CSR field name 'VMA'", + "CSR field name 'VILL'" + ], + "is_normative": false, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 162, + "line_text": "The `vtype` register has five fields, `vill`, `vma`, `vta`,", + "context": " 160| \n 161| [[norm:vtype-fields_sz]]\n>>> 162| The `vtype` register has five fields, `vill`, `vma`, `vta`,\n 163| `vsew[2:0]`, and `vlmul[2:0]`. Bits `vtype[XLEN-2:8]` should be\n 164| written with zero, and non-zero values in this field are reserved." + }, + { + "score": 9, + "reasons": [ + "Name segment 'VTYPE'", + "CSR name 'vl' in backticks", + "CSR name 'vtype' in backticks" + ], + "is_normative": true, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 1178, + "line_text": "values in `vl` and `vtype` to match application needs. [#norm:vset_op]#The", + "context": " 1176| \n 1177| A set of instructions is provided to allow rapid configuration of the\n>>> 1178| values in `vl` and `vtype` to match application needs. [#norm:vset_op]#The\n 1179| `vset{i}vl{i}` instructions set the `vtype` and `vl` CSRs based on\n 1180| their arguments, and write the new value of `vl` into `rd`.#" + }, + { + "score": 9, + "reasons": [ + "CSR field name 'VILL'", + "CSR name 'vl' in backticks", + "CSR field name 'VALUE'" + ], + "is_normative": true, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 1279, + "line_text": "[#norm:vsetvl_op_rs1_x0_rd_x0]#When _rs1_=`x0` and _rd_=`x0`, the instructions operate as if the current vector length in `vl` is used as the AVL, and the resulting value is written to `vl`, but not to a destination register. This form can only be used when VLMAX and hence `vl` is not actually changed by the new SEW/LMUL ratio.# [#norm:vtype_vset_rsv]#Use of the instructions with a new SEW/LMUL ratio that would result in a change of VLMAX is reserved. Use of the instructions is also reserved if `vill` was 1 beforehand.# [#norm:reserved_vill_set_param]#Implementations may set `vill` in either case.#", + "context": " 1277| also to the `x` register specified by `rd`.\n 1278| \n>>> 1279| [#norm:vsetvl_op_rs1_x0_rd_x0]#When _rs1_=`x0` and _rd_=`x0`, the instructions operate as if the current vector length in `vl` is used as the AVL, and the resulting value is written to `vl`, but not to a destination register. This form can only be used when VLMAX and hence `vl` is not actually changed by the new SEW/LMUL ratio.# [#norm:vtype_vset_rsv]#Use of the instructions with a new SEW/LMUL ratio that would result in a change of VLMAX is reserved. Use of the instructions is also reserved if `vill` was 1 beforehand.# [#norm:reserved_vill_set_param]#Implementations may set `vill` in either case.#\n 1280| \n 1281| NOTE: This last form of the instructions allows the `vtype` register to" + }, + { + "score": 9, + "reasons": [ + "Name segment 'VTYPE'", + "CSR name 'vl' in backticks", + "CSR field name 'VALUE'", + "CSR name 'vtype' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 1284, + "line_text": "legal value for current `vtype` setting. The current `vl` value can", + "context": " 1282| be changed while maintaining the current `vl`, provided VLMAX is not\n 1283| reduced. This design was chosen to ensure `vl` would always hold a\n>>> 1284| legal value for current `vtype` setting. The current `vl` value can\n 1285| be read from the `vl` CSR. The `vl` value could be reduced by these\n 1286| instructions if the new SEW/LMUL ratio causes VLMAX to shrink, and so" + } + ] + }, + { + "parameter_name": "FORCE_UPGRADE_CBO_INVAL_TO_FLUSH", + "classification": "NORM_CSR_WARL", + "value_type": "binary", + "num_candidates": 10, + "best_score": 20, + "candidates": [ + { + "score": 20, + "reasons": [ + "Optional/read-only pattern for boolean param", + "Description keyword 'CBIE'", + "CSR field name 'CBIE'", + "Name segment 'INVAL'", + "Description keyword 'cbo.inval'", + "Description keyword 'INVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 913, + "line_text": "implemented, `CBIE` is read-only zero. Execution of `CBO.INVAL` in U-mode is", + "context": " 911| WARL field to `senvcfg` to control execution of the `CBO.INVAL` instruction in\n 912| U-mode. The encoding `10b` is reserved. When the Zicbom extension is not\n>>> 913| implemented, `CBIE` is read-only zero. Execution of `CBO.INVAL` in U-mode is\n 914| enabled only if execution of the instruction is enabled for use in S-mode and\n 915| `CBIE` is set to `01b` or `11b`; otherwise, an illegal-instruction exception is" + }, + { + "score": 19, + "reasons": [ + "Description keyword 'CBIE'", + "CSR field name 'CBIE'", + "Name segment 'INVAL'", + "Description keyword 'cbo.inval'", + "Description keyword 'INVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 2293, + "line_text": "instruction (`CBO.INVAL`) in modes less privileged than M. When `CBIE` is set to", + "context": " 2291| [#norm:menvcfg-cbie]#The Zicbom extension adds the `CBIE` (Cache Block Invalidate instruction Enable)\n 2292| WARL field to `menvcfg` to control execution of the cache block invalidate\n>>> 2293| instruction (`CBO.INVAL`) in modes less privileged than M. When `CBIE` is set to\n 2294| `00b`, the instruction raises an illegal-instruction exception in modes less\n 2295| privileged than M. When the Zicbom extension is not implemented, `CBIE` is" + }, + { + "score": 12, + "reasons": [ + "Description keyword 'CBIE'", + "CSR field name 'CBIE'" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 772, + "line_text": "[[norm:henvcfg-cbie]]", + "context": " 770| not implemented, `CBCFE` is read-only zero.\n 771| \n>>> 772| [[norm:henvcfg-cbie]]\n 773| The Zicbom extension adds the `CBIE` (Cache Block Invalidate instruction Enable)\n 774| WARL field to `henvcfg`. The `CBIE` field controls execution of the cache block" + }, + { + "score": 12, + "reasons": [ + "Name segment 'INVAL'", + "Name segment 'FLUSH'", + "Description keyword 'cbo.inval'", + "Description keyword 'INVAL'" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 785, + "line_text": "[#norm:cbo-inval_h-mode_op0]#If `CBO.INVAL` is enabled in HS-mode to perform a flush operation, then when the", + "context": " 783| otherwise, it raises a virtual-instruction exception.\n 784| \n>>> 785| [#norm:cbo-inval_h-mode_op0]#If `CBO.INVAL` is enabled in HS-mode to perform a flush operation, then when the\n 786| instruction is enabled in VS- or VU-mode it performs a flush operation, even if\n 787| `CBIE` is set to `11b`. Otherwise, when the instruction is enabled for" + }, + { + "score": 12, + "reasons": [ + "Description keyword 'CBIE'", + "CSR field name 'CBIE'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 2291, + "line_text": "[#norm:menvcfg-cbie]#The Zicbom extension adds the `CBIE` (Cache Block Invalidate instruction Enable)", + "context": " 2289| than M. When the Zicbom extension is not implemented, `CBCFE` is read-only zero.\n 2290| \n>>> 2291| [#norm:menvcfg-cbie]#The Zicbom extension adds the `CBIE` (Cache Block Invalidate instruction Enable)\n 2292| WARL field to `menvcfg` to control execution of the cache block invalidate\n 2293| instruction (`CBO.INVAL`) in modes less privileged than M. When `CBIE` is set to" + } + ] + }, + { + "parameter_name": "GSTAGE_MODE_BARE", + "classification": "NORM_CSR_WARL", + "value_type": "binary", + "num_candidates": 10, + "best_score": 11, + "candidates": [ + { + "score": 11, + "reasons": [ + "Description keyword 'hgatp'", + "WARL + CSR 'hgatp'", + "CSR name 'hgatp' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1075, + "line_text": "is for `satp`. Instead, the fields of `hgatp` are *WARL* in the normal way,", + "context": " 1073| [[norm:hgatp-mode_warl]]\n 1074| A write to `hgatp` with an unsupported MODE value is not ignored as it\n>>> 1075| is for `satp`. Instead, the fields of `hgatp` are *WARL* in the normal way,\n 1076| when so indicated.\n 1077| " + }, + { + "score": 9, + "reasons": [ + "Description keyword 'hgatp'", + "CSR field name 'MODE'", + "Name segment 'BARE'", + "CSR name 'hgatp' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1007, + "line_text": ".Hypervisor guest address translation and protection register `hgatp` when HSXLEN=64 for MODE values Bare, Sv39x4, Sv48x4, and Sv57x4.", + "context": " 1005| \n 1006| [[rv64hgatp]]\n>>> 1007| .Hypervisor guest address translation and protection register `hgatp` when HSXLEN=64 for MODE values Bare, Sv39x4, Sv48x4, and Sv57x4.\n 1008| include::images/bytefield/rv64hgatp.edn[]\n 1009| " + }, + { + "score": 8, + "reasons": [ + "Description keyword 'hgatp'", + "CSR name 'hgatp' in backticks" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 989, + "line_text": "[#norm:hgatp_sz_acc_op]#The `hgatp` register is an HSXLEN-bit read/write register, formatted as", + "context": " 987| ==== Hypervisor Guest Address Translation and Protection (`hgatp`) Register\n 988| \n>>> 989| [#norm:hgatp_sz_acc_op]#The `hgatp` register is an HSXLEN-bit read/write register, formatted as\n 990| shown in <> for HSXLEN=32 and\n 991| <> for HSXLEN=64, which controls" + }, + { + "score": 8, + "reasons": [ + "Description keyword 'hgatp'", + "CSR name 'hgatp' in backticks" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 999, + "line_text": "addresses. [#norm:hgatp_tvm_illegal]#When `mstatus`.TVM=1, attempts to read or write `hgatp` while", + "context": " 997| address-translation fences on a per-virtual-machine basis; and the MODE\n 998| field, which selects the address-translation scheme for guest physical\n>>> 999| addresses. [#norm:hgatp_tvm_illegal]#When `mstatus`.TVM=1, attempts to read or write `hgatp` while\n 1000| executing in HS-mode will raise an illegal-instruction exception.#\n 1001| " + }, + { + "score": 8, + "reasons": [ + "Description keyword 'hgatp'", + "CSR field name 'MODE'", + "CSR name 'hgatp' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1033, + "line_text": ".Encoding of `hgatp` MODE field.", + "context": " 1031| \n 1032| [[hgatp-mode]]\n>>> 1033| .Encoding of `hgatp` MODE field.\n 1034| [%autowidth,float=\"center\",align=\"center\",cols=\"^,^,<\",options=\"header\"]\n 1035| |===" + } + ] + }, + { + "parameter_name": "HCONTEXT_AVAILABLE", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 8, + "candidates": [ + { + "score": 8, + "reasons": [ + "Description keyword 'HCONTEXT'", + "CSR field name 'HCONTEXT'", + "Name segment 'HCONTEXT'", + "CSR name 'hcontext' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "smstateen.adoc", + "line_number": 287, + "line_text": "`hcontext` CSRs provided by the Sdtrig extension. The CONTEXT bit in", + "context": " 285| \n 286| The CONTEXT bit in `mstateen0` controls access to the `scontext` and\n>>> 287| `hcontext` CSRs provided by the Sdtrig extension. The CONTEXT bit in\n 288| `hstateen0` controls access to the `scontext` CSR provided by the Sdtrig\n 289| extension." + }, + { + "score": 3, + "reasons": [ + "Optional/read-only pattern for boolean param" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 25, + "line_text": "registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and", + "context": " 23| The hypervisor extension depends on an \"I\" base integer ISA with 32\n 24| `x` registers (RV32I or RV64I), not RV32E or RV64E, which have only 16 `x`\n>>> 25| registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and\n 26| [#norm:H_vm_supported]#standard\n 27| page-based address translation must be supported, either Sv32 for RV32," + }, + { + "score": 3, + "reasons": [ + "Optional/read-only pattern for boolean param" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 231, + "line_text": "[#norm:misa_e_not_i]#Unless `misa` is all read-only zero, the", + "context": " 229| \n 230| [#norm:misa_e_acc]#The \"E\" bit is read-only.#\n>>> 231| [#norm:misa_e_not_i]#Unless `misa` is all read-only zero, the\n 232| \"E\" bit always reads as the complement of the \"I\" bit.#\n 233| If an execution environment supports both RV32E and RV32I, software can select" + }, + { + "score": 3, + "reasons": [ + "Optional/read-only pattern for boolean param" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 423, + "line_text": "[#norm:mstatus_sie_spie_rdonly0]#If supervisor mode is not implemented, then SIE and SPIE are read-only 0.#", + "context": " 421| to disable selected higher-privilege-mode interrupts before ceding\n 422| control to a lower-privilege mode.\n>>> 423| [#norm:mstatus_sie_spie_rdonly0]#If supervisor mode is not implemented, then SIE and SPIE are read-only 0.#\n 424| \n 425| [NOTE]" + }, + { + "score": 3, + "reasons": [ + "Optional/read-only pattern for boolean param" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 479, + "line_text": "[#norm:mstatus_xpp_rdonly0]#If privilege mode _x_ is not implemented, then __x__PP must be read-only 0.#", + "context": " 477| \n 478| [#norm:mstatus_xpp_warl]#__x__PP fields are *WARL* fields that can hold only privilege mode _x_ and any implemented privilege mode lower than _x_.#\n>>> 479| [#norm:mstatus_xpp_rdonly0]#If privilege mode _x_ is not implemented, then __x__PP must be read-only 0.#\n 480| \n 481| [NOTE]" + } + ] + }, + { + "parameter_name": "HCOUNTENABLE_EN", + "classification": "NORM_CSR_RW", + "value_type": "bitmask", + "num_candidates": 10, + "best_score": 12, + "candidates": [ + { + "score": 12, + "reasons": [ + "CSR field name 'IR'", + "CSR name 'hcounteren' in backticks", + "CSR field name 'TM'", + "Description keyword 'hcounteren'", + "CSR field name 'CY'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 857, + "line_text": "When the CY, TM, IR, or HPM__n__ bit in the `hcounteren` register is", + "context": " 855| \n 856| [[norm:hcounteren_op]]\n>>> 857| When the CY, TM, IR, or HPM__n__ bit in the `hcounteren` register is\n 858| clear, attempts to read the `cycle`, `time`, `instret`, or\n 859| `hpmcounter` _n_ register while V=1 will cause a virtual-instruction" + }, + { + "score": 8, + "reasons": [ + "CSR name 'hcounteren' in backticks", + "CSR field name 'TM'", + "Description keyword 'hcounteren'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 867, + "line_text": "In addition, when the TM bit in the `hcounteren` register is clear, attempts to", + "context": " 865| \n 866| [[norm:hcounteren_acc]]\n>>> 867| In addition, when the TM bit in the `hcounteren` register is clear, attempts to\n 868| access the `vstimecmp` register (via `stimecmp`) while executing in VS-mode will\n 869| cause a virtual-instruction exception if the same bit in `mcounteren` is set." + }, + { + "score": 8, + "reasons": [ + "CSR field name 'IR'", + "CSR field name 'TM'", + "CSR field name 'CY'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1615, + "line_text": "[#norm:mcounteren_clr_ill_inst_exc]#When the CY, TM, IR, or HPM__n__ bit in the `mcounteren` register is", + "context": " 1613| counters, which continue to increment even when not accessible.#\n 1614| \n>>> 1615| [#norm:mcounteren_clr_ill_inst_exc]#When the CY, TM, IR, or HPM__n__ bit in the `mcounteren` register is\n 1616| clear, attempts to read the `cycle`, `time`, `instret`, or\n 1617| `hpmcountern` register while executing in S-mode or U-mode will cause an" + }, + { + "score": 6, + "reasons": [ + "Description keyword 'Zihpm'", + "Description keyword 'Zicntr'" + ], + "is_normative": false, + "in_note": false, + "file": "counters.adoc", + "line_number": 2, + "line_text": "== \"Zicntr\" and \"Zihpm\" Extensions for Counters, Version 2.0", + "context": " 1| [[counters]]\n>>> 2| == \"Zicntr\" and \"Zihpm\" Extensions for Counters, Version 2.0\n 3| \n 4| [[norm:zihpm_op_sz_mode_acc]]" + }, + { + "score": 6, + "reasons": [ + "Description keyword 'Zihpm'", + "Description keyword 'Zicntr'" + ], + "is_normative": false, + "in_note": false, + "file": "counters.adoc", + "line_number": 9, + "line_text": "divided between the \"Zicntr\" and \"Zihpm\" extensions.", + "context": " 7| read-only CSR registers `0xC00`–`0xC1F` (when XLEN=32, the upper 32 bits\n 8| are accessed via CSR registers `0xC80`–`0xC9F`). These counters are\n>>> 9| divided between the \"Zicntr\" and \"Zihpm\" extensions.\n 10| \n 11| === \"Zicntr\" Extension for Base Counters and Timers" + } + ] + }, + { + "parameter_name": "HPM_COUNTER_EN", + "classification": "NORM_CSR_RW", + "value_type": "bitmask", + "num_candidates": 10, + "best_score": 8, + "candidates": [ + { + "score": 8, + "reasons": [ + "Description keyword 'TM'", + "Description keyword 'CY'", + "Description keyword 'IR'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1615, + "line_text": "[#norm:mcounteren_clr_ill_inst_exc]#When the CY, TM, IR, or HPM__n__ bit in the `mcounteren` register is", + "context": " 1613| counters, which continue to increment even when not accessible.#\n 1614| \n>>> 1615| [#norm:mcounteren_clr_ill_inst_exc]#When the CY, TM, IR, or HPM__n__ bit in the `mcounteren` register is\n 1616| clear, attempts to read the `cycle`, `time`, `instret`, or\n 1617| `hpmcountern` register while executing in S-mode or U-mode will cause an" + }, + { + "score": 6, + "reasons": [ + "Description keyword 'TM'", + "Description keyword 'CY'", + "Description keyword 'IR'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 857, + "line_text": "When the CY, TM, IR, or HPM__n__ bit in the `hcounteren` register is", + "context": " 855| \n 856| [[norm:hcounteren_op]]\n>>> 857| When the CY, TM, IR, or HPM__n__ bit in the `hcounteren` register is\n 858| clear, attempts to read the `cycle`, `time`, `instret`, or\n 859| `hpmcounter` _n_ register while V=1 will cause a virtual-instruction" + }, + { + "score": 6, + "reasons": [ + "Description keyword 'CY'", + "Description keyword 'IR'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1675, + "line_text": "[#norm:mcountinhibit_op2]#When the CY, IR, or HPM__n__ bit in the `mcountinhibit` register is clear,", + "context": " 1673| of this register.#\n 1674| \n>>> 1675| [#norm:mcountinhibit_op2]#When the CY, IR, or HPM__n__ bit in the `mcountinhibit` register is clear,\n 1676| the `mcycle`, `minstret`, or `mhpmcountern` register increments as usual.\n 1677| When the CY, IR, or HPM__n__ bit is set, the corresponding counter does" + }, + { + "score": 6, + "reasons": [ + "Description keyword 'TM'", + "Description keyword 'CY'", + "Description keyword 'IR'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 511, + "line_text": "When the CY, TM, IR, or HPM__n__ bit in the `scounteren` register is", + "context": " 509| \n 510| [[norm:scounteren_op]]\n>>> 511| When the CY, TM, IR, or HPM__n__ bit in the `scounteren` register is\n 512| clear, attempts to read the `cycle`, `time`, `instret`, or `hpmcountern`\n 513| register while executing in U-mode will cause an illegal-instruction" + }, + { + "score": 5, + "reasons": [ + "Name segment 'COUNTER'", + "Description keyword 'CY'", + "Description keyword 'IR'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 1677, + "line_text": "When the CY, IR, or HPM__n__ bit is set, the corresponding counter does", + "context": " 1675| [#norm:mcountinhibit_op2]#When the CY, IR, or HPM__n__ bit in the `mcountinhibit` register is clear,\n 1676| the `mcycle`, `minstret`, or `mhpmcountern` register increments as usual.\n>>> 1677| When the CY, IR, or HPM__n__ bit is set, the corresponding counter does\n 1678| not increment.#\n 1679| " + } + ] + }, + { + "parameter_name": "HPM_EVENTS", + "classification": "NORM_CSR_WARL", + "value_type": "set", + "num_candidates": 10, + "best_score": 8, + "candidates": [ + { + "score": 8, + "reasons": [ + "CSR name 'mhpmevent3' in backticks", + "WARL + CSR 'mhpmevent3'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 1581, + "line_text": "`mhpmevent3`-`mhpmevent31`, are 64-bit *WARL* registers that control which", + "context": " 1579| counters, `mhpmcounter3`-`mhpmcounter31`.#\n 1580| [#norm:mhpmevent_sz_warl_op]#The event selector CSRs,\n>>> 1581| `mhpmevent3`-`mhpmevent31`, are 64-bit *WARL* registers that control which\n 1582| event causes the corresponding counter to increment.#\n 1583| [#norm:mhpmevent_enc]#The meaning of these events is defined by the platform," + }, + { + "score": 4, + "reasons": [ + "CSR field name 'EVENT'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 526, + "line_text": "[#norm:trap_unexp_hndl_lead-in]#In the event of a _unexpected trap_, the handling is as follows:#", + "context": " 524| `mnstatus.NMIE` set to 0 is an _unexpected trap_.#\n 525| \n>>> 526| [#norm:trap_unexp_hndl_lead-in]#In the event of a _unexpected trap_, the handling is as follows:#\n 527| \n 528| * [#norm:trap_unexp_hndl_rnmi]#When the Smrnmi extension is implemented and `mnstatus.NMIE` is 1, the hart" + }, + { + "score": 4, + "reasons": [ + "CSR field name 'EVENT'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1578, + "line_text": "[#norm:mhpmcounter_num]#The hardware performance monitor includes 29 additional 64-bit event", + "context": " 1576| to indicate which harts share an `mcycle` CSR.\n 1577| \n>>> 1578| [#norm:mhpmcounter_num]#The hardware performance monitor includes 29 additional 64-bit event\n 1579| counters, `mhpmcounter3`-`mhpmcounter31`.#\n 1580| [#norm:mhpmevent_sz_warl_op]#The event selector CSRs," + }, + { + "score": 4, + "reasons": [ + "CSR field name 'EVENT'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1580, + "line_text": "[#norm:mhpmevent_sz_warl_op]#The event selector CSRs,", + "context": " 1578| [#norm:mhpmcounter_num]#The hardware performance monitor includes 29 additional 64-bit event\n 1579| counters, `mhpmcounter3`-`mhpmcounter31`.#\n>>> 1580| [#norm:mhpmevent_sz_warl_op]#The event selector CSRs,\n 1581| `mhpmevent3`-`mhpmevent31`, are 64-bit *WARL* registers that control which\n 1582| event causes the corresponding counter to increment.#" + }, + { + "score": 4, + "reasons": [ + "CSR field name 'EVENT'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1586, + "line_text": "[#norm:mhpmcounter_mhpmevent_rdonly0]#a legal implementation is to make both the counter and its corresponding event selector be read-only 0.#", + "context": " 1584| but event 0 is defined to mean \"no event.\"#\n 1585| [#norm:mhpmcounter_mandatory]#All counters should be implemented#, but\n>>> 1586| [#norm:mhpmcounter_mhpmevent_rdonly0]#a legal implementation is to make both the counter and its corresponding event selector be read-only 0.#\n 1587| \n 1588| .Hardware performance monitor counters." + } + ] + }, + { + "parameter_name": "HSTATEEN_AIA_TYPE", + "classification": "NORM_CSR_RW", + "value_type": "enum", + "num_candidates": 0, + "best_score": 0, + "candidates": [] + }, + { + "parameter_name": "HSTATEEN_CONTEXT_TYPE", + "classification": "NORM_CSR_RW", + "value_type": "enum", + "num_candidates": 10, + "best_score": 5, + "candidates": [ + { + "score": 5, + "reasons": [ + "Name segment 'CONTEXT'", + "Description keyword 'CONTEXT'" + ], + "is_normative": true, + "in_note": false, + "file": "smctr.adoc", + "line_number": 652, + "line_text": "[#norm:ccounter_reset]#The CtrCycleCounter is reset on writes to `__x__ctrctl`, and on execution of SCTRCLR, to ensure that any accumulated cycle counts do not persist across a context switch.#", + "context": " 650| ----\n 651| \n>>> 652| [#norm:ccounter_reset]#The CtrCycleCounter is reset on writes to `__x__ctrctl`, and on execution of SCTRCLR, to ensure that any accumulated cycle counts do not persist across a context switch.#\n 653| \n 654| [#norm:ccounter_impl]#An implementation that supports cycle counting must implement CCV and all" + }, + { + "score": 3, + "reasons": [ + "Name segment 'CONTEXT'", + "Description keyword 'CONTEXT'" + ], + "is_normative": false, + "in_note": false, + "file": "bfloat16.adoc", + "line_number": 82, + "line_text": "in context, and advise on how they best to fit the functionality.", + "context": " 80| Furthermore, we expect architects to be able to examine our instructions\n 81| for implementation issues, understand how the instructions will be used\n>>> 82| in context, and advise on how they best to fit the functionality.\n 83| \n 84| Digital design engineers & micro-architects::" + }, + { + "score": 3, + "reasons": [ + "Name segment 'CONTEXT'", + "Description keyword 'CONTEXT'" + ], + "is_normative": false, + "in_note": false, + "file": "calling-convention.adoc", + "line_number": 24, + "line_text": "NOTE: This scheme allows system calls that cause context switches to avoid", + "context": " 22| (`v0`-`v31`, `vl`, `vtype`) and `vstart` to become unspecified.\n 23| \n>>> 24| NOTE: This scheme allows system calls that cause context switches to avoid\n 25| saving and later restoring the vector registers.\n 26| " + }, + { + "score": 3, + "reasons": [ + "Name segment 'CONTEXT'", + "Description keyword 'CONTEXT'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1218, + "line_text": "Read-only fields SD and XS summarize the extension context status as it", + "context": " 1216| \n 1217| [[norm:vsstatus-sd_xs_op]]\n>>> 1218| Read-only fields SD and XS summarize the extension context status as it\n 1219| is visible to VS-mode only. For example, the value of the HS-level\n 1220| `sstatus`.FS does not affect `vsstatus`.SD." + }, + { + "score": 3, + "reasons": [ + "Name segment 'CONTEXT'", + "Description keyword 'CONTEXT'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 828, + "line_text": "===== Extension Context Status in `mstatus` Register", + "context": " 826| ====\n 827| \n>>> 828| ===== Extension Context Status in `mstatus` Register\n 829| \n 830| Supporting substantial extensions is one of the primary goals of RISC-V," + } + ] + }, + { + "parameter_name": "HSTATEEN_CSRIND_TYPE", + "classification": "NORM_CSR_RW", + "value_type": "enum", + "num_candidates": 6, + "best_score": 3, + "candidates": [ + { + "score": 3, + "reasons": [ + "Description keyword 'CSRIND'", + "Name segment 'CSRIND'" + ], + "is_normative": false, + "in_note": false, + "file": "smstateen.adoc", + "line_number": 191, + "line_text": "{bits: 1, name: 'CSRIND'},", + "context": " 189| {bits: 1, name: 'IMSIC'},\n 190| {bits: 1, name: 'AIA'},\n>>> 191| {bits: 1, name: 'CSRIND'},\n 192| {bits: 1, name: 'WPRI'},\n 193| {bits: 1, name: 'ENVCFG'}," + }, + { + "score": 3, + "reasons": [ + "Description keyword 'CSRIND'", + "Name segment 'CSRIND'" + ], + "is_normative": false, + "in_note": false, + "file": "smstateen.adoc", + "line_number": 211, + "line_text": "{bits: 1, name: 'CSRIND'},", + "context": " 209| {bits: 1, name: 'IMSIC'},\n 210| {bits: 1, name: 'AIA'},\n>>> 211| {bits: 1, name: 'CSRIND'},\n 212| {bits: 1, name: 'WPRI'},\n 213| {bits: 1, name: 'ENVCFG'}," + }, + { + "score": 3, + "reasons": [ + "Description keyword 'CSRIND'", + "Name segment 'CSRIND'" + ], + "is_normative": false, + "in_note": false, + "file": "smstateen.adoc", + "line_number": 263, + "line_text": "The CSRIND bit in `mstateen0` controls access to the `siselect`, `sireg*`,", + "context": " 261| `senvcfg` CSRs.\n 262| \n>>> 263| The CSRIND bit in `mstateen0` controls access to the `siselect`, `sireg*`,\n 264| `vsiselect`, and the `vsireg*` CSRs provided by the Sscsrind extensions.\n 265| The CSRIND bit in `hstateen0` controls access to the `siselect` and the" + }, + { + "score": 3, + "reasons": [ + "Description keyword 'CSRIND'", + "Name segment 'CSRIND'" + ], + "is_normative": false, + "in_note": false, + "file": "smstateen.adoc", + "line_number": 265, + "line_text": "The CSRIND bit in `hstateen0` controls access to the `siselect` and the", + "context": " 263| The CSRIND bit in `mstateen0` controls access to the `siselect`, `sireg*`,\n 264| `vsiselect`, and the `vsireg*` CSRs provided by the Sscsrind extensions.\n>>> 265| The CSRIND bit in `hstateen0` controls access to the `siselect` and the\n 266| `sireg*`, (really `vsiselect` and `vsireg*`) CSRs provided by the Sscsrind\n 267| extensions." + }, + { + "score": 3, + "reasons": [ + "Description keyword 'CSRIND'", + "Name segment 'CSRIND'" + ], + "is_normative": false, + "in_note": false, + "file": "smstateen.adoc", + "line_number": 281, + "line_text": "Ssaia extension and not controlled by either the CSRIND or the IMSIC", + "context": " 279| \n 280| The AIA bit in `mstateen0` controls access to all state introduced by the\n>>> 281| Ssaia extension and not controlled by either the CSRIND or the IMSIC\n 282| bits. The AIA bit in `hstateen0` controls access to all state introduced by the\n 283| Ssaia extension and not controlled by either the CSRIND or the IMSIC" + } + ] + }, + { + "parameter_name": "HSTATEEN_ENVCFG_TYPE", + "classification": "NORM_CSR_RW", + "value_type": "enum", + "num_candidates": 6, + "best_score": 3, + "candidates": [ + { + "score": 3, + "reasons": [ + "Name segment 'ENVCFG'", + "Description keyword 'ENVCFG'" + ], + "is_normative": false, + "in_note": false, + "file": "priv-cfi.adoc", + "line_number": 134, + "line_text": "*__x__*`envcfg.SSE` fields. The conditions are specified as follows:", + "context": " 132| Attempts to access the `ssp` CSR may result in either an illegal-instruction\n 133| exception or a virtual-instruction exception, contingent upon the state of the\n>>> 134| *__x__*`envcfg.SSE` fields. The conditions are specified as follows:\n 135| \n 136| * [#norm:zicfiss_m_menvcfg-sse]#If the privilege mode is less than M and `menvcfg.SSE` is 0, an" + }, + { + "score": 3, + "reasons": [ + "Name segment 'ENVCFG'", + "Description keyword 'ENVCFG'" + ], + "is_normative": false, + "in_note": false, + "file": "riscv-unprivileged.adoc", + "line_number": 47, + "line_text": ":csrname: envcfg", + "context": " 45| :stem: latexmath\n 46| :footnote:\n>>> 47| :csrname: envcfg\n 48| :imagesdir: images\n 49| " + }, + { + "score": 3, + "reasons": [ + "Name segment 'ENVCFG'", + "Description keyword 'ENVCFG'" + ], + "is_normative": false, + "in_note": false, + "file": "smstateen.adoc", + "line_number": 193, + "line_text": "{bits: 1, name: 'ENVCFG'},", + "context": " 191| {bits: 1, name: 'CSRIND'},\n 192| {bits: 1, name: 'WPRI'},\n>>> 193| {bits: 1, name: 'ENVCFG'},\n 194| {bits: 1, name: 'SE0'},\n 195| ], config: {bits: 64, lanes: 4, hspace:1024}}" + }, + { + "score": 3, + "reasons": [ + "Name segment 'ENVCFG'", + "Description keyword 'ENVCFG'" + ], + "is_normative": false, + "in_note": false, + "file": "smstateen.adoc", + "line_number": 213, + "line_text": "{bits: 1, name: 'ENVCFG'},", + "context": " 211| {bits: 1, name: 'CSRIND'},\n 212| {bits: 1, name: 'WPRI'},\n>>> 213| {bits: 1, name: 'ENVCFG'},\n 214| {bits: 1, name: 'SE0'},\n 215| ], config: {bits: 64, lanes: 4, hspace:1024}}" + }, + { + "score": 3, + "reasons": [ + "Name segment 'ENVCFG'", + "Description keyword 'ENVCFG'" + ], + "is_normative": false, + "in_note": false, + "file": "smstateen.adoc", + "line_number": 259, + "line_text": "The ENVCFG bit in `mstateen0` controls access to the `henvcfg`, `henvcfgh`,", + "context": " 257| `sstateen0` CSR.\n 258| \n>>> 259| The ENVCFG bit in `mstateen0` controls access to the `henvcfg`, `henvcfgh`,\n 260| and the `senvcfg` CSRs. The ENVCFG bit in `hstateen0` controls access to the\n 261| `senvcfg` CSRs." + } + ] + }, + { + "parameter_name": "HSTATEEN_IMSIC_TYPE", + "classification": "NORM_CSR_RW", + "value_type": "enum", + "num_candidates": 7, + "best_score": 3, + "candidates": [ + { + "score": 3, + "reasons": [ + "Description keyword 'IMSIC'", + "Name segment 'IMSIC'" + ], + "is_normative": false, + "in_note": false, + "file": "smstateen.adoc", + "line_number": 189, + "line_text": "{bits: 1, name: 'IMSIC'},", + "context": " 187| {bits: 1, name: 'P1P13'},\n 188| {bits: 1, name: 'CONTEXT'},\n>>> 189| {bits: 1, name: 'IMSIC'},\n 190| {bits: 1, name: 'AIA'},\n 191| {bits: 1, name: 'CSRIND'}," + }, + { + "score": 3, + "reasons": [ + "Description keyword 'IMSIC'", + "Name segment 'IMSIC'" + ], + "is_normative": false, + "in_note": false, + "file": "smstateen.adoc", + "line_number": 209, + "line_text": "{bits: 1, name: 'IMSIC'},", + "context": " 207| {bits: 2, name: 'WPRI'},\n 208| {bits: 1, name: 'CONTEXT'},\n>>> 209| {bits: 1, name: 'IMSIC'},\n 210| {bits: 1, name: 'AIA'},\n 211| {bits: 1, name: 'CSRIND'}," + }, + { + "score": 3, + "reasons": [ + "Description keyword 'IMSIC'", + "Name segment 'IMSIC'" + ], + "is_normative": false, + "in_note": false, + "file": "smstateen.adoc", + "line_number": 269, + "line_text": "The IMSIC bit in `mstateen0` controls access to the IMSIC state, including", + "context": " 267| extensions.\n 268| \n>>> 269| The IMSIC bit in `mstateen0` controls access to the IMSIC state, including\n 270| CSRs `stopei` and `vstopei`, provided by the Ssaia extension. The IMSIC bit in\n 271| `hstateen0` controls access to the guest IMSIC state, including CSRs `stopei`" + }, + { + "score": 3, + "reasons": [ + "Description keyword 'IMSIC'", + "Name segment 'IMSIC'" + ], + "is_normative": false, + "in_note": false, + "file": "smstateen.adoc", + "line_number": 270, + "line_text": "CSRs `stopei` and `vstopei`, provided by the Ssaia extension. The IMSIC bit in", + "context": " 268| \n 269| The IMSIC bit in `mstateen0` controls access to the IMSIC state, including\n>>> 270| CSRs `stopei` and `vstopei`, provided by the Ssaia extension. The IMSIC bit in\n 271| `hstateen0` controls access to the guest IMSIC state, including CSRs `stopei`\n 272| (really `vstopei`), provided by the Ssaia extension." + }, + { + "score": 3, + "reasons": [ + "Description keyword 'IMSIC'", + "Name segment 'IMSIC'" + ], + "is_normative": false, + "in_note": false, + "file": "smstateen.adoc", + "line_number": 271, + "line_text": "`hstateen0` controls access to the guest IMSIC state, including CSRs `stopei`", + "context": " 269| The IMSIC bit in `mstateen0` controls access to the IMSIC state, including\n 270| CSRs `stopei` and `vstopei`, provided by the Ssaia extension. The IMSIC bit in\n>>> 271| `hstateen0` controls access to the guest IMSIC state, including CSRs `stopei`\n 272| (really `vstopei`), provided by the Ssaia extension.\n 273| " + } + ] + }, + { + "parameter_name": "HSTATEEN_JVT_TYPE", + "classification": "NORM_CSR_RW", + "value_type": "enum", + "num_candidates": 1, + "best_score": 4, + "candidates": [ + { + "score": 4, + "reasons": [ + "Description keyword 'JVT'" + ], + "is_normative": true, + "in_note": false, + "file": "zc.adoc", + "line_number": 2341, + "line_text": "[#norm:Zcmt_entry_sz]#The base of the table is in the jvt CSR (see <>), each table entry is XLEN bits.#", + "context": " 2339| ==== jvt\n 2340| \n>>> 2341| [#norm:Zcmt_entry_sz]#The base of the table is in the jvt CSR (see <>), each table entry is XLEN bits.#\n 2342| \n 2343| If the same function is called with and without linking then it must have two entries in the table." + } + ] + }, + { + "parameter_name": "HW_MSTATUS_FS_DIRTY_UPDATE", + "classification": "SW_RULE", + "value_type": "enum", + "num_candidates": 10, + "best_score": 26, + "candidates": [ + { + "score": 26, + "reasons": [ + "Description keyword 'FS'", + "Name segment 'MSTATUS'", + "Description keyword 'mstatus.FS'", + "Description keyword 'mstatus'" + ], + "is_normative": true, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 3313, + "line_text": "[#norm:mstatus-FS_off_V_fp_ill]#If the floating-point unit status field `mstatus.FS` is `Off` then any", + "context": " 3311| half-precision floating-point support.\n 3312| \n>>> 3313| [#norm:mstatus-FS_off_V_fp_ill]#If the floating-point unit status field `mstatus.FS` is `Off` then any\n 3314| attempt to execute a vector floating-point instruction will raise an\n 3315| illegal-instruction exception.# [#norm:mstatus-FS_dirty_V_fp]#Any vector floating-point instruction" + }, + { + "score": 25, + "reasons": [ + "Name segment 'DIRTY'", + "Description keyword 'mstatus'", + "Description keyword 'mstatus.FS'", + "Description keyword 'FS'", + "Name segment 'MSTATUS'" + ], + "is_normative": false, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 3317, + "line_text": "CSRs or `f` registers) must set `mstatus.FS` to `Dirty`.#", + "context": " 3315| illegal-instruction exception.# [#norm:mstatus-FS_dirty_V_fp]#Any vector floating-point instruction\n 3316| that modifies any floating-point extension state (i.e., floating-point\n>>> 3317| CSRs or `f` registers) must set `mstatus.FS` to `Dirty`.#\n 3318| \n 3319| [#norm:vsstatus_mstatus-FS_off_hypervisor_V_fp_ill]#If the hypervisor extension is implemented and V=1, the `vsstatus.FS` field is" + }, + { + "score": 25, + "reasons": [ + "Name segment 'DIRTY'", + "Description keyword 'mstatus'", + "Description keyword 'mstatus.FS'", + "Description keyword 'FS'", + "Name segment 'MSTATUS'" + ], + "is_normative": false, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 3325, + "line_text": "CSRs or `f` registers) must set both `mstatus.FS` and `vsstatus.FS` to `Dirty`.#", + "context": " 3323| illegal-instruction exception.# [#norm:vsstatus_mstatus-FS_dirty_hypervisor_V_fp]#Any vector floating-point instruction\n 3324| that modifies any floating-point extension state (i.e., floating-point\n>>> 3325| CSRs or `f` registers) must set both `mstatus.FS` and `vsstatus.FS` to `Dirty`.#\n 3326| \n 3327| The vector floating-point instructions have the same behavior as the" + }, + { + "score": 24, + "reasons": [ + "Description keyword 'FS'", + "Name segment 'MSTATUS'", + "Description keyword 'mstatus.FS'", + "Description keyword 'mstatus'" + ], + "is_normative": false, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 3321, + "line_text": "`vsstatus.FS` or `mstatus.FS` is `Off` then any", + "context": " 3319| [#norm:vsstatus_mstatus-FS_off_hypervisor_V_fp_ill]#If the hypervisor extension is implemented and V=1, the `vsstatus.FS` field is\n 3320| additionally in effect for vector floating-point instructions. If\n>>> 3321| `vsstatus.FS` or `mstatus.FS` is `Off` then any\n 3322| attempt to execute a vector floating-point instruction will raise an\n 3323| illegal-instruction exception.# [#norm:vsstatus_mstatus-FS_dirty_hypervisor_V_fp]#Any vector floating-point instruction" + }, + { + "score": 15, + "reasons": [ + "Description keyword 'FS'", + "Name segment 'MSTATUS'", + "CSR name 'mstatus' in backticks", + "Description keyword 'mstatus'" + ], + "is_normative": false, + "in_note": false, + "file": "zfinx.adoc", + "line_number": 151, + "line_text": "`mstatus` field FS is hardwired to 0 if the Zfinx extension is", + "context": " 149| [[norm:Zfinx_mstatus-FS_zero]]\n 150| In the standard privileged architecture defined in Volume II, the\n>>> 151| `mstatus` field FS is hardwired to 0 if the Zfinx extension is\n 152| implemented, and FS no longer affects the trapping behavior of\n 153| floating-point instructions or `fcsr` accesses." + } + ] + }, + { + "parameter_name": "HW_MSTATUS_VS_DIRTY_UPDATE", + "classification": "SW_RULE", + "value_type": "enum", + "num_candidates": 10, + "best_score": 27, + "candidates": [ + { + "score": 27, + "reasons": [ + "Name segment 'DIRTY'", + "Description keyword 'mstatus'", + "Description keyword 'mstatus.VS'", + "CSR field name 'SD'", + "Name segment 'MSTATUS'", + "Description keyword 'VS'" + ], + "is_normative": false, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 107, + "line_text": "If `mstatus.VS` is Dirty, `mstatus.SD` is 1;", + "context": " 105| \n 106| [[norm:mstatus-sd_op]]\n>>> 107| If `mstatus.VS` is Dirty, `mstatus.SD` is 1;\n 108| otherwise, `mstatus.SD` is set in accordance with existing specifications.\n 109| " + }, + { + "score": 27, + "reasons": [ + "Name segment 'DIRTY'", + "Description keyword 'mstatus'", + "Description keyword 'mstatus.VS'", + "CSR field name 'SD'", + "Name segment 'MSTATUS'", + "Description keyword 'VS'" + ], + "is_normative": false, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 141, + "line_text": "If `mstatus.VS` is Dirty, `mstatus.SD` is 1;", + "context": " 139| \n 140| [[norm:mstatus-sd_op_vs]]\n>>> 141| If `mstatus.VS` is Dirty, `mstatus.SD` is 1;\n 142| otherwise, `mstatus.SD` is set in accordance with existing specifications.\n 143| " + }, + { + "score": 26, + "reasons": [ + "Description keyword 'mstatus'", + "Name segment 'MSTATUS'", + "Description keyword 'mstatus.VS'", + "Description keyword 'VS'" + ], + "is_normative": true, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 130, + "line_text": "[#norm:vsstatus-vs_mstatus-vs_op_active]#When V=1 and neither `vsstatus.VS` nor `mstatus.VS` is set to Off, executing", + "context": " 128| illegal-instruction exception when either field is set to Off.\n 129| \n>>> 130| [#norm:vsstatus-vs_mstatus-vs_op_active]#When V=1 and neither `vsstatus.VS` nor `mstatus.VS` is set to Off, executing\n 131| any instruction that changes vector state, including the vector CSRs, will\n 132| change both `mstatus.VS` and `vsstatus.VS` to Dirty.#" + }, + { + "score": 26, + "reasons": [ + "Description keyword 'mstatus'", + "Name segment 'MSTATUS'", + "Description keyword 'mstatus.VS'", + "Description keyword 'VS'" + ], + "is_normative": true, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 133, + "line_text": "[#norm:hw_mstatus_vs_dirty_update_param]#Implementations may also change `mstatus.VS` or `vsstatus.VS` from Initial or", + "context": " 131| any instruction that changes vector state, including the vector CSRs, will\n 132| change both `mstatus.VS` and `vsstatus.VS` to Dirty.#\n>>> 133| [#norm:hw_mstatus_vs_dirty_update_param]#Implementations may also change `mstatus.VS` or `vsstatus.VS` from Initial or\n 134| Clean to Dirty at any time, even when there is no change in vector state.#\n 135| " + }, + { + "score": 25, + "reasons": [ + "Name segment 'DIRTY'", + "Description keyword 'mstatus'", + "Description keyword 'mstatus.VS'", + "Name segment 'MSTATUS'", + "Description keyword 'VS'" + ], + "is_normative": false, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 99, + "line_text": "change `mstatus.VS` to Dirty.", + "context": " 97| When `mstatus.VS` is set to Initial or Clean, executing any\n 98| instruction that changes vector state, including the vector CSRs, will\n>>> 99| change `mstatus.VS` to Dirty.\n 100| Implementations may also change `mstatus.VS` from Initial or Clean to Dirty\n 101| at any time, even when there is no change in vector state." + } + ] + }, + { + "parameter_name": "IGNORE_INVALID_VSATP_MODE_WRITES_WHEN_V_EQ_ZERO", + "classification": "NORM_CSR_WARL", + "value_type": "binary", + "num_candidates": 10, + "best_score": 9, + "candidates": [ + { + "score": 9, + "reasons": [ + "WARL + CSR 'vsatp'", + "Name segment 'VSATP'", + "CSR name 'vsatp' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1416, + "line_text": "ignored as it is for `satp`, or the fields of `vsatp` are treated as *WARL* in", + "context": " 1414| \n 1415| [#norm:vsatp_mode_unsupported_v0]#When V=0, a write to `vsatp` with an unsupported MODE value is either\n>>> 1416| ignored as it is for `satp`, or the fields of `vsatp` are treated as *WARL* in\n 1417| the normal way.# [#norm:vsatp_mode_unsupported_v1]#However, when V=1, a write to `satp` with an unsupported\n 1418| MODE value _is_ ignored and no write to `vsatp` is effected.#" + }, + { + "score": 8, + "reasons": [ + "CSR field name 'MODE'", + "Name segment 'VSATP'", + "CSR name 'vsatp' in backticks" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1415, + "line_text": "[#norm:vsatp_mode_unsupported_v0]#When V=0, a write to `vsatp` with an unsupported MODE value is either", + "context": " 1413| ====\n 1414| \n>>> 1415| [#norm:vsatp_mode_unsupported_v0]#When V=0, a write to `vsatp` with an unsupported MODE value is either\n 1416| ignored as it is for `satp`, or the fields of `vsatp` are treated as *WARL* in\n 1417| the normal way.# [#norm:vsatp_mode_unsupported_v1]#However, when V=1, a write to `satp` with an unsupported" + }, + { + "score": 6, + "reasons": [ + "CSR field name 'MODE'", + "Name segment 'VSATP'", + "CSR name 'vsatp' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1418, + "line_text": "MODE value _is_ ignored and no write to `vsatp` is effected.#", + "context": " 1416| ignored as it is for `satp`, or the fields of `vsatp` are treated as *WARL* in\n 1417| the normal way.# [#norm:vsatp_mode_unsupported_v1]#However, when V=1, a write to `satp` with an unsupported\n>>> 1418| MODE value _is_ ignored and no write to `vsatp` is effected.#\n 1419| \n 1420| [[norm:vsatp_v0]]" + }, + { + "score": 6, + "reasons": [ + "CSR field name 'MODE'", + "Name segment 'VSATP'", + "CSR name 'vsatp' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 2800, + "line_text": "`hgatp`.MODE and `vsatp`.MODE fields are reset to 0. If the Smrnmi", + "context": " 2798| the platform mandates a different reset value for some PMP registers’ A\n 2799| and L fields. If the hypervisor extension is implemented, the\n>>> 2800| `hgatp`.MODE and `vsatp`.MODE fields are reset to 0. If the Smrnmi\n 2801| extension is implemented, the `mnstatus`.NMIE field is reset to 0. No\n 2802| *WARL* field contains an illegal value. If the Zicfilp extension is" + }, + { + "score": 6, + "reasons": [ + "CSR field name 'MODE'", + "Name segment 'VSATP'", + "CSR name 'vsatp' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 2340, + "line_text": "Second, if `vsatp`.MODE is not equal to zero, non-zero VS-stage PTE PBMT", + "context": " 2338| override the attributes in the PMA to produce an intermediate set of\n 2339| attributes. Otherwise, the PMAs serve as the intermediate attributes.\n>>> 2340| Second, if `vsatp`.MODE is not equal to zero, non-zero VS-stage PTE PBMT\n 2341| bits override the intermediate attributes to produce the final set of\n 2342| attributes used by accesses to the page in question. Otherwise, the" + } + ] + }, + { + "parameter_name": "IMP_ID_VALUE", + "classification": "NORM_DIRECT", + "value_type": "conditional", + "num_candidates": 10, + "best_score": 5, + "candidates": [ + { + "score": 5, + "reasons": [ + "CSR field name 'Implementation'", + "CSR name 'mimpid' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 335, + "line_text": "==== Machine Implementation ID (`mimpid`) Register", + "context": " 333| ====\n 334| \n>>> 335| ==== Machine Implementation ID (`mimpid`) Register\n 336| \n 337| [#norm:mimpid_op]#The `mimpid` CSR provides a unique encoding of the version of the" + }, + { + "score": 5, + "reasons": [ + "CSR name 'mimpid' in backticks" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 337, + "line_text": "[#norm:mimpid_op]#The `mimpid` CSR provides a unique encoding of the version of the", + "context": " 335| ==== Machine Implementation ID (`mimpid`) Register\n 336| \n>>> 337| [#norm:mimpid_op]#The `mimpid` CSR provides a unique encoding of the version of the\n 338| processor implementation.#\n 339| [#norm:mimpid_always_rd]#This register must be readable in any" + }, + { + "score": 5, + "reasons": [ + "CSR field name 'Implementation'", + "CSR name 'mimpid' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 343, + "line_text": ".Machine Implementation ID (`mimpid`) register", + "context": " 341| The Implementation value should reflect the design of the RISC-V processor itself and not any surrounding system.\n 342| \n>>> 343| .Machine Implementation ID (`mimpid`) register\n 344| include::images/bytefield/mimpid.edn[]\n 345| " + }, + { + "score": 4, + "reasons": [ + "CSR field name 'Implementation'" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 245, + "line_text": "implementation-specific, bounded time limit.# [#norm:vtw_virtinstr_param]#An implementation may have", + "context": " 243| an attempt in VS-mode to execute WFI raises a virtual-instruction\n 244| exception if the WFI does not complete within an\n>>> 245| implementation-specific, bounded time limit.# [#norm:vtw_virtinstr_param]#An implementation may have\n 246| WFI always raise a virtual-instruction exception in VS-mode when VTW=1\n 247| (and `mstatus`.TW=0), even if there are pending globally-disabled" + }, + { + "score": 4, + "reasons": [ + "CSR field name 'Implementation'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 22, + "line_text": "[#norm:misa_always_rd]#This register must be readable in any implementation#,", + "context": " 20| \n 21| [#norm:misa_acc]#The `misa` CSR is a *WARL* read-write register# reporting the ISA supported by the hart.\n>>> 22| [#norm:misa_always_rd]#This register must be readable in any implementation#,\n 23| but [#norm:misa_csr_implemented]#a value of zero can be returned to indicate the `misa` register has not been implemented#, requiring that CPU capabilities be determined through a separate non-standard mechanism.\n 24| " + } + ] + }, + { + "parameter_name": "JVT_BASE_MASK", + "classification": "NORM_CSR_WARL", + "value_type": "range", + "num_candidates": 10, + "best_score": 8, + "candidates": [ + { + "score": 8, + "reasons": [ + "CSR field name 'BASE'", + "Description keyword 'BASE'" + ], + "is_normative": true, + "in_note": false, + "file": "c-st-ext.adoc", + "line_number": 466, + "line_text": "instructions. [#norm:Zca_offsets_mul2]#As with base RVI instructions, the offsets of all RVC", + "context": " 464| \n 465| RVC provides unconditional jump instructions and conditional branch\n>>> 466| instructions. [#norm:Zca_offsets_mul2]#As with base RVI instructions, the offsets of all RVC\n 467| control transfer instructions are in multiples of 2 bytes.#\n 468| " + }, + { + "score": 8, + "reasons": [ + "CSR field name 'BASE'", + "Description keyword 'BASE'" + ], + "is_normative": true, + "in_note": false, + "file": "cmo.adoc", + "line_number": 858, + "line_text": "effective address is the base address specified in _rs1_.# [#norm:cbo-clean_offset]#The offset operand may", + "context": " 856| \n 857| [#norm:cbo-clean_op]#A *cbo.clean* instruction performs a clean operation on the cache block whose\n>>> 858| effective address is the base address specified in _rs1_.# [#norm:cbo-clean_offset]#The offset operand may\n 859| be omitted; otherwise, any expression that computes the offset shall evaluate to\n 860| zero.# The instruction operates on the set of coherent caches accessed by the" + }, + { + "score": 8, + "reasons": [ + "CSR field name 'BASE'", + "Description keyword 'BASE'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 29, + "line_text": "[#norm:misa_mxl_op_isa]#The MXL (Machine XLEN) field encodes the native base integer ISA width as", + "context": " 27| include::images/bytefield/misareg.edn[]\n 28| \n>>> 29| [#norm:misa_mxl_op_isa]#The MXL (Machine XLEN) field encodes the native base integer ISA width as\n 30| shown in <>.#\n 31| [#norm:misa_mxl_acc]#The MXL field is read-only.#" + }, + { + "score": 8, + "reasons": [ + "CSR field name 'BASE'", + "Description keyword 'BASE'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 69, + "line_text": "[#norm:misa_i_op]#The \"I\" bit will be set for the RV32I and RV64I base ISAs#,", + "context": " 67| extension \"A\" , bit 1 encodes presence of extension \"B\", through to\n 68| bit 25 which encodes \"Z\").#\n>>> 69| [#norm:misa_i_op]#The \"I\" bit will be set for the RV32I and RV64I base ISAs#,\n 70| and [#norm:misa_e_op]#the \"E\" bit will be set for RV32E and RV64E.#\n 71| [#norm:misa_extensions_warl_op]#The Extensions field is a *WARL* field that can contain writable bits where the" + }, + { + "score": 8, + "reasons": [ + "CSR field name 'BASE'", + "Description keyword 'BASE'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 299, + "line_text": "[#norm:marchid_sz_acc_op]#The `marchid` CSR is an MXLEN-bit read-only register encoding the base", + "context": " 297| ==== Machine Architecture ID (`marchid`) Register\n 298| \n>>> 299| [#norm:marchid_sz_acc_op]#The `marchid` CSR is an MXLEN-bit read-only register encoding the base\n 300| microarchitecture of the hart.#\n 301| [#norm:marchid_always_rd]#This register must be readable in any" + } + ] + }, + { + "parameter_name": "JVT_BASE_TYPE", + "classification": "NORM_CSR_WARL", + "value_type": "binary", + "num_candidates": 10, + "best_score": 10, + "candidates": [ + { + "score": 10, + "reasons": [ + "CSR field name 'BASE'", + "Description keyword 'BASE'" + ], + "is_normative": true, + "in_note": false, + "file": "c-st-ext.adoc", + "line_number": 466, + "line_text": "instructions. [#norm:Zca_offsets_mul2]#As with base RVI instructions, the offsets of all RVC", + "context": " 464| \n 465| RVC provides unconditional jump instructions and conditional branch\n>>> 466| instructions. [#norm:Zca_offsets_mul2]#As with base RVI instructions, the offsets of all RVC\n 467| control transfer instructions are in multiples of 2 bytes.#\n 468| " + }, + { + "score": 10, + "reasons": [ + "CSR field name 'BASE'", + "Description keyword 'BASE'" + ], + "is_normative": true, + "in_note": false, + "file": "cmo.adoc", + "line_number": 858, + "line_text": "effective address is the base address specified in _rs1_.# [#norm:cbo-clean_offset]#The offset operand may", + "context": " 856| \n 857| [#norm:cbo-clean_op]#A *cbo.clean* instruction performs a clean operation on the cache block whose\n>>> 858| effective address is the base address specified in _rs1_.# [#norm:cbo-clean_offset]#The offset operand may\n 859| be omitted; otherwise, any expression that computes the offset shall evaluate to\n 860| zero.# The instruction operates on the set of coherent caches accessed by the" + }, + { + "score": 10, + "reasons": [ + "CSR field name 'BASE'", + "Description keyword 'BASE'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 29, + "line_text": "[#norm:misa_mxl_op_isa]#The MXL (Machine XLEN) field encodes the native base integer ISA width as", + "context": " 27| include::images/bytefield/misareg.edn[]\n 28| \n>>> 29| [#norm:misa_mxl_op_isa]#The MXL (Machine XLEN) field encodes the native base integer ISA width as\n 30| shown in <>.#\n 31| [#norm:misa_mxl_acc]#The MXL field is read-only.#" + }, + { + "score": 10, + "reasons": [ + "CSR field name 'BASE'", + "Description keyword 'BASE'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 69, + "line_text": "[#norm:misa_i_op]#The \"I\" bit will be set for the RV32I and RV64I base ISAs#,", + "context": " 67| extension \"A\" , bit 1 encodes presence of extension \"B\", through to\n 68| bit 25 which encodes \"Z\").#\n>>> 69| [#norm:misa_i_op]#The \"I\" bit will be set for the RV32I and RV64I base ISAs#,\n 70| and [#norm:misa_e_op]#the \"E\" bit will be set for RV32E and RV64E.#\n 71| [#norm:misa_extensions_warl_op]#The Extensions field is a *WARL* field that can contain writable bits where the" + }, + { + "score": 10, + "reasons": [ + "CSR field name 'BASE'", + "Description keyword 'BASE'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 299, + "line_text": "[#norm:marchid_sz_acc_op]#The `marchid` CSR is an MXLEN-bit read-only register encoding the base", + "context": " 297| ==== Machine Architecture ID (`marchid`) Register\n 298| \n>>> 299| [#norm:marchid_sz_acc_op]#The `marchid` CSR is an MXLEN-bit read-only register encoding the base\n 300| microarchitecture of the hart.#\n 301| [#norm:marchid_always_rd]#This register must be readable in any" + } + ] + }, + { + "parameter_name": "JVT_READ_ONLY", + "classification": "NORM_CSR_WARL", + "value_type": "binary", + "num_candidates": 10, + "best_score": 6, + "candidates": [ + { + "score": 6, + "reasons": [ + "CSR field name 'BASE'", + "Description keyword 'JVT'" + ], + "is_normative": true, + "in_note": false, + "file": "zc.adoc", + "line_number": 2341, + "line_text": "[#norm:Zcmt_entry_sz]#The base of the table is in the jvt CSR (see <>), each table entry is XLEN bits.#", + "context": " 2339| ==== jvt\n 2340| \n>>> 2341| [#norm:Zcmt_entry_sz]#The base of the table is in the jvt CSR (see <>), each table entry is XLEN bits.#\n 2342| \n 2343| If the same function is called with and without linking then it must have two entries in the table." + }, + { + "score": 6, + "reasons": [ + "CSR field name 'BASE'", + "CSR field name 'MODE'" + ], + "is_normative": true, + "in_note": false, + "file": "zc.adoc", + "line_number": 2399, + "line_text": "[#norm:jvt_reg]#The _jvt_ register is an XLEN-bit *WARL* read/write register that holds the jump table configuration, consisting of the jump table base address (BASE) and the jump table mode (MODE).#", + "context": " 2397| Description::\n 2398| \n>>> 2399| [#norm:jvt_reg]#The _jvt_ register is an XLEN-bit *WARL* read/write register that holds the jump table configuration, consisting of the jump table base address (BASE) and the jump table mode (MODE).#\n 2400| \n 2401| [#norm:jvt_op]#If <> is implemented then _jvt_ must also be implemented, but can contain a read-only value. If _jvt_ is writable, the set of values the register may hold can vary by implementation. The value in the BASE field must always be aligned on a 64-byte boundary." + }, + { + "score": 5, + "reasons": [ + "Optional/read-only pattern for boolean param", + "CSR field name 'MODE'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 423, + "line_text": "[#norm:mstatus_sie_spie_rdonly0]#If supervisor mode is not implemented, then SIE and SPIE are read-only 0.#", + "context": " 421| to disable selected higher-privilege-mode interrupts before ceding\n 422| control to a lower-privilege mode.\n>>> 423| [#norm:mstatus_sie_spie_rdonly0]#If supervisor mode is not implemented, then SIE and SPIE are read-only 0.#\n 424| \n 425| [NOTE]" + }, + { + "score": 5, + "reasons": [ + "Optional/read-only pattern for boolean param", + "CSR field name 'MODE'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 479, + "line_text": "[#norm:mstatus_xpp_rdonly0]#If privilege mode _x_ is not implemented, then __x__PP must be read-only 0.#", + "context": " 477| \n 478| [#norm:mstatus_xpp_warl]#__x__PP fields are *WARL* fields that can hold only privilege mode _x_ and any implemented privilege mode lower than _x_.#\n>>> 479| [#norm:mstatus_xpp_rdonly0]#If privilege mode _x_ is not implemented, then __x__PP must be read-only 0.#\n 480| \n 481| [NOTE]" + }, + { + "score": 5, + "reasons": [ + "Optional/read-only pattern for boolean param", + "CSR field name 'MODE'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 577, + "line_text": "[#norm:mstatus_sxl_acc_mxlen64]#When MXLEN=64, if S-mode is not supported, then SXL is read-only zero.", + "context": " 575| When MXLEN=32, the SXL and UXL fields do not exist, and SXLEN=32 and UXLEN=32.\n 576| \n>>> 577| [#norm:mstatus_sxl_acc_mxlen64]#When MXLEN=64, if S-mode is not supported, then SXL is read-only zero.\n 578| Otherwise, it is a *WARL* field that encodes the current value of SXLEN.#\n 579| In particular, [#norm:mstatus_sxl_rdonly_mxlen64]#an implementation may make SXL be a read-only field whose" + } + ] + }, + { + "parameter_name": "LRSC_FAIL_ON_NON_EXACT_LRSC", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 3, + "candidates": [ + { + "score": 3, + "reasons": [ + "Name segment 'FAIL'", + "Description keyword 'SC'" + ], + "is_normative": false, + "in_note": false, + "file": "a-st-ext.adoc", + "line_number": 169, + "line_text": "The SC must fail if the address is not within the reservation set of the", + "context": " 167| ====\n 168| \n>>> 169| The SC must fail if the address is not within the reservation set of the\n 170| most recent LR in program order. The SC must fail if a store to the\n 171| reservation set from another hart can be observed to occur between the" + }, + { + "score": 3, + "reasons": [ + "Name segment 'FAIL'", + "Description keyword 'SC'" + ], + "is_normative": false, + "in_note": false, + "file": "a-st-ext.adoc", + "line_number": 170, + "line_text": "most recent LR in program order. The SC must fail if a store to the", + "context": " 168| \n 169| The SC must fail if the address is not within the reservation set of the\n>>> 170| most recent LR in program order. The SC must fail if a store to the\n 171| reservation set from another hart can be observed to occur between the\n 172| LR and SC. The SC must fail if a write from some other device to the" + }, + { + "score": 3, + "reasons": [ + "Name segment 'FAIL'", + "Description keyword 'SC'" + ], + "is_normative": false, + "in_note": false, + "file": "a-st-ext.adoc", + "line_number": 172, + "line_text": "LR and SC. The SC must fail if a write from some other device to the", + "context": " 170| most recent LR in program order. The SC must fail if a store to the\n 171| reservation set from another hart can be observed to occur between the\n>>> 172| LR and SC. The SC must fail if a write from some other device to the\n 173| bytes accessed by the LR can be observed to occur between the LR and SC.\n 174| (If such a device writes the reservation set but does not write the" + }, + { + "score": 3, + "reasons": [ + "Name segment 'FAIL'", + "Description keyword 'SC'" + ], + "is_normative": false, + "in_note": false, + "file": "a-st-ext.adoc", + "line_number": 175, + "line_text": "bytes accessed by the LR, the SC may or may not fail.) An SC must fail", + "context": " 173| bytes accessed by the LR can be observed to occur between the LR and SC.\n 174| (If such a device writes the reservation set but does not write the\n>>> 175| bytes accessed by the LR, the SC may or may not fail.) An SC must fail\n 176| if there is another SC (to any address) between the LR and the SC in\n 177| program order. The precise statement of the atomicity requirements for" + }, + { + "score": 3, + "reasons": [ + "Optional/read-only pattern for boolean param" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 25, + "line_text": "registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and", + "context": " 23| The hypervisor extension depends on an \"I\" base integer ISA with 32\n 24| `x` registers (RV32I or RV64I), not RV32E or RV64E, which have only 16 `x`\n>>> 25| registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and\n 26| [#norm:H_vm_supported]#standard\n 27| page-based address translation must be supported, either Sv32 for RV32," + } + ] + }, + { + "parameter_name": "LRSC_FAIL_ON_VA_SYNONYM", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 7, + "candidates": [ + { + "score": 7, + "reasons": [ + "Description keyword 'LR'", + "Description keyword 'SC'", + "Description keyword 'lr.d'" + ], + "is_normative": false, + "in_note": false, + "file": "a-st-ext.adoc", + "line_number": 76, + "line_text": "SC.W instruction invalidates any reservation held by this hart. LR.D and", + "context": " 74| treated like a store.\n 75| Regardless of success or failure, executing an\n>>> 76| SC.W instruction invalidates any reservation held by this hart. LR.D and\n 77| SC.D act analogously on doublewords and are only available on RV64. For\n 78| RV64, LR.W and SC.W sign-extend the value placed in _rd_." + }, + { + "score": 5, + "reasons": [ + "Description keyword 'sc.d'", + "Description keyword 'SC'" + ], + "is_normative": false, + "in_note": false, + "file": "a-st-ext.adoc", + "line_number": 77, + "line_text": "SC.D act analogously on doublewords and are only available on RV64. For", + "context": " 75| Regardless of success or failure, executing an\n 76| SC.W instruction invalidates any reservation held by this hart. LR.D and\n>>> 77| SC.D act analogously on doublewords and are only available on RV64. For\n 78| RV64, LR.W and SC.W sign-extend the value placed in _rd_.\n 79| " + }, + { + "score": 5, + "reasons": [ + "Description keyword 'LR'", + "Name segment 'FAIL'", + "Description keyword 'SC'" + ], + "is_normative": false, + "in_note": false, + "file": "a-st-ext.adoc", + "line_number": 170, + "line_text": "most recent LR in program order. The SC must fail if a store to the", + "context": " 168| \n 169| The SC must fail if the address is not within the reservation set of the\n>>> 170| most recent LR in program order. The SC must fail if a store to the\n 171| reservation set from another hart can be observed to occur between the\n 172| LR and SC. The SC must fail if a write from some other device to the" + }, + { + "score": 5, + "reasons": [ + "Description keyword 'LR'", + "Name segment 'FAIL'", + "Description keyword 'SC'" + ], + "is_normative": false, + "in_note": false, + "file": "a-st-ext.adoc", + "line_number": 172, + "line_text": "LR and SC. The SC must fail if a write from some other device to the", + "context": " 170| most recent LR in program order. The SC must fail if a store to the\n 171| reservation set from another hart can be observed to occur between the\n>>> 172| LR and SC. The SC must fail if a write from some other device to the\n 173| bytes accessed by the LR can be observed to occur between the LR and SC.\n 174| (If such a device writes the reservation set but does not write the" + }, + { + "score": 5, + "reasons": [ + "Description keyword 'LR'", + "Name segment 'FAIL'", + "Description keyword 'SC'" + ], + "is_normative": false, + "in_note": false, + "file": "a-st-ext.adoc", + "line_number": 175, + "line_text": "bytes accessed by the LR, the SC may or may not fail.) An SC must fail", + "context": " 173| bytes accessed by the LR can be observed to occur between the LR and SC.\n 174| (If such a device writes the reservation set but does not write the\n>>> 175| bytes accessed by the LR, the SC may or may not fail.) An SC must fail\n 176| if there is another SC (to any address) between the LR and the SC in\n 177| program order. The precise statement of the atomicity requirements for" + } + ] + }, + { + "parameter_name": "LRSC_MISALIGNED_BEHAVIOR", + "classification": "NORM_DIRECT", + "value_type": "enum", + "num_candidates": 10, + "best_score": 12, + "candidates": [ + { + "score": 12, + "reasons": [ + "Description keyword 'LR'", + "Description keyword 'SC'" + ], + "is_normative": false, + "in_note": false, + "file": "a-st-ext.adoc", + "line_number": 59, + "line_text": "are performed with the load-reserved (LR) and store-conditional (SC)", + "context": " 57| \n 58| Complex atomic memory operations on a single memory word or doubleword\n>>> 59| are performed with the load-reserved (LR) and store-conditional (SC)\n 60| instructions. LR.W loads a word from the address in _rs1_, places the\n 61| sign-extended value in _rd_, and registers a _reservation set_—a set of" + }, + { + "score": 12, + "reasons": [ + "Description keyword 'LR'", + "Description keyword 'SC'" + ], + "is_normative": false, + "in_note": false, + "file": "a-st-ext.adoc", + "line_number": 76, + "line_text": "SC.W instruction invalidates any reservation held by this hart. LR.D and", + "context": " 74| treated like a store.\n 75| Regardless of success or failure, executing an\n>>> 76| SC.W instruction invalidates any reservation held by this hart. LR.D and\n 77| SC.D act analogously on doublewords and are only available on RV64. For\n 78| RV64, LR.W and SC.W sign-extend the value placed in _rd_." + }, + { + "score": 12, + "reasons": [ + "Description keyword 'LR'", + "Description keyword 'SC'" + ], + "is_normative": false, + "in_note": false, + "file": "a-st-ext.adoc", + "line_number": 78, + "line_text": "RV64, LR.W and SC.W sign-extend the value placed in _rd_.", + "context": " 76| SC.W instruction invalidates any reservation held by this hart. LR.D and\n 77| SC.D act analogously on doublewords and are only available on RV64. For\n>>> 78| RV64, LR.W and SC.W sign-extend the value placed in _rd_.\n 79| \n 80| [NOTE]" + }, + { + "score": 12, + "reasons": [ + "Description keyword 'LR'", + "Description keyword 'SC'" + ], + "is_normative": false, + "in_note": false, + "file": "a-st-ext.adoc", + "line_number": 126, + "line_text": "For LR and SC, the Zalrsc extension requires that the address held in _rs1_", + "context": " 124| ====\n 125| \n>>> 126| For LR and SC, the Zalrsc extension requires that the address held in _rs1_\n 127| be naturally aligned to the size of the operand (i.e., eight-byte\n 128| aligned for _doublewords_ and four-byte aligned for _words_). If the" + }, + { + "score": 12, + "reasons": [ + "Description keyword 'LR'", + "Description keyword 'SC'" + ], + "is_normative": false, + "in_note": false, + "file": "a-st-ext.adoc", + "line_number": 146, + "line_text": "recent LR in program order. An SC may succeed only if no store from", + "context": " 144| each LR, provided the reservation set includes all bytes of the\n 145| addressed data word or doubleword. An SC can only pair with the most\n>>> 146| recent LR in program order. An SC may succeed only if no store from\n 147| another hart to the reservation set can be observed to have occurred\n 148| between the LR and the SC, and if there is no other SC between the LR" + } + ] + }, + { + "parameter_name": "LRSC_RESERVATION_STRATEGY", + "classification": "NORM_DIRECT", + "value_type": "enum", + "num_candidates": 10, + "best_score": 19, + "candidates": [ + { + "score": 19, + "reasons": [ + "Description keyword 'LR'", + "Description keyword 'reservation'", + "Name segment 'RESERVATION'", + "Description keyword 'SC'" + ], + "is_normative": false, + "in_note": false, + "file": "a-st-ext.adoc", + "line_number": 76, + "line_text": "SC.W instruction invalidates any reservation held by this hart. LR.D and", + "context": " 74| treated like a store.\n 75| Regardless of success or failure, executing an\n>>> 76| SC.W instruction invalidates any reservation held by this hart. LR.D and\n 77| SC.D act analogously on doublewords and are only available on RV64. For\n 78| RV64, LR.W and SC.W sign-extend the value placed in _rd_." + }, + { + "score": 19, + "reasons": [ + "Description keyword 'LR'", + "Description keyword 'reservation'", + "Name segment 'RESERVATION'", + "Description keyword 'SC'" + ], + "is_normative": false, + "in_note": false, + "file": "a-st-ext.adoc", + "line_number": 316, + "line_text": "the reservation set of the LR instruction in _H_'s constrained LR/SC", + "context": " 314| of the LR instruction in _H_'s constrained LR/SC loops.\n 315| * Some other hart executes an unconditional store or AMO instruction to\n>>> 316| the reservation set of the LR instruction in _H_'s constrained LR/SC\n 317| loop, or some other device in the system writes to that reservation set.\n 318| * _H_ executes a branch or jump that exits the constrained LR/SC loop." + }, + { + "score": 19, + "reasons": [ + "Description keyword 'LR'", + "Description keyword 'reservation'", + "Name segment 'RESERVATION'", + "Description keyword 'SC'" + ], + "is_normative": false, + "in_note": false, + "file": "priv-preface.adoc", + "line_number": 418, + "line_text": "* Constrained the LR/SC reservation set size and shape when using", + "context": " 416| specification implied that PPO rules other than fences and\n 417| acquire/release annotations did not apply.\n>>> 418| * Constrained the LR/SC reservation set size and shape when using\n 419| page-based virtual memory.\n 420| * PMP changes require an SFENCE.VMA on any hart that implements" + }, + { + "score": 19, + "reasons": [ + "Description keyword 'LR'", + "Description keyword 'reservation'", + "Name segment 'RESERVATION'", + "Description keyword 'SC'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 1714, + "line_text": "standard extension, the LR/SC reservation set must lie completely within", + "context": " 1712| \n 1713| For implementations with both page-based virtual memory and the \"A\"\n>>> 1714| standard extension, the LR/SC reservation set must lie completely within\n 1715| a single base physical page (i.e., a naturally aligned 4 KiB physical-memory\n 1716| region)." + }, + { + "score": 16, + "reasons": [ + "Description keyword 'LR'", + "Description keyword 'SC'" + ], + "is_normative": false, + "in_note": false, + "file": "a-st-ext.adoc", + "line_number": 59, + "line_text": "are performed with the load-reserved (LR) and store-conditional (SC)", + "context": " 57| \n 58| Complex atomic memory operations on a single memory word or doubleword\n>>> 59| are performed with the load-reserved (LR) and store-conditional (SC)\n 60| instructions. LR.W loads a word from the address in _rs1_, places the\n 61| sign-extended value in _rd_, and registers a _reservation set_—a set of" + } + ] + }, + { + "parameter_name": "MARCHID_IMPLEMENTED", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 10, + "candidates": [ + { + "score": 10, + "reasons": [ + "Description keyword 'implemented'", + "Name segment 'MARCHID'", + "Name segment 'IMPLEMENTED'", + "Description keyword 'marchid'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 303, + "line_text": "The combination of `mvendorid` and `marchid` should uniquely identify the type of hart microarchitecture that is implemented.", + "context": " 301| [#norm:marchid_always_rd]#This register must be readable in any\n 302| implementation, but a value of 0 can be returned to indicate the field is not implemented.#\n>>> 303| The combination of `mvendorid` and `marchid` should uniquely identify the type of hart microarchitecture that is implemented.\n 304| \n 305| .Machine Architecture ID (`marchid`) register" + }, + { + "score": 9, + "reasons": [ + "Name segment 'MARCHID'", + "Description keyword 'marchid'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 299, + "line_text": "[#norm:marchid_sz_acc_op]#The `marchid` CSR is an MXLEN-bit read-only register encoding the base", + "context": " 297| ==== Machine Architecture ID (`marchid`) Register\n 298| \n>>> 299| [#norm:marchid_sz_acc_op]#The `marchid` CSR is an MXLEN-bit read-only register encoding the base\n 300| microarchitecture of the hart.#\n 301| [#norm:marchid_always_rd]#This register must be readable in any" + }, + { + "score": 7, + "reasons": [ + "Name segment 'MARCHID'", + "Description keyword 'marchid'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 297, + "line_text": "==== Machine Architecture ID (`marchid`) Register", + "context": " 295| ====\n 296| \n>>> 297| ==== Machine Architecture ID (`marchid`) Register\n 298| \n 299| [#norm:marchid_sz_acc_op]#The `marchid` CSR is an MXLEN-bit read-only register encoding the base" + }, + { + "score": 7, + "reasons": [ + "Name segment 'MARCHID'", + "Description keyword 'marchid'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 305, + "line_text": ".Machine Architecture ID (`marchid`) register", + "context": " 303| The combination of `mvendorid` and `marchid` should uniquely identify the type of hart microarchitecture that is implemented.\n 304| \n>>> 305| .Machine Architecture ID (`marchid`) register\n 306| include::images/bytefield/marchid.edn[]\n 307| " + }, + { + "score": 7, + "reasons": [ + "Name segment 'MARCHID'", + "Description keyword 'marchid'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 306, + "line_text": "include::images/bytefield/marchid.edn[]", + "context": " 304| \n 305| .Machine Architecture ID (`marchid`) register\n>>> 306| include::images/bytefield/marchid.edn[]\n 307| \n 308| Open-source project architecture IDs are allocated globally by RISC-V" + } + ] + }, + { + "parameter_name": "MCID_WIDTH", + "classification": "NORM_CSR_WARL", + "value_type": "range", + "num_candidates": 10, + "best_score": 8, + "candidates": [ + { + "score": 8, + "reasons": [ + "CSR field name 'MCID'", + "CSR name 'srmcfg' in backticks", + "Description keyword 'MCID'", + "Name segment 'MCID'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 2586, + "line_text": "The `RCID` and `MCID` configured in the `srmcfg` CSR apply to all privilege", + "context": " 2584| ....\n 2585| \n>>> 2586| The `RCID` and `MCID` configured in the `srmcfg` CSR apply to all privilege\n 2587| modes of software execution on that hart by default, but this behavior may be\n 2588| overridden by future extensions." + }, + { + "score": 7, + "reasons": [ + "Description keyword 'ID'", + "CSR field name 'MCID'", + "Description keyword 'MCID'", + "Name segment 'MCID'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 2531, + "line_text": "Control ID (`RCID`) and a Monitoring Counter ID (`MCID`). These identifiers", + "context": " 2529| To facilitate this, the QoS Identifiers extension (Ssqosid) introduces the\n 2530| `srmcfg` register, which configures a hart with two identifiers: a Resource\n>>> 2531| Control ID (`RCID`) and a Monitoring Counter ID (`MCID`). These identifiers\n 2532| accompany each request issued by the hart to shared resource controllers.\n 2533| " + }, + { + "score": 7, + "reasons": [ + "Description keyword 'ID'", + "CSR field name 'MCID'", + "Description keyword 'MCID'", + "Name segment 'MCID'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 2551, + "line_text": "Resource Control ID (`RCID`) and a Monitoring Counter ID (`MCID`). Both `RCID`", + "context": " 2549| \n 2550| The `srmcfg` register is an SXLEN-bit read/write register used to configure a\n>>> 2551| Resource Control ID (`RCID`) and a Monitoring Counter ID (`MCID`). Both `RCID`\n 2552| and `MCID` are WARL fields. The register is formatted as shown in <>\n 2553| when SXLEN=64 and <> when SXLEN=32." + }, + { + "score": 5, + "reasons": [ + "CSR field name 'MCID'", + "Description keyword 'MCID'", + "Name segment 'MCID'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 2535, + "line_text": "originating supervisor domain, can accompany `RCID` and `MCID`. Resource", + "context": " 2533| \n 2534| Additional metadata, like the nature of the memory access and the ID of the\n>>> 2535| originating supervisor domain, can accompany `RCID` and `MCID`. Resource\n 2536| controllers may use this metadata for differentiated service such as a different\n 2537| capacity allocation for code storage vs. data storage. Resource controllers can" + }, + { + "score": 5, + "reasons": [ + "CSR field name 'MCID'", + "Description keyword 'MCID'", + "Name segment 'MCID'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 2544, + "line_text": "resource allocations, while the `MCID` is used for tracking resource usage.", + "context": " 2542| QoS Register Interface (CBQRI) specification, which provides methods for setting\n 2543| resource usage limits and monitoring resource consumption. The `RCID` controls\n>>> 2544| resource allocations, while the `MCID` is used for tracking resource usage.\n 2545| \n 2546| NOTE: The Ssqosid extension does not require that S-mode mode be implemented." + } + ] + }, + { + "parameter_name": "MCONTEXT_AVAILABLE", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 6, + "candidates": [ + { + "score": 6, + "reasons": [ + "Description keyword 'MCONTEXT'", + "Name segment 'MCONTEXT'", + "CSR name 'mcontext' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "priv-csrs.adoc", + "line_number": 1019, + "line_text": "`mcontext`", + "context": " 1017| `tdata2` +\n 1018| `tdata3` +\n>>> 1019| `mcontext`\n 1020| \n 1021| |Debug/Trace trigger register select. +" + }, + { + "score": 3, + "reasons": [ + "Optional/read-only pattern for boolean param" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 25, + "line_text": "registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and", + "context": " 23| The hypervisor extension depends on an \"I\" base integer ISA with 32\n 24| `x` registers (RV32I or RV64I), not RV32E or RV64E, which have only 16 `x`\n>>> 25| registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and\n 26| [#norm:H_vm_supported]#standard\n 27| page-based address translation must be supported, either Sv32 for RV32," + }, + { + "score": 3, + "reasons": [ + "Optional/read-only pattern for boolean param" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 231, + "line_text": "[#norm:misa_e_not_i]#Unless `misa` is all read-only zero, the", + "context": " 229| \n 230| [#norm:misa_e_acc]#The \"E\" bit is read-only.#\n>>> 231| [#norm:misa_e_not_i]#Unless `misa` is all read-only zero, the\n 232| \"E\" bit always reads as the complement of the \"I\" bit.#\n 233| If an execution environment supports both RV32E and RV32I, software can select" + }, + { + "score": 3, + "reasons": [ + "Optional/read-only pattern for boolean param" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 423, + "line_text": "[#norm:mstatus_sie_spie_rdonly0]#If supervisor mode is not implemented, then SIE and SPIE are read-only 0.#", + "context": " 421| to disable selected higher-privilege-mode interrupts before ceding\n 422| control to a lower-privilege mode.\n>>> 423| [#norm:mstatus_sie_spie_rdonly0]#If supervisor mode is not implemented, then SIE and SPIE are read-only 0.#\n 424| \n 425| [NOTE]" + }, + { + "score": 3, + "reasons": [ + "Optional/read-only pattern for boolean param" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 479, + "line_text": "[#norm:mstatus_xpp_rdonly0]#If privilege mode _x_ is not implemented, then __x__PP must be read-only 0.#", + "context": " 477| \n 478| [#norm:mstatus_xpp_warl]#__x__PP fields are *WARL* fields that can hold only privilege mode _x_ and any implemented privilege mode lower than _x_.#\n>>> 479| [#norm:mstatus_xpp_rdonly0]#If privilege mode _x_ is not implemented, then __x__PP must be read-only 0.#\n 480| \n 481| [NOTE]" + } + ] + }, + { + "parameter_name": "MCOUNTENABLE_EN", + "classification": "NORM_CSR_RW", + "value_type": "bitmask", + "num_candidates": 10, + "best_score": 13, + "candidates": [ + { + "score": 13, + "reasons": [ + "Description keyword 'mcounteren'", + "CSR name 'mcounteren' in backticks", + "WARL + CSR 'mcounteren'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1656, + "line_text": "[#norm:mcounteren_flds_mandatory_warl]#In harts with U-mode, the `mcounteren` must be", + "context": " 1654| ====\n 1655| \n>>> 1656| [#norm:mcounteren_flds_mandatory_warl]#In harts with U-mode, the `mcounteren` must be\n 1657| implemented, but all fields are *WARL*# and\n 1658| [#norm:mcounteren_flds_rdonly0]#may be read-only zero, indicating reads to the" + }, + { + "score": 12, + "reasons": [ + "Description keyword 'mcounteren'", + "CSR field name 'IR'", + "CSR name 'mcounteren' in backticks", + "CSR field name 'CY'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1615, + "line_text": "[#norm:mcounteren_clr_ill_inst_exc]#When the CY, TM, IR, or HPM__n__ bit in the `mcounteren` register is", + "context": " 1613| counters, which continue to increment even when not accessible.#\n 1614| \n>>> 1615| [#norm:mcounteren_clr_ill_inst_exc]#When the CY, TM, IR, or HPM__n__ bit in the `mcounteren` register is\n 1616| clear, attempts to read the `cycle`, `time`, `instret`, or\n 1617| `hpmcountern` register while executing in S-mode or U-mode will cause an" + }, + { + "score": 8, + "reasons": [ + "Description keyword 'mcounteren'", + "CSR name 'mcounteren' in backticks" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1603, + "line_text": "[#norm:mcounteren_sz]#The counter-enable `mcounteren` register is a 32-bit register# that", + "context": " 1601| ==== Machine Counter-Enable (`mcounteren`) Register\n 1602| \n>>> 1603| [#norm:mcounteren_sz]#The counter-enable `mcounteren` register is a 32-bit register# that\n 1604| [#norm:mcounteren_op]#controls the availability of the hardware performance-monitoring\n 1605| counters to the next-lower privileged mode.#" + }, + { + "score": 8, + "reasons": [ + "Description keyword 'mcounteren'", + "CSR name 'mcounteren' in backticks" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1633, + "line_text": "In addition, [#norm:mcounteren_tm_clr]#when the TM bit in the `mcounteren` register is clear, attempts to", + "context": " 1631| ====\n 1632| \n>>> 1633| In addition, [#norm:mcounteren_tm_clr]#when the TM bit in the `mcounteren` register is clear, attempts to\n 1634| access the `stimecmp` or `vstimecmp` register while executing in a mode less\n 1635| privileged than M will cause an illegal-instruction exception.#" + }, + { + "score": 8, + "reasons": [ + "Description keyword 'mcounteren'", + "CSR name 'mcounteren' in backticks" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1661, + "line_text": "[#norm:mcounteren_presence]#In harts without U-mode, the `mcounteren` register should not exist.#", + "context": " 1659| corresponding counter will cause an illegal-instruction exception when\n 1660| executing in a less-privileged mode.#\n>>> 1661| [#norm:mcounteren_presence]#In harts without U-mode, the `mcounteren` register should not exist.#\n 1662| \n 1663| ==== Machine Counter-Inhibit (`mcountinhibit`) Register" + } + ] + }, + { + "parameter_name": "MIMPID_IMPLEMENTED", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 9, + "candidates": [ + { + "score": 9, + "reasons": [ + "Description keyword 'mimpid'", + "Name segment 'MIMPID'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 337, + "line_text": "[#norm:mimpid_op]#The `mimpid` CSR provides a unique encoding of the version of the", + "context": " 335| ==== Machine Implementation ID (`mimpid`) Register\n 336| \n>>> 337| [#norm:mimpid_op]#The `mimpid` CSR provides a unique encoding of the version of the\n 338| processor implementation.#\n 339| [#norm:mimpid_always_rd]#This register must be readable in any" + }, + { + "score": 7, + "reasons": [ + "Description keyword 'mimpid'", + "Name segment 'MIMPID'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 335, + "line_text": "==== Machine Implementation ID (`mimpid`) Register", + "context": " 333| ====\n 334| \n>>> 335| ==== Machine Implementation ID (`mimpid`) Register\n 336| \n 337| [#norm:mimpid_op]#The `mimpid` CSR provides a unique encoding of the version of the" + }, + { + "score": 7, + "reasons": [ + "Description keyword 'mimpid'", + "Name segment 'MIMPID'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 343, + "line_text": ".Machine Implementation ID (`mimpid`) register", + "context": " 341| The Implementation value should reflect the design of the RISC-V processor itself and not any surrounding system.\n 342| \n>>> 343| .Machine Implementation ID (`mimpid`) register\n 344| include::images/bytefield/mimpid.edn[]\n 345| " + }, + { + "score": 7, + "reasons": [ + "Description keyword 'mimpid'", + "Name segment 'MIMPID'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 344, + "line_text": "include::images/bytefield/mimpid.edn[]", + "context": " 342| \n 343| .Machine Implementation ID (`mimpid`) register\n>>> 344| include::images/bytefield/mimpid.edn[]\n 345| \n 346| [NOTE]" + }, + { + "score": 7, + "reasons": [ + "Description keyword 'mimpid'", + "Name segment 'MIMPID'" + ], + "is_normative": false, + "in_note": false, + "file": "priv-csrs.adoc", + "line_number": 651, + "line_text": "`mimpid` +", + "context": " 649| |`mvendorid` +\n 650| `marchid` +\n>>> 651| `mimpid` +\n 652| `mhartid` +\n 653| `mconfigptr`" + } + ] + }, + { + "parameter_name": "MISALIGNED_AMO", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 5, + "candidates": [ + { + "score": 5, + "reasons": [ + "Name segment 'MISALIGNED'", + "Description keyword 'misaligned'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1976, + "line_text": "[#norm:mcause_exccode_pri2]#Load/store/AMO address-misaligned exceptions may have either higher or", + "context": " 1974| raised.\n 1975| \n>>> 1976| [#norm:mcause_exccode_pri2]#Load/store/AMO address-misaligned exceptions may have either higher or\n 1977| lower priority than load/store/AMO page-fault and access-fault exceptions.#\n 1978| " + }, + { + "score": 5, + "reasons": [ + "Name segment 'MISALIGNED'", + "Description keyword 'misaligned'" + ], + "is_normative": true, + "in_note": false, + "file": "rv32.adoc", + "line_number": 139, + "line_text": "[#norm:taken_cti_misaligned_exc]#An instruction-address-misaligned exception is generated on a taken branch", + "context": " 137| (R/I/S/U), as shown in <>. All are a fixed 32 bits in length.\n 138| The base ISA has `IALIGN=32`, meaning that instructions must be aligned on a four-byte boundary in memory.\n>>> 139| [#norm:taken_cti_misaligned_exc]#An instruction-address-misaligned exception is generated on a taken branch\n 140| or unconditional jump if the target address is not `IALIGN-bit` aligned.\n 141| This exception is reported on the branch or jump instruction, not on the target instruction.#" + }, + { + "score": 5, + "reasons": [ + "Name segment 'MISALIGNED'", + "Description keyword 'misaligned'" + ], + "is_normative": true, + "in_note": false, + "file": "rv32.adoc", + "line_number": 142, + "line_text": "[#norm:cond_br_no_ia_misaligned_exc_not_taken]#No instruction-address-misaligned exception is generated", + "context": " 140| or unconditional jump if the target address is not `IALIGN-bit` aligned.\n 141| This exception is reported on the branch or jump instruction, not on the target instruction.#\n>>> 142| [#norm:cond_br_no_ia_misaligned_exc_not_taken]#No instruction-address-misaligned exception is generated\n 143| for a conditional branch that is not taken.#\n 144| " + }, + { + "score": 5, + "reasons": [ + "Name segment 'MISALIGNED'", + "Description keyword 'misaligned'" + ], + "is_normative": true, + "in_note": false, + "file": "rv32.adoc", + "line_number": 739, + "line_text": "[#norm:MISALIGNED_LDST_FULLY_HW_SUPPORTED]#misaligned loads and stores can be handled in hardware#, or", + "context": " 737| supported, and so the software running inside the execution environment\n 738| will never experience a contained or fatal address-misaligned trap. In this case, the\n>>> 739| [#norm:MISALIGNED_LDST_FULLY_HW_SUPPORTED]#misaligned loads and stores can be handled in hardware#, or\n 740| [#norm:MISALIGNED_LDST_INVISIBLE_TRAP]#via an invisible trap into the execution environment implementation#, or possibly a\n 741| [#norm:MISALIGNED_LDST_HW_OR_INVISIBLE_TRAP_FUNC_OF_ADDR]#combination of hardware and invisible trap depending on address.#" + }, + { + "score": 5, + "reasons": [ + "Name segment 'MISALIGNED'", + "Description keyword 'misaligned'" + ], + "is_normative": true, + "in_note": false, + "file": "rv32.adoc", + "line_number": 753, + "line_text": "[#norm:MISALIGNED_LDST_CONTAINED_OR_FATAL_TRAP]#When an EEI does not guarantee misaligned loads and", + "context": " 751| access should not be emulated, e.g., if accesses to the memory region\n 752| have side effects.#\n>>> 753| [#norm:MISALIGNED_LDST_CONTAINED_OR_FATAL_TRAP]#When an EEI does not guarantee misaligned loads and\n 754| stores are handled invisibly, the EEI must define if exceptions caused\n 755| by address misalignment result in a contained trap (allowing software" + } + ] + }, + { + "parameter_name": "MISALIGNED_LDST", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 5, + "candidates": [ + { + "score": 5, + "reasons": [ + "Name segment 'MISALIGNED'", + "Description keyword 'misaligned'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1976, + "line_text": "[#norm:mcause_exccode_pri2]#Load/store/AMO address-misaligned exceptions may have either higher or", + "context": " 1974| raised.\n 1975| \n>>> 1976| [#norm:mcause_exccode_pri2]#Load/store/AMO address-misaligned exceptions may have either higher or\n 1977| lower priority than load/store/AMO page-fault and access-fault exceptions.#\n 1978| " + }, + { + "score": 5, + "reasons": [ + "Name segment 'MISALIGNED'", + "Description keyword 'misaligned'" + ], + "is_normative": true, + "in_note": false, + "file": "rv32.adoc", + "line_number": 139, + "line_text": "[#norm:taken_cti_misaligned_exc]#An instruction-address-misaligned exception is generated on a taken branch", + "context": " 137| (R/I/S/U), as shown in <>. All are a fixed 32 bits in length.\n 138| The base ISA has `IALIGN=32`, meaning that instructions must be aligned on a four-byte boundary in memory.\n>>> 139| [#norm:taken_cti_misaligned_exc]#An instruction-address-misaligned exception is generated on a taken branch\n 140| or unconditional jump if the target address is not `IALIGN-bit` aligned.\n 141| This exception is reported on the branch or jump instruction, not on the target instruction.#" + }, + { + "score": 5, + "reasons": [ + "Name segment 'MISALIGNED'", + "Description keyword 'misaligned'" + ], + "is_normative": true, + "in_note": false, + "file": "rv32.adoc", + "line_number": 142, + "line_text": "[#norm:cond_br_no_ia_misaligned_exc_not_taken]#No instruction-address-misaligned exception is generated", + "context": " 140| or unconditional jump if the target address is not `IALIGN-bit` aligned.\n 141| This exception is reported on the branch or jump instruction, not on the target instruction.#\n>>> 142| [#norm:cond_br_no_ia_misaligned_exc_not_taken]#No instruction-address-misaligned exception is generated\n 143| for a conditional branch that is not taken.#\n 144| " + }, + { + "score": 5, + "reasons": [ + "Name segment 'MISALIGNED'", + "Description keyword 'misaligned'" + ], + "is_normative": true, + "in_note": false, + "file": "rv32.adoc", + "line_number": 739, + "line_text": "[#norm:MISALIGNED_LDST_FULLY_HW_SUPPORTED]#misaligned loads and stores can be handled in hardware#, or", + "context": " 737| supported, and so the software running inside the execution environment\n 738| will never experience a contained or fatal address-misaligned trap. In this case, the\n>>> 739| [#norm:MISALIGNED_LDST_FULLY_HW_SUPPORTED]#misaligned loads and stores can be handled in hardware#, or\n 740| [#norm:MISALIGNED_LDST_INVISIBLE_TRAP]#via an invisible trap into the execution environment implementation#, or possibly a\n 741| [#norm:MISALIGNED_LDST_HW_OR_INVISIBLE_TRAP_FUNC_OF_ADDR]#combination of hardware and invisible trap depending on address.#" + }, + { + "score": 5, + "reasons": [ + "Name segment 'MISALIGNED'", + "Description keyword 'misaligned'" + ], + "is_normative": true, + "in_note": false, + "file": "rv32.adoc", + "line_number": 753, + "line_text": "[#norm:MISALIGNED_LDST_CONTAINED_OR_FATAL_TRAP]#When an EEI does not guarantee misaligned loads and", + "context": " 751| access should not be emulated, e.g., if accesses to the memory region\n 752| have side effects.#\n>>> 753| [#norm:MISALIGNED_LDST_CONTAINED_OR_FATAL_TRAP]#When an EEI does not guarantee misaligned loads and\n 754| stores are handled invisibly, the EEI must define if exceptions caused\n 755| by address misalignment result in a contained trap (allowing software" + } + ] + }, + { + "parameter_name": "MISALIGNED_LDST_EXCEPTION_PRIORITY", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 6, + "candidates": [ + { + "score": 6, + "reasons": [ + "Name segment 'MISALIGNED'", + "Description keyword 'misaligned'", + "Name segment 'EXCEPTION'" + ], + "is_normative": true, + "in_note": false, + "file": "rv32.adoc", + "line_number": 139, + "line_text": "[#norm:taken_cti_misaligned_exc]#An instruction-address-misaligned exception is generated on a taken branch", + "context": " 137| (R/I/S/U), as shown in <>. All are a fixed 32 bits in length.\n 138| The base ISA has `IALIGN=32`, meaning that instructions must be aligned on a four-byte boundary in memory.\n>>> 139| [#norm:taken_cti_misaligned_exc]#An instruction-address-misaligned exception is generated on a taken branch\n 140| or unconditional jump if the target address is not `IALIGN-bit` aligned.\n 141| This exception is reported on the branch or jump instruction, not on the target instruction.#" + }, + { + "score": 6, + "reasons": [ + "Name segment 'MISALIGNED'", + "Description keyword 'misaligned'", + "Name segment 'EXCEPTION'" + ], + "is_normative": true, + "in_note": false, + "file": "rv32.adoc", + "line_number": 142, + "line_text": "[#norm:cond_br_no_ia_misaligned_exc_not_taken]#No instruction-address-misaligned exception is generated", + "context": " 140| or unconditional jump if the target address is not `IALIGN-bit` aligned.\n 141| This exception is reported on the branch or jump instruction, not on the target instruction.#\n>>> 142| [#norm:cond_br_no_ia_misaligned_exc_not_taken]#No instruction-address-misaligned exception is generated\n 143| for a conditional branch that is not taken.#\n 144| " + }, + { + "score": 5, + "reasons": [ + "Name segment 'MISALIGNED'", + "Description keyword 'misaligned'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1976, + "line_text": "[#norm:mcause_exccode_pri2]#Load/store/AMO address-misaligned exceptions may have either higher or", + "context": " 1974| raised.\n 1975| \n>>> 1976| [#norm:mcause_exccode_pri2]#Load/store/AMO address-misaligned exceptions may have either higher or\n 1977| lower priority than load/store/AMO page-fault and access-fault exceptions.#\n 1978| " + }, + { + "score": 5, + "reasons": [ + "Name segment 'MISALIGNED'", + "Description keyword 'misaligned'" + ], + "is_normative": true, + "in_note": false, + "file": "rv32.adoc", + "line_number": 739, + "line_text": "[#norm:MISALIGNED_LDST_FULLY_HW_SUPPORTED]#misaligned loads and stores can be handled in hardware#, or", + "context": " 737| supported, and so the software running inside the execution environment\n 738| will never experience a contained or fatal address-misaligned trap. In this case, the\n>>> 739| [#norm:MISALIGNED_LDST_FULLY_HW_SUPPORTED]#misaligned loads and stores can be handled in hardware#, or\n 740| [#norm:MISALIGNED_LDST_INVISIBLE_TRAP]#via an invisible trap into the execution environment implementation#, or possibly a\n 741| [#norm:MISALIGNED_LDST_HW_OR_INVISIBLE_TRAP_FUNC_OF_ADDR]#combination of hardware and invisible trap depending on address.#" + }, + { + "score": 5, + "reasons": [ + "Name segment 'MISALIGNED'", + "Description keyword 'misaligned'" + ], + "is_normative": true, + "in_note": false, + "file": "rv32.adoc", + "line_number": 753, + "line_text": "[#norm:MISALIGNED_LDST_CONTAINED_OR_FATAL_TRAP]#When an EEI does not guarantee misaligned loads and", + "context": " 751| access should not be emulated, e.g., if accesses to the memory region\n 752| have side effects.#\n>>> 753| [#norm:MISALIGNED_LDST_CONTAINED_OR_FATAL_TRAP]#When an EEI does not guarantee misaligned loads and\n 754| stores are handled invisibly, the EEI must define if exceptions caused\n 755| by address misalignment result in a contained trap (allowing software" + } + ] + }, + { + "parameter_name": "MISALIGNED_MAX_ATOMICITY_GRANULE_SIZE", + "classification": "NORM_DIRECT", + "value_type": "enum", + "num_candidates": 10, + "best_score": 7, + "candidates": [ + { + "score": 7, + "reasons": [ + "Name segment 'ATOMICITY'", + "Name segment 'MISALIGNED'", + "Description keyword 'misaligned'", + "Name segment 'GRANULE'", + "Description keyword 'PMA'" + ], + "is_normative": false, + "in_note": false, + "file": "a-st-ext.adoc", + "line_number": 385, + "line_text": "The misaligned atomicity granule PMA, defined in Volume II of this manual,", + "context": " 383| not be emulated.\n 384| \n>>> 385| The misaligned atomicity granule PMA, defined in Volume II of this manual,\n 386| optionally relaxes this alignment requirement.\n 387| If present, the misaligned atomicity granule PMA specifies the size" + }, + { + "score": 7, + "reasons": [ + "Name segment 'ATOMICITY'", + "Name segment 'MISALIGNED'", + "Description keyword 'misaligned'", + "Name segment 'GRANULE'", + "Description keyword 'PMA'" + ], + "is_normative": false, + "in_note": false, + "file": "a-st-ext.adoc", + "line_number": 387, + "line_text": "If present, the misaligned atomicity granule PMA specifies the size", + "context": " 385| The misaligned atomicity granule PMA, defined in Volume II of this manual,\n 386| optionally relaxes this alignment requirement.\n>>> 387| If present, the misaligned atomicity granule PMA specifies the size\n 388| of a misaligned atomicity granule, a power-of-two number of bytes.\n 389| The misaligned atomicity granule PMA applies only to AMOs, loads and stores" + }, + { + "score": 7, + "reasons": [ + "Name segment 'ATOMICITY'", + "Name segment 'MISALIGNED'", + "Description keyword 'misaligned'", + "Name segment 'GRANULE'", + "Description keyword 'PMA'" + ], + "is_normative": false, + "in_note": false, + "file": "a-st-ext.adoc", + "line_number": 389, + "line_text": "The misaligned atomicity granule PMA applies only to AMOs, loads and stores", + "context": " 387| If present, the misaligned atomicity granule PMA specifies the size\n 388| of a misaligned atomicity granule, a power-of-two number of bytes.\n>>> 389| The misaligned atomicity granule PMA applies only to AMOs, loads and stores\n 390| defined in the base ISAs, and loads and stores of no more than XLEN bits\n 391| defined in the F, D, and Q extensions, and compressed encodings thereof." + }, + { + "score": 7, + "reasons": [ + "Name segment 'ATOMICITY'", + "Name segment 'MISALIGNED'", + "Description keyword 'misaligned'", + "Name segment 'GRANULE'", + "Description keyword 'PMA'" + ], + "is_normative": false, + "in_note": false, + "file": "colophon.adoc", + "line_number": 157, + "line_text": "* The draft Zam extension has been removed, in favor of the definition of a misaligned atomicity granule PMA.", + "context": " 155| \n 156| * The inclusion of all ratified extensions through February 2025.\n>>> 157| * The draft Zam extension has been removed, in favor of the definition of a misaligned atomicity granule PMA.\n 158| * The concept of vacant memory regions has been superseded by inaccessible memory or I/O regions.\n 159| * The removal of unratified content, including the sketch of the RV128I base ISA." + }, + { + "score": 7, + "reasons": [ + "Name segment 'ATOMICITY'", + "Name segment 'MISALIGNED'", + "Description keyword 'misaligned'", + "Name segment 'GRANULE'", + "Description keyword 'PMA'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 3084, + "line_text": "==== Misaligned Atomicity Granule PMA", + "context": " 3082| ====\n 3083| \n>>> 3084| ==== Misaligned Atomicity Granule PMA\n 3085| \n 3086| The misaligned atomicity granule PMA provides constrained support for" + } + ] + }, + { + "parameter_name": "MISALIGNED_SPLIT_STRATEGY", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 5, + "candidates": [ + { + "score": 5, + "reasons": [ + "Name segment 'MISALIGNED'", + "Description keyword 'misaligned'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1976, + "line_text": "[#norm:mcause_exccode_pri2]#Load/store/AMO address-misaligned exceptions may have either higher or", + "context": " 1974| raised.\n 1975| \n>>> 1976| [#norm:mcause_exccode_pri2]#Load/store/AMO address-misaligned exceptions may have either higher or\n 1977| lower priority than load/store/AMO page-fault and access-fault exceptions.#\n 1978| " + }, + { + "score": 5, + "reasons": [ + "Name segment 'MISALIGNED'", + "Description keyword 'misaligned'" + ], + "is_normative": true, + "in_note": false, + "file": "rv32.adoc", + "line_number": 139, + "line_text": "[#norm:taken_cti_misaligned_exc]#An instruction-address-misaligned exception is generated on a taken branch", + "context": " 137| (R/I/S/U), as shown in <>. All are a fixed 32 bits in length.\n 138| The base ISA has `IALIGN=32`, meaning that instructions must be aligned on a four-byte boundary in memory.\n>>> 139| [#norm:taken_cti_misaligned_exc]#An instruction-address-misaligned exception is generated on a taken branch\n 140| or unconditional jump if the target address is not `IALIGN-bit` aligned.\n 141| This exception is reported on the branch or jump instruction, not on the target instruction.#" + }, + { + "score": 5, + "reasons": [ + "Name segment 'MISALIGNED'", + "Description keyword 'misaligned'" + ], + "is_normative": true, + "in_note": false, + "file": "rv32.adoc", + "line_number": 142, + "line_text": "[#norm:cond_br_no_ia_misaligned_exc_not_taken]#No instruction-address-misaligned exception is generated", + "context": " 140| or unconditional jump if the target address is not `IALIGN-bit` aligned.\n 141| This exception is reported on the branch or jump instruction, not on the target instruction.#\n>>> 142| [#norm:cond_br_no_ia_misaligned_exc_not_taken]#No instruction-address-misaligned exception is generated\n 143| for a conditional branch that is not taken.#\n 144| " + }, + { + "score": 5, + "reasons": [ + "Name segment 'MISALIGNED'", + "Description keyword 'misaligned'" + ], + "is_normative": true, + "in_note": false, + "file": "rv32.adoc", + "line_number": 739, + "line_text": "[#norm:MISALIGNED_LDST_FULLY_HW_SUPPORTED]#misaligned loads and stores can be handled in hardware#, or", + "context": " 737| supported, and so the software running inside the execution environment\n 738| will never experience a contained or fatal address-misaligned trap. In this case, the\n>>> 739| [#norm:MISALIGNED_LDST_FULLY_HW_SUPPORTED]#misaligned loads and stores can be handled in hardware#, or\n 740| [#norm:MISALIGNED_LDST_INVISIBLE_TRAP]#via an invisible trap into the execution environment implementation#, or possibly a\n 741| [#norm:MISALIGNED_LDST_HW_OR_INVISIBLE_TRAP_FUNC_OF_ADDR]#combination of hardware and invisible trap depending on address.#" + }, + { + "score": 5, + "reasons": [ + "Name segment 'MISALIGNED'", + "Description keyword 'misaligned'" + ], + "is_normative": true, + "in_note": false, + "file": "rv32.adoc", + "line_number": 753, + "line_text": "[#norm:MISALIGNED_LDST_CONTAINED_OR_FATAL_TRAP]#When an EEI does not guarantee misaligned loads and", + "context": " 751| access should not be emulated, e.g., if accesses to the memory region\n 752| have side effects.#\n>>> 753| [#norm:MISALIGNED_LDST_CONTAINED_OR_FATAL_TRAP]#When an EEI does not guarantee misaligned loads and\n 754| stores are handled invisibly, the EEI must define if exceptions caused\n 755| by address misalignment result in a contained trap (allowing software" + } + ] + }, + { + "parameter_name": "MISA_CSR_IMPLEMENTED", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 12, + "candidates": [ + { + "score": 12, + "reasons": [ + "Description keyword 'implemented'", + "Name segment 'MISA'", + "Name segment 'IMPLEMENTED'", + "Description keyword 'misa'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 23, + "line_text": "but [#norm:misa_csr_implemented]#a value of zero can be returned to indicate the `misa` register has not been implemented#, requiring that CPU capabilities be determined through a separate non-standard mechanism.", + "context": " 21| [#norm:misa_acc]#The `misa` CSR is a *WARL* read-write register# reporting the ISA supported by the hart.\n 22| [#norm:misa_always_rd]#This register must be readable in any implementation#,\n>>> 23| but [#norm:misa_csr_implemented]#a value of zero can be returned to indicate the `misa` register has not been implemented#, requiring that CPU capabilities be determined through a separate non-standard mechanism.\n 24| \n 25| [[norm:misa_enc_img]]" + }, + { + "score": 10, + "reasons": [ + "Optional/read-only pattern for boolean param", + "Name segment 'MISA'", + "Description keyword 'misa'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 231, + "line_text": "[#norm:misa_e_not_i]#Unless `misa` is all read-only zero, the", + "context": " 229| \n 230| [#norm:misa_e_acc]#The \"E\" bit is read-only.#\n>>> 231| [#norm:misa_e_not_i]#Unless `misa` is all read-only zero, the\n 232| \"E\" bit always reads as the complement of the \"I\" bit.#\n 233| If an execution environment supports both RV32E and RV32I, software can select" + }, + { + "score": 10, + "reasons": [ + "Name segment 'MISA'", + "CSR name 'mstatus' in backticks", + "Description keyword 'misa'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 2791, + "line_text": "supported, the `mstatus`/`mstatush` field MBE is reset to 0. The `misa`", + "context": " 2789| Upon reset, a hart’s privilege mode is set to M. The `mstatus` fields\n 2790| MIE and MPRV are reset to 0. If little-endian memory accesses are\n>>> 2791| supported, the `mstatus`/`mstatush` field MBE is reset to 0. The `misa`\n 2792| register is reset to enable the maximal set of supported extensions,\n 2793| as described in <>. For" + }, + { + "score": 9, + "reasons": [ + "Name segment 'MISA'", + "Description keyword 'misa'" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 30, + "line_text": "[#norm:misa-h_op]#The hypervisor extension is enabled by setting bit 7 in the `misa` CSR#,", + "context": " 28| or a minimum of Sv39 for RV64#.\n 29| \n>>> 30| [#norm:misa-h_op]#The hypervisor extension is enabled by setting bit 7 in the `misa` CSR#,\n 31| which corresponds to the letter H. RISC-V harts that implement the\n 32| hypervisor extension are encouraged not to hardwire `misa`[7], so that" + }, + { + "score": 9, + "reasons": [ + "Name segment 'MISA'", + "Description keyword 'misa'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 21, + "line_text": "[#norm:misa_acc]#The `misa` CSR is a *WARL* read-write register# reporting the ISA supported by the hart.", + "context": " 19| ==== Machine ISA (`misa`) Register\n 20| \n>>> 21| [#norm:misa_acc]#The `misa` CSR is a *WARL* read-write register# reporting the ISA supported by the hart.\n 22| [#norm:misa_always_rd]#This register must be readable in any implementation#,\n 23| but [#norm:misa_csr_implemented]#a value of zero can be returned to indicate the `misa` register has not been implemented#, requiring that CPU capabilities be determined through a separate non-standard mechanism." + } + ] + }, + { + "parameter_name": "MSTATEEN_AIA_TYPE", + "classification": "NORM_CSR_RW", + "value_type": "enum", + "num_candidates": 0, + "best_score": 0, + "candidates": [] + }, + { + "parameter_name": "MSTATEEN_CONTEXT_TYPE", + "classification": "NORM_CSR_RW", + "value_type": "enum", + "num_candidates": 10, + "best_score": 5, + "candidates": [ + { + "score": 5, + "reasons": [ + "Name segment 'CONTEXT'", + "Description keyword 'CONTEXT'" + ], + "is_normative": true, + "in_note": false, + "file": "smctr.adoc", + "line_number": 652, + "line_text": "[#norm:ccounter_reset]#The CtrCycleCounter is reset on writes to `__x__ctrctl`, and on execution of SCTRCLR, to ensure that any accumulated cycle counts do not persist across a context switch.#", + "context": " 650| ----\n 651| \n>>> 652| [#norm:ccounter_reset]#The CtrCycleCounter is reset on writes to `__x__ctrctl`, and on execution of SCTRCLR, to ensure that any accumulated cycle counts do not persist across a context switch.#\n 653| \n 654| [#norm:ccounter_impl]#An implementation that supports cycle counting must implement CCV and all" + }, + { + "score": 3, + "reasons": [ + "Name segment 'CONTEXT'", + "Description keyword 'CONTEXT'" + ], + "is_normative": false, + "in_note": false, + "file": "bfloat16.adoc", + "line_number": 82, + "line_text": "in context, and advise on how they best to fit the functionality.", + "context": " 80| Furthermore, we expect architects to be able to examine our instructions\n 81| for implementation issues, understand how the instructions will be used\n>>> 82| in context, and advise on how they best to fit the functionality.\n 83| \n 84| Digital design engineers & micro-architects::" + }, + { + "score": 3, + "reasons": [ + "Name segment 'CONTEXT'", + "Description keyword 'CONTEXT'" + ], + "is_normative": false, + "in_note": false, + "file": "calling-convention.adoc", + "line_number": 24, + "line_text": "NOTE: This scheme allows system calls that cause context switches to avoid", + "context": " 22| (`v0`-`v31`, `vl`, `vtype`) and `vstart` to become unspecified.\n 23| \n>>> 24| NOTE: This scheme allows system calls that cause context switches to avoid\n 25| saving and later restoring the vector registers.\n 26| " + }, + { + "score": 3, + "reasons": [ + "Name segment 'CONTEXT'", + "Description keyword 'CONTEXT'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1218, + "line_text": "Read-only fields SD and XS summarize the extension context status as it", + "context": " 1216| \n 1217| [[norm:vsstatus-sd_xs_op]]\n>>> 1218| Read-only fields SD and XS summarize the extension context status as it\n 1219| is visible to VS-mode only. For example, the value of the HS-level\n 1220| `sstatus`.FS does not affect `vsstatus`.SD." + }, + { + "score": 3, + "reasons": [ + "Name segment 'CONTEXT'", + "Description keyword 'CONTEXT'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 828, + "line_text": "===== Extension Context Status in `mstatus` Register", + "context": " 826| ====\n 827| \n>>> 828| ===== Extension Context Status in `mstatus` Register\n 829| \n 830| Supporting substantial extensions is one of the primary goals of RISC-V," + } + ] + }, + { + "parameter_name": "MSTATEEN_CSRIND_TYPE", + "classification": "NORM_CSR_RW", + "value_type": "enum", + "num_candidates": 6, + "best_score": 3, + "candidates": [ + { + "score": 3, + "reasons": [ + "Description keyword 'CSRIND'", + "Name segment 'CSRIND'" + ], + "is_normative": false, + "in_note": false, + "file": "smstateen.adoc", + "line_number": 191, + "line_text": "{bits: 1, name: 'CSRIND'},", + "context": " 189| {bits: 1, name: 'IMSIC'},\n 190| {bits: 1, name: 'AIA'},\n>>> 191| {bits: 1, name: 'CSRIND'},\n 192| {bits: 1, name: 'WPRI'},\n 193| {bits: 1, name: 'ENVCFG'}," + }, + { + "score": 3, + "reasons": [ + "Description keyword 'CSRIND'", + "Name segment 'CSRIND'" + ], + "is_normative": false, + "in_note": false, + "file": "smstateen.adoc", + "line_number": 211, + "line_text": "{bits: 1, name: 'CSRIND'},", + "context": " 209| {bits: 1, name: 'IMSIC'},\n 210| {bits: 1, name: 'AIA'},\n>>> 211| {bits: 1, name: 'CSRIND'},\n 212| {bits: 1, name: 'WPRI'},\n 213| {bits: 1, name: 'ENVCFG'}," + }, + { + "score": 3, + "reasons": [ + "Description keyword 'CSRIND'", + "Name segment 'CSRIND'" + ], + "is_normative": false, + "in_note": false, + "file": "smstateen.adoc", + "line_number": 263, + "line_text": "The CSRIND bit in `mstateen0` controls access to the `siselect`, `sireg*`,", + "context": " 261| `senvcfg` CSRs.\n 262| \n>>> 263| The CSRIND bit in `mstateen0` controls access to the `siselect`, `sireg*`,\n 264| `vsiselect`, and the `vsireg*` CSRs provided by the Sscsrind extensions.\n 265| The CSRIND bit in `hstateen0` controls access to the `siselect` and the" + }, + { + "score": 3, + "reasons": [ + "Description keyword 'CSRIND'", + "Name segment 'CSRIND'" + ], + "is_normative": false, + "in_note": false, + "file": "smstateen.adoc", + "line_number": 265, + "line_text": "The CSRIND bit in `hstateen0` controls access to the `siselect` and the", + "context": " 263| The CSRIND bit in `mstateen0` controls access to the `siselect`, `sireg*`,\n 264| `vsiselect`, and the `vsireg*` CSRs provided by the Sscsrind extensions.\n>>> 265| The CSRIND bit in `hstateen0` controls access to the `siselect` and the\n 266| `sireg*`, (really `vsiselect` and `vsireg*`) CSRs provided by the Sscsrind\n 267| extensions." + }, + { + "score": 3, + "reasons": [ + "Description keyword 'CSRIND'", + "Name segment 'CSRIND'" + ], + "is_normative": false, + "in_note": false, + "file": "smstateen.adoc", + "line_number": 281, + "line_text": "Ssaia extension and not controlled by either the CSRIND or the IMSIC", + "context": " 279| \n 280| The AIA bit in `mstateen0` controls access to all state introduced by the\n>>> 281| Ssaia extension and not controlled by either the CSRIND or the IMSIC\n 282| bits. The AIA bit in `hstateen0` controls access to all state introduced by the\n 283| Ssaia extension and not controlled by either the CSRIND or the IMSIC" + } + ] + }, + { + "parameter_name": "MSTATEEN_ENVCFG_TYPE", + "classification": "NORM_CSR_RW", + "value_type": "enum", + "num_candidates": 6, + "best_score": 3, + "candidates": [ + { + "score": 3, + "reasons": [ + "Name segment 'ENVCFG'", + "Description keyword 'ENVCFG'" + ], + "is_normative": false, + "in_note": false, + "file": "priv-cfi.adoc", + "line_number": 134, + "line_text": "*__x__*`envcfg.SSE` fields. The conditions are specified as follows:", + "context": " 132| Attempts to access the `ssp` CSR may result in either an illegal-instruction\n 133| exception or a virtual-instruction exception, contingent upon the state of the\n>>> 134| *__x__*`envcfg.SSE` fields. The conditions are specified as follows:\n 135| \n 136| * [#norm:zicfiss_m_menvcfg-sse]#If the privilege mode is less than M and `menvcfg.SSE` is 0, an" + }, + { + "score": 3, + "reasons": [ + "Name segment 'ENVCFG'", + "Description keyword 'ENVCFG'" + ], + "is_normative": false, + "in_note": false, + "file": "riscv-unprivileged.adoc", + "line_number": 47, + "line_text": ":csrname: envcfg", + "context": " 45| :stem: latexmath\n 46| :footnote:\n>>> 47| :csrname: envcfg\n 48| :imagesdir: images\n 49| " + }, + { + "score": 3, + "reasons": [ + "Name segment 'ENVCFG'", + "Description keyword 'ENVCFG'" + ], + "is_normative": false, + "in_note": false, + "file": "smstateen.adoc", + "line_number": 193, + "line_text": "{bits: 1, name: 'ENVCFG'},", + "context": " 191| {bits: 1, name: 'CSRIND'},\n 192| {bits: 1, name: 'WPRI'},\n>>> 193| {bits: 1, name: 'ENVCFG'},\n 194| {bits: 1, name: 'SE0'},\n 195| ], config: {bits: 64, lanes: 4, hspace:1024}}" + }, + { + "score": 3, + "reasons": [ + "Name segment 'ENVCFG'", + "Description keyword 'ENVCFG'" + ], + "is_normative": false, + "in_note": false, + "file": "smstateen.adoc", + "line_number": 213, + "line_text": "{bits: 1, name: 'ENVCFG'},", + "context": " 211| {bits: 1, name: 'CSRIND'},\n 212| {bits: 1, name: 'WPRI'},\n>>> 213| {bits: 1, name: 'ENVCFG'},\n 214| {bits: 1, name: 'SE0'},\n 215| ], config: {bits: 64, lanes: 4, hspace:1024}}" + }, + { + "score": 3, + "reasons": [ + "Name segment 'ENVCFG'", + "Description keyword 'ENVCFG'" + ], + "is_normative": false, + "in_note": false, + "file": "smstateen.adoc", + "line_number": 259, + "line_text": "The ENVCFG bit in `mstateen0` controls access to the `henvcfg`, `henvcfgh`,", + "context": " 257| `sstateen0` CSR.\n 258| \n>>> 259| The ENVCFG bit in `mstateen0` controls access to the `henvcfg`, `henvcfgh`,\n 260| and the `senvcfg` CSRs. The ENVCFG bit in `hstateen0` controls access to the\n 261| `senvcfg` CSRs." + } + ] + }, + { + "parameter_name": "MSTATEEN_IMSIC_TYPE", + "classification": "NORM_CSR_RW", + "value_type": "enum", + "num_candidates": 7, + "best_score": 3, + "candidates": [ + { + "score": 3, + "reasons": [ + "Description keyword 'IMSIC'", + "Name segment 'IMSIC'" + ], + "is_normative": false, + "in_note": false, + "file": "smstateen.adoc", + "line_number": 189, + "line_text": "{bits: 1, name: 'IMSIC'},", + "context": " 187| {bits: 1, name: 'P1P13'},\n 188| {bits: 1, name: 'CONTEXT'},\n>>> 189| {bits: 1, name: 'IMSIC'},\n 190| {bits: 1, name: 'AIA'},\n 191| {bits: 1, name: 'CSRIND'}," + }, + { + "score": 3, + "reasons": [ + "Description keyword 'IMSIC'", + "Name segment 'IMSIC'" + ], + "is_normative": false, + "in_note": false, + "file": "smstateen.adoc", + "line_number": 209, + "line_text": "{bits: 1, name: 'IMSIC'},", + "context": " 207| {bits: 2, name: 'WPRI'},\n 208| {bits: 1, name: 'CONTEXT'},\n>>> 209| {bits: 1, name: 'IMSIC'},\n 210| {bits: 1, name: 'AIA'},\n 211| {bits: 1, name: 'CSRIND'}," + }, + { + "score": 3, + "reasons": [ + "Description keyword 'IMSIC'", + "Name segment 'IMSIC'" + ], + "is_normative": false, + "in_note": false, + "file": "smstateen.adoc", + "line_number": 269, + "line_text": "The IMSIC bit in `mstateen0` controls access to the IMSIC state, including", + "context": " 267| extensions.\n 268| \n>>> 269| The IMSIC bit in `mstateen0` controls access to the IMSIC state, including\n 270| CSRs `stopei` and `vstopei`, provided by the Ssaia extension. The IMSIC bit in\n 271| `hstateen0` controls access to the guest IMSIC state, including CSRs `stopei`" + }, + { + "score": 3, + "reasons": [ + "Description keyword 'IMSIC'", + "Name segment 'IMSIC'" + ], + "is_normative": false, + "in_note": false, + "file": "smstateen.adoc", + "line_number": 270, + "line_text": "CSRs `stopei` and `vstopei`, provided by the Ssaia extension. The IMSIC bit in", + "context": " 268| \n 269| The IMSIC bit in `mstateen0` controls access to the IMSIC state, including\n>>> 270| CSRs `stopei` and `vstopei`, provided by the Ssaia extension. The IMSIC bit in\n 271| `hstateen0` controls access to the guest IMSIC state, including CSRs `stopei`\n 272| (really `vstopei`), provided by the Ssaia extension." + }, + { + "score": 3, + "reasons": [ + "Description keyword 'IMSIC'", + "Name segment 'IMSIC'" + ], + "is_normative": false, + "in_note": false, + "file": "smstateen.adoc", + "line_number": 271, + "line_text": "`hstateen0` controls access to the guest IMSIC state, including CSRs `stopei`", + "context": " 269| The IMSIC bit in `mstateen0` controls access to the IMSIC state, including\n 270| CSRs `stopei` and `vstopei`, provided by the Ssaia extension. The IMSIC bit in\n>>> 271| `hstateen0` controls access to the guest IMSIC state, including CSRs `stopei`\n 272| (really `vstopei`), provided by the Ssaia extension.\n 273| " + } + ] + }, + { + "parameter_name": "MSTATEEN_JVT_TYPE", + "classification": "NORM_CSR_RW", + "value_type": "enum", + "num_candidates": 1, + "best_score": 4, + "candidates": [ + { + "score": 4, + "reasons": [ + "Description keyword 'JVT'" + ], + "is_normative": true, + "in_note": false, + "file": "zc.adoc", + "line_number": 2341, + "line_text": "[#norm:Zcmt_entry_sz]#The base of the table is in the jvt CSR (see <>), each table entry is XLEN bits.#", + "context": " 2339| ==== jvt\n 2340| \n>>> 2341| [#norm:Zcmt_entry_sz]#The base of the table is in the jvt CSR (see <>), each table entry is XLEN bits.#\n 2342| \n 2343| If the same function is called with and without linking then it must have two entries in the table." + } + ] + }, + { + "parameter_name": "MSTATUS_FS_LEGAL_VALUES", + "classification": "NORM_CSR_WARL", + "value_type": "set", + "num_candidates": 10, + "best_score": 11, + "candidates": [ + { + "score": 11, + "reasons": [ + "WARL + CSR 'mstatus'", + "Name segment 'MSTATUS'", + "CSR name 'mstatus' in backticks" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 679, + "line_text": "[#norm:mstatus_mstatush_xbe_warl]#The MBE, SBE, and UBE bits in `mstatus` and `mstatush` are *WARL* fields# that", + "context": " 677| ===== Endianness Control in `mstatus` and `mstatush` Registers\n 678| \n>>> 679| [#norm:mstatus_mstatush_xbe_warl]#The MBE, SBE, and UBE bits in `mstatus` and `mstatush` are *WARL* fields# that\n 680| control the endianness of memory accesses other than instruction fetches.\n 681| [#norm:endianness_inst_fetch_little]#Instruction fetches are always little-endian.#" + }, + { + "score": 9, + "reasons": [ + "WARL + CSR 'mstatus'", + "Name segment 'MSTATUS'", + "CSR name 'mstatus' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "priv-preface.adoc", + "line_number": 501, + "line_text": "* Made the `mstatus`.MPP field *WARL*, rather than *WLRL*.", + "context": " 499| the possibility of a future global-ASID extension.\n 500| * SFENCE.VMA semantics have been clarified.\n>>> 501| * Made the `mstatus`.MPP field *WARL*, rather than *WLRL*.\n 502| * Made the unused `__x__ip` fields *WPRI*, rather than *WIRI*.\n 503| * Made the unused `misa` fields *WARL*, rather than *WIRI*." + }, + { + "score": 8, + "reasons": [ + "Description keyword 'FS'", + "Name segment 'MSTATUS'", + "CSR name 'mstatus' in backticks", + "CSR field name 'FS'" + ], + "is_normative": false, + "in_note": false, + "file": "zfinx.adoc", + "line_number": 151, + "line_text": "`mstatus` field FS is hardwired to 0 if the Zfinx extension is", + "context": " 149| [[norm:Zfinx_mstatus-FS_zero]]\n 150| In the standard privileged architecture defined in Volume II, the\n>>> 151| `mstatus` field FS is hardwired to 0 if the Zfinx extension is\n 152| implemented, and FS no longer affects the trapping behavior of\n 153| floating-point instructions or `fcsr` accesses." + }, + { + "score": 7, + "reasons": [ + "Description keyword 'FS'", + "Name segment 'MSTATUS'", + "CSR field name 'FS'" + ], + "is_normative": true, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 3313, + "line_text": "[#norm:mstatus-FS_off_V_fp_ill]#If the floating-point unit status field `mstatus.FS` is `Off` then any", + "context": " 3311| half-precision floating-point support.\n 3312| \n>>> 3313| [#norm:mstatus-FS_off_V_fp_ill]#If the floating-point unit status field `mstatus.FS` is `Off` then any\n 3314| attempt to execute a vector floating-point instruction will raise an\n 3315| illegal-instruction exception.# [#norm:mstatus-FS_dirty_V_fp]#Any vector floating-point instruction" + }, + { + "score": 6, + "reasons": [ + "Name segment 'MSTATUS'", + "CSR name 'mstatus' in backticks" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 242, + "line_text": "[#norm:hstatus-vtw_op]#When VTW=1 (and assuming `mstatus`.TW=0),", + "context": " 240| [#norm:hstatus-vtsr_op]#When VTSR=1, an attempt in VS-mode to execute SRET raises a\n 241| virtual-instruction exception.#\n>>> 242| [#norm:hstatus-vtw_op]#When VTW=1 (and assuming `mstatus`.TW=0),\n 243| an attempt in VS-mode to execute WFI raises a virtual-instruction\n 244| exception if the WFI does not complete within an" + } + ] + }, + { + "parameter_name": "MSTATUS_TVM_IMPLEMENTED", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 12, + "candidates": [ + { + "score": 12, + "reasons": [ + "CSR field name 'TVM'", + "Description keyword 'TVM'", + "Name segment 'MSTATUS'", + "CSR name 'mstatus' in backticks" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 999, + "line_text": "addresses. [#norm:hgatp_tvm_illegal]#When `mstatus`.TVM=1, attempts to read or write `hgatp` while", + "context": " 997| address-translation fences on a per-virtual-machine basis; and the MODE\n 998| field, which selects the address-translation scheme for guest physical\n>>> 999| addresses. [#norm:hgatp_tvm_illegal]#When `mstatus`.TVM=1, attempts to read or write `hgatp` while\n 1000| executing in HS-mode will raise an illegal-instruction exception.#\n 1001| " + }, + { + "score": 10, + "reasons": [ + "CSR field name 'TVM'", + "Description keyword 'TVM'", + "Name segment 'MSTATUS'", + "CSR name 'mstatus' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 237, + "line_text": "`mstatus` fields TSR, TW, and TVM, but affect execution only in VS-mode,", + "context": " 235| \n 236| The `hstatus` fields VTSR, VTW, and VTVM are defined analogously to the\n>>> 237| `mstatus` fields TSR, TW, and TVM, but affect execution only in VS-mode,\n 238| and cause virtual-instruction exceptions instead of illegal-instruction\n 239| exceptions." + }, + { + "score": 10, + "reasons": [ + "CSR field name 'TVM'", + "Description keyword 'TVM'", + "Name segment 'MSTATUS'", + "CSR name 'mstatus' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1585, + "line_text": "Neither `mstatus`.TVM nor `hstatus`.VTVM causes HFENCE.VVMA to trap.", + "context": " 1583| \n 1584| [[norm:hfence-vvma_tvm]]\n>>> 1585| Neither `mstatus`.TVM nor `hstatus`.VTVM causes HFENCE.VVMA to trap.\n 1586| \n 1587| [[norm:hfence-gvma_op]]" + }, + { + "score": 10, + "reasons": [ + "CSR field name 'TVM'", + "Description keyword 'TVM'", + "Name segment 'MSTATUS'", + "CSR name 'mstatus' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1588, + "line_text": "HFENCE.GVMA is valid only in HS-mode when `mstatus`.TVM=0, or in M-mode", + "context": " 1586| \n 1587| [[norm:hfence-gvma_op]]\n>>> 1588| HFENCE.GVMA is valid only in HS-mode when `mstatus`.TVM=0, or in M-mode\n 1589| (irrespective of `mstatus`.TVM). Executing an HFENCE.GVMA instruction\n 1590| guarantees that any previous stores already visible to the current hart" + }, + { + "score": 10, + "reasons": [ + "CSR field name 'TVM'", + "Description keyword 'TVM'", + "Name segment 'MSTATUS'", + "CSR name 'mstatus' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1589, + "line_text": "(irrespective of `mstatus`.TVM). Executing an HFENCE.GVMA instruction", + "context": " 1587| [[norm:hfence-gvma_op]]\n 1588| HFENCE.GVMA is valid only in HS-mode when `mstatus`.TVM=0, or in M-mode\n>>> 1589| (irrespective of `mstatus`.TVM). Executing an HFENCE.GVMA instruction\n 1590| guarantees that any previous stores already visible to the current hart\n 1591| are ordered before all implicit reads by that hart done for G-stage" + } + ] + }, + { + "parameter_name": "MSTATUS_VS_LEGAL_VALUES", + "classification": "NORM_CSR_WARL", + "value_type": "set", + "num_candidates": 10, + "best_score": 11, + "candidates": [ + { + "score": 11, + "reasons": [ + "WARL + CSR 'mstatus'", + "Name segment 'MSTATUS'", + "CSR name 'mstatus' in backticks" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 679, + "line_text": "[#norm:mstatus_mstatush_xbe_warl]#The MBE, SBE, and UBE bits in `mstatus` and `mstatush` are *WARL* fields# that", + "context": " 677| ===== Endianness Control in `mstatus` and `mstatush` Registers\n 678| \n>>> 679| [#norm:mstatus_mstatush_xbe_warl]#The MBE, SBE, and UBE bits in `mstatus` and `mstatush` are *WARL* fields# that\n 680| control the endianness of memory accesses other than instruction fetches.\n 681| [#norm:endianness_inst_fetch_little]#Instruction fetches are always little-endian.#" + }, + { + "score": 9, + "reasons": [ + "WARL + CSR 'mstatus'", + "Name segment 'MSTATUS'", + "CSR name 'mstatus' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "priv-preface.adoc", + "line_number": 501, + "line_text": "* Made the `mstatus`.MPP field *WARL*, rather than *WLRL*.", + "context": " 499| the possibility of a future global-ASID extension.\n 500| * SFENCE.VMA semantics have been clarified.\n>>> 501| * Made the `mstatus`.MPP field *WARL*, rather than *WLRL*.\n 502| * Made the unused `__x__ip` fields *WPRI*, rather than *WIRI*.\n 503| * Made the unused `misa` fields *WARL*, rather than *WIRI*." + }, + { + "score": 8, + "reasons": [ + "Name segment 'MSTATUS'", + "CSR name 'mstatus' in backticks", + "CSR field name 'VS'", + "Description keyword 'VS'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 237, + "line_text": "`mstatus` fields TSR, TW, and TVM, but affect execution only in VS-mode,", + "context": " 235| \n 236| The `hstatus` fields VTSR, VTW, and VTVM are defined analogously to the\n>>> 237| `mstatus` fields TSR, TW, and TVM, but affect execution only in VS-mode,\n 238| and cause virtual-instruction exceptions instead of illegal-instruction\n 239| exceptions." + }, + { + "score": 7, + "reasons": [ + "Name segment 'MSTATUS'", + "CSR field name 'VS'", + "Description keyword 'VS'" + ], + "is_normative": true, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 130, + "line_text": "[#norm:vsstatus-vs_mstatus-vs_op_active]#When V=1 and neither `vsstatus.VS` nor `mstatus.VS` is set to Off, executing", + "context": " 128| illegal-instruction exception when either field is set to Off.\n 129| \n>>> 130| [#norm:vsstatus-vs_mstatus-vs_op_active]#When V=1 and neither `vsstatus.VS` nor `mstatus.VS` is set to Off, executing\n 131| any instruction that changes vector state, including the vector CSRs, will\n 132| change both `mstatus.VS` and `vsstatus.VS` to Dirty.#" + }, + { + "score": 7, + "reasons": [ + "Name segment 'MSTATUS'", + "CSR field name 'VS'", + "Description keyword 'VS'" + ], + "is_normative": true, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 133, + "line_text": "[#norm:hw_mstatus_vs_dirty_update_param]#Implementations may also change `mstatus.VS` or `vsstatus.VS` from Initial or", + "context": " 131| any instruction that changes vector state, including the vector CSRs, will\n 132| change both `mstatus.VS` and `vsstatus.VS` to Dirty.#\n>>> 133| [#norm:hw_mstatus_vs_dirty_update_param]#Implementations may also change `mstatus.VS` or `vsstatus.VS` from Initial or\n 134| Clean to Dirty at any time, even when there is no change in vector state.#\n 135| " + } + ] + }, + { + "parameter_name": "MTVAL_WIDTH", + "classification": "NORM_DIRECT", + "value_type": "conditional", + "num_candidates": 10, + "best_score": 6, + "candidates": [ + { + "score": 6, + "reasons": [ + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 25, + "line_text": "registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and", + "context": " 23| The hypervisor extension depends on an \"I\" base integer ISA with 32\n 24| `x` registers (RV32I or RV64I), not RV32E or RV64E, which have only 16 `x`\n>>> 25| registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and\n 26| [#norm:H_vm_supported]#standard\n 27| page-based address translation must be supported, either Sv32 for RV32," + }, + { + "score": 6, + "reasons": [ + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1310, + "line_text": "[#norm:trap_del_S-mode_no_M-mode]#The `mcause`, `mepc`, and `mtval` registers and the MPP and MPIE fields of", + "context": " 1308| field of `mstatus` is written with the value of the SIE field at the\n 1309| time of the trap; and the SIE field of `mstatus` is cleared.#\n>>> 1310| [#norm:trap_del_S-mode_no_M-mode]#The `mcause`, `mepc`, and `mtval` registers and the MPP and MPIE fields of\n 1311| `mstatus` are not written.#\n 1312| " + }, + { + "score": 4, + "reasons": [ + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1691, + "line_text": "guest virtual address to `mtval`, GVA is set to 1. For any other trap", + "context": " 1689| whenever a trap is taken into M-mode. For any trap (breakpoint, address\n 1690| misaligned, access fault, page fault, or guest-page fault) that writes a\n>>> 1691| guest virtual address to `mtval`, GVA is set to 1. For any other trap\n 1692| into M-mode, GVA is set to 0.\n 1693| " + }, + { + "score": 4, + "reasons": [ + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1814, + "line_text": "information, alongside `mtval`, to assist software in handling the trap.", + "context": " 1812| shown in <>. When a trap is taken into\n 1813| M-mode, `mtval2` is written with additional exception-specific\n>>> 1814| information, alongside `mtval`, to assist software in handling the trap.\n 1815| \n 1816| [[mtval2reg]]" + }, + { + "score": 4, + "reasons": [ + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1837, + "line_text": "portion of the access as indicated by the virtual address in `mtval`.", + "context": " 1835| Otherwise, for misaligned loads and stores that cause guest-page faults,\n 1836| a nonzero guest physical address in `mtval2` corresponds to the faulting\n>>> 1837| portion of the access as indicated by the virtual address in `mtval`.\n 1838| For instruction guest-page faults on systems with variable-length\n 1839| instructions, a nonzero `mtval2` corresponds to the faulting portion of" + } + ] + }, + { + "parameter_name": "MTVEC_ACCESS", + "classification": "NORM_CSR_RW", + "value_type": "binary", + "num_candidates": 10, + "best_score": 17, + "candidates": [ + { + "score": 17, + "reasons": [ + "Description keyword 'mtvec'", + "CSR name 'mtvec' in backticks", + "WARL + CSR 'mtvec'", + "Name segment 'MTVEC'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1209, + "line_text": "[#norm:mtvec_sz_warl_acc]#The `mtvec` register is an MXLEN-bit *WARL* read/write register that holds", + "context": " 1207| ==== Machine Trap-Vector Base-Address (`mtvec`) Register\n 1208| \n>>> 1209| [#norm:mtvec_sz_warl_acc]#The `mtvec` register is an MXLEN-bit *WARL* read/write register that holds\n 1210| trap vector configuration, consisting of a vector base address (BASE)\n 1211| and a vector mode (MODE).#" + }, + { + "score": 12, + "reasons": [ + "CSR field name 'BASE'", + "Description keyword 'mtvec'", + "CSR name 'mtvec' in backticks", + "Name segment 'MTVEC'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 1207, + "line_text": "==== Machine Trap-Vector Base-Address (`mtvec`) Register", + "context": " 1205| * 1 - `LP_EXPECTED` - a landing pad instruction is expected.\n 1206| \n>>> 1207| ==== Machine Trap-Vector Base-Address (`mtvec`) Register\n 1208| \n 1209| [#norm:mtvec_sz_warl_acc]#The `mtvec` register is an MXLEN-bit *WARL* read/write register that holds" + }, + { + "score": 12, + "reasons": [ + "Description keyword 'mtvec'", + "CSR name 'mtvec' in backticks", + "Name segment 'MTVEC'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1217, + "line_text": "[#norm:mtvec_mandatory]#The `mtvec` register must always be implemented#, but", + "context": " 1215| include::images/bytefield/mtvec.edn[]\n 1216| \n>>> 1217| [#norm:mtvec_mandatory]#The `mtvec` register must always be implemented#, but\n 1218| [#norm:mtvec_rdonly]#can contain a read-only value.#\n 1219| If `mtvec` is writable, the set of values the register" + }, + { + "score": 10, + "reasons": [ + "Description keyword 'mtvec'", + "CSR name 'mtvec' in backticks", + "Name segment 'MTVEC'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 1219, + "line_text": "If `mtvec` is writable, the set of values the register", + "context": " 1217| [#norm:mtvec_mandatory]#The `mtvec` register must always be implemented#, but\n 1218| [#norm:mtvec_rdonly]#can contain a read-only value.#\n>>> 1219| If `mtvec` is writable, the set of values the register\n 1220| may hold can vary by implementation.\n 1221| [#norm:mtvec_base_align_4B]#The value in the BASE field must" + }, + { + "score": 10, + "reasons": [ + "Description keyword 'mtvec'", + "CSR name 'mtvec' in backticks", + "Name segment 'MTVEC'" + ], + "is_normative": false, + "in_note": false, + "file": "priv-csrs.adoc", + "line_number": 685, + "line_text": "`mtvec` +", + "context": " 683| `mideleg` +\n 684| `mie` +\n>>> 685| `mtvec` +\n 686| `mcounteren` +\n 687| `mstatush` +" + } + ] + }, + { + "parameter_name": "MTVEC_BASE_ALIGNMENT_DIRECT", + "classification": "NORM_CSR_WARL", + "value_type": "conditional", + "num_candidates": 10, + "best_score": 6, + "candidates": [ + { + "score": 6, + "reasons": [ + "Description keyword 'mtvec'", + "Name segment 'MTVEC'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1209, + "line_text": "[#norm:mtvec_sz_warl_acc]#The `mtvec` register is an MXLEN-bit *WARL* read/write register that holds", + "context": " 1207| ==== Machine Trap-Vector Base-Address (`mtvec`) Register\n 1208| \n>>> 1209| [#norm:mtvec_sz_warl_acc]#The `mtvec` register is an MXLEN-bit *WARL* read/write register that holds\n 1210| trap vector configuration, consisting of a vector base address (BASE)\n 1211| and a vector mode (MODE).#" + }, + { + "score": 6, + "reasons": [ + "Description keyword 'mtvec'", + "Name segment 'MTVEC'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1217, + "line_text": "[#norm:mtvec_mandatory]#The `mtvec` register must always be implemented#, but", + "context": " 1215| include::images/bytefield/mtvec.edn[]\n 1216| \n>>> 1217| [#norm:mtvec_mandatory]#The `mtvec` register must always be implemented#, but\n 1218| [#norm:mtvec_rdonly]#can contain a read-only value.#\n 1219| If `mtvec` is writable, the set of values the register" + }, + { + "score": 4, + "reasons": [ + "Description keyword 'mtvec'", + "Name segment 'MTVEC'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 1207, + "line_text": "==== Machine Trap-Vector Base-Address (`mtvec`) Register", + "context": " 1205| * 1 - `LP_EXPECTED` - a landing pad instruction is expected.\n 1206| \n>>> 1207| ==== Machine Trap-Vector Base-Address (`mtvec`) Register\n 1208| \n 1209| [#norm:mtvec_sz_warl_acc]#The `mtvec` register is an MXLEN-bit *WARL* read/write register that holds" + }, + { + "score": 4, + "reasons": [ + "Description keyword 'mtvec'", + "Name segment 'MTVEC'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 1214, + "line_text": ".Encoding of mtvec MODE field.", + "context": " 1212| \n 1213| [[norm:mtvec_enc]]\n>>> 1214| .Encoding of mtvec MODE field.\n 1215| include::images/bytefield/mtvec.edn[]\n 1216| " + }, + { + "score": 4, + "reasons": [ + "Description keyword 'mtvec'", + "Name segment 'MTVEC'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 1215, + "line_text": "include::images/bytefield/mtvec.edn[]", + "context": " 1213| [[norm:mtvec_enc]]\n 1214| .Encoding of mtvec MODE field.\n>>> 1215| include::images/bytefield/mtvec.edn[]\n 1216| \n 1217| [#norm:mtvec_mandatory]#The `mtvec` register must always be implemented#, but" + } + ] + }, + { + "parameter_name": "MTVEC_BASE_ALIGNMENT_VECTORED", + "classification": "NORM_CSR_WARL", + "value_type": "conditional", + "num_candidates": 10, + "best_score": 7, + "candidates": [ + { + "score": 7, + "reasons": [ + "Name segment 'VECTORED'", + "Description keyword 'mtvec'", + "Description keyword 'vectored'", + "Name segment 'MTVEC'" + ], + "is_normative": false, + "in_note": false, + "file": "priv-preface.adoc", + "line_number": 540, + "line_text": "* Optional vectored interrupt support has been added to the `mtvec` and", + "context": " 538| * Clarified expected use of XS to summarize additional extension state\n 539| status fields in `mstatus`.\n>>> 540| * Optional vectored interrupt support has been added to the `mtvec` and\n 541| `stvec` CSRs.\n 542| * The SEIP and UEIP bits in the `mip` CSR have been redefined to support" + }, + { + "score": 6, + "reasons": [ + "Description keyword 'mtvec'", + "Name segment 'MTVEC'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1209, + "line_text": "[#norm:mtvec_sz_warl_acc]#The `mtvec` register is an MXLEN-bit *WARL* read/write register that holds", + "context": " 1207| ==== Machine Trap-Vector Base-Address (`mtvec`) Register\n 1208| \n>>> 1209| [#norm:mtvec_sz_warl_acc]#The `mtvec` register is an MXLEN-bit *WARL* read/write register that holds\n 1210| trap vector configuration, consisting of a vector base address (BASE)\n 1211| and a vector mode (MODE).#" + }, + { + "score": 6, + "reasons": [ + "Description keyword 'mtvec'", + "Name segment 'MTVEC'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1217, + "line_text": "[#norm:mtvec_mandatory]#The `mtvec` register must always be implemented#, but", + "context": " 1215| include::images/bytefield/mtvec.edn[]\n 1216| \n>>> 1217| [#norm:mtvec_mandatory]#The `mtvec` register must always be implemented#, but\n 1218| [#norm:mtvec_rdonly]#can contain a read-only value.#\n 1219| If `mtvec` is writable, the set of values the register" + }, + { + "score": 5, + "reasons": [ + "Name segment 'VECTORED'", + "Description keyword 'vectored'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1256, + "line_text": "[#norm:mtvec_mode_vectored_op]#When MODE=Vectored, all synchronous exceptions into machine mode cause", + "context": " 1254| [#norm:mtvec_mode_direct_op]#When MODE=Direct, all traps into\n 1255| machine mode cause the `pc` to be set to the address in the BASE field.#\n>>> 1256| [#norm:mtvec_mode_vectored_op]#When MODE=Vectored, all synchronous exceptions into machine mode cause\n 1257| the `pc` to be set to the address in the BASE field, whereas interrupts\n 1258| cause the `pc` to be set to the address in the BASE field plus four" + }, + { + "score": 4, + "reasons": [ + "Description keyword 'mtvec'", + "Name segment 'MTVEC'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 1207, + "line_text": "==== Machine Trap-Vector Base-Address (`mtvec`) Register", + "context": " 1205| * 1 - `LP_EXPECTED` - a landing pad instruction is expected.\n 1206| \n>>> 1207| ==== Machine Trap-Vector Base-Address (`mtvec`) Register\n 1208| \n 1209| [#norm:mtvec_sz_warl_acc]#The `mtvec` register is an MXLEN-bit *WARL* read/write register that holds" + } + ] + }, + { + "parameter_name": "MTVEC_ILLEGAL_WRITE_BEHAVIOR", + "classification": "NORM_CSR_WARL", + "value_type": "binary", + "num_candidates": 10, + "best_score": 18, + "candidates": [ + { + "score": 18, + "reasons": [ + "Name segment 'WRITE'", + "WARL + CSR 'mtvec'", + "CSR name 'mtvec' in backticks", + "Description keyword 'mtvec'", + "Name segment 'MTVEC'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1209, + "line_text": "[#norm:mtvec_sz_warl_acc]#The `mtvec` register is an MXLEN-bit *WARL* read/write register that holds", + "context": " 1207| ==== Machine Trap-Vector Base-Address (`mtvec`) Register\n 1208| \n>>> 1209| [#norm:mtvec_sz_warl_acc]#The `mtvec` register is an MXLEN-bit *WARL* read/write register that holds\n 1210| trap vector configuration, consisting of a vector base address (BASE)\n 1211| and a vector mode (MODE).#" + }, + { + "score": 16, + "reasons": [ + "CSR field name 'BASE'", + "Description keyword 'BASE'", + "CSR name 'mtvec' in backticks", + "Description keyword 'mtvec'", + "Name segment 'MTVEC'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 1207, + "line_text": "==== Machine Trap-Vector Base-Address (`mtvec`) Register", + "context": " 1205| * 1 - `LP_EXPECTED` - a landing pad instruction is expected.\n 1206| \n>>> 1207| ==== Machine Trap-Vector Base-Address (`mtvec`) Register\n 1208| \n 1209| [#norm:mtvec_sz_warl_acc]#The `mtvec` register is an MXLEN-bit *WARL* read/write register that holds" + }, + { + "score": 15, + "reasons": [ + "Name segment 'WRITE'", + "CSR field name 'BASE'", + "CSR field name 'MODE'", + "Description keyword 'BASE'", + "Description keyword 'MODE'" + ], + "is_normative": true, + "in_note": false, + "file": "zc.adoc", + "line_number": 2399, + "line_text": "[#norm:jvt_reg]#The _jvt_ register is an XLEN-bit *WARL* read/write register that holds the jump table configuration, consisting of the jump table base address (BASE) and the jump table mode (MODE).#", + "context": " 2397| Description::\n 2398| \n>>> 2399| [#norm:jvt_reg]#The _jvt_ register is an XLEN-bit *WARL* read/write register that holds the jump table configuration, consisting of the jump table base address (BASE) and the jump table mode (MODE).#\n 2400| \n 2401| [#norm:jvt_op]#If <> is implemented then _jvt_ must also be implemented, but can contain a read-only value. If _jvt_ is writable, the set of values the register may hold can vary by implementation. The value in the BASE field must always be aligned on a 64-byte boundary." + }, + { + "score": 13, + "reasons": [ + "CSR field name 'MODE'", + "Description keyword 'mtvec'", + "Description keyword 'MODE'", + "Name segment 'MTVEC'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 1214, + "line_text": ".Encoding of mtvec MODE field.", + "context": " 1212| \n 1213| [[norm:mtvec_enc]]\n>>> 1214| .Encoding of mtvec MODE field.\n 1215| include::images/bytefield/mtvec.edn[]\n 1216| " + }, + { + "score": 13, + "reasons": [ + "CSR field name 'MODE'", + "Description keyword 'mtvec'", + "Description keyword 'MODE'", + "Name segment 'MTVEC'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 1238, + "line_text": ".Encoding of mtvec MODE field.", + "context": " 1236| \n 1237| [[norm:mtvec_mode_enc]]\n>>> 1238| .Encoding of mtvec MODE field.\n 1239| [%autowidth,float=\"center\",align=\"center\",cols=\">,^,<\",options=\"header\"]\n 1240| |===" + } + ] + }, + { + "parameter_name": "MTVEC_MODES", + "classification": "NORM_CSR_WARL", + "value_type": "set", + "num_candidates": 10, + "best_score": 18, + "candidates": [ + { + "score": 18, + "reasons": [ + "CSR field name 'BASE'", + "CSR field name 'MODE'", + "Description keyword 'pc'", + "Description keyword 'BASE'", + "Description keyword 'MODE'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 1255, + "line_text": "machine mode cause the `pc` to be set to the address in the BASE field.#", + "context": " 1253| The encoding of the MODE field is shown in <>.\n 1254| [#norm:mtvec_mode_direct_op]#When MODE=Direct, all traps into\n>>> 1255| machine mode cause the `pc` to be set to the address in the BASE field.#\n 1256| [#norm:mtvec_mode_vectored_op]#When MODE=Vectored, all synchronous exceptions into machine mode cause\n 1257| the `pc` to be set to the address in the BASE field, whereas interrupts" + }, + { + "score": 18, + "reasons": [ + "CSR field name 'BASE'", + "CSR field name 'MODE'", + "Description keyword 'pc'", + "Description keyword 'BASE'", + "Description keyword 'MODE'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 1260, + "line_text": "For example, a machine-mode timer interrupt (see <>) causes the `pc` to be set to BASE+`0x1c`.", + "context": " 1258| cause the `pc` to be set to the address in the BASE field plus four\n 1259| times the interrupt cause number.#\n>>> 1260| For example, a machine-mode timer interrupt (see <>) causes the `pc` to be set to BASE+`0x1c`.\n 1261| \n 1262| An implementation may have different alignment constraints for different" + }, + { + "score": 18, + "reasons": [ + "CSR field name 'BASE'", + "CSR field name 'MODE'", + "Description keyword 'pc'", + "Description keyword 'BASE'", + "Description keyword 'MODE'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 356, + "line_text": "supervisor mode cause the `pc` to be set to the address in the BASE", + "context": " 354| The encoding of the MODE field is shown in\n 355| <>. When MODE=Direct, all traps into\n>>> 356| supervisor mode cause the `pc` to be set to the address in the BASE\n 357| field. When MODE=Vectored, all synchronous exceptions into supervisor\n 358| mode cause the `pc` to be set to the address in the BASE field, whereas" + }, + { + "score": 18, + "reasons": [ + "CSR field name 'BASE'", + "CSR field name 'MODE'", + "Description keyword 'pc'", + "Description keyword 'BASE'", + "Description keyword 'MODE'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 358, + "line_text": "mode cause the `pc` to be set to the address in the BASE field, whereas", + "context": " 356| supervisor mode cause the `pc` to be set to the address in the BASE\n 357| field. When MODE=Vectored, all synchronous exceptions into supervisor\n>>> 358| mode cause the `pc` to be set to the address in the BASE field, whereas\n 359| interrupts cause the `pc` to be set to the address in the BASE field\n 360| plus four times the interrupt cause number. For example, a" + }, + { + "score": 18, + "reasons": [ + "CSR field name 'BASE'", + "CSR field name 'MODE'", + "Description keyword 'pc'", + "Description keyword 'BASE'", + "Description keyword 'MODE'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 362, + "line_text": "causes the `pc` to be set to BASE+`0x14`. Setting MODE=Vectored may", + "context": " 360| plus four times the interrupt cause number. For example, a\n 361| supervisor-mode timer interrupt (see <>)\n>>> 362| causes the `pc` to be set to BASE+`0x14`. Setting MODE=Vectored may\n 363| impose a stricter alignment constraint on BASE.\n 364| " + } + ] + }, + { + "parameter_name": "MUTABLE_MISA_A", + "classification": "NORM_CSR_RW", + "value_type": "binary", + "num_candidates": 10, + "best_score": 16, + "candidates": [ + { + "score": 16, + "reasons": [ + "WARL + CSR 'misa'", + "Name segment 'MISA'", + "CSR name 'misa' in backticks", + "Description keyword 'A'", + "CSR field name 'A'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 21, + "line_text": "[#norm:misa_acc]#The `misa` CSR is a *WARL* read-write register# reporting the ISA supported by the hart.", + "context": " 19| ==== Machine ISA (`misa`) Register\n 20| \n>>> 21| [#norm:misa_acc]#The `misa` CSR is a *WARL* read-write register# reporting the ISA supported by the hart.\n 22| [#norm:misa_always_rd]#This register must be readable in any implementation#,\n 23| but [#norm:misa_csr_implemented]#a value of zero can be returned to indicate the `misa` register has not been implemented#, requiring that CPU capabilities be determined through a separate non-standard mechanism." + }, + { + "score": 14, + "reasons": [ + "WARL + CSR 'misa'", + "Name segment 'MISA'", + "CSR name 'misa' in backticks", + "Description keyword 'A'", + "CSR field name 'A'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 226, + "line_text": "VSXL is a *WARL* field that is encoded the same as the MXL field of `misa`,", + "context": " 224| VSXLEN), which may differ from the XLEN for HS-mode (HSXLEN).# [#norm:hstatus-vsxl_32]#When\n 225| HSXLEN=32, the VSXL field does not exist, and VSXLEN=32.# [#norm:hstatus-vsxl_64]#When HSXLEN=64,\n>>> 226| VSXL is a *WARL* field that is encoded the same as the MXL field of `misa`,\n 227| shown in <>.# [#norm:vsxl_ro_param]#In particular, an\n 228| implementation may make VSXL be a read-only field whose value always" + }, + { + "score": 11, + "reasons": [ + "CSR field name 'A'", + "Name segment 'MISA'", + "CSR name 'misa' in backticks", + "Description keyword 'A'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 23, + "line_text": "but [#norm:misa_csr_implemented]#a value of zero can be returned to indicate the `misa` register has not been implemented#, requiring that CPU capabilities be determined through a separate non-standard mechanism.", + "context": " 21| [#norm:misa_acc]#The `misa` CSR is a *WARL* read-write register# reporting the ISA supported by the hart.\n 22| [#norm:misa_always_rd]#This register must be readable in any implementation#,\n>>> 23| but [#norm:misa_csr_implemented]#a value of zero can be returned to indicate the `misa` register has not been implemented#, requiring that CPU capabilities be determined through a separate non-standard mechanism.\n 24| \n 25| [[norm:misa_enc_img]]" + }, + { + "score": 10, + "reasons": [ + "Optional/read-only pattern for boolean param", + "CSR field name 'G'", + "CSR field name 'A'", + "Description keyword 'A'" + ], + "is_normative": true, + "in_note": false, + "file": "smctr.adoc", + "line_number": 250, + "line_text": "|WRPTR |[#norm:sctrstatus-wrptr]#WARL field that indicates the physical CTR buffer entry to be written next. It is incremented after new transfers are recorded (see <>), though there are exceptions when `__x__ctrctl`.RASEMU=1, see <>. For a given CTR depth (where depth = 2^(DEPTH+4)^), WRPTR wraps to 0 on an increment when the value matches depth-1, and to depth-1 on a decrement when the value is 0. Bits above those needed to represent depth-1 (e.g., bits 7:4 for a depth of 16) are read-only 0. On depth changes, WRPTR holds an unspecified but legal value.#", + "context": " 248| |===\n 249| |Field |Description\n>>> 250| |WRPTR |[#norm:sctrstatus-wrptr]#WARL field that indicates the physical CTR buffer entry to be written next. It is incremented after new transfers are recorded (see <>), though there are exceptions when `__x__ctrctl`.RASEMU=1, see <>. For a given CTR depth (where depth = 2^(DEPTH+4)^), WRPTR wraps to 0 on an increment when the value matches depth-1, and to depth-1 on a decrement when the value is 0. Bits above those needed to represent depth-1 (e.g., bits 7:4 for a depth of 16) are read-only 0. On depth changes, WRPTR holds an unspecified but legal value.#\n 251| |FROZEN |[#norm:sctrstatus-frozen_op]#Inhibit transfer recording.# See <>.\n 252| |===" + }, + { + "score": 9, + "reasons": [ + "CSR field name 'A'", + "Name segment 'MISA'", + "CSR name 'misa' in backticks", + "Description keyword 'A'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1184, + "line_text": "encoded the same as the MXL field of `misa`, shown in <>. In particular, an implementation may make UXL be a read-only copy of field VSXL of `hstatus`, forcing VU-mode XLEN=VSXLEN.", + "context": " 1182| from the XLEN for VS-mode (VSXLEN). When VSXLEN=32, the UXL field does\n 1183| not exist, and VU-mode XLEN=32. When VSXLEN=64, UXL is a *WARL* field that is\n>>> 1184| encoded the same as the MXL field of `misa`, shown in <>. In particular, an implementation may make UXL be a read-only copy of field VSXL of `hstatus`, forcing VU-mode XLEN=VSXLEN.\n 1185| \n 1186| [[norm:vsstatus-uxl_change]]" + } + ] + }, + { + "parameter_name": "MUTABLE_MISA_B", + "classification": "NORM_CSR_RW", + "value_type": "binary", + "num_candidates": 10, + "best_score": 11, + "candidates": [ + { + "score": 11, + "reasons": [ + "Name segment 'MISA'", + "CSR name 'misa' in backticks", + "WARL + CSR 'misa'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 21, + "line_text": "[#norm:misa_acc]#The `misa` CSR is a *WARL* read-write register# reporting the ISA supported by the hart.", + "context": " 19| ==== Machine ISA (`misa`) Register\n 20| \n>>> 21| [#norm:misa_acc]#The `misa` CSR is a *WARL* read-write register# reporting the ISA supported by the hart.\n 22| [#norm:misa_always_rd]#This register must be readable in any implementation#,\n 23| but [#norm:misa_csr_implemented]#a value of zero can be returned to indicate the `misa` register has not been implemented#, requiring that CPU capabilities be determined through a separate non-standard mechanism." + }, + { + "score": 9, + "reasons": [ + "Name segment 'MISA'", + "CSR name 'misa' in backticks", + "WARL + CSR 'misa'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 226, + "line_text": "VSXL is a *WARL* field that is encoded the same as the MXL field of `misa`,", + "context": " 224| VSXLEN), which may differ from the XLEN for HS-mode (HSXLEN).# [#norm:hstatus-vsxl_32]#When\n 225| HSXLEN=32, the VSXL field does not exist, and VSXLEN=32.# [#norm:hstatus-vsxl_64]#When HSXLEN=64,\n>>> 226| VSXL is a *WARL* field that is encoded the same as the MXL field of `misa`,\n 227| shown in <>.# [#norm:vsxl_ro_param]#In particular, an\n 228| implementation may make VSXL be a read-only field whose value always" + }, + { + "score": 9, + "reasons": [ + "Name segment 'MISA'", + "CSR name 'misa' in backticks", + "Description keyword 'B'", + "CSR field name 'B'" + ], + "is_normative": false, + "in_note": false, + "file": "priv-preface.adoc", + "line_number": 341, + "line_text": "* Defined the `misa`.B field to reflect that the B extension has been", + "context": " 339| made to the Machine and Supervisor ISAs since version 1.12:\n 340| \n>>> 341| * Defined the `misa`.B field to reflect that the B extension has been\n 342| implemented.\n 343| * Defined the `misa`.V field to reflect that the V extension has been" + }, + { + "score": 9, + "reasons": [ + "Name segment 'MISA'", + "CSR name 'misa' in backticks", + "WARL + CSR 'misa'" + ], + "is_normative": false, + "in_note": false, + "file": "priv-preface.adoc", + "line_number": 503, + "line_text": "* Made the unused `misa` fields *WARL*, rather than *WIRI*.", + "context": " 501| * Made the `mstatus`.MPP field *WARL*, rather than *WLRL*.\n 502| * Made the unused `__x__ip` fields *WPRI*, rather than *WIRI*.\n>>> 503| * Made the unused `misa` fields *WARL*, rather than *WIRI*.\n 504| * Made the unused `pmpaddr` and `pmpcfg` fields *WARL*, rather than *WIRI*.\n 505| * Required all harts in a system to employ the same PTE-update scheme as" + }, + { + "score": 7, + "reasons": [ + "Description keyword 'B'", + "CSR field name 'B'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 199, + "line_text": "[#norm:misa_b_op]#When the \"B\" bit is 1, the implementation supports the instructions provided by the", + "context": " 197| [#norm:misa_x_op]#The \"X\" bit will be set if there are any non-standard extensions.#\n 198| \n>>> 199| [#norm:misa_b_op]#When the \"B\" bit is 1, the implementation supports the instructions provided by the\n 200| Zba, Zbb, and Zbs extensions.# When the \"B\" bit is 0, it indicates that the\n 201| implementation might not support one or more of the Zba, Zbb, or Zbs extensions." + } + ] + }, + { + "parameter_name": "MUTABLE_MISA_C", + "classification": "NORM_CSR_RW", + "value_type": "binary", + "num_candidates": 10, + "best_score": 11, + "candidates": [ + { + "score": 11, + "reasons": [ + "Name segment 'MISA'", + "CSR name 'misa' in backticks", + "WARL + CSR 'misa'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 21, + "line_text": "[#norm:misa_acc]#The `misa` CSR is a *WARL* read-write register# reporting the ISA supported by the hart.", + "context": " 19| ==== Machine ISA (`misa`) Register\n 20| \n>>> 21| [#norm:misa_acc]#The `misa` CSR is a *WARL* read-write register# reporting the ISA supported by the hart.\n 22| [#norm:misa_always_rd]#This register must be readable in any implementation#,\n 23| but [#norm:misa_csr_implemented]#a value of zero can be returned to indicate the `misa` register has not been implemented#, requiring that CPU capabilities be determined through a separate non-standard mechanism." + }, + { + "score": 11, + "reasons": [ + "CSR field name 'C'", + "Description keyword 'C'", + "Name segment 'MISA'", + "CSR name 'misa' in backticks" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 246, + "line_text": "[#norm:misa_inc_ialign]#Writing `misa` may increase IALIGN, e.g., by disabling the \"C\"", + "context": " 244| collectively as a single *WARL* field. An attempt to write an unsupported combination causes those bits to be set to some supported combination.\n 245| \n>>> 246| [#norm:misa_inc_ialign]#Writing `misa` may increase IALIGN, e.g., by disabling the \"C\"\n 247| extension. If an instruction that would write `misa` increases IALIGN,\n 248| and the subsequent instruction's address is not IALIGN-bit aligned, the" + }, + { + "score": 11, + "reasons": [ + "CSR field name 'C'", + "Description keyword 'C'", + "Name segment 'MISA'", + "Description keyword 'misa.C'" + ], + "is_normative": true, + "in_note": false, + "file": "zc.adoc", + "line_number": 84, + "line_text": "[#norm:misa-c_set_line]#MISA.C is set if the following extensions are selected:#", + "context": " 82| === MISA.C\n 83| \n>>> 84| [#norm:misa-c_set_line]#MISA.C is set if the following extensions are selected:#\n 85| \n 86| [[norm:misa-c_set_list]]" + }, + { + "score": 9, + "reasons": [ + "Name segment 'MISA'", + "CSR name 'misa' in backticks", + "WARL + CSR 'misa'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 226, + "line_text": "VSXL is a *WARL* field that is encoded the same as the MXL field of `misa`,", + "context": " 224| VSXLEN), which may differ from the XLEN for HS-mode (HSXLEN).# [#norm:hstatus-vsxl_32]#When\n 225| HSXLEN=32, the VSXL field does not exist, and VSXLEN=32.# [#norm:hstatus-vsxl_64]#When HSXLEN=64,\n>>> 226| VSXL is a *WARL* field that is encoded the same as the MXL field of `misa`,\n 227| shown in <>.# [#norm:vsxl_ro_param]#In particular, an\n 228| implementation may make VSXL be a read-only field whose value always" + }, + { + "score": 9, + "reasons": [ + "Name segment 'MISA'", + "CSR name 'misa' in backticks", + "WARL + CSR 'misa'" + ], + "is_normative": false, + "in_note": false, + "file": "priv-preface.adoc", + "line_number": 503, + "line_text": "* Made the unused `misa` fields *WARL*, rather than *WIRI*.", + "context": " 501| * Made the `mstatus`.MPP field *WARL*, rather than *WLRL*.\n 502| * Made the unused `__x__ip` fields *WPRI*, rather than *WIRI*.\n>>> 503| * Made the unused `misa` fields *WARL*, rather than *WIRI*.\n 504| * Made the unused `pmpaddr` and `pmpcfg` fields *WARL*, rather than *WIRI*.\n 505| * Required all harts in a system to employ the same PTE-update scheme as" + } + ] + }, + { + "parameter_name": "MUTABLE_MISA_D", + "classification": "NORM_CSR_RW", + "value_type": "binary", + "num_candidates": 10, + "best_score": 11, + "candidates": [ + { + "score": 11, + "reasons": [ + "Name segment 'MISA'", + "CSR name 'misa' in backticks", + "WARL + CSR 'misa'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 21, + "line_text": "[#norm:misa_acc]#The `misa` CSR is a *WARL* read-write register# reporting the ISA supported by the hart.", + "context": " 19| ==== Machine ISA (`misa`) Register\n 20| \n>>> 21| [#norm:misa_acc]#The `misa` CSR is a *WARL* read-write register# reporting the ISA supported by the hart.\n 22| [#norm:misa_always_rd]#This register must be readable in any implementation#,\n 23| but [#norm:misa_csr_implemented]#a value of zero can be returned to indicate the `misa` register has not been implemented#, requiring that CPU capabilities be determined through a separate non-standard mechanism." + }, + { + "score": 9, + "reasons": [ + "Name segment 'MISA'", + "CSR name 'misa' in backticks", + "WARL + CSR 'misa'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 226, + "line_text": "VSXL is a *WARL* field that is encoded the same as the MXL field of `misa`,", + "context": " 224| VSXLEN), which may differ from the XLEN for HS-mode (HSXLEN).# [#norm:hstatus-vsxl_32]#When\n 225| HSXLEN=32, the VSXL field does not exist, and VSXLEN=32.# [#norm:hstatus-vsxl_64]#When HSXLEN=64,\n>>> 226| VSXL is a *WARL* field that is encoded the same as the MXL field of `misa`,\n 227| shown in <>.# [#norm:vsxl_ro_param]#In particular, an\n 228| implementation may make VSXL be a read-only field whose value always" + }, + { + "score": 9, + "reasons": [ + "Name segment 'MISA'", + "CSR name 'misa' in backticks", + "WARL + CSR 'misa'" + ], + "is_normative": false, + "in_note": false, + "file": "priv-preface.adoc", + "line_number": 503, + "line_text": "* Made the unused `misa` fields *WARL*, rather than *WIRI*.", + "context": " 501| * Made the `mstatus`.MPP field *WARL*, rather than *WLRL*.\n 502| * Made the unused `__x__ip` fields *WPRI*, rather than *WIRI*.\n>>> 503| * Made the unused `misa` fields *WARL*, rather than *WIRI*.\n 504| * Made the unused `pmpaddr` and `pmpcfg` fields *WARL*, rather than *WIRI*.\n 505| * Required all harts in a system to employ the same PTE-update scheme as" + }, + { + "score": 9, + "reasons": [ + "Name segment 'MISA'", + "Description keyword 'D'", + "CSR name 'misa' in backticks", + "CSR field name 'D'" + ], + "is_normative": false, + "in_note": false, + "file": "zfinx.adoc", + "line_number": 156, + "line_text": "The `misa` bits F, D, and Q are hardwired to 0 when the Zfinx extension", + "context": " 154| \n 155| [[norm:Zfinx_misa-F_D_Q_zero]]\n>>> 156| The `misa` bits F, D, and Q are hardwired to 0 when the Zfinx extension\n 157| is implemented.\n 158| [NOTE]" + }, + { + "score": 8, + "reasons": [ + "CSR field name 'G'", + "Name segment 'MISA'", + "CSR name 'misa' in backticks" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 246, + "line_text": "[#norm:misa_inc_ialign]#Writing `misa` may increase IALIGN, e.g., by disabling the \"C\"", + "context": " 244| collectively as a single *WARL* field. An attempt to write an unsupported combination causes those bits to be set to some supported combination.\n 245| \n>>> 246| [#norm:misa_inc_ialign]#Writing `misa` may increase IALIGN, e.g., by disabling the \"C\"\n 247| extension. If an instruction that would write `misa` increases IALIGN,\n 248| and the subsequent instruction's address is not IALIGN-bit aligned, the" + } + ] + }, + { + "parameter_name": "MUTABLE_MISA_F", + "classification": "NORM_CSR_RW", + "value_type": "binary", + "num_candidates": 10, + "best_score": 11, + "candidates": [ + { + "score": 11, + "reasons": [ + "Name segment 'MISA'", + "CSR name 'misa' in backticks", + "WARL + CSR 'misa'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 21, + "line_text": "[#norm:misa_acc]#The `misa` CSR is a *WARL* read-write register# reporting the ISA supported by the hart.", + "context": " 19| ==== Machine ISA (`misa`) Register\n 20| \n>>> 21| [#norm:misa_acc]#The `misa` CSR is a *WARL* read-write register# reporting the ISA supported by the hart.\n 22| [#norm:misa_always_rd]#This register must be readable in any implementation#,\n 23| but [#norm:misa_csr_implemented]#a value of zero can be returned to indicate the `misa` register has not been implemented#, requiring that CPU capabilities be determined through a separate non-standard mechanism." + }, + { + "score": 9, + "reasons": [ + "Name segment 'MISA'", + "CSR name 'misa' in backticks", + "WARL + CSR 'misa'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 226, + "line_text": "VSXL is a *WARL* field that is encoded the same as the MXL field of `misa`,", + "context": " 224| VSXLEN), which may differ from the XLEN for HS-mode (HSXLEN).# [#norm:hstatus-vsxl_32]#When\n 225| HSXLEN=32, the VSXL field does not exist, and VSXLEN=32.# [#norm:hstatus-vsxl_64]#When HSXLEN=64,\n>>> 226| VSXL is a *WARL* field that is encoded the same as the MXL field of `misa`,\n 227| shown in <>.# [#norm:vsxl_ro_param]#In particular, an\n 228| implementation may make VSXL be a read-only field whose value always" + }, + { + "score": 9, + "reasons": [ + "Name segment 'MISA'", + "CSR name 'misa' in backticks", + "WARL + CSR 'misa'" + ], + "is_normative": false, + "in_note": false, + "file": "priv-preface.adoc", + "line_number": 503, + "line_text": "* Made the unused `misa` fields *WARL*, rather than *WIRI*.", + "context": " 501| * Made the `mstatus`.MPP field *WARL*, rather than *WLRL*.\n 502| * Made the unused `__x__ip` fields *WPRI*, rather than *WIRI*.\n>>> 503| * Made the unused `misa` fields *WARL*, rather than *WIRI*.\n 504| * Made the unused `pmpaddr` and `pmpcfg` fields *WARL*, rather than *WIRI*.\n 505| * Required all harts in a system to employ the same PTE-update scheme as" + }, + { + "score": 9, + "reasons": [ + "Description keyword 'misa.F'", + "CSR field name 'F'", + "Name segment 'MISA'", + "Description keyword 'F'" + ], + "is_normative": false, + "in_note": false, + "file": "smstateen.adoc", + "line_number": 245, + "line_text": "the Zfinx and related extensions (Zdinx, etc.). Whenever `misa.F` = 1, FCSR bit", + "context": " 243| The FCSR bit controls access to `fcsr` for the case when floating-point\n 244| instructions operate on `x` registers instead of `f` registers as specified by\n>>> 245| the Zfinx and related extensions (Zdinx, etc.). Whenever `misa.F` = 1, FCSR bit\n 246| of `mstateen0` is read-only zero (and hence read-only zero in `hstateen0` and\n 247| `sstateen0` too). For convenience, when the `stateen` CSRs are implemented and" + }, + { + "score": 9, + "reasons": [ + "Description keyword 'misa.F'", + "CSR field name 'F'", + "Name segment 'MISA'", + "Description keyword 'F'" + ], + "is_normative": false, + "in_note": false, + "file": "smstateen.adoc", + "line_number": 248, + "line_text": "`misa.F` = 0, then if the FCSR bit of a controlling `stateen0` CSR is zero, all", + "context": " 246| of `mstateen0` is read-only zero (and hence read-only zero in `hstateen0` and\n 247| `sstateen0` too). For convenience, when the `stateen` CSRs are implemented and\n>>> 248| `misa.F` = 0, then if the FCSR bit of a controlling `stateen0` CSR is zero, all\n 249| floating-point instructions cause an illegal-instruction exception (or virtual-instruction\n 250| exception, if relevant), as though they all access `fcsr`, regardless of" + } + ] + }, + { + "parameter_name": "MUTABLE_MISA_H", + "classification": "NORM_CSR_RW", + "value_type": "binary", + "num_candidates": 10, + "best_score": 11, + "candidates": [ + { + "score": 11, + "reasons": [ + "Name segment 'MISA'", + "CSR name 'misa' in backticks", + "WARL + CSR 'misa'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 21, + "line_text": "[#norm:misa_acc]#The `misa` CSR is a *WARL* read-write register# reporting the ISA supported by the hart.", + "context": " 19| ==== Machine ISA (`misa`) Register\n 20| \n>>> 21| [#norm:misa_acc]#The `misa` CSR is a *WARL* read-write register# reporting the ISA supported by the hart.\n 22| [#norm:misa_always_rd]#This register must be readable in any implementation#,\n 23| but [#norm:misa_csr_implemented]#a value of zero can be returned to indicate the `misa` register has not been implemented#, requiring that CPU capabilities be determined through a separate non-standard mechanism." + }, + { + "score": 9, + "reasons": [ + "Name segment 'MISA'", + "CSR name 'misa' in backticks", + "WARL + CSR 'misa'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 226, + "line_text": "VSXL is a *WARL* field that is encoded the same as the MXL field of `misa`,", + "context": " 224| VSXLEN), which may differ from the XLEN for HS-mode (HSXLEN).# [#norm:hstatus-vsxl_32]#When\n 225| HSXLEN=32, the VSXL field does not exist, and VSXLEN=32.# [#norm:hstatus-vsxl_64]#When HSXLEN=64,\n>>> 226| VSXL is a *WARL* field that is encoded the same as the MXL field of `misa`,\n 227| shown in <>.# [#norm:vsxl_ro_param]#In particular, an\n 228| implementation may make VSXL be a read-only field whose value always" + }, + { + "score": 9, + "reasons": [ + "Name segment 'MISA'", + "CSR name 'misa' in backticks", + "WARL + CSR 'misa'" + ], + "is_normative": false, + "in_note": false, + "file": "priv-preface.adoc", + "line_number": 503, + "line_text": "* Made the unused `misa` fields *WARL*, rather than *WIRI*.", + "context": " 501| * Made the `mstatus`.MPP field *WARL*, rather than *WLRL*.\n 502| * Made the unused `__x__ip` fields *WPRI*, rather than *WIRI*.\n>>> 503| * Made the unused `misa` fields *WARL*, rather than *WIRI*.\n 504| * Made the unused `pmpaddr` and `pmpcfg` fields *WARL*, rather than *WIRI*.\n 505| * Required all harts in a system to employ the same PTE-update scheme as" + }, + { + "score": 8, + "reasons": [ + "Optional/read-only pattern for boolean param", + "Description keyword 'H'", + "CSR field name 'H'" + ], + "is_normative": true, + "in_note": false, + "file": "smctr.adoc", + "line_number": 413, + "line_text": "[#norm:hstateen_ctr]#If the H extension is implemented and `mstateen0`.CTR=1, the `hstateen0`.CTR bit controls access to supervisor CTR state when V=1. This state includes `sctrctl` (really `vsctrctl`), `sctrstatus`, and `sireg*` (really `vsireg*`) when `siselect` (really `vsiselect`) is in 0x200..0x2FF. `hstateen0`.CTR is read-only 0 when `mstateen0`.CTR=0.#", + "context": " 411| [#norm:mstateen_ctr0_qualified_transfer]#When `mstateen0`.CTR=0, qualified control transfers executed in privilege modes less privileged than M-mode will continue to implicitly update entry registers and `sctrstatus`.#\n 412| \n>>> 413| [#norm:hstateen_ctr]#If the H extension is implemented and `mstateen0`.CTR=1, the `hstateen0`.CTR bit controls access to supervisor CTR state when V=1. This state includes `sctrctl` (really `vsctrctl`), `sctrstatus`, and `sireg*` (really `vsireg*`) when `siselect` (really `vsiselect`) is in 0x200..0x2FF. `hstateen0`.CTR is read-only 0 when `mstateen0`.CTR=0.#\n 414| \n 415| [#norm:hstateen_vs]#When `mstateen0`.CTR=1 and `hstateen0`.CTR=1, VS-mode accesses to supervisor CTR state behave as described in <> and <> above, while SCTRCLR behaves as described in <>. When `mstateen0`.CTR=1 and `hstateen0`.CTR=0, both VS-mode accesses to supervisor CTR state and VS-mode execution of SCTRCLR raise a virtual-instruction exception.#" + }, + { + "score": 7, + "reasons": [ + "Optional/read-only pattern for boolean param", + "Name segment 'MISA'", + "CSR name 'misa' in backticks" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 231, + "line_text": "[#norm:misa_e_not_i]#Unless `misa` is all read-only zero, the", + "context": " 229| \n 230| [#norm:misa_e_acc]#The \"E\" bit is read-only.#\n>>> 231| [#norm:misa_e_not_i]#Unless `misa` is all read-only zero, the\n 232| \"E\" bit always reads as the complement of the \"I\" bit.#\n 233| If an execution environment supports both RV32E and RV32I, software can select" + } + ] + }, + { + "parameter_name": "MUTABLE_MISA_M", + "classification": "NORM_CSR_RW", + "value_type": "binary", + "num_candidates": 10, + "best_score": 11, + "candidates": [ + { + "score": 11, + "reasons": [ + "Name segment 'MISA'", + "CSR name 'misa' in backticks", + "WARL + CSR 'misa'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 21, + "line_text": "[#norm:misa_acc]#The `misa` CSR is a *WARL* read-write register# reporting the ISA supported by the hart.", + "context": " 19| ==== Machine ISA (`misa`) Register\n 20| \n>>> 21| [#norm:misa_acc]#The `misa` CSR is a *WARL* read-write register# reporting the ISA supported by the hart.\n 22| [#norm:misa_always_rd]#This register must be readable in any implementation#,\n 23| but [#norm:misa_csr_implemented]#a value of zero can be returned to indicate the `misa` register has not been implemented#, requiring that CPU capabilities be determined through a separate non-standard mechanism." + }, + { + "score": 9, + "reasons": [ + "Name segment 'MISA'", + "CSR name 'misa' in backticks", + "WARL + CSR 'misa'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 226, + "line_text": "VSXL is a *WARL* field that is encoded the same as the MXL field of `misa`,", + "context": " 224| VSXLEN), which may differ from the XLEN for HS-mode (HSXLEN).# [#norm:hstatus-vsxl_32]#When\n 225| HSXLEN=32, the VSXL field does not exist, and VSXLEN=32.# [#norm:hstatus-vsxl_64]#When HSXLEN=64,\n>>> 226| VSXL is a *WARL* field that is encoded the same as the MXL field of `misa`,\n 227| shown in <>.# [#norm:vsxl_ro_param]#In particular, an\n 228| implementation may make VSXL be a read-only field whose value always" + }, + { + "score": 9, + "reasons": [ + "Name segment 'MISA'", + "CSR name 'misa' in backticks", + "WARL + CSR 'misa'" + ], + "is_normative": false, + "in_note": false, + "file": "priv-preface.adoc", + "line_number": 503, + "line_text": "* Made the unused `misa` fields *WARL*, rather than *WIRI*.", + "context": " 501| * Made the `mstatus`.MPP field *WARL*, rather than *WLRL*.\n 502| * Made the unused `__x__ip` fields *WPRI*, rather than *WIRI*.\n>>> 503| * Made the unused `misa` fields *WARL*, rather than *WIRI*.\n 504| * Made the unused `pmpaddr` and `pmpcfg` fields *WARL*, rather than *WIRI*.\n 505| * Required all harts in a system to employ the same PTE-update scheme as" + }, + { + "score": 8, + "reasons": [ + "CSR field name 'G'", + "Name segment 'MISA'", + "CSR name 'misa' in backticks" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 246, + "line_text": "[#norm:misa_inc_ialign]#Writing `misa` may increase IALIGN, e.g., by disabling the \"C\"", + "context": " 244| collectively as a single *WARL* field. An attempt to write an unsupported combination causes those bits to be set to some supported combination.\n 245| \n>>> 246| [#norm:misa_inc_ialign]#Writing `misa` may increase IALIGN, e.g., by disabling the \"C\"\n 247| extension. If an instruction that would write `misa` increases IALIGN,\n 248| and the subsequent instruction's address is not IALIGN-bit aligned, the" + }, + { + "score": 8, + "reasons": [ + "Optional/read-only pattern for boolean param", + "Description keyword 'M'", + "CSR field name 'M'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 802, + "line_text": "[#norm:mstatus_tw_acc]#TW is read-only 0 when there are no modes less privileged than M.#", + "context": " 800| TW=1, even if there are pending globally-disabled interrupts when the\n 801| instruction is executed.#\n>>> 802| [#norm:mstatus_tw_acc]#TW is read-only 0 when there are no modes less privileged than M.#\n 803| \n 804| [NOTE]" + } + ] + }, + { + "parameter_name": "MUTABLE_MISA_Q", + "classification": "NORM_CSR_RW", + "value_type": "binary", + "num_candidates": 10, + "best_score": 11, + "candidates": [ + { + "score": 11, + "reasons": [ + "Name segment 'MISA'", + "CSR name 'misa' in backticks", + "WARL + CSR 'misa'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 21, + "line_text": "[#norm:misa_acc]#The `misa` CSR is a *WARL* read-write register# reporting the ISA supported by the hart.", + "context": " 19| ==== Machine ISA (`misa`) Register\n 20| \n>>> 21| [#norm:misa_acc]#The `misa` CSR is a *WARL* read-write register# reporting the ISA supported by the hart.\n 22| [#norm:misa_always_rd]#This register must be readable in any implementation#,\n 23| but [#norm:misa_csr_implemented]#a value of zero can be returned to indicate the `misa` register has not been implemented#, requiring that CPU capabilities be determined through a separate non-standard mechanism." + }, + { + "score": 9, + "reasons": [ + "Name segment 'MISA'", + "CSR name 'misa' in backticks", + "WARL + CSR 'misa'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 226, + "line_text": "VSXL is a *WARL* field that is encoded the same as the MXL field of `misa`,", + "context": " 224| VSXLEN), which may differ from the XLEN for HS-mode (HSXLEN).# [#norm:hstatus-vsxl_32]#When\n 225| HSXLEN=32, the VSXL field does not exist, and VSXLEN=32.# [#norm:hstatus-vsxl_64]#When HSXLEN=64,\n>>> 226| VSXL is a *WARL* field that is encoded the same as the MXL field of `misa`,\n 227| shown in <>.# [#norm:vsxl_ro_param]#In particular, an\n 228| implementation may make VSXL be a read-only field whose value always" + }, + { + "score": 9, + "reasons": [ + "Name segment 'MISA'", + "CSR name 'misa' in backticks", + "WARL + CSR 'misa'" + ], + "is_normative": false, + "in_note": false, + "file": "priv-preface.adoc", + "line_number": 503, + "line_text": "* Made the unused `misa` fields *WARL*, rather than *WIRI*.", + "context": " 501| * Made the `mstatus`.MPP field *WARL*, rather than *WLRL*.\n 502| * Made the unused `__x__ip` fields *WPRI*, rather than *WIRI*.\n>>> 503| * Made the unused `misa` fields *WARL*, rather than *WIRI*.\n 504| * Made the unused `pmpaddr` and `pmpcfg` fields *WARL*, rather than *WIRI*.\n 505| * Required all harts in a system to employ the same PTE-update scheme as" + }, + { + "score": 9, + "reasons": [ + "Description keyword 'Q'", + "Name segment 'MISA'", + "CSR name 'misa' in backticks", + "CSR field name 'Q'" + ], + "is_normative": false, + "in_note": false, + "file": "zfinx.adoc", + "line_number": 156, + "line_text": "The `misa` bits F, D, and Q are hardwired to 0 when the Zfinx extension", + "context": " 154| \n 155| [[norm:Zfinx_misa-F_D_Q_zero]]\n>>> 156| The `misa` bits F, D, and Q are hardwired to 0 when the Zfinx extension\n 157| is implemented.\n 158| [NOTE]" + }, + { + "score": 7, + "reasons": [ + "Optional/read-only pattern for boolean param", + "Name segment 'MISA'", + "CSR name 'misa' in backticks" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 231, + "line_text": "[#norm:misa_e_not_i]#Unless `misa` is all read-only zero, the", + "context": " 229| \n 230| [#norm:misa_e_acc]#The \"E\" bit is read-only.#\n>>> 231| [#norm:misa_e_not_i]#Unless `misa` is all read-only zero, the\n 232| \"E\" bit always reads as the complement of the \"I\" bit.#\n 233| If an execution environment supports both RV32E and RV32I, software can select" + } + ] + }, + { + "parameter_name": "MUTABLE_MISA_S", + "classification": "NORM_CSR_RW", + "value_type": "binary", + "num_candidates": 10, + "best_score": 11, + "candidates": [ + { + "score": 11, + "reasons": [ + "Name segment 'MISA'", + "CSR name 'misa' in backticks", + "WARL + CSR 'misa'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 21, + "line_text": "[#norm:misa_acc]#The `misa` CSR is a *WARL* read-write register# reporting the ISA supported by the hart.", + "context": " 19| ==== Machine ISA (`misa`) Register\n 20| \n>>> 21| [#norm:misa_acc]#The `misa` CSR is a *WARL* read-write register# reporting the ISA supported by the hart.\n 22| [#norm:misa_always_rd]#This register must be readable in any implementation#,\n 23| but [#norm:misa_csr_implemented]#a value of zero can be returned to indicate the `misa` register has not been implemented#, requiring that CPU capabilities be determined through a separate non-standard mechanism." + }, + { + "score": 9, + "reasons": [ + "Name segment 'MISA'", + "CSR name 'misa' in backticks", + "WARL + CSR 'misa'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 226, + "line_text": "VSXL is a *WARL* field that is encoded the same as the MXL field of `misa`,", + "context": " 224| VSXLEN), which may differ from the XLEN for HS-mode (HSXLEN).# [#norm:hstatus-vsxl_32]#When\n 225| HSXLEN=32, the VSXL field does not exist, and VSXLEN=32.# [#norm:hstatus-vsxl_64]#When HSXLEN=64,\n>>> 226| VSXL is a *WARL* field that is encoded the same as the MXL field of `misa`,\n 227| shown in <>.# [#norm:vsxl_ro_param]#In particular, an\n 228| implementation may make VSXL be a read-only field whose value always" + }, + { + "score": 9, + "reasons": [ + "Name segment 'MISA'", + "CSR name 'misa' in backticks", + "WARL + CSR 'misa'" + ], + "is_normative": false, + "in_note": false, + "file": "priv-preface.adoc", + "line_number": 503, + "line_text": "* Made the unused `misa` fields *WARL*, rather than *WIRI*.", + "context": " 501| * Made the `mstatus`.MPP field *WARL*, rather than *WLRL*.\n 502| * Made the unused `__x__ip` fields *WPRI*, rather than *WIRI*.\n>>> 503| * Made the unused `misa` fields *WARL*, rather than *WIRI*.\n 504| * Made the unused `pmpaddr` and `pmpcfg` fields *WARL*, rather than *WIRI*.\n 505| * Required all harts in a system to employ the same PTE-update scheme as" + }, + { + "score": 8, + "reasons": [ + "Optional/read-only pattern for boolean param", + "CSR field name 'S'", + "Description keyword 'S'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 577, + "line_text": "[#norm:mstatus_sxl_acc_mxlen64]#When MXLEN=64, if S-mode is not supported, then SXL is read-only zero.", + "context": " 575| When MXLEN=32, the SXL and UXL fields do not exist, and SXLEN=32 and UXLEN=32.\n 576| \n>>> 577| [#norm:mstatus_sxl_acc_mxlen64]#When MXLEN=64, if S-mode is not supported, then SXL is read-only zero.\n 578| Otherwise, it is a *WARL* field that encodes the current value of SXLEN.#\n 579| In particular, [#norm:mstatus_sxl_rdonly_mxlen64]#an implementation may make SXL be a read-only field whose" + }, + { + "score": 8, + "reasons": [ + "Optional/read-only pattern for boolean param", + "CSR field name 'S'", + "Description keyword 'S'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 648, + "line_text": "[#norm:mstatus_mxr_rdonly0_no_smode]#MXR is read-only 0 if S-mode is not supported.#", + "context": " 646| When MXR=1, loads from pages marked either readable or executable (R=1 or\n 647| X=1) will succeed. MXR has no effect when page-based virtual memory is not in effect.#\n>>> 648| [#norm:mstatus_mxr_rdonly0_no_smode]#MXR is read-only 0 if S-mode is not supported.#\n 649| \n 650| [NOTE]" + } + ] + }, + { + "parameter_name": "MUTABLE_MISA_U", + "classification": "NORM_CSR_RW", + "value_type": "binary", + "num_candidates": 10, + "best_score": 11, + "candidates": [ + { + "score": 11, + "reasons": [ + "Name segment 'MISA'", + "CSR name 'misa' in backticks", + "WARL + CSR 'misa'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 21, + "line_text": "[#norm:misa_acc]#The `misa` CSR is a *WARL* read-write register# reporting the ISA supported by the hart.", + "context": " 19| ==== Machine ISA (`misa`) Register\n 20| \n>>> 21| [#norm:misa_acc]#The `misa` CSR is a *WARL* read-write register# reporting the ISA supported by the hart.\n 22| [#norm:misa_always_rd]#This register must be readable in any implementation#,\n 23| but [#norm:misa_csr_implemented]#a value of zero can be returned to indicate the `misa` register has not been implemented#, requiring that CPU capabilities be determined through a separate non-standard mechanism." + }, + { + "score": 9, + "reasons": [ + "Name segment 'MISA'", + "CSR name 'misa' in backticks", + "WARL + CSR 'misa'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 226, + "line_text": "VSXL is a *WARL* field that is encoded the same as the MXL field of `misa`,", + "context": " 224| VSXLEN), which may differ from the XLEN for HS-mode (HSXLEN).# [#norm:hstatus-vsxl_32]#When\n 225| HSXLEN=32, the VSXL field does not exist, and VSXLEN=32.# [#norm:hstatus-vsxl_64]#When HSXLEN=64,\n>>> 226| VSXL is a *WARL* field that is encoded the same as the MXL field of `misa`,\n 227| shown in <>.# [#norm:vsxl_ro_param]#In particular, an\n 228| implementation may make VSXL be a read-only field whose value always" + }, + { + "score": 9, + "reasons": [ + "Name segment 'MISA'", + "CSR name 'misa' in backticks", + "WARL + CSR 'misa'" + ], + "is_normative": false, + "in_note": false, + "file": "priv-preface.adoc", + "line_number": 503, + "line_text": "* Made the unused `misa` fields *WARL*, rather than *WIRI*.", + "context": " 501| * Made the `mstatus`.MPP field *WARL*, rather than *WLRL*.\n 502| * Made the unused `__x__ip` fields *WPRI*, rather than *WIRI*.\n>>> 503| * Made the unused `misa` fields *WARL*, rather than *WIRI*.\n 504| * Made the unused `pmpaddr` and `pmpcfg` fields *WARL*, rather than *WIRI*.\n 505| * Required all harts in a system to employ the same PTE-update scheme as" + }, + { + "score": 8, + "reasons": [ + "Optional/read-only pattern for boolean param", + "Description keyword 'U'", + "CSR field name 'U'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 582, + "line_text": "[#norm:mstatus_uxl_acc_mxlen64]#When MXLEN=64, if U-mode is not supported, then UXL is read-only zero.", + "context": " 580| value always ensures that SXLEN=MXLEN.#\n 581| \n>>> 582| [#norm:mstatus_uxl_acc_mxlen64]#When MXLEN=64, if U-mode is not supported, then UXL is read-only zero.\n 583| Otherwise, it is a *WARL* field that encodes the current value of UXLEN.#\n 584| In particular, [#norm:mstatus_uxl_rdonly_mxlen64]#an implementation may make UXL be a read-only field whose" + }, + { + "score": 8, + "reasons": [ + "Optional/read-only pattern for boolean param", + "Description keyword 'U'", + "CSR field name 'U'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 639, + "line_text": "[#norm:mstatus_mprv_rdonly0_no_umode]#MPRV is read-only 0 if U-mode is not supported.#", + "context": " 637| [#norm:mstatus_mprv_inst_xlat_op]#Instruction address-translation and protection are unaffected by the\n 638| setting of MPRV.#\n>>> 639| [#norm:mstatus_mprv_rdonly0_no_umode]#MPRV is read-only 0 if U-mode is not supported.#\n 640| \n 641| [#norm:mstatus_mprv_clr_mret_sret_less_priv]#An MRET or SRET instruction that changes the privilege mode to a mode" + } + ] + }, + { + "parameter_name": "MUTABLE_MISA_V", + "classification": "NORM_CSR_RW", + "value_type": "binary", + "num_candidates": 10, + "best_score": 14, + "candidates": [ + { + "score": 14, + "reasons": [ + "CSR field name 'V'", + "Description keyword 'misa.V'", + "Name segment 'MISA'", + "CSR name 'misa' in backticks", + "Description keyword 'V'" + ], + "is_normative": true, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 5161, + "line_text": "[#norm:misa-V_op]#The `misa.v` bit is set for implementations providing `misa` and", + "context": " 5159| processor profiles.\n 5160| \n>>> 5161| [#norm:misa-V_op]#The `misa.v` bit is set for implementations providing `misa` and\n 5162| supporting V.#\n 5163| " + }, + { + "score": 11, + "reasons": [ + "Name segment 'MISA'", + "CSR name 'misa' in backticks", + "WARL + CSR 'misa'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 21, + "line_text": "[#norm:misa_acc]#The `misa` CSR is a *WARL* read-write register# reporting the ISA supported by the hart.", + "context": " 19| ==== Machine ISA (`misa`) Register\n 20| \n>>> 21| [#norm:misa_acc]#The `misa` CSR is a *WARL* read-write register# reporting the ISA supported by the hart.\n 22| [#norm:misa_always_rd]#This register must be readable in any implementation#,\n 23| but [#norm:misa_csr_implemented]#a value of zero can be returned to indicate the `misa` register has not been implemented#, requiring that CPU capabilities be determined through a separate non-standard mechanism." + }, + { + "score": 11, + "reasons": [ + "Description keyword 'misa.V'", + "CSR field name 'V'", + "Name segment 'MISA'", + "Description keyword 'V'" + ], + "is_normative": true, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 110, + "line_text": "[#norm:mutable_misa_v_param]#Implementations may have a writable `misa.V` field.# [#norm:mstatus_vs_exists_param]#Analogous to the", + "context": " 108| otherwise, `mstatus.SD` is set in accordance with existing specifications.\n 109| \n>>> 110| [#norm:mutable_misa_v_param]#Implementations may have a writable `misa.V` field.# [#norm:mstatus_vs_exists_param]#Analogous to the\n 111| way in which the floating-point unit is handled, the `mstatus.VS`\n 112| field may exist even if `misa.V` is clear.#" + }, + { + "score": 9, + "reasons": [ + "Name segment 'MISA'", + "CSR name 'misa' in backticks", + "WARL + CSR 'misa'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 226, + "line_text": "VSXL is a *WARL* field that is encoded the same as the MXL field of `misa`,", + "context": " 224| VSXLEN), which may differ from the XLEN for HS-mode (HSXLEN).# [#norm:hstatus-vsxl_32]#When\n 225| HSXLEN=32, the VSXL field does not exist, and VSXLEN=32.# [#norm:hstatus-vsxl_64]#When HSXLEN=64,\n>>> 226| VSXL is a *WARL* field that is encoded the same as the MXL field of `misa`,\n 227| shown in <>.# [#norm:vsxl_ro_param]#In particular, an\n 228| implementation may make VSXL be a read-only field whose value always" + }, + { + "score": 9, + "reasons": [ + "CSR field name 'V'", + "Name segment 'MISA'", + "CSR name 'misa' in backticks", + "Description keyword 'V'" + ], + "is_normative": false, + "in_note": false, + "file": "priv-preface.adoc", + "line_number": 343, + "line_text": "* Defined the `misa`.V field to reflect that the V extension has been", + "context": " 341| * Defined the `misa`.B field to reflect that the B extension has been\n 342| implemented.\n>>> 343| * Defined the `misa`.V field to reflect that the V extension has been\n 344| implemented.\n 345| * Defined the RV32-only `medelegh` and `hedelegh` CSRs." + } + ] + }, + { + "parameter_name": "MXLEN", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 12, + "candidates": [ + { + "score": 12, + "reasons": [ + "Exact parameter name 'MXLEN'", + "Name segment 'MXLEN'", + "CSR name 'misa' in backticks" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 50, + "line_text": "[#norm:misa_sz]#The `misa` CSR is MXLEN bits wide.#", + "context": " 48| |===\n 49| \n>>> 50| [#norm:misa_sz]#The `misa` CSR is MXLEN bits wide.#\n 51| \n 52| [NOTE]" + }, + { + "score": 12, + "reasons": [ + "Exact parameter name 'MXLEN'", + "Name segment 'MXLEN'", + "CSR name 'misa' in backticks", + "CSR field name 'MXL'" + ], + "is_normative": false, + "in_note": false, + "file": "priv-preface.adoc", + "line_number": 335, + "line_text": "* Redefined `misa`.MXL to be read-only, making MXLEN a constant.", + "context": " 333| anticipated to cause software portability problems in practice:\n 334| \n>>> 335| * Redefined `misa`.MXL to be read-only, making MXLEN a constant.\n 336| * Added the constraint that SXLEN{ge}UXLEN.\n 337| " + }, + { + "score": 11, + "reasons": [ + "Exact parameter name 'MXLEN'", + "Name segment 'MXLEN'", + "CSR field name 'ADDRESS'" + ], + "is_normative": true, + "in_note": false, + "file": "smctr.adoc", + "line_number": 296, + "line_text": "[#norm:Ssctr_ctrsource_sz_acc_op]#`ctrsource` is an MXLEN-bit WARL register that must be able to hold all valid virtual or physical addresses that can serve as a `pc`. It need not be able to hold any invalid addresses; implementations may convert an invalid address into a valid address that the register is capable of holding. When XLEN < MXLEN, both explicit writes (by software) and implicit writes (for recorded transfers) will be zero-extended.#", + "context": " 294| [#norm:ctrsource_op]#The `ctrsource` register contains the source program counter, which is the `pc` of the recorded control transfer instruction, or the epc of the recorded trap.# [#norm:ctrsource_ctrtartget_ctrdata_Vbit]#The valid (V) bit is set by the hardware when a transfer is recorded in the selected CTR buffer entry, and implies that data in `ctrsource`, `ctrtarget`, and `ctrdata` is valid for this entry.#\n 295| \n>>> 296| [#norm:Ssctr_ctrsource_sz_acc_op]#`ctrsource` is an MXLEN-bit WARL register that must be able to hold all valid virtual or physical addresses that can serve as a `pc`. It need not be able to hold any invalid addresses; implementations may convert an invalid address into a valid address that the register is capable of holding. When XLEN < MXLEN, both explicit writes (by software) and implicit writes (for recorded transfers) will be zero-extended.#\n 297| \n 298| .Control Transfer Record Source Register Format for MXLEN=64" + }, + { + "score": 11, + "reasons": [ + "Exact parameter name 'MXLEN'", + "Name segment 'MXLEN'", + "CSR field name 'ADDRESS'" + ], + "is_normative": true, + "in_note": false, + "file": "smctr.adoc", + "line_number": 324, + "line_text": "[#norm:ctrtarget_sz_acc]#`ctrtarget` is an MXLEN-bit WARL register that must be able to hold all valid virtual or physical addresses that can serve as a `pc`. It need not be able to hold any invalid addresses; implementations may convert an invalid address into a valid address that the register is capable of holding. When XLEN < MXLEN, both explicit writes (by software) and implicit writes (by recorded transfers) will be zero-extended.#", + "context": " 322| is read-only 0 when not implemented.#\n 323| \n>>> 324| [#norm:ctrtarget_sz_acc]#`ctrtarget` is an MXLEN-bit WARL register that must be able to hold all valid virtual or physical addresses that can serve as a `pc`. It need not be able to hold any invalid addresses; implementations may convert an invalid address into a valid address that the register is capable of holding. When XLEN < MXLEN, both explicit writes (by software) and implicit writes (by recorded transfers) will be zero-extended.#\n 325| \n 326| .Control Transfer Record Target Register Format for MXLEN=64" + }, + { + "score": 10, + "reasons": [ + "Exact parameter name 'MXLEN'", + "Name segment 'MXLEN'", + "CSR name 'mconfigptr' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 2138, + "line_text": "The `mconfigptr` register is an MXLEN-bit read-only CSR, formatted as shown in", + "context": " 2136| ==== Machine Configuration Pointer (`mconfigptr`) Register\n 2137| \n>>> 2138| The `mconfigptr` register is an MXLEN-bit read-only CSR, formatted as shown in\n 2139| <>, that holds the physical\n 2140| address of a configuration data structure. Software can traverse this" + } + ] + }, + { + "parameter_name": "M_MODE_ENDIANNESS", + "classification": "NORM_CSR_RW", + "value_type": "enum", + "num_candidates": 10, + "best_score": 22, + "candidates": [ + { + "score": 22, + "reasons": [ + "WARL + CSR 'mstatush'", + "CSR field name 'MBE'", + "CSR name 'mstatus' in backticks", + "CSR name 'mstatush' in backticks", + "Description keyword 'MBE'", + "WARL + CSR 'mstatus'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 679, + "line_text": "[#norm:mstatus_mstatush_xbe_warl]#The MBE, SBE, and UBE bits in `mstatus` and `mstatush` are *WARL* fields# that", + "context": " 677| ===== Endianness Control in `mstatus` and `mstatush` Registers\n 678| \n>>> 679| [#norm:mstatus_mstatush_xbe_warl]#The MBE, SBE, and UBE bits in `mstatus` and `mstatush` are *WARL* fields# that\n 680| control the endianness of memory accesses other than instruction fetches.\n 681| [#norm:endianness_inst_fetch_little]#Instruction fetches are always little-endian.#" + }, + { + "score": 10, + "reasons": [ + "Description keyword 'MBE'", + "CSR name 'mstatus' in backticks", + "CSR field name 'MBE'", + "CSR name 'mstatush' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 2791, + "line_text": "supported, the `mstatus`/`mstatush` field MBE is reset to 0. The `misa`", + "context": " 2789| Upon reset, a hart’s privilege mode is set to M. The `mstatus` fields\n 2790| MIE and MPRV are reset to 0. If little-endian memory accesses are\n>>> 2791| supported, the `mstatus`/`mstatush` field MBE is reset to 0. The `misa`\n 2792| register is reset to enable the maximal set of supported extensions,\n 2793| as described in <>. For" + }, + { + "score": 9, + "reasons": [ + "Description keyword 'MBE'", + "CSR name 'mstatus' in backticks", + "CSR field name 'MBE'", + "Description keyword 'endian'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 685, + "line_text": "M-mode (assuming `mstatus`.MPRV=0) are little-endian (MBE=0) or", + "context": " 683| [[norm:mstatus_mbe_op]]\n 684| MBE controls whether non-instruction-fetch memory accesses made from\n>>> 685| M-mode (assuming `mstatus`.MPRV=0) are little-endian (MBE=0) or\n 686| big-endian (MBE=1).\n 687| " + }, + { + "score": 8, + "reasons": [ + "CSR name 'mstatus' in backticks", + "CSR name 'mstatush' in backticks" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 393, + "line_text": "[#norm:mstatush_enc]#Bits 30:4 of `mstatush` generally contain the same fields found in bits 62:36 of `mstatus` for RV64. Fields SD, SXL, and UXL do not exist in `mstatush`.#", + "context": " 391| \n 392| [#norm:mstatush_sz_acc]#For RV32 only, `mstatush` is a 32-bit read/write register formatted as shown in <>.#\n>>> 393| [#norm:mstatush_enc]#Bits 30:4 of `mstatush` generally contain the same fields found in bits 62:36 of `mstatus` for RV64. Fields SD, SXL, and UXL do not exist in `mstatush`.#\n 394| \n 395| [[mstatushreg]]" + }, + { + "score": 8, + "reasons": [ + "WARL + CSR 'mstatus'", + "CSR name 'mstatus' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "priv-preface.adoc", + "line_number": 501, + "line_text": "* Made the `mstatus`.MPP field *WARL*, rather than *WLRL*.", + "context": " 499| the possibility of a future global-ASID extension.\n 500| * SFENCE.VMA semantics have been clarified.\n>>> 501| * Made the `mstatus`.MPP field *WARL*, rather than *WLRL*.\n 502| * Made the unused `__x__ip` fields *WPRI*, rather than *WIRI*.\n 503| * Made the unused `misa` fields *WARL*, rather than *WIRI*." + } + ] + }, + { + "parameter_name": "NUM_EXTERNAL_GUEST_INTERRUPTS", + "classification": "NORM_DIRECT", + "value_type": "conditional", + "num_candidates": 10, + "best_score": 9, + "candidates": [ + { + "score": 9, + "reasons": [ + "Name segment 'INTERRUPTS'", + "CSR field name 'VGEIN'", + "Description keyword 'GEILEN'", + "Name segment 'EXTERNAL'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 259, + "line_text": "VS-level external interrupts. GEILEN may be zero, in which case VGEIN", + "context": " 257| maximum guest external interrupt number (known as GEILEN), inclusive.\n 258| When VGEIN=0, no guest external interrupt source is selected for\n>>> 259| VS-level external interrupts. GEILEN may be zero, in which case VGEIN\n 260| may be read-only zero. Guest external interrupts are explained in\n 261| <>, and the use of VGEIN is covered" + }, + { + "score": 7, + "reasons": [ + "Name segment 'GUEST'", + "Description keyword 'GEILEN'", + "Name segment 'EXTERNAL'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 257, + "line_text": "maximum guest external interrupt number (known as GEILEN), inclusive.", + "context": " 255| guest external interrupt source for VS-level external interrupts. VGEIN\n 256| is a *WLRL* field that must be able to hold values between zero and the\n>>> 257| maximum guest external interrupt number (known as GEILEN), inclusive.\n 258| When VGEIN=0, no guest external interrupt source is selected for\n 259| VS-level external interrupts. GEILEN may be zero, in which case VGEIN" + }, + { + "score": 5, + "reasons": [ + "Name segment 'GUEST'", + "Name segment 'INTERRUPTS'", + "CSR field name 'VGEIN'", + "Name segment 'EXTERNAL'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 255, + "line_text": "guest external interrupt source for VS-level external interrupts. VGEIN", + "context": " 253| [[norm:hstatus-vgein_op]]\n 254| The VGEIN (Virtual Guest External Interrupt Number) field selects a\n>>> 255| guest external interrupt source for VS-level external interrupts. VGEIN\n 256| is a *WLRL* field that must be able to hold values between zero and the\n 257| maximum guest external interrupt number (known as GEILEN), inclusive." + }, + { + "score": 5, + "reasons": [ + "CSR field name 'VGEIN'", + "CSR name 'hstatus' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 571, + "line_text": "* the bit of `hgeip` selected by `hstatus`.VGEIN; and", + "context": " 569| \n 570| * bit VSEIP of `hvip`;\n>>> 571| * the bit of `hgeip` selected by `hstatus`.VGEIN; and\n 572| * any other platform-specific external interrupt signal directed to\n 573| VS-level." + }, + { + "score": 5, + "reasons": [ + "Name segment 'GUEST'", + "Name segment 'INTERRUPTS'", + "Name segment 'EXTERNAL'" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 604, + "line_text": "guest external interrupts at this hart.# [#norm:hgeip_hgeie_fields]#Guest external interrupt number", + "context": " 602| read/write register, formatted as shown in\n 603| <>, that contains enable bits for the\n>>> 604| guest external interrupts at this hart.# [#norm:hgeip_hgeie_fields]#Guest external interrupt number\n 605| _i_ corresponds with bit _i_ in both `hgeip` and `hgeie`.#\n 606| " + } + ] + }, + { + "parameter_name": "NUM_PMP_ENTRIES", + "classification": "NORM_DIRECT", + "value_type": "range", + "num_candidates": 10, + "best_score": 4, + "candidates": [ + { + "score": 4, + "reasons": [ + "Description keyword 'NOTE'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 668, + "line_text": "Note that, [#norm:mstatus_sum_op_mprv_mpp]#while SUM is ordinarily ignored when not", + "context": " 666| (U=1 in <>) will fault. When SUM=1, these accesses are permitted.#\n 667| [#norm:mstatus_sum_op_no-vm]#SUM has no effect when page-based virtual memory is not in effect.#\n>>> 668| Note that, [#norm:mstatus_sum_op_mprv_mpp]#while SUM is ordinarily ignored when not\n 669| executing in S-mode, it _is_ in effect when MPRV=1 and MPP=S.#\n 670| [#norm:mstatus_sum_rdonly0]#SUM is read-only 0 if S-mode is not supported or if `satp`.MODE is read-only 0.#" + }, + { + "score": 4, + "reasons": [ + "Description keyword 'NOTE'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1780, + "line_text": "[#norm:mcause_exccode_ld_ldrsv]#Note that load and load-reserved instructions generate load exceptions#, whereas", + "context": " 1778| include::images/bytefield/mcausereg.edn[]\n 1779| \n>>> 1780| [#norm:mcause_exccode_ld_ldrsv]#Note that load and load-reserved instructions generate load exceptions#, whereas\n 1781| [#norm:mcause_exccode_st_sc_amo]#store, store-conditional, and AMO instructions generate\n 1782| store/AMO exceptions.#" + }, + { + "score": 4, + "reasons": [ + "Description keyword 'NOTE'" + ], + "is_normative": true, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 169, + "line_text": "NOTE: [#norm:vill_implicit_encoding_param]#A small implementation supporting ELEN=32 requires only seven bits of state in `vtype`: two bits for `ma` and `ta`, two bits for `vsew[1:0]` and three bits for `vlmul[2:0]`. The illegal value represented by `vill` can be internally encoded using the illegal 64-bit combination in `vsew[1:0]` without requiring an additional storage", + "context": " 167| \n 168| \n>>> 169| NOTE: [#norm:vill_implicit_encoding_param]#A small implementation supporting ELEN=32 requires only seven bits of state in `vtype`: two bits for `ma` and `ta`, two bits for `vsew[1:0]` and three bits for `vlmul[2:0]`. The illegal value represented by `vill` can be internally encoded using the illegal 64-bit combination in `vsew[1:0]` without requiring an additional storage\n 170| bit to hold `vill`.#\n 171| " + }, + { + "score": 4, + "reasons": [ + "Description keyword 'NOTE'" + ], + "is_normative": true, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 206, + "line_text": "NOTE: [#norm:vtype-vsew_rsv]#While it is anticipated the larger `vsew[2:0]` encodings", + "context": " 204| |===\n 205| \n>>> 206| NOTE: [#norm:vtype-vsew_rsv]#While it is anticipated the larger `vsew[2:0]` encodings\n 207| (`100`-`111`) will be used to encode larger SEW, the encodings are\n 208| formally _reserved_ at this point.#" + }, + { + "score": 4, + "reasons": [ + "Description keyword 'NOTE'" + ], + "is_normative": true, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 2309, + "line_text": "NOTE: [#norm:V_Zinx_fp_scalar]#When adding a vector extension to the Zfinx/Zdinx/Zhinx", + "context": " 2307| by naming the immediate `uimm` in the assembly syntax.\n 2308| \n>>> 2309| NOTE: [#norm:V_Zinx_fp_scalar]#When adding a vector extension to the Zfinx/Zdinx/Zhinx\n 2310| extensions, floating-point scalar arguments are taken from the `x` registers.\n 2311| NaN-boxing is not supported in these extensions, and so operands narrower" + } + ] + }, + { + "parameter_name": "PHYS_ADDR_WIDTH", + "classification": "NORM_DIRECT", + "value_type": "conditional", + "num_candidates": 10, + "best_score": 3, + "candidates": [ + { + "score": 3, + "reasons": [ + "Name segment 'ADDR'", + "CSR field name 'ADDR'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1027, + "line_text": "<>.", + "context": " 1025| Sv39, Sv48, and Sv57 paged virtual-memory schemes. All of these paged\n 1026| virtual-memory schemes are described in\n>>> 1027| <>.\n 1028| \n 1029| The remaining MODE settings when HSXLEN=64 are reserved for future use" + }, + { + "score": 3, + "reasons": [ + "Name segment 'ADDR'", + "CSR field name 'ADDR'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1079, + "line_text": "As explained in <>, for the", + "context": " 1077| \n 1078| [[norm:hgatp-ppn_op]]\n>>> 1079| As explained in <>, for the\n 1080| paged virtual-memory schemes (Sv32x4, Sv39x4, Sv48x4, and Sv57x4), the\n 1081| root page table is 16 KiB and must be aligned to a 16-KiB boundary. In" + }, + { + "score": 3, + "reasons": [ + "Name segment 'ADDR'", + "CSR field name 'ADDR'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1901, + "line_text": "[[guest-addr-translation]]", + "context": " 1899| addresses and is in effect regardless of virtualization mode.\n 1900| \n>>> 1901| [[guest-addr-translation]]\n 1902| ==== Guest Physical Address Translation\n 1903| " + }, + { + "score": 3, + "reasons": [ + "Name segment 'ADDR'", + "CSR field name 'ADDR'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2784, + "line_text": ".Transformed atomic instruction (load-reserved, store-conditional, or AMO instruction). All fields are the same as the trapping instruction except bits 19:15, Addr. Offset.", + "context": " 2782| \n 2783| [[transformedatomicinst]]\n>>> 2784| .Transformed atomic instruction (load-reserved, store-conditional, or AMO instruction). All fields are the same as the trapping instruction except bits 19:15, Addr. Offset.\n 2785| include::images/wavedrom/transformedatomicinst.edn[]\n 2786| " + }, + { + "score": 3, + "reasons": [ + "Name segment 'ADDR'", + "CSR field name 'ADDR'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2790, + "line_text": ".Transformed virtual-machine load/store instruction (HLV, HLVX, HSV). All fields are the same as the trapping instruction except bits 19:15, Addr. Offset", + "context": " 2788| \n 2789| [[transformedvmaccessinst]]\n>>> 2790| .Transformed virtual-machine load/store instruction (HLV, HLVX, HSV). All fields are the same as the trapping instruction except bits 19:15, Addr. Offset\n 2791| include::images/wavedrom/transformedvmaccessinst.edn[]\n 2792| " + } + ] + }, + { + "parameter_name": "PMA_GRANULARITY", + "classification": "NORM_DIRECT", + "value_type": "range", + "num_candidates": 10, + "best_score": 3, + "candidates": [ + { + "score": 3, + "reasons": [ + "Name segment 'GRANULARITY'", + "Description keyword 'granularity'" + ], + "is_normative": false, + "in_note": false, + "file": "cmo.adoc", + "line_number": 754, + "line_text": "granularity and atomicity, including individual bytes.", + "context": " 752| Cache-block zero instructions store zeros to the set of bytes corresponding to a\n 753| cache block. An implementation may update the bytes in any order and with any\n>>> 754| granularity and atomicity, including individual bytes.\n 755| \n 756| [NOTE]" + }, + { + "score": 3, + "reasons": [ + "Name segment 'GRANULARITY'", + "Description keyword 'granularity'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 2901, + "line_text": "registers can be provided to specify these attributes at a granularity", + "context": " 2899| region, and can be hardwired into the PMA checker. Where the attributes\n 2900| are run-time configurable, platform-specific memory-mapped control\n>>> 2901| registers can be provided to specify these attributes at a granularity\n 2902| appropriate to each region on the platform (e.g., for an on-chip SRAM\n 2903| that can be flexibly divided between cacheable and uncacheable uses)." + }, + { + "score": 3, + "reasons": [ + "Name segment 'GRANULARITY'", + "Description keyword 'granularity'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 3308, + "line_text": "The granularity of PMP access control settings are platform-specific,", + "context": " 3306| checks described in <>.\n 3307| \n>>> 3308| The granularity of PMP access control settings are platform-specific,\n 3309| but the standard PMP encoding supports regions as small as four bytes.\n 3310| Certain regions’ privileges can be hardwired—for example, some regions" + }, + { + "score": 3, + "reasons": [ + "Name segment 'GRANULARITY'", + "Description keyword 'granularity'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 3428, + "line_text": "(TOR). These modes support four-byte granularity.", + "context": " 3426| regions (NAPOT), including the special case of naturally aligned\n 3427| four-byte regions (NA4); and the top boundary of an arbitrary range\n>>> 3428| (TOR). These modes support four-byte granularity.\n 3429| \n 3430| [[pmpcfg-a]]" + }, + { + "score": 3, + "reasons": [ + "Name segment 'GRANULARITY'", + "Description keyword 'granularity'" + ], + "is_normative": false, + "in_note": false, + "file": "mm-eplan.adoc", + "line_number": 423, + "line_text": "cache line granularity (and which therefore will see the four snippets", + "context": " 421| the same hart as the paired load-reserved and store-conditional\n 422| instructions. This way, a memory system that tracks memory accesses at\n>>> 423| cache line granularity (and which therefore will see the four snippets\n 424| of <> as identical) will not\n 425| be forced to fail a store-conditional instruction that happens to" + } + ] + }, + { + "parameter_name": "PMLEN", + "classification": "NORM_DIRECT", + "value_type": "value", + "num_candidates": 10, + "best_score": 7, + "candidates": [ + { + "score": 7, + "reasons": [ + "Name segment 'PMLEN'", + "Exact parameter name 'PMLEN'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 807, + "line_text": "|00|Pointer masking is disabled (PMLEN = 0)", + "context": " 805| |===\n 806| |Value|Description\n>>> 807| |00|Pointer masking is disabled (PMLEN = 0)\n 808| |01|Reserved\n 809| |10|Pointer masking is enabled with PMLEN = XLEN - 57 (PMLEN = 7 on RV64)" + }, + { + "score": 7, + "reasons": [ + "Name segment 'PMLEN'", + "Exact parameter name 'PMLEN'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 809, + "line_text": "|10|Pointer masking is enabled with PMLEN = XLEN - 57 (PMLEN = 7 on RV64)", + "context": " 807| |00|Pointer masking is disabled (PMLEN = 0)\n 808| |01|Reserved\n>>> 809| |10|Pointer masking is enabled with PMLEN = XLEN - 57 (PMLEN = 7 on RV64)\n 810| |11|Pointer masking is enabled with PMLEN = XLEN - 48 (PMLEN = 16 on RV64)\n 811| |===" + }, + { + "score": 7, + "reasons": [ + "Name segment 'PMLEN'", + "Exact parameter name 'PMLEN'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 810, + "line_text": "|11|Pointer masking is enabled with PMLEN = XLEN - 48 (PMLEN = 16 on RV64)", + "context": " 808| |01|Reserved\n 809| |10|Pointer masking is enabled with PMLEN = XLEN - 57 (PMLEN = 7 on RV64)\n>>> 810| |11|Pointer masking is enabled with PMLEN = XLEN - 48 (PMLEN = 16 on RV64)\n 811| |===\n 812| " + }, + { + "score": 7, + "reasons": [ + "Name segment 'PMLEN'", + "Exact parameter name 'PMLEN'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2149, + "line_text": "To support implementations where (XLEN-PMLEN) can be less than the GPA width", + "context": " 2147| ====\n 2148| \n>>> 2149| To support implementations where (XLEN-PMLEN) can be less than the GPA width\n 2150| supported by `hgatp.MODE`, hypervisors should execute an `HFENCE.GVMA` with\n 2151| _rs1_=`x0` if the `henvcfg.PMM` is changed from or to a value where (XLEN-PMLEN)" + }, + { + "score": 7, + "reasons": [ + "Name segment 'PMLEN'", + "Exact parameter name 'PMLEN'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2151, + "line_text": "_rs1_=`x0` if the `henvcfg.PMM` is changed from or to a value where (XLEN-PMLEN)", + "context": " 2149| To support implementations where (XLEN-PMLEN) can be less than the GPA width\n 2150| supported by `hgatp.MODE`, hypervisors should execute an `HFENCE.GVMA` with\n>>> 2151| _rs1_=`x0` if the `henvcfg.PMM` is changed from or to a value where (XLEN-PMLEN)\n 2152| is less than GPA width supported by the `hgatp` translation mode of that guest.\n 2153| Specifically, these cases are:" + } + ] + }, + { + "parameter_name": "PMP_GRANULARITY", + "classification": "NORM_DIRECT", + "value_type": "range", + "num_candidates": 10, + "best_score": 3, + "candidates": [ + { + "score": 3, + "reasons": [ + "Name segment 'GRANULARITY'", + "Description keyword 'granularity'" + ], + "is_normative": false, + "in_note": false, + "file": "cmo.adoc", + "line_number": 754, + "line_text": "granularity and atomicity, including individual bytes.", + "context": " 752| Cache-block zero instructions store zeros to the set of bytes corresponding to a\n 753| cache block. An implementation may update the bytes in any order and with any\n>>> 754| granularity and atomicity, including individual bytes.\n 755| \n 756| [NOTE]" + }, + { + "score": 3, + "reasons": [ + "Name segment 'GRANULARITY'", + "Description keyword 'granularity'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 2901, + "line_text": "registers can be provided to specify these attributes at a granularity", + "context": " 2899| region, and can be hardwired into the PMA checker. Where the attributes\n 2900| are run-time configurable, platform-specific memory-mapped control\n>>> 2901| registers can be provided to specify these attributes at a granularity\n 2902| appropriate to each region on the platform (e.g., for an on-chip SRAM\n 2903| that can be flexibly divided between cacheable and uncacheable uses)." + }, + { + "score": 3, + "reasons": [ + "Name segment 'GRANULARITY'", + "Description keyword 'granularity'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 3308, + "line_text": "The granularity of PMP access control settings are platform-specific,", + "context": " 3306| checks described in <>.\n 3307| \n>>> 3308| The granularity of PMP access control settings are platform-specific,\n 3309| but the standard PMP encoding supports regions as small as four bytes.\n 3310| Certain regions’ privileges can be hardwired—for example, some regions" + }, + { + "score": 3, + "reasons": [ + "CSR name 'pmpcfg14' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 3349, + "line_text": "even-numbered CSRs, `pmpcfg0`, `pmpcfg2`, …, `pmpcfg14`, hold the", + "context": " 3347| the configurations `pmp0cfg`–`pmp63cfg` for the 64 PMP entries, as shown\n 3348| in <>. For RV64, eight\n>>> 3349| even-numbered CSRs, `pmpcfg0`, `pmpcfg2`, …, `pmpcfg14`, hold the\n 3350| configurations for the 64 PMP entries, as shown in\n 3351| <>. For RV64, the odd-numbered" + }, + { + "score": 3, + "reasons": [ + "Name segment 'GRANULARITY'", + "Description keyword 'granularity'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 3428, + "line_text": "(TOR). These modes support four-byte granularity.", + "context": " 3426| regions (NAPOT), including the special case of naturally aligned\n 3427| four-byte regions (NA4); and the top boundary of an arbitrary range\n>>> 3428| (TOR). These modes support four-byte granularity.\n 3429| \n 3430| [[pmpcfg-a]]" + } + ] + }, + { + "parameter_name": "PRECISE_SYNCHRONOUS_EXCEPTIONS", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 4, + "candidates": [ + { + "score": 4, + "reasons": [ + "Name segment 'EXCEPTIONS'", + "Name segment 'SYNCHRONOUS'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1256, + "line_text": "[#norm:mtvec_mode_vectored_op]#When MODE=Vectored, all synchronous exceptions into machine mode cause", + "context": " 1254| [#norm:mtvec_mode_direct_op]#When MODE=Direct, all traps into\n 1255| machine mode cause the `pc` to be set to the address in the BASE field.#\n>>> 1256| [#norm:mtvec_mode_vectored_op]#When MODE=Vectored, all synchronous exceptions into machine mode cause\n 1257| the `pc` to be set to the address in the BASE field, whereas interrupts\n 1258| cause the `pc` to be set to the address in the BASE field plus four" + }, + { + "score": 4, + "reasons": [ + "Name segment 'EXCEPTIONS'", + "Name segment 'SYNCHRONOUS'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1801, + "line_text": "[#norm:mcause_exccode_pri1]#If an instruction may raise multiple synchronous exceptions, the", + "context": " 1799| ====\n 1800| \n>>> 1801| [#norm:mcause_exccode_pri1]#If an instruction may raise multiple synchronous exceptions, the\n 1802| decreasing priority order of <> indicates which\n 1803| exception is taken and reported in `mcause`.#" + }, + { + "score": 4, + "reasons": [ + "Name segment 'EXCEPTIONS'", + "Name segment 'SYNCHRONOUS'" + ], + "is_normative": true, + "in_note": false, + "file": "priv-cfi.adoc", + "line_number": 65, + "line_text": "* [#norm:zicflip_forward_trap_async_exception]#Synchronous exceptions with priority higher than that of a software-check", + "context": " 63| \n 64| * [#norm:zicflip_forward_trap_async_interrupt]#Asynchronous interrupts.#\n>>> 65| * [#norm:zicflip_forward_trap_async_exception]#Synchronous exceptions with priority higher than that of a software-check\n 66| exception with `__x__tval` set to \"landing pad fault (code=2)\" (See\n 67| <> of Privileged Specification).#" + }, + { + "score": 4, + "reasons": [ + "Optional/read-only pattern for boolean param", + "Name segment 'EXCEPTIONS'" + ], + "is_normative": true, + "in_note": false, + "file": "smctr.adoc", + "line_number": 250, + "line_text": "|WRPTR |[#norm:sctrstatus-wrptr]#WARL field that indicates the physical CTR buffer entry to be written next. It is incremented after new transfers are recorded (see <>), though there are exceptions when `__x__ctrctl`.RASEMU=1, see <>. For a given CTR depth (where depth = 2^(DEPTH+4)^), WRPTR wraps to 0 on an increment when the value matches depth-1, and to depth-1 on a decrement when the value is 0. Bits above those needed to represent depth-1 (e.g., bits 7:4 for a depth of 16) are read-only 0. On depth changes, WRPTR holds an unspecified but legal value.#", + "context": " 248| |===\n 249| |Field |Description\n>>> 250| |WRPTR |[#norm:sctrstatus-wrptr]#WARL field that indicates the physical CTR buffer entry to be written next. It is incremented after new transfers are recorded (see <>), though there are exceptions when `__x__ctrctl`.RASEMU=1, see <>. For a given CTR depth (where depth = 2^(DEPTH+4)^), WRPTR wraps to 0 on an increment when the value matches depth-1, and to depth-1 on a decrement when the value is 0. Bits above those needed to represent depth-1 (e.g., bits 7:4 for a depth of 16) are read-only 0. On depth changes, WRPTR holds an unspecified but legal value.#\n 251| |FROZEN |[#norm:sctrstatus-frozen_op]#Inhibit transfer recording.# See <>.\n 252| |===" + }, + { + "score": 3, + "reasons": [ + "Name segment 'EXCEPTIONS'" + ], + "is_normative": true, + "in_note": false, + "file": "cmo.adoc", + "line_number": 391, + "line_text": "exceptions and shall not access any caches or memory.# [#norm:cbp_unperm_translate]#During address", + "context": " 389| permitted to access the corresponding physical addresses.# [#norm:cbp_unperm_noexcep]#If access to the cache\n 390| block is not permitted, a cache-block prefetch instruction does not raise any\n>>> 391| exceptions and shall not access any caches or memory.# [#norm:cbp_unperm_translate]#During address\n 392| translation, the instruction does _not_ check the accessed and dirty bits and\n 393| neither raises an exception nor sets the bits.#" + } + ] + }, + { + "parameter_name": "RCID_WIDTH", + "classification": "NORM_CSR_WARL", + "value_type": "range", + "num_candidates": 10, + "best_score": 8, + "candidates": [ + { + "score": 8, + "reasons": [ + "Description keyword 'RCID'", + "CSR name 'srmcfg' in backticks", + "Name segment 'RCID'", + "CSR field name 'RCID'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 2586, + "line_text": "The `RCID` and `MCID` configured in the `srmcfg` CSR apply to all privilege", + "context": " 2584| ....\n 2585| \n>>> 2586| The `RCID` and `MCID` configured in the `srmcfg` CSR apply to all privilege\n 2587| modes of software execution on that hart by default, but this behavior may be\n 2588| overridden by future extensions." + }, + { + "score": 7, + "reasons": [ + "Description keyword 'RCID'", + "Name segment 'RCID'", + "Description keyword 'ID'", + "CSR field name 'RCID'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 2531, + "line_text": "Control ID (`RCID`) and a Monitoring Counter ID (`MCID`). These identifiers", + "context": " 2529| To facilitate this, the QoS Identifiers extension (Ssqosid) introduces the\n 2530| `srmcfg` register, which configures a hart with two identifiers: a Resource\n>>> 2531| Control ID (`RCID`) and a Monitoring Counter ID (`MCID`). These identifiers\n 2532| accompany each request issued by the hart to shared resource controllers.\n 2533| " + }, + { + "score": 7, + "reasons": [ + "Description keyword 'RCID'", + "Name segment 'RCID'", + "Description keyword 'ID'", + "CSR field name 'RCID'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 2551, + "line_text": "Resource Control ID (`RCID`) and a Monitoring Counter ID (`MCID`). Both `RCID`", + "context": " 2549| \n 2550| The `srmcfg` register is an SXLEN-bit read/write register used to configure a\n>>> 2551| Resource Control ID (`RCID`) and a Monitoring Counter ID (`MCID`). Both `RCID`\n 2552| and `MCID` are WARL fields. The register is formatted as shown in <>\n 2553| when SXLEN=64 and <> when SXLEN=32." + }, + { + "score": 5, + "reasons": [ + "Description keyword 'RCID'", + "Name segment 'RCID'", + "CSR field name 'RCID'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 2535, + "line_text": "originating supervisor domain, can accompany `RCID` and `MCID`. Resource", + "context": " 2533| \n 2534| Additional metadata, like the nature of the memory access and the ID of the\n>>> 2535| originating supervisor domain, can accompany `RCID` and `MCID`. Resource\n 2536| controllers may use this metadata for differentiated service such as a different\n 2537| capacity allocation for code storage vs. data storage. Resource controllers can" + }, + { + "score": 5, + "reasons": [ + "Description keyword 'RCID'", + "Name segment 'RCID'", + "CSR field name 'RCID'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 2543, + "line_text": "resource usage limits and monitoring resource consumption. The `RCID` controls", + "context": " 2541| These identifiers are crucial for the RISC-V Capacity and Bandwidth Controller\n 2542| QoS Register Interface (CBQRI) specification, which provides methods for setting\n>>> 2543| resource usage limits and monitoring resource consumption. The `RCID` controls\n 2544| resource allocations, while the `MCID` is used for tracking resource usage.\n 2545| " + } + ] + }, + { + "parameter_name": "REPORT_CAUSE_IN_MTVAL_ON_LANDING_PAD_SOFTWARE_CHECK", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 10, + "candidates": [ + { + "score": 10, + "reasons": [ + "Optional/read-only pattern for boolean param", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 25, + "line_text": "registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and", + "context": " 23| The hypervisor extension depends on an \"I\" base integer ISA with 32\n 24| `x` registers (RV32I or RV64I), not RV32E or RV64E, which have only 16 `x`\n>>> 25| registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and\n 26| [#norm:H_vm_supported]#standard\n 27| page-based address translation must be supported, either Sv32 for RV32," + }, + { + "score": 9, + "reasons": [ + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1310, + "line_text": "[#norm:trap_del_S-mode_no_M-mode]#The `mcause`, `mepc`, and `mtval` registers and the MPP and MPIE fields of", + "context": " 1308| field of `mstatus` is written with the value of the SIE field at the\n 1309| time of the trap; and the SIE field of `mstatus` is cleared.#\n>>> 1310| [#norm:trap_del_S-mode_no_M-mode]#The `mcause`, `mepc`, and `mtval` registers and the MPP and MPIE fields of\n 1311| `mstatus` are not written.#\n 1312| " + }, + { + "score": 9, + "reasons": [ + "Name segment 'SOFTWARE'", + "Name segment 'CHECK'", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 2117, + "line_text": "On a trap caused by a software-check exception, the `mtval` register holds", + "context": " 2115| ====\n 2116| \n>>> 2117| On a trap caused by a software-check exception, the `mtval` register holds\n 2118| the cause for the exception. The following encodings are defined:\n 2119| " + }, + { + "score": 8, + "reasons": [ + "Name segment 'SOFTWARE'", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1814, + "line_text": "information, alongside `mtval`, to assist software in handling the trap.", + "context": " 1812| shown in <>. When a trap is taken into\n 1813| M-mode, `mtval2` is written with additional exception-specific\n>>> 1814| information, alongside `mtval`, to assist software in handling the trap.\n 1815| \n 1816| [[mtval2reg]]" + }, + { + "score": 8, + "reasons": [ + "Name segment 'SOFTWARE'", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 2034, + "line_text": "information to assist software in handling the trap. Otherwise, `mtval`", + "context": " 2032| shown in <>. When a trap is taken into\n 2033| M-mode, `mtval` is either set to zero or written with exception-specific\n>>> 2034| information to assist software in handling the trap. Otherwise, `mtval`\n 2035| is never written by the implementation, though it may be explicitly\n 2036| written by software. The hardware platform will specify which exceptions" + } + ] + }, + { + "parameter_name": "REPORT_CAUSE_IN_MTVAL_ON_SHADOW_STACK_SOFTWARE_CHECK", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 10, + "candidates": [ + { + "score": 10, + "reasons": [ + "Optional/read-only pattern for boolean param", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 25, + "line_text": "registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and", + "context": " 23| The hypervisor extension depends on an \"I\" base integer ISA with 32\n 24| `x` registers (RV32I or RV64I), not RV32E or RV64E, which have only 16 `x`\n>>> 25| registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and\n 26| [#norm:H_vm_supported]#standard\n 27| page-based address translation must be supported, either Sv32 for RV32," + }, + { + "score": 9, + "reasons": [ + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1310, + "line_text": "[#norm:trap_del_S-mode_no_M-mode]#The `mcause`, `mepc`, and `mtval` registers and the MPP and MPIE fields of", + "context": " 1308| field of `mstatus` is written with the value of the SIE field at the\n 1309| time of the trap; and the SIE field of `mstatus` is cleared.#\n>>> 1310| [#norm:trap_del_S-mode_no_M-mode]#The `mcause`, `mepc`, and `mtval` registers and the MPP and MPIE fields of\n 1311| `mstatus` are not written.#\n 1312| " + }, + { + "score": 9, + "reasons": [ + "Name segment 'SOFTWARE'", + "Name segment 'CHECK'", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 2117, + "line_text": "On a trap caused by a software-check exception, the `mtval` register holds", + "context": " 2115| ====\n 2116| \n>>> 2117| On a trap caused by a software-check exception, the `mtval` register holds\n 2118| the cause for the exception. The following encodings are defined:\n 2119| " + }, + { + "score": 8, + "reasons": [ + "Name segment 'SOFTWARE'", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1814, + "line_text": "information, alongside `mtval`, to assist software in handling the trap.", + "context": " 1812| shown in <>. When a trap is taken into\n 1813| M-mode, `mtval2` is written with additional exception-specific\n>>> 1814| information, alongside `mtval`, to assist software in handling the trap.\n 1815| \n 1816| [[mtval2reg]]" + }, + { + "score": 8, + "reasons": [ + "Name segment 'SOFTWARE'", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 2034, + "line_text": "information to assist software in handling the trap. Otherwise, `mtval`", + "context": " 2032| shown in <>. When a trap is taken into\n 2033| M-mode, `mtval` is either set to zero or written with exception-specific\n>>> 2034| information to assist software in handling the trap. Otherwise, `mtval`\n 2035| is never written by the implementation, though it may be explicitly\n 2036| written by software. The hardware platform will specify which exceptions" + } + ] + }, + { + "parameter_name": "REPORT_CAUSE_IN_STVAL_ON_LANDING_PAD_SOFTWARE_CHECK", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 9, + "candidates": [ + { + "score": 9, + "reasons": [ + "Name segment 'STVAL'", + "Description keyword 'stval'" + ], + "is_normative": true, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 707, + "line_text": "[[norm:stval]]", + "context": " 705| ==== Supervisor Trap Value (`stval`) Register\n 706| \n>>> 707| [[norm:stval]]\n 708| The `stval` CSR is an SXLEN-bit read-write register formatted as\n 709| shown in <>. When a trap is taken into" + }, + { + "score": 9, + "reasons": [ + "Name segment 'STVAL'", + "Name segment 'SOFTWARE'", + "Description keyword 'stval'", + "Name segment 'CHECK'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 763, + "line_text": "On a trap caused by a software-check exception, the `stval` register holds the", + "context": " 761| \n 762| [[norm:stval_exception_info]]\n>>> 763| On a trap caused by a software-check exception, the `stval` register holds the\n 764| cause for the exception. The following encodings are defined:\n 765| " + }, + { + "score": 8, + "reasons": [ + "Name segment 'STVAL'", + "Name segment 'SOFTWARE'", + "Description keyword 'stval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 910, + "line_text": "information, alongside `stval`, to assist software in handling the trap.", + "context": " 908| shown in <>. When a trap is taken into\n 909| HS-mode, `htval` is written with additional exception-specific\n>>> 910| information, alongside `stval`, to assist software in handling the trap.\n 911| \n 912| [[htvalreg]]" + }, + { + "score": 8, + "reasons": [ + "Name segment 'STVAL'", + "Name segment 'SOFTWARE'", + "Description keyword 'stval'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 711, + "line_text": "software in handling the trap. Otherwise, `stval` is never written by", + "context": " 709| shown in <>. When a trap is taken into\n 710| S-mode, `stval` is written with exception-specific information to assist\n>>> 711| software in handling the trap. Otherwise, `stval` is never written by\n 712| the implementation, though it may be explicitly written by software. The\n 713| hardware platform will specify which exceptions must set `stval`" + }, + { + "score": 8, + "reasons": [ + "Optional/read-only pattern for boolean param", + "Name segment 'STVAL'", + "Description keyword 'stval'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 748, + "line_text": "The `stval` register can optionally also be used to return the faulting", + "context": " 746| \n 747| [[norm:stval_op_illegal_instr]]\n>>> 748| The `stval` register can optionally also be used to return the faulting\n 749| instruction bits on an illegal-instruction exception (`sepc` points to\n 750| the faulting instruction in memory). If `stval` is written with a" + } + ] + }, + { + "parameter_name": "REPORT_CAUSE_IN_STVAL_ON_SHADOW_STACK_SOFTWARE_CHECK", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 9, + "candidates": [ + { + "score": 9, + "reasons": [ + "Name segment 'STVAL'", + "Description keyword 'stval'" + ], + "is_normative": true, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 707, + "line_text": "[[norm:stval]]", + "context": " 705| ==== Supervisor Trap Value (`stval`) Register\n 706| \n>>> 707| [[norm:stval]]\n 708| The `stval` CSR is an SXLEN-bit read-write register formatted as\n 709| shown in <>. When a trap is taken into" + }, + { + "score": 9, + "reasons": [ + "Name segment 'STVAL'", + "Name segment 'SOFTWARE'", + "Description keyword 'stval'", + "Name segment 'CHECK'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 763, + "line_text": "On a trap caused by a software-check exception, the `stval` register holds the", + "context": " 761| \n 762| [[norm:stval_exception_info]]\n>>> 763| On a trap caused by a software-check exception, the `stval` register holds the\n 764| cause for the exception. The following encodings are defined:\n 765| " + }, + { + "score": 8, + "reasons": [ + "Name segment 'STVAL'", + "Name segment 'SOFTWARE'", + "Description keyword 'stval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 910, + "line_text": "information, alongside `stval`, to assist software in handling the trap.", + "context": " 908| shown in <>. When a trap is taken into\n 909| HS-mode, `htval` is written with additional exception-specific\n>>> 910| information, alongside `stval`, to assist software in handling the trap.\n 911| \n 912| [[htvalreg]]" + }, + { + "score": 8, + "reasons": [ + "Name segment 'STVAL'", + "Name segment 'SOFTWARE'", + "Description keyword 'stval'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 711, + "line_text": "software in handling the trap. Otherwise, `stval` is never written by", + "context": " 709| shown in <>. When a trap is taken into\n 710| S-mode, `stval` is written with exception-specific information to assist\n>>> 711| software in handling the trap. Otherwise, `stval` is never written by\n 712| the implementation, though it may be explicitly written by software. The\n 713| hardware platform will specify which exceptions must set `stval`" + }, + { + "score": 8, + "reasons": [ + "Optional/read-only pattern for boolean param", + "Name segment 'STVAL'", + "Description keyword 'stval'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 748, + "line_text": "The `stval` register can optionally also be used to return the faulting", + "context": " 746| \n 747| [[norm:stval_op_illegal_instr]]\n>>> 748| The `stval` register can optionally also be used to return the faulting\n 749| instruction bits on an illegal-instruction exception (`sepc` points to\n 750| the faulting instruction in memory). If `stval` is written with a" + } + ] + }, + { + "parameter_name": "REPORT_CAUSE_IN_VSTVAL_ON_LANDING_PAD_SOFTWARE_CHECK", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 7, + "candidates": [ + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1364, + "line_text": "==== Virtual Supervisor Trap Value (`vstval`) Register", + "context": " 1362| include::images/bytefield/vscausereg.edn[]\n 1363| \n>>> 1364| ==== Virtual Supervisor Trap Value (`vstval`) Register\n 1365| \n 1366| [[norm:vstval_sz_acc_op]]" + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1367, + "line_text": "The `vstval` register is a VSXLEN-bit read/write register that is", + "context": " 1365| \n 1366| [[norm:vstval_sz_acc_op]]\n>>> 1367| The `vstval` register is a VSXLEN-bit read/write register that is\n 1368| VS-mode’s version of supervisor register `stval`, formatted as shown in\n 1369| <>. When V=1, `vstval` substitutes for" + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1369, + "line_text": "<>. When V=1, `vstval` substitutes for", + "context": " 1367| The `vstval` register is a VSXLEN-bit read/write register that is\n 1368| VS-mode’s version of supervisor register `stval`, formatted as shown in\n>>> 1369| <>. When V=1, `vstval` substitutes for\n 1370| the usual `stval`, so instructions that normally read or modify `stval`\n 1371| actually access `vstval` instead. When V=0, `vstval` does not directly" + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1371, + "line_text": "actually access `vstval` instead. When V=0, `vstval` does not directly", + "context": " 1369| <>. When V=1, `vstval` substitutes for\n 1370| the usual `stval`, so instructions that normally read or modify `stval`\n>>> 1371| actually access `vstval` instead. When V=0, `vstval` does not directly\n 1372| affect the behavior of the machine.\n 1373| " + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1375, + "line_text": "`vstval` is a *WARL* register that must be able to hold the same set of values", + "context": " 1373| \n 1374| [[norm:vstval_warl]]\n>>> 1375| `vstval` is a *WARL* register that must be able to hold the same set of values\n 1376| that `stval` can hold.\n 1377| " + } + ] + }, + { + "parameter_name": "REPORT_CAUSE_IN_VSTVAL_ON_SHADOW_STACK_SOFTWARE_CHECK", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 7, + "candidates": [ + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1364, + "line_text": "==== Virtual Supervisor Trap Value (`vstval`) Register", + "context": " 1362| include::images/bytefield/vscausereg.edn[]\n 1363| \n>>> 1364| ==== Virtual Supervisor Trap Value (`vstval`) Register\n 1365| \n 1366| [[norm:vstval_sz_acc_op]]" + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1367, + "line_text": "The `vstval` register is a VSXLEN-bit read/write register that is", + "context": " 1365| \n 1366| [[norm:vstval_sz_acc_op]]\n>>> 1367| The `vstval` register is a VSXLEN-bit read/write register that is\n 1368| VS-mode’s version of supervisor register `stval`, formatted as shown in\n 1369| <>. When V=1, `vstval` substitutes for" + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1369, + "line_text": "<>. When V=1, `vstval` substitutes for", + "context": " 1367| The `vstval` register is a VSXLEN-bit read/write register that is\n 1368| VS-mode’s version of supervisor register `stval`, formatted as shown in\n>>> 1369| <>. When V=1, `vstval` substitutes for\n 1370| the usual `stval`, so instructions that normally read or modify `stval`\n 1371| actually access `vstval` instead. When V=0, `vstval` does not directly" + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1371, + "line_text": "actually access `vstval` instead. When V=0, `vstval` does not directly", + "context": " 1369| <>. When V=1, `vstval` substitutes for\n 1370| the usual `stval`, so instructions that normally read or modify `stval`\n>>> 1371| actually access `vstval` instead. When V=0, `vstval` does not directly\n 1372| affect the behavior of the machine.\n 1373| " + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1375, + "line_text": "`vstval` is a *WARL* register that must be able to hold the same set of values", + "context": " 1373| \n 1374| [[norm:vstval_warl]]\n>>> 1375| `vstval` is a *WARL* register that must be able to hold the same set of values\n 1376| that `stval` can hold.\n 1377| " + } + ] + }, + { + "parameter_name": "REPORT_ENCODING_IN_MTVAL_ON_ILLEGAL_INSTRUCTION", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 11, + "candidates": [ + { + "score": 11, + "reasons": [ + "Description keyword 'mtval'", + "Name segment 'ILLEGAL'", + "Description keyword 'instruction'", + "Name segment 'MTVAL'", + "Name segment 'INSTRUCTION'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 2082, + "line_text": "nonzero value when an illegal-instruction exception occurs, then `mtval`", + "context": " 2080| instruction bits on an illegal-instruction exception (`mepc` points to\n 2081| the faulting instruction in memory). If `mtval` is written with a\n>>> 2082| nonzero value when an illegal-instruction exception occurs, then `mtval`\n 2083| will contain the shortest of:\n 2084| " + }, + { + "score": 11, + "reasons": [ + "Description keyword 'mtval'", + "Name segment 'ILLEGAL'", + "Description keyword 'instruction'", + "Name segment 'MTVAL'", + "Name segment 'INSTRUCTION'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 2091, + "line_text": "The value loaded into `mtval` on an illegal-instruction exception is", + "context": " 2089| * the first MXLEN bits of the faulting instruction\n 2090| \n>>> 2091| The value loaded into `mtval` on an illegal-instruction exception is\n 2092| right-justified and all unused upper bits are cleared to zero.\n 2093| " + }, + { + "score": 10, + "reasons": [ + "Optional/read-only pattern for boolean param", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 25, + "line_text": "registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and", + "context": " 23| The hypervisor extension depends on an \"I\" base integer ISA with 32\n 24| `x` registers (RV32I or RV64I), not RV32E or RV64E, which have only 16 `x`\n>>> 25| registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and\n 26| [#norm:H_vm_supported]#standard\n 27| page-based address translation must be supported, either Sv32 for RV32," + }, + { + "score": 10, + "reasons": [ + "Description keyword 'instruction'", + "Name segment 'INSTRUCTION'", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1840, + "line_text": "the instruction as indicated by the virtual address in `mtval`.", + "context": " 1838| For instruction guest-page faults on systems with variable-length\n 1839| instructions, a nonzero `mtval2` corresponds to the faulting portion of\n>>> 1840| the instruction as indicated by the virtual address in `mtval`.\n 1841| \n 1842| [[norm:mtval2_val]]" + }, + { + "score": 10, + "reasons": [ + "Description keyword 'instruction'", + "Name segment 'INSTRUCTION'", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2405, + "line_text": "On a virtual-instruction trap, `mtval` or `stval` is written the same as", + "context": " 2403| \n 2404| [[norm:H_virtinst_xtval]]\n>>> 2405| On a virtual-instruction trap, `mtval` or `stval` is written the same as\n 2406| for an illegal-instruction trap.\n 2407| " + } + ] + }, + { + "parameter_name": "REPORT_ENCODING_IN_STVAL_ON_ILLEGAL_INSTRUCTION", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 11, + "candidates": [ + { + "score": 11, + "reasons": [ + "Name segment 'STVAL'", + "Name segment 'ILLEGAL'", + "Description keyword 'instruction'", + "Name segment 'INSTRUCTION'", + "Description keyword 'stval'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 751, + "line_text": "nonzero value when an illegal-instruction exception occurs, then `stval`", + "context": " 749| instruction bits on an illegal-instruction exception (`sepc` points to\n 750| the faulting instruction in memory). If `stval` is written with a\n>>> 751| nonzero value when an illegal-instruction exception occurs, then `stval`\n 752| will contain the shortest of:\n 753| " + }, + { + "score": 11, + "reasons": [ + "Name segment 'STVAL'", + "Name segment 'ILLEGAL'", + "Description keyword 'instruction'", + "Name segment 'INSTRUCTION'", + "Description keyword 'stval'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 759, + "line_text": "The value loaded into `stval` on an illegal-instruction exception is", + "context": " 757| \n 758| [[norm:stval_op_illegal_instr_format]]\n>>> 759| The value loaded into `stval` on an illegal-instruction exception is\n 760| right-justified and all unused upper bits are cleared to zero.\n 761| " + }, + { + "score": 10, + "reasons": [ + "Name segment 'STVAL'", + "Name segment 'INSTRUCTION'", + "Description keyword 'stval'", + "Description keyword 'instruction'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 936, + "line_text": "the instruction as indicated by the virtual address in `stval`.", + "context": " 934| For instruction guest-page faults on systems with variable-length\n 935| instructions, a nonzero `htval` corresponds to the faulting portion of\n>>> 936| the instruction as indicated by the virtual address in `stval`.\n 937| \n 938| [NOTE]" + }, + { + "score": 10, + "reasons": [ + "Name segment 'STVAL'", + "Name segment 'INSTRUCTION'", + "Description keyword 'stval'", + "Description keyword 'instruction'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2405, + "line_text": "On a virtual-instruction trap, `mtval` or `stval` is written the same as", + "context": " 2403| \n 2404| [[norm:H_virtinst_xtval]]\n>>> 2405| On a virtual-instruction trap, `mtval` or `stval` is written the same as\n 2406| for an illegal-instruction trap.\n 2407| " + }, + { + "score": 10, + "reasons": [ + "Name segment 'STVAL'", + "Name segment 'INSTRUCTION'", + "Description keyword 'stval'", + "Description keyword 'instruction'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 1305, + "line_text": "address of the instruction that took the trap; the `stval` register is", + "context": " 1303| [#norm:trap_del_S-mode_op]#the `scause` register is written\n 1304| with the trap cause; the `sepc` register is written with the virtual\n>>> 1305| address of the instruction that took the trap; the `stval` register is\n 1306| written with an exception-specific datum; the SPP field of `mstatus` is\n 1307| written with the active privilege mode at the time of the trap; the SPIE" + } + ] + }, + { + "parameter_name": "REPORT_ENCODING_IN_VSTVAL_ON_ILLEGAL_INSTRUCTION", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 7, + "candidates": [ + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1364, + "line_text": "==== Virtual Supervisor Trap Value (`vstval`) Register", + "context": " 1362| include::images/bytefield/vscausereg.edn[]\n 1363| \n>>> 1364| ==== Virtual Supervisor Trap Value (`vstval`) Register\n 1365| \n 1366| [[norm:vstval_sz_acc_op]]" + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1367, + "line_text": "The `vstval` register is a VSXLEN-bit read/write register that is", + "context": " 1365| \n 1366| [[norm:vstval_sz_acc_op]]\n>>> 1367| The `vstval` register is a VSXLEN-bit read/write register that is\n 1368| VS-mode’s version of supervisor register `stval`, formatted as shown in\n 1369| <>. When V=1, `vstval` substitutes for" + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1369, + "line_text": "<>. When V=1, `vstval` substitutes for", + "context": " 1367| The `vstval` register is a VSXLEN-bit read/write register that is\n 1368| VS-mode’s version of supervisor register `stval`, formatted as shown in\n>>> 1369| <>. When V=1, `vstval` substitutes for\n 1370| the usual `stval`, so instructions that normally read or modify `stval`\n 1371| actually access `vstval` instead. When V=0, `vstval` does not directly" + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1371, + "line_text": "actually access `vstval` instead. When V=0, `vstval` does not directly", + "context": " 1369| <>. When V=1, `vstval` substitutes for\n 1370| the usual `stval`, so instructions that normally read or modify `stval`\n>>> 1371| actually access `vstval` instead. When V=0, `vstval` does not directly\n 1372| affect the behavior of the machine.\n 1373| " + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1375, + "line_text": "`vstval` is a *WARL* register that must be able to hold the same set of values", + "context": " 1373| \n 1374| [[norm:vstval_warl]]\n>>> 1375| `vstval` is a *WARL* register that must be able to hold the same set of values\n 1376| that `stval` can hold.\n 1377| " + } + ] + }, + { + "parameter_name": "REPORT_ENCODING_IN_VSTVAL_ON_VIRTUAL_INSTRUCTION", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 8, + "candidates": [ + { + "score": 8, + "reasons": [ + "Name segment 'VSTVAL'", + "Name segment 'VIRTUAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1364, + "line_text": "==== Virtual Supervisor Trap Value (`vstval`) Register", + "context": " 1362| include::images/bytefield/vscausereg.edn[]\n 1363| \n>>> 1364| ==== Virtual Supervisor Trap Value (`vstval`) Register\n 1365| \n 1366| [[norm:vstval_sz_acc_op]]" + }, + { + "score": 8, + "reasons": [ + "Name segment 'VSTVAL'", + "Name segment 'VIRTUAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1379, + "line_text": ".Virtual supervisor trap value register (`vstval`).", + "context": " 1377| \n 1378| [[vstvalreg]]\n>>> 1379| .Virtual supervisor trap value register (`vstval`).\n 1380| include::images/bytefield/vstvalreg.edn[]\n 1381| " + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1367, + "line_text": "The `vstval` register is a VSXLEN-bit read/write register that is", + "context": " 1365| \n 1366| [[norm:vstval_sz_acc_op]]\n>>> 1367| The `vstval` register is a VSXLEN-bit read/write register that is\n 1368| VS-mode’s version of supervisor register `stval`, formatted as shown in\n 1369| <>. When V=1, `vstval` substitutes for" + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1369, + "line_text": "<>. When V=1, `vstval` substitutes for", + "context": " 1367| The `vstval` register is a VSXLEN-bit read/write register that is\n 1368| VS-mode’s version of supervisor register `stval`, formatted as shown in\n>>> 1369| <>. When V=1, `vstval` substitutes for\n 1370| the usual `stval`, so instructions that normally read or modify `stval`\n 1371| actually access `vstval` instead. When V=0, `vstval` does not directly" + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1371, + "line_text": "actually access `vstval` instead. When V=0, `vstval` does not directly", + "context": " 1369| <>. When V=1, `vstval` substitutes for\n 1370| the usual `stval`, so instructions that normally read or modify `stval`\n>>> 1371| actually access `vstval` instead. When V=0, `vstval` does not directly\n 1372| affect the behavior of the machine.\n 1373| " + } + ] + }, + { + "parameter_name": "REPORT_GPA_IN_HTVAL_ON_GUEST_PAGE_FAULT", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 9, + "candidates": [ + { + "score": 9, + "reasons": [ + "Name segment 'HTVAL'", + "Name segment 'PAGE'", + "Description keyword 'htval'", + "Name segment 'GUEST'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 917, + "line_text": "When a guest-page-fault trap is taken into HS-mode, `htval` is written", + "context": " 915| \n 916| [[norm:htval_trapval_param]]\n>>> 917| When a guest-page-fault trap is taken into HS-mode, `htval` is written\n 918| with either zero or the guest physical address that faulted, shifted\n 919| right by 2 bits. For other traps, `htval` is set to zero, but a future" + }, + { + "score": 8, + "reasons": [ + "Name segment 'HTVAL'", + "Description keyword 'htval'", + "Name segment 'GUEST'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 932, + "line_text": "a nonzero guest physical address in `htval` corresponds to the faulting", + "context": " 930| \n 931| Otherwise, for misaligned loads and stores that cause guest-page faults,\n>>> 932| a nonzero guest physical address in `htval` corresponds to the faulting\n 933| portion of the access as indicated by the virtual address in `stval`.\n 934| For instruction guest-page faults on systems with variable-length" + }, + { + "score": 8, + "reasons": [ + "Name segment 'HTVAL'", + "Description keyword 'htval'", + "Name segment 'GUEST'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2047, + "line_text": "faulting guest virtual address as usual, and `mtval2` or `htval` is", + "context": " 2045| control of CSR `medeleg`, but cannot be delegated to other privilege\n 2046| modes. On a guest-page fault, CSR `mtval` or `stval` is written with the\n>>> 2047| faulting guest virtual address as usual, and `mtval2` or `htval` is\n 2048| written either with zero or with the faulting guest physical address,\n 2049| shifted right by 2 bits. CSR `mtinst` or `htinst` may also be written" + }, + { + "score": 7, + "reasons": [ + "Name segment 'HTVAL'", + "Description keyword 'htval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 120, + "line_text": "`htimedeltah`, `htval`, `htinst`, and `hgatp`.#", + "context": " 118| VS-mode guest: `hstatus`, `hedeleg`, `hideleg`, `hvip`, `hip`, `hie`,\n 119| `hgeip`, `hgeie`, `henvcfg`, `henvcfgh`, `hcounteren`, `htimedelta`,\n>>> 120| `htimedeltah`, `htval`, `htinst`, and `hgatp`.#\n 121| \n 122| Furthermore, several _virtual supervisor_ CSRs (VS CSRs) are replicas of" + }, + { + "score": 7, + "reasons": [ + "Name segment 'HTVAL'", + "Description keyword 'htval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 904, + "line_text": "==== Hypervisor Trap Value (`htval`) Register", + "context": " 902| must be implemented.\n 903| \n>>> 904| ==== Hypervisor Trap Value (`htval`) Register\n 905| \n 906| [[norm:htval_sz_acc_op]]" + } + ] + }, + { + "parameter_name": "REPORT_GPA_IN_TVAL_ON_INSTRUCTION_GUEST_PAGE_FAULT", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 8, + "candidates": [ + { + "score": 8, + "reasons": [ + "CSR field name 'VALUE'", + "CSR name 'mtval2' in backticks", + "CSR name 'htval' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2832, + "line_text": "`mtval2` or `htval`. If both conditions are met, the value written to", + "context": " 2830| implicit memory access for VS-stage address translation, and (b) a\n 2831| nonzero value (the faulting guest physical address) is written to\n>>> 2832| `mtval2` or `htval`. If both conditions are met, the value written to\n 2833| `mtinst` or `htinst` must be taken from\n 2834| <>; zero is not allowed." + }, + { + "score": 7, + "reasons": [ + "Name segment 'INSTRUCTION'", + "CSR field name 'VALUE'", + "Description keyword 'instruction'" + ], + "is_normative": true, + "in_note": false, + "file": "c-st-ext.adoc", + "line_number": 310, + "line_text": "[#norm:c-ldsp_op]#C.LDSP is an RV64C-only instruction that loads a 64-bit value", + "context": " 308| valid only when _rd_≠`x0`; the code points with _rd_=`x0` are reserved.#\n 309| \n>>> 310| [#norm:c-ldsp_op]#C.LDSP is an RV64C-only instruction that loads a 64-bit value\n 311| from memory into register _rd_. It computes its effective address by\n 312| adding the zero-extended offset, scaled by 8, to the stack pointer," + }, + { + "score": 7, + "reasons": [ + "Name segment 'INSTRUCTION'", + "CSR field name 'VALUE'", + "Description keyword 'instruction'" + ], + "is_normative": true, + "in_note": false, + "file": "c-st-ext.adoc", + "line_number": 340, + "line_text": "[#norm:c-sdsp_op]#C.SDSP is an RV64C-only instruction that stores a 64-bit value in", + "context": " 338| the stack pointer, `x2`. It expands to `sw rs2, offset(x2)`.#\n 339| \n>>> 340| [#norm:c-sdsp_op]#C.SDSP is an RV64C-only instruction that stores a 64-bit value in\n 341| register _rs2_ to memory. It computes an effective address by adding the\n 342| _zero_-extended offset, scaled by 8, to the stack pointer, `x2`. It" + }, + { + "score": 7, + "reasons": [ + "Name segment 'INSTRUCTION'", + "CSR field name 'VALUE'", + "Description keyword 'instruction'" + ], + "is_normative": true, + "in_note": false, + "file": "c-st-ext.adoc", + "line_number": 411, + "line_text": "[#norm:c-ld_op]#C.LD is an RV64C-only instruction that loads a 64-bit value from", + "context": " 409| `_rs1′_`. It expands to `lw rd′, offset(rs1′)`.#\n 410| \n>>> 411| [#norm:c-ld_op]#C.LD is an RV64C-only instruction that loads a 64-bit value from\n 412| memory into register `_rd′_`. It computes an effective\n 413| address by adding the _zero_-extended offset, scaled by 8, to the base" + }, + { + "score": 7, + "reasons": [ + "Name segment 'INSTRUCTION'", + "CSR field name 'VALUE'", + "Description keyword 'instruction'" + ], + "is_normative": true, + "in_note": false, + "file": "c-st-ext.adoc", + "line_number": 443, + "line_text": "[#norm:c-sd_op]#C.SD is an RV64C-only instruction that stores a 64-bit value in", + "context": " 441| expands to `sw rs2′, offset(rs1′)`.#\n 442| \n>>> 443| [#norm:c-sd_op]#C.SD is an RV64C-only instruction that stores a 64-bit value in\n 444| register `_rs2′_` to memory. It computes an effective\n 445| address by adding the _zero_-extended offset, scaled by 8, to the base" + } + ] + }, + { + "parameter_name": "REPORT_GPA_IN_TVAL_ON_INTERMEDIATE_GUEST_PAGE_FAULT", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 8, + "candidates": [ + { + "score": 8, + "reasons": [ + "CSR field name 'VALUE'", + "CSR name 'mtval2' in backticks", + "CSR name 'htval' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2832, + "line_text": "`mtval2` or `htval`. If both conditions are met, the value written to", + "context": " 2830| implicit memory access for VS-stage address translation, and (b) a\n 2831| nonzero value (the faulting guest physical address) is written to\n>>> 2832| `mtval2` or `htval`. If both conditions are met, the value written to\n 2833| `mtinst` or `htinst` must be taken from\n 2834| <>; zero is not allowed." + }, + { + "score": 7, + "reasons": [ + "Name segment 'GUEST'", + "CSR name 'mtval2' in backticks", + "CSR name 'htval' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2047, + "line_text": "faulting guest virtual address as usual, and `mtval2` or `htval` is", + "context": " 2045| control of CSR `medeleg`, but cannot be delegated to other privilege\n 2046| modes. On a guest-page fault, CSR `mtval` or `stval` is written with the\n>>> 2047| faulting guest virtual address as usual, and `mtval2` or `htval` is\n 2048| written either with zero or with the faulting guest physical address,\n 2049| shifted right by 2 bits. CSR `mtinst` or `htinst` may also be written" + }, + { + "score": 6, + "reasons": [ + "Name segment 'GUEST'", + "Name segment 'PAGE'", + "Name segment 'FAULT'", + "CSR name 'htval' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 917, + "line_text": "When a guest-page-fault trap is taken into HS-mode, `htval` is written", + "context": " 915| \n 916| [[norm:htval_trapval_param]]\n>>> 917| When a guest-page-fault trap is taken into HS-mode, `htval` is written\n 918| with either zero or the guest physical address that faulted, shifted\n 919| right by 2 bits. For other traps, `htval` is set to zero, but a future" + }, + { + "score": 6, + "reasons": [ + "Name segment 'GUEST'", + "Name segment 'PAGE'", + "Name segment 'FAULT'", + "CSR name 'mtval2' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1822, + "line_text": "When a guest-page-fault trap is taken into M-mode, `mtval2` is written", + "context": " 1820| \n 1821| [[norm:mtval2_trapval_param]]\n>>> 1822| When a guest-page-fault trap is taken into M-mode, `mtval2` is written\n 1823| with either zero or the guest physical address that faulted, shifted\n 1824| right by 2 bits. For other traps, `mtval2` is set to zero, but a future" + }, + { + "score": 6, + "reasons": [ + "CSR name 'mtval2' in backticks", + "CSR name 'htval' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2066, + "line_text": "to `mtval2`/`htval` shall correspond to the exact virtual address", + "context": " 2064| When a guest-page fault is not due to an implicit memory access for\n 2065| VS-stage address translation, a nonzero guest physical address written\n>>> 2066| to `mtval2`/`htval` shall correspond to the exact virtual address\n 2067| written to `mtval`/`stval`.\n 2068| " + } + ] + }, + { + "parameter_name": "REPORT_GPA_IN_TVAL_ON_LOAD_GUEST_PAGE_FAULT", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 8, + "candidates": [ + { + "score": 8, + "reasons": [ + "CSR field name 'VALUE'", + "CSR name 'mtval2' in backticks", + "CSR name 'htval' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2832, + "line_text": "`mtval2` or `htval`. If both conditions are met, the value written to", + "context": " 2830| implicit memory access for VS-stage address translation, and (b) a\n 2831| nonzero value (the faulting guest physical address) is written to\n>>> 2832| `mtval2` or `htval`. If both conditions are met, the value written to\n 2833| `mtinst` or `htinst` must be taken from\n 2834| <>; zero is not allowed." + }, + { + "score": 7, + "reasons": [ + "Name segment 'GUEST'", + "CSR name 'mtval2' in backticks", + "CSR name 'htval' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2047, + "line_text": "faulting guest virtual address as usual, and `mtval2` or `htval` is", + "context": " 2045| control of CSR `medeleg`, but cannot be delegated to other privilege\n 2046| modes. On a guest-page fault, CSR `mtval` or `stval` is written with the\n>>> 2047| faulting guest virtual address as usual, and `mtval2` or `htval` is\n 2048| written either with zero or with the faulting guest physical address,\n 2049| shifted right by 2 bits. CSR `mtinst` or `htinst` may also be written" + }, + { + "score": 6, + "reasons": [ + "Name segment 'GUEST'", + "Name segment 'PAGE'", + "Name segment 'FAULT'", + "CSR name 'htval' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 917, + "line_text": "When a guest-page-fault trap is taken into HS-mode, `htval` is written", + "context": " 915| \n 916| [[norm:htval_trapval_param]]\n>>> 917| When a guest-page-fault trap is taken into HS-mode, `htval` is written\n 918| with either zero or the guest physical address that faulted, shifted\n 919| right by 2 bits. For other traps, `htval` is set to zero, but a future" + }, + { + "score": 6, + "reasons": [ + "Name segment 'GUEST'", + "Name segment 'PAGE'", + "Name segment 'FAULT'", + "CSR name 'mtval2' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1822, + "line_text": "When a guest-page-fault trap is taken into M-mode, `mtval2` is written", + "context": " 1820| \n 1821| [[norm:mtval2_trapval_param]]\n>>> 1822| When a guest-page-fault trap is taken into M-mode, `mtval2` is written\n 1823| with either zero or the guest physical address that faulted, shifted\n 1824| right by 2 bits. For other traps, `mtval2` is set to zero, but a future" + }, + { + "score": 6, + "reasons": [ + "CSR name 'mtval2' in backticks", + "CSR name 'htval' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2066, + "line_text": "to `mtval2`/`htval` shall correspond to the exact virtual address", + "context": " 2064| When a guest-page fault is not due to an implicit memory access for\n 2065| VS-stage address translation, a nonzero guest physical address written\n>>> 2066| to `mtval2`/`htval` shall correspond to the exact virtual address\n 2067| written to `mtval`/`stval`.\n 2068| " + } + ] + }, + { + "parameter_name": "REPORT_GPA_IN_TVAL_ON_STORE_AMO_GUEST_PAGE_FAULT", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 8, + "candidates": [ + { + "score": 8, + "reasons": [ + "CSR field name 'VALUE'", + "CSR name 'mtval2' in backticks", + "CSR name 'htval' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2832, + "line_text": "`mtval2` or `htval`. If both conditions are met, the value written to", + "context": " 2830| implicit memory access for VS-stage address translation, and (b) a\n 2831| nonzero value (the faulting guest physical address) is written to\n>>> 2832| `mtval2` or `htval`. If both conditions are met, the value written to\n 2833| `mtinst` or `htinst` must be taken from\n 2834| <>; zero is not allowed." + }, + { + "score": 7, + "reasons": [ + "Name segment 'GUEST'", + "CSR name 'mtval2' in backticks", + "CSR name 'htval' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2047, + "line_text": "faulting guest virtual address as usual, and `mtval2` or `htval` is", + "context": " 2045| control of CSR `medeleg`, but cannot be delegated to other privilege\n 2046| modes. On a guest-page fault, CSR `mtval` or `stval` is written with the\n>>> 2047| faulting guest virtual address as usual, and `mtval2` or `htval` is\n 2048| written either with zero or with the faulting guest physical address,\n 2049| shifted right by 2 bits. CSR `mtinst` or `htinst` may also be written" + }, + { + "score": 6, + "reasons": [ + "Name segment 'GUEST'", + "Name segment 'PAGE'", + "Name segment 'FAULT'", + "CSR name 'htval' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 917, + "line_text": "When a guest-page-fault trap is taken into HS-mode, `htval` is written", + "context": " 915| \n 916| [[norm:htval_trapval_param]]\n>>> 917| When a guest-page-fault trap is taken into HS-mode, `htval` is written\n 918| with either zero or the guest physical address that faulted, shifted\n 919| right by 2 bits. For other traps, `htval` is set to zero, but a future" + }, + { + "score": 6, + "reasons": [ + "Name segment 'GUEST'", + "Name segment 'PAGE'", + "Name segment 'FAULT'", + "CSR name 'mtval2' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1822, + "line_text": "When a guest-page-fault trap is taken into M-mode, `mtval2` is written", + "context": " 1820| \n 1821| [[norm:mtval2_trapval_param]]\n>>> 1822| When a guest-page-fault trap is taken into M-mode, `mtval2` is written\n 1823| with either zero or the guest physical address that faulted, shifted\n 1824| right by 2 bits. For other traps, `mtval2` is set to zero, but a future" + }, + { + "score": 6, + "reasons": [ + "CSR name 'mtval2' in backticks", + "CSR name 'htval' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2066, + "line_text": "to `mtval2`/`htval` shall correspond to the exact virtual address", + "context": " 2064| When a guest-page fault is not due to an implicit memory access for\n 2065| VS-stage address translation, a nonzero guest physical address written\n>>> 2066| to `mtval2`/`htval` shall correspond to the exact virtual address\n 2067| written to `mtval`/`stval`.\n 2068| " + } + ] + }, + { + "parameter_name": "REPORT_VA_IN_MTVAL_ON_BREAKPOINT", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 17, + "candidates": [ + { + "score": 17, + "reasons": [ + "Description keyword 'mtval'", + "Name segment 'MTVAL'", + "Name segment 'BREAKPOINT'", + "Description keyword 'EBREAK'", + "Description keyword 'breakpoint'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 2049, + "line_text": "On a breakpoint exception raised by an EBREAK or C.EBREAK instruction, `mtval`", + "context": " 2047| faulting virtual address.\n 2048| \n>>> 2049| On a breakpoint exception raised by an EBREAK or C.EBREAK instruction, `mtval`\n 2050| is written with either zero or the virtual address of the instruction.\n 2051| " + }, + { + "score": 15, + "reasons": [ + "Description keyword 'mepc'", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1310, + "line_text": "[#norm:trap_del_S-mode_no_M-mode]#The `mcause`, `mepc`, and `mtval` registers and the MPP and MPIE fields of", + "context": " 1308| field of `mstatus` is written with the value of the SIE field at the\n 1309| time of the trap; and the SIE field of `mstatus` is cleared.#\n>>> 1310| [#norm:trap_del_S-mode_no_M-mode]#The `mcause`, `mepc`, and `mtval` registers and the MPP and MPIE fields of\n 1311| `mstatus` are not written.#\n 1312| " + }, + { + "score": 13, + "reasons": [ + "Optional/read-only pattern for boolean param", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 25, + "line_text": "registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and", + "context": " 23| The hypervisor extension depends on an \"I\" base integer ISA with 32\n 24| `x` registers (RV32I or RV64I), not RV32E or RV64E, which have only 16 `x`\n>>> 25| registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and\n 26| [#norm:H_vm_supported]#standard\n 27| page-based address translation must be supported, either Sv32 for RV32," + }, + { + "score": 13, + "reasons": [ + "Description keyword 'breakpoint'", + "Description keyword 'mtval'", + "Name segment 'BREAKPOINT'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 2043, + "line_text": "If `mtval` is written with a nonzero value when a breakpoint,", + "context": " 2041| to a nonzero value, then `mtval` is read-only zero.\n 2042| \n>>> 2043| If `mtval` is written with a nonzero value when a breakpoint,\n 2044| address-misaligned, access-fault, page-fault, or hardware-error exception\n 2045| occurs on an" + }, + { + "score": 11, + "reasons": [ + "Optional/read-only pattern for boolean param", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 2041, + "line_text": "to a nonzero value, then `mtval` is read-only zero.", + "context": " 2039| that caused the exception.\n 2040| If the hardware platform specifies that no exceptions set `mtval`\n>>> 2041| to a nonzero value, then `mtval` is read-only zero.\n 2042| \n 2043| If `mtval` is written with a nonzero value when a breakpoint," + } + ] + }, + { + "parameter_name": "REPORT_VA_IN_MTVAL_ON_INSTRUCTION_ACCESS_FAULT", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 10, + "candidates": [ + { + "score": 10, + "reasons": [ + "Optional/read-only pattern for boolean param", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 25, + "line_text": "registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and", + "context": " 23| The hypervisor extension depends on an \"I\" base integer ISA with 32\n 24| `x` registers (RV32I or RV64I), not RV32E or RV64E, which have only 16 `x`\n>>> 25| registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and\n 26| [#norm:H_vm_supported]#standard\n 27| page-based address translation must be supported, either Sv32 for RV32," + }, + { + "score": 10, + "reasons": [ + "Description keyword 'instruction'", + "Name segment 'INSTRUCTION'", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1840, + "line_text": "the instruction as indicated by the virtual address in `mtval`.", + "context": " 1838| For instruction guest-page faults on systems with variable-length\n 1839| instructions, a nonzero `mtval2` corresponds to the faulting portion of\n>>> 1840| the instruction as indicated by the virtual address in `mtval`.\n 1841| \n 1842| [[norm:mtval2_val]]" + }, + { + "score": 10, + "reasons": [ + "Description keyword 'instruction'", + "Name segment 'INSTRUCTION'", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2405, + "line_text": "On a virtual-instruction trap, `mtval` or `stval` is written the same as", + "context": " 2403| \n 2404| [[norm:H_virtinst_xtval]]\n>>> 2405| On a virtual-instruction trap, `mtval` or `stval` is written the same as\n 2406| for an illegal-instruction trap.\n 2407| " + }, + { + "score": 10, + "reasons": [ + "Description keyword 'instruction'", + "Name segment 'INSTRUCTION'", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 2046, + "line_text": "instruction fetch, load, or store, then `mtval` will contain the", + "context": " 2044| address-misaligned, access-fault, page-fault, or hardware-error exception\n 2045| occurs on an\n>>> 2046| instruction fetch, load, or store, then `mtval` will contain the\n 2047| faulting virtual address.\n 2048| " + }, + { + "score": 10, + "reasons": [ + "Description keyword 'instruction'", + "Name segment 'INSTRUCTION'", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 2049, + "line_text": "On a breakpoint exception raised by an EBREAK or C.EBREAK instruction, `mtval`", + "context": " 2047| faulting virtual address.\n 2048| \n>>> 2049| On a breakpoint exception raised by an EBREAK or C.EBREAK instruction, `mtval`\n 2050| is written with either zero or the virtual address of the instruction.\n 2051| " + } + ] + }, + { + "parameter_name": "REPORT_VA_IN_MTVAL_ON_INSTRUCTION_MISALIGNED", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 10, + "candidates": [ + { + "score": 10, + "reasons": [ + "Optional/read-only pattern for boolean param", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 25, + "line_text": "registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and", + "context": " 23| The hypervisor extension depends on an \"I\" base integer ISA with 32\n 24| `x` registers (RV32I or RV64I), not RV32E or RV64E, which have only 16 `x`\n>>> 25| registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and\n 26| [#norm:H_vm_supported]#standard\n 27| page-based address translation must be supported, either Sv32 for RV32," + }, + { + "score": 10, + "reasons": [ + "Description keyword 'instruction'", + "Name segment 'INSTRUCTION'", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1840, + "line_text": "the instruction as indicated by the virtual address in `mtval`.", + "context": " 1838| For instruction guest-page faults on systems with variable-length\n 1839| instructions, a nonzero `mtval2` corresponds to the faulting portion of\n>>> 1840| the instruction as indicated by the virtual address in `mtval`.\n 1841| \n 1842| [[norm:mtval2_val]]" + }, + { + "score": 10, + "reasons": [ + "Description keyword 'instruction'", + "Name segment 'INSTRUCTION'", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2405, + "line_text": "On a virtual-instruction trap, `mtval` or `stval` is written the same as", + "context": " 2403| \n 2404| [[norm:H_virtinst_xtval]]\n>>> 2405| On a virtual-instruction trap, `mtval` or `stval` is written the same as\n 2406| for an illegal-instruction trap.\n 2407| " + }, + { + "score": 10, + "reasons": [ + "Description keyword 'instruction'", + "Name segment 'INSTRUCTION'", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 2046, + "line_text": "instruction fetch, load, or store, then `mtval` will contain the", + "context": " 2044| address-misaligned, access-fault, page-fault, or hardware-error exception\n 2045| occurs on an\n>>> 2046| instruction fetch, load, or store, then `mtval` will contain the\n 2047| faulting virtual address.\n 2048| " + }, + { + "score": 10, + "reasons": [ + "Description keyword 'instruction'", + "Name segment 'INSTRUCTION'", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 2049, + "line_text": "On a breakpoint exception raised by an EBREAK or C.EBREAK instruction, `mtval`", + "context": " 2047| faulting virtual address.\n 2048| \n>>> 2049| On a breakpoint exception raised by an EBREAK or C.EBREAK instruction, `mtval`\n 2050| is written with either zero or the virtual address of the instruction.\n 2051| " + } + ] + }, + { + "parameter_name": "REPORT_VA_IN_MTVAL_ON_INSTRUCTION_PAGE_FAULT", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 10, + "candidates": [ + { + "score": 10, + "reasons": [ + "Optional/read-only pattern for boolean param", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 25, + "line_text": "registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and", + "context": " 23| The hypervisor extension depends on an \"I\" base integer ISA with 32\n 24| `x` registers (RV32I or RV64I), not RV32E or RV64E, which have only 16 `x`\n>>> 25| registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and\n 26| [#norm:H_vm_supported]#standard\n 27| page-based address translation must be supported, either Sv32 for RV32," + }, + { + "score": 10, + "reasons": [ + "Description keyword 'instruction'", + "Name segment 'INSTRUCTION'", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1840, + "line_text": "the instruction as indicated by the virtual address in `mtval`.", + "context": " 1838| For instruction guest-page faults on systems with variable-length\n 1839| instructions, a nonzero `mtval2` corresponds to the faulting portion of\n>>> 1840| the instruction as indicated by the virtual address in `mtval`.\n 1841| \n 1842| [[norm:mtval2_val]]" + }, + { + "score": 10, + "reasons": [ + "Description keyword 'instruction'", + "Name segment 'INSTRUCTION'", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2405, + "line_text": "On a virtual-instruction trap, `mtval` or `stval` is written the same as", + "context": " 2403| \n 2404| [[norm:H_virtinst_xtval]]\n>>> 2405| On a virtual-instruction trap, `mtval` or `stval` is written the same as\n 2406| for an illegal-instruction trap.\n 2407| " + }, + { + "score": 10, + "reasons": [ + "Description keyword 'instruction'", + "Name segment 'INSTRUCTION'", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 2046, + "line_text": "instruction fetch, load, or store, then `mtval` will contain the", + "context": " 2044| address-misaligned, access-fault, page-fault, or hardware-error exception\n 2045| occurs on an\n>>> 2046| instruction fetch, load, or store, then `mtval` will contain the\n 2047| faulting virtual address.\n 2048| " + }, + { + "score": 10, + "reasons": [ + "Description keyword 'instruction'", + "Name segment 'INSTRUCTION'", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 2049, + "line_text": "On a breakpoint exception raised by an EBREAK or C.EBREAK instruction, `mtval`", + "context": " 2047| faulting virtual address.\n 2048| \n>>> 2049| On a breakpoint exception raised by an EBREAK or C.EBREAK instruction, `mtval`\n 2050| is written with either zero or the virtual address of the instruction.\n 2051| " + } + ] + }, + { + "parameter_name": "REPORT_VA_IN_MTVAL_ON_LOAD_ACCESS_FAULT", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 10, + "candidates": [ + { + "score": 10, + "reasons": [ + "Optional/read-only pattern for boolean param", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 25, + "line_text": "registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and", + "context": " 23| The hypervisor extension depends on an \"I\" base integer ISA with 32\n 24| `x` registers (RV32I or RV64I), not RV32E or RV64E, which have only 16 `x`\n>>> 25| registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and\n 26| [#norm:H_vm_supported]#standard\n 27| page-based address translation must be supported, either Sv32 for RV32," + }, + { + "score": 9, + "reasons": [ + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1310, + "line_text": "[#norm:trap_del_S-mode_no_M-mode]#The `mcause`, `mepc`, and `mtval` registers and the MPP and MPIE fields of", + "context": " 1308| field of `mstatus` is written with the value of the SIE field at the\n 1309| time of the trap; and the SIE field of `mstatus` is cleared.#\n>>> 1310| [#norm:trap_del_S-mode_no_M-mode]#The `mcause`, `mepc`, and `mtval` registers and the MPP and MPIE fields of\n 1311| `mstatus` are not written.#\n 1312| " + }, + { + "score": 8, + "reasons": [ + "Name segment 'ACCESS'", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1837, + "line_text": "portion of the access as indicated by the virtual address in `mtval`.", + "context": " 1835| Otherwise, for misaligned loads and stores that cause guest-page faults,\n 1836| a nonzero guest physical address in `mtval2` corresponds to the faulting\n>>> 1837| portion of the access as indicated by the virtual address in `mtval`.\n 1838| For instruction guest-page faults on systems with variable-length\n 1839| instructions, a nonzero `mtval2` corresponds to the faulting portion of" + }, + { + "score": 8, + "reasons": [ + "Description keyword 'mtval'", + "Name segment 'FAULT'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2046, + "line_text": "modes. On a guest-page fault, CSR `mtval` or `stval` is written with the", + "context": " 2044| Guest-page-fault traps may be delegated from M-mode to HS-mode under the\n 2045| control of CSR `medeleg`, but cannot be delegated to other privilege\n>>> 2046| modes. On a guest-page fault, CSR `mtval` or `stval` is written with the\n 2047| faulting guest virtual address as usual, and `mtval2` or `htval` is\n 2048| written either with zero or with the faulting guest physical address," + }, + { + "score": 8, + "reasons": [ + "Optional/read-only pattern for boolean param", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 2041, + "line_text": "to a nonzero value, then `mtval` is read-only zero.", + "context": " 2039| that caused the exception.\n 2040| If the hardware platform specifies that no exceptions set `mtval`\n>>> 2041| to a nonzero value, then `mtval` is read-only zero.\n 2042| \n 2043| If `mtval` is written with a nonzero value when a breakpoint," + } + ] + }, + { + "parameter_name": "REPORT_VA_IN_MTVAL_ON_LOAD_MISALIGNED", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 11, + "candidates": [ + { + "score": 11, + "reasons": [ + "Description keyword 'mtval'", + "Name segment 'MISALIGNED'", + "Description keyword 'misaligned'", + "Name segment 'MTVAL'", + "Name segment 'LOAD'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 2067, + "line_text": "If `mtval` is written with a nonzero value when a misaligned load or", + "context": " 2065| \n 2066| \n>>> 2067| If `mtval` is written with a nonzero value when a misaligned load or\n 2068| store causes an access-fault, page-fault, or hardware-error exception,\n 2069| then `mtval` will" + }, + { + "score": 10, + "reasons": [ + "Optional/read-only pattern for boolean param", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 25, + "line_text": "registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and", + "context": " 23| The hypervisor extension depends on an \"I\" base integer ISA with 32\n 24| `x` registers (RV32I or RV64I), not RV32E or RV64E, which have only 16 `x`\n>>> 25| registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and\n 26| [#norm:H_vm_supported]#standard\n 27| page-based address translation must be supported, either Sv32 for RV32," + }, + { + "score": 9, + "reasons": [ + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1310, + "line_text": "[#norm:trap_del_S-mode_no_M-mode]#The `mcause`, `mepc`, and `mtval` registers and the MPP and MPIE fields of", + "context": " 1308| field of `mstatus` is written with the value of the SIE field at the\n 1309| time of the trap; and the SIE field of `mstatus` is cleared.#\n>>> 1310| [#norm:trap_del_S-mode_no_M-mode]#The `mcause`, `mepc`, and `mtval` registers and the MPP and MPIE fields of\n 1311| `mstatus` are not written.#\n 1312| " + }, + { + "score": 8, + "reasons": [ + "Optional/read-only pattern for boolean param", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 2041, + "line_text": "to a nonzero value, then `mtval` is read-only zero.", + "context": " 2039| that caused the exception.\n 2040| If the hardware platform specifies that no exceptions set `mtval`\n>>> 2041| to a nonzero value, then `mtval` is read-only zero.\n 2042| \n 2043| If `mtval` is written with a nonzero value when a breakpoint," + }, + { + "score": 8, + "reasons": [ + "Description keyword 'mtval'", + "Name segment 'LOAD'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 2046, + "line_text": "instruction fetch, load, or store, then `mtval` will contain the", + "context": " 2044| address-misaligned, access-fault, page-fault, or hardware-error exception\n 2045| occurs on an\n>>> 2046| instruction fetch, load, or store, then `mtval` will contain the\n 2047| faulting virtual address.\n 2048| " + } + ] + }, + { + "parameter_name": "REPORT_VA_IN_MTVAL_ON_LOAD_PAGE_FAULT", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 10, + "candidates": [ + { + "score": 10, + "reasons": [ + "Optional/read-only pattern for boolean param", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 25, + "line_text": "registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and", + "context": " 23| The hypervisor extension depends on an \"I\" base integer ISA with 32\n 24| `x` registers (RV32I or RV64I), not RV32E or RV64E, which have only 16 `x`\n>>> 25| registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and\n 26| [#norm:H_vm_supported]#standard\n 27| page-based address translation must be supported, either Sv32 for RV32," + }, + { + "score": 9, + "reasons": [ + "Name segment 'PAGE'", + "Description keyword 'mtval'", + "Name segment 'FAULT'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2046, + "line_text": "modes. On a guest-page fault, CSR `mtval` or `stval` is written with the", + "context": " 2044| Guest-page-fault traps may be delegated from M-mode to HS-mode under the\n 2045| control of CSR `medeleg`, but cannot be delegated to other privilege\n>>> 2046| modes. On a guest-page fault, CSR `mtval` or `stval` is written with the\n 2047| faulting guest virtual address as usual, and `mtval2` or `htval` is\n 2048| written either with zero or with the faulting guest physical address," + }, + { + "score": 9, + "reasons": [ + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1310, + "line_text": "[#norm:trap_del_S-mode_no_M-mode]#The `mcause`, `mepc`, and `mtval` registers and the MPP and MPIE fields of", + "context": " 1308| field of `mstatus` is written with the value of the SIE field at the\n 1309| time of the trap; and the SIE field of `mstatus` is cleared.#\n>>> 1310| [#norm:trap_del_S-mode_no_M-mode]#The `mcause`, `mepc`, and `mtval` registers and the MPP and MPIE fields of\n 1311| `mstatus` are not written.#\n 1312| " + }, + { + "score": 8, + "reasons": [ + "Optional/read-only pattern for boolean param", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 2041, + "line_text": "to a nonzero value, then `mtval` is read-only zero.", + "context": " 2039| that caused the exception.\n 2040| If the hardware platform specifies that no exceptions set `mtval`\n>>> 2041| to a nonzero value, then `mtval` is read-only zero.\n 2042| \n 2043| If `mtval` is written with a nonzero value when a breakpoint," + }, + { + "score": 8, + "reasons": [ + "Description keyword 'mtval'", + "Name segment 'LOAD'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 2046, + "line_text": "instruction fetch, load, or store, then `mtval` will contain the", + "context": " 2044| address-misaligned, access-fault, page-fault, or hardware-error exception\n 2045| occurs on an\n>>> 2046| instruction fetch, load, or store, then `mtval` will contain the\n 2047| faulting virtual address.\n 2048| " + } + ] + }, + { + "parameter_name": "REPORT_VA_IN_MTVAL_ON_STORE_AMO_ACCESS_FAULT", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 10, + "candidates": [ + { + "score": 10, + "reasons": [ + "Optional/read-only pattern for boolean param", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 25, + "line_text": "registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and", + "context": " 23| The hypervisor extension depends on an \"I\" base integer ISA with 32\n 24| `x` registers (RV32I or RV64I), not RV32E or RV64E, which have only 16 `x`\n>>> 25| registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and\n 26| [#norm:H_vm_supported]#standard\n 27| page-based address translation must be supported, either Sv32 for RV32," + }, + { + "score": 9, + "reasons": [ + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1310, + "line_text": "[#norm:trap_del_S-mode_no_M-mode]#The `mcause`, `mepc`, and `mtval` registers and the MPP and MPIE fields of", + "context": " 1308| field of `mstatus` is written with the value of the SIE field at the\n 1309| time of the trap; and the SIE field of `mstatus` is cleared.#\n>>> 1310| [#norm:trap_del_S-mode_no_M-mode]#The `mcause`, `mepc`, and `mtval` registers and the MPP and MPIE fields of\n 1311| `mstatus` are not written.#\n 1312| " + }, + { + "score": 8, + "reasons": [ + "Name segment 'ACCESS'", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1837, + "line_text": "portion of the access as indicated by the virtual address in `mtval`.", + "context": " 1835| Otherwise, for misaligned loads and stores that cause guest-page faults,\n 1836| a nonzero guest physical address in `mtval2` corresponds to the faulting\n>>> 1837| portion of the access as indicated by the virtual address in `mtval`.\n 1838| For instruction guest-page faults on systems with variable-length\n 1839| instructions, a nonzero `mtval2` corresponds to the faulting portion of" + }, + { + "score": 8, + "reasons": [ + "Description keyword 'mtval'", + "Name segment 'FAULT'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2046, + "line_text": "modes. On a guest-page fault, CSR `mtval` or `stval` is written with the", + "context": " 2044| Guest-page-fault traps may be delegated from M-mode to HS-mode under the\n 2045| control of CSR `medeleg`, but cannot be delegated to other privilege\n>>> 2046| modes. On a guest-page fault, CSR `mtval` or `stval` is written with the\n 2047| faulting guest virtual address as usual, and `mtval2` or `htval` is\n 2048| written either with zero or with the faulting guest physical address," + }, + { + "score": 8, + "reasons": [ + "Optional/read-only pattern for boolean param", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 2041, + "line_text": "to a nonzero value, then `mtval` is read-only zero.", + "context": " 2039| that caused the exception.\n 2040| If the hardware platform specifies that no exceptions set `mtval`\n>>> 2041| to a nonzero value, then `mtval` is read-only zero.\n 2042| \n 2043| If `mtval` is written with a nonzero value when a breakpoint," + } + ] + }, + { + "parameter_name": "REPORT_VA_IN_MTVAL_ON_STORE_AMO_MISALIGNED", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 10, + "candidates": [ + { + "score": 10, + "reasons": [ + "Optional/read-only pattern for boolean param", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 25, + "line_text": "registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and", + "context": " 23| The hypervisor extension depends on an \"I\" base integer ISA with 32\n 24| `x` registers (RV32I or RV64I), not RV32E or RV64E, which have only 16 `x`\n>>> 25| registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and\n 26| [#norm:H_vm_supported]#standard\n 27| page-based address translation must be supported, either Sv32 for RV32," + }, + { + "score": 10, + "reasons": [ + "Description keyword 'mtval'", + "Name segment 'MISALIGNED'", + "Description keyword 'misaligned'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 2067, + "line_text": "If `mtval` is written with a nonzero value when a misaligned load or", + "context": " 2065| \n 2066| \n>>> 2067| If `mtval` is written with a nonzero value when a misaligned load or\n 2068| store causes an access-fault, page-fault, or hardware-error exception,\n 2069| then `mtval` will" + }, + { + "score": 9, + "reasons": [ + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1310, + "line_text": "[#norm:trap_del_S-mode_no_M-mode]#The `mcause`, `mepc`, and `mtval` registers and the MPP and MPIE fields of", + "context": " 1308| field of `mstatus` is written with the value of the SIE field at the\n 1309| time of the trap; and the SIE field of `mstatus` is cleared.#\n>>> 1310| [#norm:trap_del_S-mode_no_M-mode]#The `mcause`, `mepc`, and `mtval` registers and the MPP and MPIE fields of\n 1311| `mstatus` are not written.#\n 1312| " + }, + { + "score": 8, + "reasons": [ + "Optional/read-only pattern for boolean param", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 2041, + "line_text": "to a nonzero value, then `mtval` is read-only zero.", + "context": " 2039| that caused the exception.\n 2040| If the hardware platform specifies that no exceptions set `mtval`\n>>> 2041| to a nonzero value, then `mtval` is read-only zero.\n 2042| \n 2043| If `mtval` is written with a nonzero value when a breakpoint," + }, + { + "score": 8, + "reasons": [ + "Name segment 'STORE'", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 2046, + "line_text": "instruction fetch, load, or store, then `mtval` will contain the", + "context": " 2044| address-misaligned, access-fault, page-fault, or hardware-error exception\n 2045| occurs on an\n>>> 2046| instruction fetch, load, or store, then `mtval` will contain the\n 2047| faulting virtual address.\n 2048| " + } + ] + }, + { + "parameter_name": "REPORT_VA_IN_MTVAL_ON_STORE_AMO_PAGE_FAULT", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 10, + "candidates": [ + { + "score": 10, + "reasons": [ + "Optional/read-only pattern for boolean param", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 25, + "line_text": "registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and", + "context": " 23| The hypervisor extension depends on an \"I\" base integer ISA with 32\n 24| `x` registers (RV32I or RV64I), not RV32E or RV64E, which have only 16 `x`\n>>> 25| registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and\n 26| [#norm:H_vm_supported]#standard\n 27| page-based address translation must be supported, either Sv32 for RV32," + }, + { + "score": 9, + "reasons": [ + "Name segment 'PAGE'", + "Description keyword 'mtval'", + "Name segment 'FAULT'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2046, + "line_text": "modes. On a guest-page fault, CSR `mtval` or `stval` is written with the", + "context": " 2044| Guest-page-fault traps may be delegated from M-mode to HS-mode under the\n 2045| control of CSR `medeleg`, but cannot be delegated to other privilege\n>>> 2046| modes. On a guest-page fault, CSR `mtval` or `stval` is written with the\n 2047| faulting guest virtual address as usual, and `mtval2` or `htval` is\n 2048| written either with zero or with the faulting guest physical address," + }, + { + "score": 9, + "reasons": [ + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1310, + "line_text": "[#norm:trap_del_S-mode_no_M-mode]#The `mcause`, `mepc`, and `mtval` registers and the MPP and MPIE fields of", + "context": " 1308| field of `mstatus` is written with the value of the SIE field at the\n 1309| time of the trap; and the SIE field of `mstatus` is cleared.#\n>>> 1310| [#norm:trap_del_S-mode_no_M-mode]#The `mcause`, `mepc`, and `mtval` registers and the MPP and MPIE fields of\n 1311| `mstatus` are not written.#\n 1312| " + }, + { + "score": 8, + "reasons": [ + "Optional/read-only pattern for boolean param", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 2041, + "line_text": "to a nonzero value, then `mtval` is read-only zero.", + "context": " 2039| that caused the exception.\n 2040| If the hardware platform specifies that no exceptions set `mtval`\n>>> 2041| to a nonzero value, then `mtval` is read-only zero.\n 2042| \n 2043| If `mtval` is written with a nonzero value when a breakpoint," + }, + { + "score": 8, + "reasons": [ + "Name segment 'STORE'", + "Description keyword 'mtval'", + "Name segment 'MTVAL'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 2046, + "line_text": "instruction fetch, load, or store, then `mtval` will contain the", + "context": " 2044| address-misaligned, access-fault, page-fault, or hardware-error exception\n 2045| occurs on an\n>>> 2046| instruction fetch, load, or store, then `mtval` will contain the\n 2047| faulting virtual address.\n 2048| " + } + ] + }, + { + "parameter_name": "REPORT_VA_IN_STVAL_ON_BREAKPOINT", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 17, + "candidates": [ + { + "score": 17, + "reasons": [ + "Name segment 'STVAL'", + "Description keyword 'stval'", + "Name segment 'BREAKPOINT'", + "Description keyword 'EBREAK'", + "Description keyword 'breakpoint'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 726, + "line_text": "On a breakpoint exception raised by an EBREAK or C.EBREAK instruction, `stval`", + "context": " 724| \n 725| [[norm:stval_op_breakpoint]]\n>>> 726| On a breakpoint exception raised by an EBREAK or C.EBREAK instruction, `stval`\n 727| is written with either zero or the virtual address of the instruction.\n 728| " + }, + { + "score": 13, + "reasons": [ + "Description keyword 'breakpoint'", + "Name segment 'STVAL'", + "Description keyword 'stval'", + "Name segment 'BREAKPOINT'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 719, + "line_text": "If `stval` is written with a nonzero value when a breakpoint,", + "context": " 717| \n 718| [[norm:stval_op_faulting_addr]]\n>>> 719| If `stval` is written with a nonzero value when a breakpoint,\n 720| address-misaligned, access-fault, page-fault, or hardware-error exception\n 721| occurs on an" + }, + { + "score": 12, + "reasons": [ + "Name segment 'STVAL'", + "Description keyword 'stval'" + ], + "is_normative": true, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 707, + "line_text": "[[norm:stval]]", + "context": " 705| ==== Supervisor Trap Value (`stval`) Register\n 706| \n>>> 707| [[norm:stval]]\n 708| The `stval` CSR is an SXLEN-bit read-write register formatted as\n 709| shown in <>. When a trap is taken into" + }, + { + "score": 11, + "reasons": [ + "Optional/read-only pattern for boolean param", + "Name segment 'STVAL'", + "Description keyword 'stval'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 748, + "line_text": "The `stval` register can optionally also be used to return the faulting", + "context": " 746| \n 747| [[norm:stval_op_illegal_instr]]\n>>> 748| The `stval` register can optionally also be used to return the faulting\n 749| instruction bits on an illegal-instruction exception (`sepc` points to\n 750| the faulting instruction in memory). If `stval` is written with a" + }, + { + "score": 10, + "reasons": [ + "Name segment 'STVAL'", + "Description keyword 'stval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 325, + "line_text": "guest virtual address to `stval`, GVA is set to 1. For any other trap", + "context": " 323| whenever a trap is taken into HS-mode. For any trap (breakpoint, address\n 324| misaligned, access fault, page fault, or guest-page fault) that writes a\n>>> 325| guest virtual address to `stval`, GVA is set to 1. For any other trap\n 326| into HS-mode, GVA is set to 0.\n 327| " + } + ] + }, + { + "parameter_name": "REPORT_VA_IN_STVAL_ON_INSTRUCTION_ACCESS_FAULT", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 10, + "candidates": [ + { + "score": 10, + "reasons": [ + "Name segment 'STVAL'", + "Name segment 'INSTRUCTION'", + "Description keyword 'stval'", + "Description keyword 'instruction'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 936, + "line_text": "the instruction as indicated by the virtual address in `stval`.", + "context": " 934| For instruction guest-page faults on systems with variable-length\n 935| instructions, a nonzero `htval` corresponds to the faulting portion of\n>>> 936| the instruction as indicated by the virtual address in `stval`.\n 937| \n 938| [NOTE]" + }, + { + "score": 10, + "reasons": [ + "Name segment 'STVAL'", + "Name segment 'INSTRUCTION'", + "Description keyword 'stval'", + "Description keyword 'instruction'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2405, + "line_text": "On a virtual-instruction trap, `mtval` or `stval` is written the same as", + "context": " 2403| \n 2404| [[norm:H_virtinst_xtval]]\n>>> 2405| On a virtual-instruction trap, `mtval` or `stval` is written the same as\n 2406| for an illegal-instruction trap.\n 2407| " + }, + { + "score": 10, + "reasons": [ + "Name segment 'STVAL'", + "Name segment 'INSTRUCTION'", + "Description keyword 'stval'", + "Description keyword 'instruction'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 1305, + "line_text": "address of the instruction that took the trap; the `stval` register is", + "context": " 1303| [#norm:trap_del_S-mode_op]#the `scause` register is written\n 1304| with the trap cause; the `sepc` register is written with the virtual\n>>> 1305| address of the instruction that took the trap; the `stval` register is\n 1306| written with an exception-specific datum; the SPP field of `mstatus` is\n 1307| written with the active privilege mode at the time of the trap; the SPIE" + }, + { + "score": 10, + "reasons": [ + "Name segment 'STVAL'", + "Name segment 'INSTRUCTION'", + "Description keyword 'stval'", + "Description keyword 'instruction'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 722, + "line_text": "instruction fetch, load, or store, then `stval` will contain the", + "context": " 720| address-misaligned, access-fault, page-fault, or hardware-error exception\n 721| occurs on an\n>>> 722| instruction fetch, load, or store, then `stval` will contain the\n 723| faulting virtual address.\n 724| " + }, + { + "score": 10, + "reasons": [ + "Name segment 'STVAL'", + "Name segment 'INSTRUCTION'", + "Description keyword 'stval'", + "Description keyword 'instruction'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 726, + "line_text": "On a breakpoint exception raised by an EBREAK or C.EBREAK instruction, `stval`", + "context": " 724| \n 725| [[norm:stval_op_breakpoint]]\n>>> 726| On a breakpoint exception raised by an EBREAK or C.EBREAK instruction, `stval`\n 727| is written with either zero or the virtual address of the instruction.\n 728| " + } + ] + }, + { + "parameter_name": "REPORT_VA_IN_STVAL_ON_INSTRUCTION_MISALIGNED", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 13, + "candidates": [ + { + "score": 13, + "reasons": [ + "Name segment 'STVAL'", + "Description keyword 'instruction'", + "Description keyword 'C'", + "Name segment 'INSTRUCTION'", + "Description keyword 'stval'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 726, + "line_text": "On a breakpoint exception raised by an EBREAK or C.EBREAK instruction, `stval`", + "context": " 724| \n 725| [[norm:stval_op_breakpoint]]\n>>> 726| On a breakpoint exception raised by an EBREAK or C.EBREAK instruction, `stval`\n 727| is written with either zero or the virtual address of the instruction.\n 728| " + }, + { + "score": 10, + "reasons": [ + "Name segment 'STVAL'", + "Name segment 'INSTRUCTION'", + "Description keyword 'stval'", + "Description keyword 'instruction'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 936, + "line_text": "the instruction as indicated by the virtual address in `stval`.", + "context": " 934| For instruction guest-page faults on systems with variable-length\n 935| instructions, a nonzero `htval` corresponds to the faulting portion of\n>>> 936| the instruction as indicated by the virtual address in `stval`.\n 937| \n 938| [NOTE]" + }, + { + "score": 10, + "reasons": [ + "Name segment 'STVAL'", + "Name segment 'INSTRUCTION'", + "Description keyword 'stval'", + "Description keyword 'instruction'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2405, + "line_text": "On a virtual-instruction trap, `mtval` or `stval` is written the same as", + "context": " 2403| \n 2404| [[norm:H_virtinst_xtval]]\n>>> 2405| On a virtual-instruction trap, `mtval` or `stval` is written the same as\n 2406| for an illegal-instruction trap.\n 2407| " + }, + { + "score": 10, + "reasons": [ + "Name segment 'STVAL'", + "Name segment 'INSTRUCTION'", + "Description keyword 'stval'", + "Description keyword 'instruction'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 1305, + "line_text": "address of the instruction that took the trap; the `stval` register is", + "context": " 1303| [#norm:trap_del_S-mode_op]#the `scause` register is written\n 1304| with the trap cause; the `sepc` register is written with the virtual\n>>> 1305| address of the instruction that took the trap; the `stval` register is\n 1306| written with an exception-specific datum; the SPP field of `mstatus` is\n 1307| written with the active privilege mode at the time of the trap; the SPIE" + }, + { + "score": 10, + "reasons": [ + "Name segment 'STVAL'", + "Name segment 'INSTRUCTION'", + "Description keyword 'stval'", + "Description keyword 'instruction'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 722, + "line_text": "instruction fetch, load, or store, then `stval` will contain the", + "context": " 720| address-misaligned, access-fault, page-fault, or hardware-error exception\n 721| occurs on an\n>>> 722| instruction fetch, load, or store, then `stval` will contain the\n 723| faulting virtual address.\n 724| " + } + ] + }, + { + "parameter_name": "REPORT_VA_IN_STVAL_ON_INSTRUCTION_PAGE_FAULT", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 10, + "candidates": [ + { + "score": 10, + "reasons": [ + "Name segment 'STVAL'", + "Name segment 'INSTRUCTION'", + "Description keyword 'stval'", + "Description keyword 'instruction'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 936, + "line_text": "the instruction as indicated by the virtual address in `stval`.", + "context": " 934| For instruction guest-page faults on systems with variable-length\n 935| instructions, a nonzero `htval` corresponds to the faulting portion of\n>>> 936| the instruction as indicated by the virtual address in `stval`.\n 937| \n 938| [NOTE]" + }, + { + "score": 10, + "reasons": [ + "Name segment 'STVAL'", + "Name segment 'INSTRUCTION'", + "Description keyword 'stval'", + "Description keyword 'instruction'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2405, + "line_text": "On a virtual-instruction trap, `mtval` or `stval` is written the same as", + "context": " 2403| \n 2404| [[norm:H_virtinst_xtval]]\n>>> 2405| On a virtual-instruction trap, `mtval` or `stval` is written the same as\n 2406| for an illegal-instruction trap.\n 2407| " + }, + { + "score": 10, + "reasons": [ + "Name segment 'STVAL'", + "Name segment 'INSTRUCTION'", + "Description keyword 'stval'", + "Description keyword 'instruction'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 1305, + "line_text": "address of the instruction that took the trap; the `stval` register is", + "context": " 1303| [#norm:trap_del_S-mode_op]#the `scause` register is written\n 1304| with the trap cause; the `sepc` register is written with the virtual\n>>> 1305| address of the instruction that took the trap; the `stval` register is\n 1306| written with an exception-specific datum; the SPP field of `mstatus` is\n 1307| written with the active privilege mode at the time of the trap; the SPIE" + }, + { + "score": 10, + "reasons": [ + "Name segment 'STVAL'", + "Name segment 'INSTRUCTION'", + "Description keyword 'stval'", + "Description keyword 'instruction'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 722, + "line_text": "instruction fetch, load, or store, then `stval` will contain the", + "context": " 720| address-misaligned, access-fault, page-fault, or hardware-error exception\n 721| occurs on an\n>>> 722| instruction fetch, load, or store, then `stval` will contain the\n 723| faulting virtual address.\n 724| " + }, + { + "score": 10, + "reasons": [ + "Name segment 'STVAL'", + "Name segment 'INSTRUCTION'", + "Description keyword 'stval'", + "Description keyword 'instruction'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 726, + "line_text": "On a breakpoint exception raised by an EBREAK or C.EBREAK instruction, `stval`", + "context": " 724| \n 725| [[norm:stval_op_breakpoint]]\n>>> 726| On a breakpoint exception raised by an EBREAK or C.EBREAK instruction, `stval`\n 727| is written with either zero or the virtual address of the instruction.\n 728| " + } + ] + }, + { + "parameter_name": "REPORT_VA_IN_STVAL_ON_LOAD_ACCESS_FAULT", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 9, + "candidates": [ + { + "score": 9, + "reasons": [ + "Name segment 'STVAL'", + "Description keyword 'stval'" + ], + "is_normative": true, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 707, + "line_text": "[[norm:stval]]", + "context": " 705| ==== Supervisor Trap Value (`stval`) Register\n 706| \n>>> 707| [[norm:stval]]\n 708| The `stval` CSR is an SXLEN-bit read-write register formatted as\n 709| shown in <>. When a trap is taken into" + }, + { + "score": 8, + "reasons": [ + "Name segment 'STVAL'", + "Description keyword 'stval'", + "Name segment 'ACCESS'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 933, + "line_text": "portion of the access as indicated by the virtual address in `stval`.", + "context": " 931| Otherwise, for misaligned loads and stores that cause guest-page faults,\n 932| a nonzero guest physical address in `htval` corresponds to the faulting\n>>> 933| portion of the access as indicated by the virtual address in `stval`.\n 934| For instruction guest-page faults on systems with variable-length\n 935| instructions, a nonzero `htval` corresponds to the faulting portion of" + }, + { + "score": 8, + "reasons": [ + "Name segment 'STVAL'", + "Name segment 'FAULT'", + "Description keyword 'stval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2046, + "line_text": "modes. On a guest-page fault, CSR `mtval` or `stval` is written with the", + "context": " 2044| Guest-page-fault traps may be delegated from M-mode to HS-mode under the\n 2045| control of CSR `medeleg`, but cannot be delegated to other privilege\n>>> 2046| modes. On a guest-page fault, CSR `mtval` or `stval` is written with the\n 2047| faulting guest virtual address as usual, and `mtval2` or `htval` is\n 2048| written either with zero or with the faulting guest physical address," + }, + { + "score": 8, + "reasons": [ + "Name segment 'STVAL'", + "Name segment 'LOAD'", + "Description keyword 'stval'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 722, + "line_text": "instruction fetch, load, or store, then `stval` will contain the", + "context": " 720| address-misaligned, access-fault, page-fault, or hardware-error exception\n 721| occurs on an\n>>> 722| instruction fetch, load, or store, then `stval` will contain the\n 723| faulting virtual address.\n 724| " + }, + { + "score": 8, + "reasons": [ + "Name segment 'STVAL'", + "Name segment 'LOAD'", + "Description keyword 'stval'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 734, + "line_text": "If `stval` is written with a nonzero value when a misaligned load or", + "context": " 732| \n 733| [[norm:stval_op_load_store_fault]]\n>>> 734| If `stval` is written with a nonzero value when a misaligned load or\n 735| store causes an access-fault, page-fault, or hardware-error exception,\n 736| then `stval` will" + } + ] + }, + { + "parameter_name": "REPORT_VA_IN_STVAL_ON_LOAD_MISALIGNED", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 11, + "candidates": [ + { + "score": 11, + "reasons": [ + "Name segment 'STVAL'", + "Name segment 'MISALIGNED'", + "Description keyword 'misaligned'", + "Name segment 'LOAD'", + "Description keyword 'stval'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 734, + "line_text": "If `stval` is written with a nonzero value when a misaligned load or", + "context": " 732| \n 733| [[norm:stval_op_load_store_fault]]\n>>> 734| If `stval` is written with a nonzero value when a misaligned load or\n 735| store causes an access-fault, page-fault, or hardware-error exception,\n 736| then `stval` will" + }, + { + "score": 9, + "reasons": [ + "Name segment 'STVAL'", + "Description keyword 'stval'" + ], + "is_normative": true, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 707, + "line_text": "[[norm:stval]]", + "context": " 705| ==== Supervisor Trap Value (`stval`) Register\n 706| \n>>> 707| [[norm:stval]]\n 708| The `stval` CSR is an SXLEN-bit read-write register formatted as\n 709| shown in <>. When a trap is taken into" + }, + { + "score": 8, + "reasons": [ + "Name segment 'STVAL'", + "Name segment 'LOAD'", + "Description keyword 'stval'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 722, + "line_text": "instruction fetch, load, or store, then `stval` will contain the", + "context": " 720| address-misaligned, access-fault, page-fault, or hardware-error exception\n 721| occurs on an\n>>> 722| instruction fetch, load, or store, then `stval` will contain the\n 723| faulting virtual address.\n 724| " + }, + { + "score": 8, + "reasons": [ + "Optional/read-only pattern for boolean param", + "Name segment 'STVAL'", + "Description keyword 'stval'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 748, + "line_text": "The `stval` register can optionally also be used to return the faulting", + "context": " 746| \n 747| [[norm:stval_op_illegal_instr]]\n>>> 748| The `stval` register can optionally also be used to return the faulting\n 749| instruction bits on an illegal-instruction exception (`sepc` points to\n 750| the faulting instruction in memory). If `stval` is written with a" + }, + { + "score": 7, + "reasons": [ + "Name segment 'STVAL'", + "Description keyword 'stval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 325, + "line_text": "guest virtual address to `stval`, GVA is set to 1. For any other trap", + "context": " 323| whenever a trap is taken into HS-mode. For any trap (breakpoint, address\n 324| misaligned, access fault, page fault, or guest-page fault) that writes a\n>>> 325| guest virtual address to `stval`, GVA is set to 1. For any other trap\n 326| into HS-mode, GVA is set to 0.\n 327| " + } + ] + }, + { + "parameter_name": "REPORT_VA_IN_STVAL_ON_LOAD_PAGE_FAULT", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 9, + "candidates": [ + { + "score": 9, + "reasons": [ + "Name segment 'STVAL'", + "Name segment 'PAGE'", + "Name segment 'FAULT'", + "Description keyword 'stval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2046, + "line_text": "modes. On a guest-page fault, CSR `mtval` or `stval` is written with the", + "context": " 2044| Guest-page-fault traps may be delegated from M-mode to HS-mode under the\n 2045| control of CSR `medeleg`, but cannot be delegated to other privilege\n>>> 2046| modes. On a guest-page fault, CSR `mtval` or `stval` is written with the\n 2047| faulting guest virtual address as usual, and `mtval2` or `htval` is\n 2048| written either with zero or with the faulting guest physical address," + }, + { + "score": 9, + "reasons": [ + "Name segment 'STVAL'", + "Description keyword 'stval'" + ], + "is_normative": true, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 707, + "line_text": "[[norm:stval]]", + "context": " 705| ==== Supervisor Trap Value (`stval`) Register\n 706| \n>>> 707| [[norm:stval]]\n 708| The `stval` CSR is an SXLEN-bit read-write register formatted as\n 709| shown in <>. When a trap is taken into" + }, + { + "score": 8, + "reasons": [ + "Name segment 'STVAL'", + "Name segment 'LOAD'", + "Description keyword 'stval'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 722, + "line_text": "instruction fetch, load, or store, then `stval` will contain the", + "context": " 720| address-misaligned, access-fault, page-fault, or hardware-error exception\n 721| occurs on an\n>>> 722| instruction fetch, load, or store, then `stval` will contain the\n 723| faulting virtual address.\n 724| " + }, + { + "score": 8, + "reasons": [ + "Name segment 'STVAL'", + "Name segment 'LOAD'", + "Description keyword 'stval'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 734, + "line_text": "If `stval` is written with a nonzero value when a misaligned load or", + "context": " 732| \n 733| [[norm:stval_op_load_store_fault]]\n>>> 734| If `stval` is written with a nonzero value when a misaligned load or\n 735| store causes an access-fault, page-fault, or hardware-error exception,\n 736| then `stval` will" + }, + { + "score": 8, + "reasons": [ + "Optional/read-only pattern for boolean param", + "Name segment 'STVAL'", + "Description keyword 'stval'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 748, + "line_text": "The `stval` register can optionally also be used to return the faulting", + "context": " 746| \n 747| [[norm:stval_op_illegal_instr]]\n>>> 748| The `stval` register can optionally also be used to return the faulting\n 749| instruction bits on an illegal-instruction exception (`sepc` points to\n 750| the faulting instruction in memory). If `stval` is written with a" + } + ] + }, + { + "parameter_name": "REPORT_VA_IN_STVAL_ON_STORE_AMO_ACCESS_FAULT", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 9, + "candidates": [ + { + "score": 9, + "reasons": [ + "Name segment 'STVAL'", + "Description keyword 'stval'" + ], + "is_normative": true, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 707, + "line_text": "[[norm:stval]]", + "context": " 705| ==== Supervisor Trap Value (`stval`) Register\n 706| \n>>> 707| [[norm:stval]]\n 708| The `stval` CSR is an SXLEN-bit read-write register formatted as\n 709| shown in <>. When a trap is taken into" + }, + { + "score": 8, + "reasons": [ + "Name segment 'STVAL'", + "Description keyword 'stval'", + "Name segment 'ACCESS'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 933, + "line_text": "portion of the access as indicated by the virtual address in `stval`.", + "context": " 931| Otherwise, for misaligned loads and stores that cause guest-page faults,\n 932| a nonzero guest physical address in `htval` corresponds to the faulting\n>>> 933| portion of the access as indicated by the virtual address in `stval`.\n 934| For instruction guest-page faults on systems with variable-length\n 935| instructions, a nonzero `htval` corresponds to the faulting portion of" + }, + { + "score": 8, + "reasons": [ + "Name segment 'STVAL'", + "Name segment 'FAULT'", + "Description keyword 'stval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2046, + "line_text": "modes. On a guest-page fault, CSR `mtval` or `stval` is written with the", + "context": " 2044| Guest-page-fault traps may be delegated from M-mode to HS-mode under the\n 2045| control of CSR `medeleg`, but cannot be delegated to other privilege\n>>> 2046| modes. On a guest-page fault, CSR `mtval` or `stval` is written with the\n 2047| faulting guest virtual address as usual, and `mtval2` or `htval` is\n 2048| written either with zero or with the faulting guest physical address," + }, + { + "score": 8, + "reasons": [ + "Name segment 'STVAL'", + "Description keyword 'stval'", + "Name segment 'STORE'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 722, + "line_text": "instruction fetch, load, or store, then `stval` will contain the", + "context": " 720| address-misaligned, access-fault, page-fault, or hardware-error exception\n 721| occurs on an\n>>> 722| instruction fetch, load, or store, then `stval` will contain the\n 723| faulting virtual address.\n 724| " + }, + { + "score": 8, + "reasons": [ + "Optional/read-only pattern for boolean param", + "Name segment 'STVAL'", + "Description keyword 'stval'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 748, + "line_text": "The `stval` register can optionally also be used to return the faulting", + "context": " 746| \n 747| [[norm:stval_op_illegal_instr]]\n>>> 748| The `stval` register can optionally also be used to return the faulting\n 749| instruction bits on an illegal-instruction exception (`sepc` points to\n 750| the faulting instruction in memory). If `stval` is written with a" + } + ] + }, + { + "parameter_name": "REPORT_VA_IN_STVAL_ON_STORE_AMO_MISALIGNED", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 10, + "candidates": [ + { + "score": 10, + "reasons": [ + "Name segment 'STVAL'", + "Description keyword 'stval'", + "Name segment 'MISALIGNED'", + "Description keyword 'misaligned'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 734, + "line_text": "If `stval` is written with a nonzero value when a misaligned load or", + "context": " 732| \n 733| [[norm:stval_op_load_store_fault]]\n>>> 734| If `stval` is written with a nonzero value when a misaligned load or\n 735| store causes an access-fault, page-fault, or hardware-error exception,\n 736| then `stval` will" + }, + { + "score": 9, + "reasons": [ + "Name segment 'STVAL'", + "Description keyword 'stval'" + ], + "is_normative": true, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 707, + "line_text": "[[norm:stval]]", + "context": " 705| ==== Supervisor Trap Value (`stval`) Register\n 706| \n>>> 707| [[norm:stval]]\n 708| The `stval` CSR is an SXLEN-bit read-write register formatted as\n 709| shown in <>. When a trap is taken into" + }, + { + "score": 8, + "reasons": [ + "Name segment 'STVAL'", + "Description keyword 'stval'", + "Name segment 'STORE'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 722, + "line_text": "instruction fetch, load, or store, then `stval` will contain the", + "context": " 720| address-misaligned, access-fault, page-fault, or hardware-error exception\n 721| occurs on an\n>>> 722| instruction fetch, load, or store, then `stval` will contain the\n 723| faulting virtual address.\n 724| " + }, + { + "score": 8, + "reasons": [ + "Optional/read-only pattern for boolean param", + "Name segment 'STVAL'", + "Description keyword 'stval'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 748, + "line_text": "The `stval` register can optionally also be used to return the faulting", + "context": " 746| \n 747| [[norm:stval_op_illegal_instr]]\n>>> 748| The `stval` register can optionally also be used to return the faulting\n 749| instruction bits on an illegal-instruction exception (`sepc` points to\n 750| the faulting instruction in memory). If `stval` is written with a" + }, + { + "score": 7, + "reasons": [ + "Name segment 'STVAL'", + "Description keyword 'stval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 325, + "line_text": "guest virtual address to `stval`, GVA is set to 1. For any other trap", + "context": " 323| whenever a trap is taken into HS-mode. For any trap (breakpoint, address\n 324| misaligned, access fault, page fault, or guest-page fault) that writes a\n>>> 325| guest virtual address to `stval`, GVA is set to 1. For any other trap\n 326| into HS-mode, GVA is set to 0.\n 327| " + } + ] + }, + { + "parameter_name": "REPORT_VA_IN_STVAL_ON_STORE_AMO_PAGE_FAULT", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 9, + "candidates": [ + { + "score": 9, + "reasons": [ + "Name segment 'STVAL'", + "Name segment 'PAGE'", + "Name segment 'FAULT'", + "Description keyword 'stval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2046, + "line_text": "modes. On a guest-page fault, CSR `mtval` or `stval` is written with the", + "context": " 2044| Guest-page-fault traps may be delegated from M-mode to HS-mode under the\n 2045| control of CSR `medeleg`, but cannot be delegated to other privilege\n>>> 2046| modes. On a guest-page fault, CSR `mtval` or `stval` is written with the\n 2047| faulting guest virtual address as usual, and `mtval2` or `htval` is\n 2048| written either with zero or with the faulting guest physical address," + }, + { + "score": 9, + "reasons": [ + "Name segment 'STVAL'", + "Description keyword 'stval'" + ], + "is_normative": true, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 707, + "line_text": "[[norm:stval]]", + "context": " 705| ==== Supervisor Trap Value (`stval`) Register\n 706| \n>>> 707| [[norm:stval]]\n 708| The `stval` CSR is an SXLEN-bit read-write register formatted as\n 709| shown in <>. When a trap is taken into" + }, + { + "score": 8, + "reasons": [ + "Name segment 'STVAL'", + "Description keyword 'stval'", + "Name segment 'STORE'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 722, + "line_text": "instruction fetch, load, or store, then `stval` will contain the", + "context": " 720| address-misaligned, access-fault, page-fault, or hardware-error exception\n 721| occurs on an\n>>> 722| instruction fetch, load, or store, then `stval` will contain the\n 723| faulting virtual address.\n 724| " + }, + { + "score": 8, + "reasons": [ + "Optional/read-only pattern for boolean param", + "Name segment 'STVAL'", + "Description keyword 'stval'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 748, + "line_text": "The `stval` register can optionally also be used to return the faulting", + "context": " 746| \n 747| [[norm:stval_op_illegal_instr]]\n>>> 748| The `stval` register can optionally also be used to return the faulting\n 749| instruction bits on an illegal-instruction exception (`sepc` points to\n 750| the faulting instruction in memory). If `stval` is written with a" + }, + { + "score": 7, + "reasons": [ + "Name segment 'STVAL'", + "Description keyword 'stval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 325, + "line_text": "guest virtual address to `stval`, GVA is set to 1. For any other trap", + "context": " 323| whenever a trap is taken into HS-mode. For any trap (breakpoint, address\n 324| misaligned, access fault, page fault, or guest-page fault) that writes a\n>>> 325| guest virtual address to `stval`, GVA is set to 1. For any other trap\n 326| into HS-mode, GVA is set to 0.\n 327| " + } + ] + }, + { + "parameter_name": "REPORT_VA_IN_VSTVAL_ON_BREAKPOINT", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 10, + "candidates": [ + { + "score": 10, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1364, + "line_text": "==== Virtual Supervisor Trap Value (`vstval`) Register", + "context": " 1362| include::images/bytefield/vscausereg.edn[]\n 1363| \n>>> 1364| ==== Virtual Supervisor Trap Value (`vstval`) Register\n 1365| \n 1366| [[norm:vstval_sz_acc_op]]" + }, + { + "score": 10, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1367, + "line_text": "The `vstval` register is a VSXLEN-bit read/write register that is", + "context": " 1365| \n 1366| [[norm:vstval_sz_acc_op]]\n>>> 1367| The `vstval` register is a VSXLEN-bit read/write register that is\n 1368| VS-mode’s version of supervisor register `stval`, formatted as shown in\n 1369| <>. When V=1, `vstval` substitutes for" + }, + { + "score": 10, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1369, + "line_text": "<>. When V=1, `vstval` substitutes for", + "context": " 1367| The `vstval` register is a VSXLEN-bit read/write register that is\n 1368| VS-mode’s version of supervisor register `stval`, formatted as shown in\n>>> 1369| <>. When V=1, `vstval` substitutes for\n 1370| the usual `stval`, so instructions that normally read or modify `stval`\n 1371| actually access `vstval` instead. When V=0, `vstval` does not directly" + }, + { + "score": 10, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1371, + "line_text": "actually access `vstval` instead. When V=0, `vstval` does not directly", + "context": " 1369| <>. When V=1, `vstval` substitutes for\n 1370| the usual `stval`, so instructions that normally read or modify `stval`\n>>> 1371| actually access `vstval` instead. When V=0, `vstval` does not directly\n 1372| affect the behavior of the machine.\n 1373| " + }, + { + "score": 10, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1375, + "line_text": "`vstval` is a *WARL* register that must be able to hold the same set of values", + "context": " 1373| \n 1374| [[norm:vstval_warl]]\n>>> 1375| `vstval` is a *WARL* register that must be able to hold the same set of values\n 1376| that `stval` can hold.\n 1377| " + } + ] + }, + { + "parameter_name": "REPORT_VA_IN_VSTVAL_ON_INSTRUCTION_ACCESS_FAULT", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 9, + "candidates": [ + { + "score": 9, + "reasons": [ + "Description keyword 'PC'", + "Name segment 'ACCESS'", + "Name segment 'FAULT'", + "Description keyword 'instruction'", + "Name segment 'INSTRUCTION'" + ], + "is_normative": true, + "in_note": false, + "file": "zc.adoc", + "line_number": 1183, + "line_text": "[#norm:Zcmp_trap]#If a trap occurs during the sequence then _xEPC_ is updated with the PC of the instruction, _xTVAL_ (if not read-only-zero) updated with the bad address if it was an access fault and _xCAUSE_ updated with the type of trap.#", + "context": " 1181| The entire PUSH/POP sequence is re-executed after returning from the trap handler, and multiple traps are possible during the sequence.\n 1182| \n>>> 1183| [#norm:Zcmp_trap]#If a trap occurs during the sequence then _xEPC_ is updated with the PC of the instruction, _xTVAL_ (if not read-only-zero) updated with the bad address if it was an access fault and _xCAUSE_ updated with the type of trap.#\n 1184| \n 1185| [[norm:interrupts_allowed_in_pushpop_param]]" + }, + { + "score": 8, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'", + "Name segment 'ACCESS'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1371, + "line_text": "actually access `vstval` instead. When V=0, `vstval` does not directly", + "context": " 1369| <>. When V=1, `vstval` substitutes for\n 1370| the usual `stval`, so instructions that normally read or modify `stval`\n>>> 1371| actually access `vstval` instead. When V=0, `vstval` does not directly\n 1372| affect the behavior of the machine.\n 1373| " + }, + { + "score": 8, + "reasons": [ + "Name segment 'INSTRUCTION'", + "Name segment 'FAULT'", + "Description keyword 'PC'", + "Description keyword 'instruction'" + ], + "is_normative": true, + "in_note": false, + "file": "zc.adoc", + "line_number": 2359, + "line_text": "[#norm:Zcmt_trap]#If an exception occurs on either instruction fetch, xEPC is set to the PC of the table jump instruction, xCAUSE is set as expected for the type of fault and xTVAL (if not set to zero) contains the fetch address which caused the fault.#", + "context": " 2357| if the tables have not been updated in memory since the last _fence.i_.\n 2358| \n>>> 2359| [#norm:Zcmt_trap]#If an exception occurs on either instruction fetch, xEPC is set to the PC of the table jump instruction, xCAUSE is set as expected for the type of fault and xTVAL (if not set to zero) contains the fetch address which caused the fault.#\n 2360| \n 2361| <<<" + }, + { + "score": 7, + "reasons": [ + "Name segment 'INSTRUCTION'", + "Name segment 'FAULT'", + "Description keyword 'instruction'", + "Name segment 'ACCESS'" + ], + "is_normative": true, + "in_note": false, + "file": "cmo.adoc", + "line_number": 383, + "line_text": "access-fault exception otherwise.# [#norm:cbz_unperm_translate]#During address translation, the instruction", + "context": " 381| cache-block zero instruction raises a store page-fault or store guest-page-fault\n 382| exception if address translation does not permit write access or raises a store\n>>> 383| access-fault exception otherwise.# [#norm:cbz_unperm_translate]#During address translation, the instruction\n 384| also checks the accessed and dirty bits and may either raise an exception or set\n 385| the bits as required.#" + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1364, + "line_text": "==== Virtual Supervisor Trap Value (`vstval`) Register", + "context": " 1362| include::images/bytefield/vscausereg.edn[]\n 1363| \n>>> 1364| ==== Virtual Supervisor Trap Value (`vstval`) Register\n 1365| \n 1366| [[norm:vstval_sz_acc_op]]" + } + ] + }, + { + "parameter_name": "REPORT_VA_IN_VSTVAL_ON_INSTRUCTION_MISALIGNED", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 8, + "candidates": [ + { + "score": 8, + "reasons": [ + "Description keyword 'C'", + "Name segment 'INSTRUCTION'", + "Description keyword 'instruction'" + ], + "is_normative": true, + "in_note": false, + "file": "c-st-ext.adoc", + "line_number": 310, + "line_text": "[#norm:c-ldsp_op]#C.LDSP is an RV64C-only instruction that loads a 64-bit value", + "context": " 308| valid only when _rd_≠`x0`; the code points with _rd_=`x0` are reserved.#\n 309| \n>>> 310| [#norm:c-ldsp_op]#C.LDSP is an RV64C-only instruction that loads a 64-bit value\n 311| from memory into register _rd_. It computes its effective address by\n 312| adding the zero-extended offset, scaled by 8, to the stack pointer," + }, + { + "score": 8, + "reasons": [ + "Description keyword 'C'", + "Name segment 'INSTRUCTION'", + "Description keyword 'instruction'" + ], + "is_normative": true, + "in_note": false, + "file": "c-st-ext.adoc", + "line_number": 318, + "line_text": "[#norm:c-flwsp_op]#C.FLWSP is an RV32FC-only instruction that loads a single-precision", + "context": " 316| _rd_=`x0` are reserved.#\n 317| \n>>> 318| [#norm:c-flwsp_op]#C.FLWSP is an RV32FC-only instruction that loads a single-precision\n 319| floating-point value from memory into floating-point register _rd_. It\n 320| computes its effective address by adding the _zero_-extended offset," + }, + { + "score": 8, + "reasons": [ + "Description keyword 'C'", + "Name segment 'INSTRUCTION'", + "Description keyword 'instruction'" + ], + "is_normative": true, + "in_note": false, + "file": "c-st-ext.adoc", + "line_number": 324, + "line_text": "[#norm:c-fldsp_op]#C.FLDSP is an RV32DC/RV64DC-only instruction that loads a", + "context": " 322| `flw rd, offset(x2)`.#\n 323| \n>>> 324| [#norm:c-fldsp_op]#C.FLDSP is an RV32DC/RV64DC-only instruction that loads a\n 325| double-precision floating-point value from memory into floating-point\n 326| register _rd_. It computes its effective address by adding the" + }, + { + "score": 8, + "reasons": [ + "Description keyword 'C'", + "Name segment 'INSTRUCTION'", + "Description keyword 'instruction'" + ], + "is_normative": true, + "in_note": false, + "file": "c-st-ext.adoc", + "line_number": 340, + "line_text": "[#norm:c-sdsp_op]#C.SDSP is an RV64C-only instruction that stores a 64-bit value in", + "context": " 338| the stack pointer, `x2`. It expands to `sw rs2, offset(x2)`.#\n 339| \n>>> 340| [#norm:c-sdsp_op]#C.SDSP is an RV64C-only instruction that stores a 64-bit value in\n 341| register _rs2_ to memory. It computes an effective address by adding the\n 342| _zero_-extended offset, scaled by 8, to the stack pointer, `x2`. It" + }, + { + "score": 8, + "reasons": [ + "Description keyword 'C'", + "Name segment 'INSTRUCTION'", + "Description keyword 'instruction'" + ], + "is_normative": true, + "in_note": false, + "file": "c-st-ext.adoc", + "line_number": 345, + "line_text": "[#norm:c-fswsp_op]#C.FSWSP is an RV32FC-only instruction that stores a single-precision", + "context": " 343| expands to `sd rs2, offset(x2)`.#\n 344| \n>>> 345| [#norm:c-fswsp_op]#C.FSWSP is an RV32FC-only instruction that stores a single-precision\n 346| floating-point value in floating-point register _rs2_ to memory. It\n 347| computes an effective address by adding the _zero_-extended offset," + } + ] + }, + { + "parameter_name": "REPORT_VA_IN_VSTVAL_ON_INSTRUCTION_PAGE_FAULT", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 8, + "candidates": [ + { + "score": 8, + "reasons": [ + "Name segment 'INSTRUCTION'", + "Name segment 'FAULT'", + "Description keyword 'PC'", + "Description keyword 'instruction'" + ], + "is_normative": true, + "in_note": false, + "file": "zc.adoc", + "line_number": 1183, + "line_text": "[#norm:Zcmp_trap]#If a trap occurs during the sequence then _xEPC_ is updated with the PC of the instruction, _xTVAL_ (if not read-only-zero) updated with the bad address if it was an access fault and _xCAUSE_ updated with the type of trap.#", + "context": " 1181| The entire PUSH/POP sequence is re-executed after returning from the trap handler, and multiple traps are possible during the sequence.\n 1182| \n>>> 1183| [#norm:Zcmp_trap]#If a trap occurs during the sequence then _xEPC_ is updated with the PC of the instruction, _xTVAL_ (if not read-only-zero) updated with the bad address if it was an access fault and _xCAUSE_ updated with the type of trap.#\n 1184| \n 1185| [[norm:interrupts_allowed_in_pushpop_param]]" + }, + { + "score": 8, + "reasons": [ + "Name segment 'INSTRUCTION'", + "Name segment 'FAULT'", + "Description keyword 'PC'", + "Description keyword 'instruction'" + ], + "is_normative": true, + "in_note": false, + "file": "zc.adoc", + "line_number": 2359, + "line_text": "[#norm:Zcmt_trap]#If an exception occurs on either instruction fetch, xEPC is set to the PC of the table jump instruction, xCAUSE is set as expected for the type of fault and xTVAL (if not set to zero) contains the fetch address which caused the fault.#", + "context": " 2357| if the tables have not been updated in memory since the last _fence.i_.\n 2358| \n>>> 2359| [#norm:Zcmt_trap]#If an exception occurs on either instruction fetch, xEPC is set to the PC of the table jump instruction, xCAUSE is set as expected for the type of fault and xTVAL (if not set to zero) contains the fetch address which caused the fault.#\n 2360| \n 2361| <<<" + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1364, + "line_text": "==== Virtual Supervisor Trap Value (`vstval`) Register", + "context": " 1362| include::images/bytefield/vscausereg.edn[]\n 1363| \n>>> 1364| ==== Virtual Supervisor Trap Value (`vstval`) Register\n 1365| \n 1366| [[norm:vstval_sz_acc_op]]" + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1367, + "line_text": "The `vstval` register is a VSXLEN-bit read/write register that is", + "context": " 1365| \n 1366| [[norm:vstval_sz_acc_op]]\n>>> 1367| The `vstval` register is a VSXLEN-bit read/write register that is\n 1368| VS-mode’s version of supervisor register `stval`, formatted as shown in\n 1369| <>. When V=1, `vstval` substitutes for" + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1369, + "line_text": "<>. When V=1, `vstval` substitutes for", + "context": " 1367| The `vstval` register is a VSXLEN-bit read/write register that is\n 1368| VS-mode’s version of supervisor register `stval`, formatted as shown in\n>>> 1369| <>. When V=1, `vstval` substitutes for\n 1370| the usual `stval`, so instructions that normally read or modify `stval`\n 1371| actually access `vstval` instead. When V=0, `vstval` does not directly" + } + ] + }, + { + "parameter_name": "REPORT_VA_IN_VSTVAL_ON_LOAD_ACCESS_FAULT", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 8, + "candidates": [ + { + "score": 8, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'", + "Name segment 'ACCESS'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1371, + "line_text": "actually access `vstval` instead. When V=0, `vstval` does not directly", + "context": " 1369| <>. When V=1, `vstval` substitutes for\n 1370| the usual `stval`, so instructions that normally read or modify `stval`\n>>> 1371| actually access `vstval` instead. When V=0, `vstval` does not directly\n 1372| affect the behavior of the machine.\n 1373| " + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1364, + "line_text": "==== Virtual Supervisor Trap Value (`vstval`) Register", + "context": " 1362| include::images/bytefield/vscausereg.edn[]\n 1363| \n>>> 1364| ==== Virtual Supervisor Trap Value (`vstval`) Register\n 1365| \n 1366| [[norm:vstval_sz_acc_op]]" + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1367, + "line_text": "The `vstval` register is a VSXLEN-bit read/write register that is", + "context": " 1365| \n 1366| [[norm:vstval_sz_acc_op]]\n>>> 1367| The `vstval` register is a VSXLEN-bit read/write register that is\n 1368| VS-mode’s version of supervisor register `stval`, formatted as shown in\n 1369| <>. When V=1, `vstval` substitutes for" + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1369, + "line_text": "<>. When V=1, `vstval` substitutes for", + "context": " 1367| The `vstval` register is a VSXLEN-bit read/write register that is\n 1368| VS-mode’s version of supervisor register `stval`, formatted as shown in\n>>> 1369| <>. When V=1, `vstval` substitutes for\n 1370| the usual `stval`, so instructions that normally read or modify `stval`\n 1371| actually access `vstval` instead. When V=0, `vstval` does not directly" + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1375, + "line_text": "`vstval` is a *WARL* register that must be able to hold the same set of values", + "context": " 1373| \n 1374| [[norm:vstval_warl]]\n>>> 1375| `vstval` is a *WARL* register that must be able to hold the same set of values\n 1376| that `stval` can hold.\n 1377| " + } + ] + }, + { + "parameter_name": "REPORT_VA_IN_VSTVAL_ON_LOAD_MISALIGNED", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 7, + "candidates": [ + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1364, + "line_text": "==== Virtual Supervisor Trap Value (`vstval`) Register", + "context": " 1362| include::images/bytefield/vscausereg.edn[]\n 1363| \n>>> 1364| ==== Virtual Supervisor Trap Value (`vstval`) Register\n 1365| \n 1366| [[norm:vstval_sz_acc_op]]" + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1367, + "line_text": "The `vstval` register is a VSXLEN-bit read/write register that is", + "context": " 1365| \n 1366| [[norm:vstval_sz_acc_op]]\n>>> 1367| The `vstval` register is a VSXLEN-bit read/write register that is\n 1368| VS-mode’s version of supervisor register `stval`, formatted as shown in\n 1369| <>. When V=1, `vstval` substitutes for" + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1369, + "line_text": "<>. When V=1, `vstval` substitutes for", + "context": " 1367| The `vstval` register is a VSXLEN-bit read/write register that is\n 1368| VS-mode’s version of supervisor register `stval`, formatted as shown in\n>>> 1369| <>. When V=1, `vstval` substitutes for\n 1370| the usual `stval`, so instructions that normally read or modify `stval`\n 1371| actually access `vstval` instead. When V=0, `vstval` does not directly" + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1371, + "line_text": "actually access `vstval` instead. When V=0, `vstval` does not directly", + "context": " 1369| <>. When V=1, `vstval` substitutes for\n 1370| the usual `stval`, so instructions that normally read or modify `stval`\n>>> 1371| actually access `vstval` instead. When V=0, `vstval` does not directly\n 1372| affect the behavior of the machine.\n 1373| " + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1375, + "line_text": "`vstval` is a *WARL* register that must be able to hold the same set of values", + "context": " 1373| \n 1374| [[norm:vstval_warl]]\n>>> 1375| `vstval` is a *WARL* register that must be able to hold the same set of values\n 1376| that `stval` can hold.\n 1377| " + } + ] + }, + { + "parameter_name": "REPORT_VA_IN_VSTVAL_ON_LOAD_PAGE_FAULT", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 7, + "candidates": [ + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1364, + "line_text": "==== Virtual Supervisor Trap Value (`vstval`) Register", + "context": " 1362| include::images/bytefield/vscausereg.edn[]\n 1363| \n>>> 1364| ==== Virtual Supervisor Trap Value (`vstval`) Register\n 1365| \n 1366| [[norm:vstval_sz_acc_op]]" + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1367, + "line_text": "The `vstval` register is a VSXLEN-bit read/write register that is", + "context": " 1365| \n 1366| [[norm:vstval_sz_acc_op]]\n>>> 1367| The `vstval` register is a VSXLEN-bit read/write register that is\n 1368| VS-mode’s version of supervisor register `stval`, formatted as shown in\n 1369| <>. When V=1, `vstval` substitutes for" + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1369, + "line_text": "<>. When V=1, `vstval` substitutes for", + "context": " 1367| The `vstval` register is a VSXLEN-bit read/write register that is\n 1368| VS-mode’s version of supervisor register `stval`, formatted as shown in\n>>> 1369| <>. When V=1, `vstval` substitutes for\n 1370| the usual `stval`, so instructions that normally read or modify `stval`\n 1371| actually access `vstval` instead. When V=0, `vstval` does not directly" + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1371, + "line_text": "actually access `vstval` instead. When V=0, `vstval` does not directly", + "context": " 1369| <>. When V=1, `vstval` substitutes for\n 1370| the usual `stval`, so instructions that normally read or modify `stval`\n>>> 1371| actually access `vstval` instead. When V=0, `vstval` does not directly\n 1372| affect the behavior of the machine.\n 1373| " + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1375, + "line_text": "`vstval` is a *WARL* register that must be able to hold the same set of values", + "context": " 1373| \n 1374| [[norm:vstval_warl]]\n>>> 1375| `vstval` is a *WARL* register that must be able to hold the same set of values\n 1376| that `stval` can hold.\n 1377| " + } + ] + }, + { + "parameter_name": "REPORT_VA_IN_VSTVAL_ON_STORE_AMO_ACCESS_FAULT", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 8, + "candidates": [ + { + "score": 8, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'", + "Name segment 'ACCESS'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1371, + "line_text": "actually access `vstval` instead. When V=0, `vstval` does not directly", + "context": " 1369| <>. When V=1, `vstval` substitutes for\n 1370| the usual `stval`, so instructions that normally read or modify `stval`\n>>> 1371| actually access `vstval` instead. When V=0, `vstval` does not directly\n 1372| affect the behavior of the machine.\n 1373| " + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1364, + "line_text": "==== Virtual Supervisor Trap Value (`vstval`) Register", + "context": " 1362| include::images/bytefield/vscausereg.edn[]\n 1363| \n>>> 1364| ==== Virtual Supervisor Trap Value (`vstval`) Register\n 1365| \n 1366| [[norm:vstval_sz_acc_op]]" + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1367, + "line_text": "The `vstval` register is a VSXLEN-bit read/write register that is", + "context": " 1365| \n 1366| [[norm:vstval_sz_acc_op]]\n>>> 1367| The `vstval` register is a VSXLEN-bit read/write register that is\n 1368| VS-mode’s version of supervisor register `stval`, formatted as shown in\n 1369| <>. When V=1, `vstval` substitutes for" + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1369, + "line_text": "<>. When V=1, `vstval` substitutes for", + "context": " 1367| The `vstval` register is a VSXLEN-bit read/write register that is\n 1368| VS-mode’s version of supervisor register `stval`, formatted as shown in\n>>> 1369| <>. When V=1, `vstval` substitutes for\n 1370| the usual `stval`, so instructions that normally read or modify `stval`\n 1371| actually access `vstval` instead. When V=0, `vstval` does not directly" + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1375, + "line_text": "`vstval` is a *WARL* register that must be able to hold the same set of values", + "context": " 1373| \n 1374| [[norm:vstval_warl]]\n>>> 1375| `vstval` is a *WARL* register that must be able to hold the same set of values\n 1376| that `stval` can hold.\n 1377| " + } + ] + }, + { + "parameter_name": "REPORT_VA_IN_VSTVAL_ON_STORE_AMO_MISALIGNED", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 7, + "candidates": [ + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1364, + "line_text": "==== Virtual Supervisor Trap Value (`vstval`) Register", + "context": " 1362| include::images/bytefield/vscausereg.edn[]\n 1363| \n>>> 1364| ==== Virtual Supervisor Trap Value (`vstval`) Register\n 1365| \n 1366| [[norm:vstval_sz_acc_op]]" + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1367, + "line_text": "The `vstval` register is a VSXLEN-bit read/write register that is", + "context": " 1365| \n 1366| [[norm:vstval_sz_acc_op]]\n>>> 1367| The `vstval` register is a VSXLEN-bit read/write register that is\n 1368| VS-mode’s version of supervisor register `stval`, formatted as shown in\n 1369| <>. When V=1, `vstval` substitutes for" + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1369, + "line_text": "<>. When V=1, `vstval` substitutes for", + "context": " 1367| The `vstval` register is a VSXLEN-bit read/write register that is\n 1368| VS-mode’s version of supervisor register `stval`, formatted as shown in\n>>> 1369| <>. When V=1, `vstval` substitutes for\n 1370| the usual `stval`, so instructions that normally read or modify `stval`\n 1371| actually access `vstval` instead. When V=0, `vstval` does not directly" + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1371, + "line_text": "actually access `vstval` instead. When V=0, `vstval` does not directly", + "context": " 1369| <>. When V=1, `vstval` substitutes for\n 1370| the usual `stval`, so instructions that normally read or modify `stval`\n>>> 1371| actually access `vstval` instead. When V=0, `vstval` does not directly\n 1372| affect the behavior of the machine.\n 1373| " + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1375, + "line_text": "`vstval` is a *WARL* register that must be able to hold the same set of values", + "context": " 1373| \n 1374| [[norm:vstval_warl]]\n>>> 1375| `vstval` is a *WARL* register that must be able to hold the same set of values\n 1376| that `stval` can hold.\n 1377| " + } + ] + }, + { + "parameter_name": "REPORT_VA_IN_VSTVAL_ON_STORE_AMO_PAGE_FAULT", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 7, + "candidates": [ + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1364, + "line_text": "==== Virtual Supervisor Trap Value (`vstval`) Register", + "context": " 1362| include::images/bytefield/vscausereg.edn[]\n 1363| \n>>> 1364| ==== Virtual Supervisor Trap Value (`vstval`) Register\n 1365| \n 1366| [[norm:vstval_sz_acc_op]]" + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1367, + "line_text": "The `vstval` register is a VSXLEN-bit read/write register that is", + "context": " 1365| \n 1366| [[norm:vstval_sz_acc_op]]\n>>> 1367| The `vstval` register is a VSXLEN-bit read/write register that is\n 1368| VS-mode’s version of supervisor register `stval`, formatted as shown in\n 1369| <>. When V=1, `vstval` substitutes for" + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1369, + "line_text": "<>. When V=1, `vstval` substitutes for", + "context": " 1367| The `vstval` register is a VSXLEN-bit read/write register that is\n 1368| VS-mode’s version of supervisor register `stval`, formatted as shown in\n>>> 1369| <>. When V=1, `vstval` substitutes for\n 1370| the usual `stval`, so instructions that normally read or modify `stval`\n 1371| actually access `vstval` instead. When V=0, `vstval` does not directly" + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1371, + "line_text": "actually access `vstval` instead. When V=0, `vstval` does not directly", + "context": " 1369| <>. When V=1, `vstval` substitutes for\n 1370| the usual `stval`, so instructions that normally read or modify `stval`\n>>> 1371| actually access `vstval` instead. When V=0, `vstval` does not directly\n 1372| affect the behavior of the machine.\n 1373| " + }, + { + "score": 7, + "reasons": [ + "Name segment 'VSTVAL'", + "Description keyword 'vstval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1375, + "line_text": "`vstval` is a *WARL* register that must be able to hold the same set of values", + "context": " 1373| \n 1374| [[norm:vstval_warl]]\n>>> 1375| `vstval` is a *WARL* register that must be able to hold the same set of values\n 1376| that `stval` can hold.\n 1377| " + } + ] + }, + { + "parameter_name": "RVV_VL_WHEN_AVL_LT_DOUBLE_VLMAX", + "classification": "NORM_DIRECT", + "value_type": "enum", + "num_candidates": 10, + "best_score": 9, + "candidates": [ + { + "score": 9, + "reasons": [ + "Name segment 'VLMAX'", + "Description keyword 'VLMAX'", + "Description keyword 'AVL'", + "Description keyword 'VL'" + ], + "is_normative": true, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 1279, + "line_text": "[#norm:vsetvl_op_rs1_x0_rd_x0]#When _rs1_=`x0` and _rd_=`x0`, the instructions operate as if the current vector length in `vl` is used as the AVL, and the resulting value is written to `vl`, but not to a destination register. This form can only be used when VLMAX and hence `vl` is not actually changed by the new SEW/LMUL ratio.# [#norm:vtype_vset_rsv]#Use of the instructions with a new SEW/LMUL ratio that would result in a change of VLMAX is reserved. Use of the instructions is also reserved if `vill` was 1 beforehand.# [#norm:reserved_vill_set_param]#Implementations may set `vill` in either case.#", + "context": " 1277| also to the `x` register specified by `rd`.\n 1278| \n>>> 1279| [#norm:vsetvl_op_rs1_x0_rd_x0]#When _rs1_=`x0` and _rd_=`x0`, the instructions operate as if the current vector length in `vl` is used as the AVL, and the resulting value is written to `vl`, but not to a destination register. This form can only be used when VLMAX and hence `vl` is not actually changed by the new SEW/LMUL ratio.# [#norm:vtype_vset_rsv]#Use of the instructions with a new SEW/LMUL ratio that would result in a change of VLMAX is reserved. Use of the instructions is also reserved if `vill` was 1 beforehand.# [#norm:reserved_vill_set_param]#Implementations may set `vill` in either case.#\n 1280| \n 1281| NOTE: This last form of the instructions allows the `vtype` register to" + }, + { + "score": 7, + "reasons": [ + "Name segment 'VLMAX'", + "Description keyword 'VLMAX'", + "Description keyword 'AVL'", + "Description keyword 'VL'" + ], + "is_normative": false, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 1276, + "line_text": "is used as the AVL, and the resulting VLMAX is written to `vl` and", + "context": " 1274| [[norm:vsetvl_op_rs1_x0_rd_nx0]]\n 1275| When _rs1_=`x0` but _rd_≠`x0`, the maximum unsigned integer value (`~0`)\n>>> 1276| is used as the AVL, and the resulting VLMAX is written to `vl` and\n 1277| also to the `x` register specified by `rd`.\n 1278| " + }, + { + "score": 7, + "reasons": [ + "Name segment 'VLMAX'", + "Description keyword 'VLMAX'", + "Description keyword 'AVL'", + "Description keyword 'VL'" + ], + "is_normative": false, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 1310, + "line_text": ". `vl = AVL` if `AVL {le} VLMAX`", + "context": " 1308| \n 1309| [[norm:vl_val_list]]\n>>> 1310| . `vl = AVL` if `AVL {le} VLMAX`\n 1311| . `ceil(AVL / 2) {le} vl {le} VLMAX` if `AVL < (2 * VLMAX)`\n 1312| . `vl = VLMAX` if `AVL {ge} (2 * VLMAX)`" + }, + { + "score": 7, + "reasons": [ + "Name segment 'VLMAX'", + "Description keyword 'VLMAX'", + "Description keyword 'AVL'", + "Description keyword 'VL'" + ], + "is_normative": false, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 1311, + "line_text": ". `ceil(AVL / 2) {le} vl {le} VLMAX` if `AVL < (2 * VLMAX)`", + "context": " 1309| [[norm:vl_val_list]]\n 1310| . `vl = AVL` if `AVL {le} VLMAX`\n>>> 1311| . `ceil(AVL / 2) {le} vl {le} VLMAX` if `AVL < (2 * VLMAX)`\n 1312| . `vl = VLMAX` if `AVL {ge} (2 * VLMAX)`\n 1313| . Deterministic on any given implementation for same input AVL and VLMAX values" + }, + { + "score": 7, + "reasons": [ + "Name segment 'VLMAX'", + "Description keyword 'VLMAX'", + "Description keyword 'AVL'", + "Description keyword 'VL'" + ], + "is_normative": false, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 1312, + "line_text": ". `vl = VLMAX` if `AVL {ge} (2 * VLMAX)`", + "context": " 1310| . `vl = AVL` if `AVL {le} VLMAX`\n 1311| . `ceil(AVL / 2) {le} vl {le} VLMAX` if `AVL < (2 * VLMAX)`\n>>> 1312| . `vl = VLMAX` if `AVL {ge} (2 * VLMAX)`\n 1313| . Deterministic on any given implementation for same input AVL and VLMAX values\n 1314| . These specific properties follow from the prior rules:" + } + ] + }, + { + "parameter_name": "SATP_MODE_BARE", + "classification": "NORM_CSR_WARL", + "value_type": "binary", + "num_candidates": 10, + "best_score": 11, + "candidates": [ + { + "score": 11, + "reasons": [ + "Optional/read-only pattern for boolean param", + "CSR name 'satp' in backticks", + "Name segment 'SATP'", + "CSR field name 'MODE'", + "Description keyword 'MODE'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 670, + "line_text": "[#norm:mstatus_sum_rdonly0]#SUM is read-only 0 if S-mode is not supported or if `satp`.MODE is read-only 0.#", + "context": " 668| Note that, [#norm:mstatus_sum_op_mprv_mpp]#while SUM is ordinarily ignored when not\n 669| executing in S-mode, it _is_ in effect when MPRV=1 and MPP=S.#\n>>> 670| [#norm:mstatus_sum_rdonly0]#SUM is read-only 0 if S-mode is not supported or if `satp`.MODE is read-only 0.#\n 671| \n 672| [[norm:mstatus_mxr_sum_op_acc_fault]]" + }, + { + "score": 10, + "reasons": [ + "Optional/read-only pattern for boolean param", + "CSR name 'satp' in backticks", + "Name segment 'SATP'", + "CSR field name 'MODE'", + "Name segment 'BARE'", + "Description keyword 'MODE'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 840, + "line_text": "If `satp`.MODE is read-only zero (always Bare), the implementation may", + "context": " 838| \n 839| [[norm:senvcfg-fiom_acc]]\n>>> 840| If `satp`.MODE is read-only zero (always Bare), the implementation may\n 841| make FIOM read-only zero.\n 842| " + }, + { + "score": 10, + "reasons": [ + "Optional/read-only pattern for boolean param", + "CSR name 'satp' in backticks", + "Name segment 'SATP'", + "CSR field name 'MODE'", + "Name segment 'BARE'", + "Description keyword 'MODE'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 1426, + "line_text": "For implementations that make `satp`.MODE read-only zero (always Bare),", + "context": " 1424| \n 1425| [[norm:satp-mode_roz_sfence_illegal_param]]\n>>> 1426| For implementations that make `satp`.MODE read-only zero (always Bare),\n 1427| attempts to execute an SFENCE.VMA instruction might raise an\n 1428| illegal-instruction exception." + }, + { + "score": 9, + "reasons": [ + "Name segment 'SATP'", + "CSR name 'satp' in backticks", + "WARL + CSR 'satp'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1075, + "line_text": "is for `satp`. Instead, the fields of `hgatp` are *WARL* in the normal way,", + "context": " 1073| [[norm:hgatp-mode_warl]]\n 1074| A write to `hgatp` with an unsupported MODE value is not ignored as it\n>>> 1075| is for `satp`. Instead, the fields of `hgatp` are *WARL* in the normal way,\n 1076| when so indicated.\n 1077| " + }, + { + "score": 9, + "reasons": [ + "Name segment 'SATP'", + "CSR name 'satp' in backticks", + "WARL + CSR 'satp'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1416, + "line_text": "ignored as it is for `satp`, or the fields of `vsatp` are treated as *WARL* in", + "context": " 1414| \n 1415| [#norm:vsatp_mode_unsupported_v0]#When V=0, a write to `vsatp` with an unsupported MODE value is either\n>>> 1416| ignored as it is for `satp`, or the fields of `vsatp` are treated as *WARL* in\n 1417| the normal way.# [#norm:vsatp_mode_unsupported_v1]#However, when V=1, a write to `satp` with an unsupported\n 1418| MODE value _is_ ignored and no write to `vsatp` is effected.#" + } + ] + }, + { + "parameter_name": "SCOUNTENABLE_EN", + "classification": "NORM_CSR_RW", + "value_type": "bitmask", + "num_candidates": 10, + "best_score": 12, + "candidates": [ + { + "score": 12, + "reasons": [ + "Description keyword 'scounteren'", + "CSR field name 'IR'", + "CSR name 'scounteren' in backticks", + "CSR field name 'TM'", + "CSR field name 'CY'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 511, + "line_text": "When the CY, TM, IR, or HPM__n__ bit in the `scounteren` register is", + "context": " 509| \n 510| [[norm:scounteren_op]]\n>>> 511| When the CY, TM, IR, or HPM__n__ bit in the `scounteren` register is\n 512| clear, attempts to read the `cycle`, `time`, `instret`, or `hpmcountern`\n 513| register while executing in U-mode will cause an illegal-instruction" + }, + { + "score": 8, + "reasons": [ + "CSR field name 'IR'", + "CSR field name 'TM'", + "CSR field name 'CY'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1615, + "line_text": "[#norm:mcounteren_clr_ill_inst_exc]#When the CY, TM, IR, or HPM__n__ bit in the `mcounteren` register is", + "context": " 1613| counters, which continue to increment even when not accessible.#\n 1614| \n>>> 1615| [#norm:mcounteren_clr_ill_inst_exc]#When the CY, TM, IR, or HPM__n__ bit in the `mcounteren` register is\n 1616| clear, attempts to read the `cycle`, `time`, `instret`, or\n 1617| `hpmcountern` register while executing in S-mode or U-mode will cause an" + }, + { + "score": 6, + "reasons": [ + "Description keyword 'Zihpm'", + "Description keyword 'Zicntr'" + ], + "is_normative": false, + "in_note": false, + "file": "counters.adoc", + "line_number": 2, + "line_text": "== \"Zicntr\" and \"Zihpm\" Extensions for Counters, Version 2.0", + "context": " 1| [[counters]]\n>>> 2| == \"Zicntr\" and \"Zihpm\" Extensions for Counters, Version 2.0\n 3| \n 4| [[norm:zihpm_op_sz_mode_acc]]" + }, + { + "score": 6, + "reasons": [ + "Description keyword 'Zihpm'", + "Description keyword 'Zicntr'" + ], + "is_normative": false, + "in_note": false, + "file": "counters.adoc", + "line_number": 9, + "line_text": "divided between the \"Zicntr\" and \"Zihpm\" extensions.", + "context": " 7| read-only CSR registers `0xC00`–`0xC1F` (when XLEN=32, the upper 32 bits\n 8| are accessed via CSR registers `0xC80`–`0xC9F`). These counters are\n>>> 9| divided between the \"Zicntr\" and \"Zihpm\" extensions.\n 10| \n 11| === \"Zicntr\" Extension for Base Counters and Timers" + }, + { + "score": 6, + "reasons": [ + "Description keyword 'scounteren'", + "CSR name 'scounteren' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 146, + "line_text": "Some standard supervisor CSRs (`senvcfg`, `scounteren`, and `scontext`,", + "context": " 144| \n 145| [[norm:H_scsrs_nomatch]]\n>>> 146| Some standard supervisor CSRs (`senvcfg`, `scounteren`, and `scontext`,\n 147| possibly others) have no matching VS CSR. These supervisor CSRs continue\n 148| to have their usual function and accessibility even when V=1, except" + } + ] + }, + { + "parameter_name": "SSTATEEN_JVT_TYPE", + "classification": "NORM_CSR_RW", + "value_type": "enum", + "num_candidates": 1, + "best_score": 4, + "candidates": [ + { + "score": 4, + "reasons": [ + "Description keyword 'JVT'" + ], + "is_normative": true, + "in_note": false, + "file": "zc.adoc", + "line_number": 2341, + "line_text": "[#norm:Zcmt_entry_sz]#The base of the table is in the jvt CSR (see <>), each table entry is XLEN bits.#", + "context": " 2339| ==== jvt\n 2340| \n>>> 2341| [#norm:Zcmt_entry_sz]#The base of the table is in the jvt CSR (see <>), each table entry is XLEN bits.#\n 2342| \n 2343| If the same function is called with and without linking then it must have two entries in the table." + } + ] + }, + { + "parameter_name": "STVAL_WIDTH", + "classification": "NORM_DIRECT", + "value_type": "range", + "num_candidates": 10, + "best_score": 6, + "candidates": [ + { + "score": 6, + "reasons": [ + "Name segment 'STVAL'", + "Description keyword 'stval'" + ], + "is_normative": true, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 707, + "line_text": "[[norm:stval]]", + "context": " 705| ==== Supervisor Trap Value (`stval`) Register\n 706| \n>>> 707| [[norm:stval]]\n 708| The `stval` CSR is an SXLEN-bit read-write register formatted as\n 709| shown in <>. When a trap is taken into" + }, + { + "score": 4, + "reasons": [ + "Name segment 'STVAL'", + "Description keyword 'stval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 325, + "line_text": "guest virtual address to `stval`, GVA is set to 1. For any other trap", + "context": " 323| whenever a trap is taken into HS-mode. For any trap (breakpoint, address\n 324| misaligned, access fault, page fault, or guest-page fault) that writes a\n>>> 325| guest virtual address to `stval`, GVA is set to 1. For any other trap\n 326| into HS-mode, GVA is set to 0.\n 327| " + }, + { + "score": 4, + "reasons": [ + "Name segment 'STVAL'", + "Description keyword 'stval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 910, + "line_text": "information, alongside `stval`, to assist software in handling the trap.", + "context": " 908| shown in <>. When a trap is taken into\n 909| HS-mode, `htval` is written with additional exception-specific\n>>> 910| information, alongside `stval`, to assist software in handling the trap.\n 911| \n 912| [[htvalreg]]" + }, + { + "score": 4, + "reasons": [ + "Name segment 'STVAL'", + "Description keyword 'stval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 933, + "line_text": "portion of the access as indicated by the virtual address in `stval`.", + "context": " 931| Otherwise, for misaligned loads and stores that cause guest-page faults,\n 932| a nonzero guest physical address in `htval` corresponds to the faulting\n>>> 933| portion of the access as indicated by the virtual address in `stval`.\n 934| For instruction guest-page faults on systems with variable-length\n 935| instructions, a nonzero `htval` corresponds to the faulting portion of" + }, + { + "score": 4, + "reasons": [ + "Name segment 'STVAL'", + "Description keyword 'stval'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 936, + "line_text": "the instruction as indicated by the virtual address in `stval`.", + "context": " 934| For instruction guest-page faults on systems with variable-length\n 935| instructions, a nonzero `htval` corresponds to the faulting portion of\n>>> 936| the instruction as indicated by the virtual address in `stval`.\n 937| \n 938| [NOTE]" + } + ] + }, + { + "parameter_name": "STVEC_MODE_DIRECT", + "classification": "NORM_CSR_WARL", + "value_type": "binary", + "num_candidates": 10, + "best_score": 8, + "candidates": [ + { + "score": 8, + "reasons": [ + "CSR field name 'MODE'", + "CSR name 'stvec' in backticks", + "Description keyword 'MODE'", + "Name segment 'STVEC'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1304, + "line_text": "VS-mode’s version of supervisor register `stvec`, formatted as shown in", + "context": " 1302| [[norm:vstvec_sz_acc_op]]\n 1303| The `vstvec` register is a VSXLEN-bit read/write register that is\n>>> 1304| VS-mode’s version of supervisor register `stvec`, formatted as shown in\n 1305| <>. When V=1, `vstvec` substitutes for\n 1306| the usual `stvec`, so instructions that normally read or modify `stvec`" + }, + { + "score": 8, + "reasons": [ + "CSR field name 'MODE'", + "CSR name 'stvec' in backticks", + "Description keyword 'MODE'", + "Name segment 'STVEC'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 340, + "line_text": ".Encoding of `stvec` MODE field.", + "context": " 338| \n 339| [[stvec-mode]]\n>>> 340| .Encoding of `stvec` MODE field.\n 341| [%autowidth,float=\"center\",align=\"center\",cols=\">,^,<\",options=\"header\",]\n 342| |===" + }, + { + "score": 7, + "reasons": [ + "Optional/read-only pattern for boolean param", + "CSR field name 'MODE'", + "Description keyword 'MODE'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 423, + "line_text": "[#norm:mstatus_sie_spie_rdonly0]#If supervisor mode is not implemented, then SIE and SPIE are read-only 0.#", + "context": " 421| to disable selected higher-privilege-mode interrupts before ceding\n 422| control to a lower-privilege mode.\n>>> 423| [#norm:mstatus_sie_spie_rdonly0]#If supervisor mode is not implemented, then SIE and SPIE are read-only 0.#\n 424| \n 425| [NOTE]" + }, + { + "score": 7, + "reasons": [ + "Optional/read-only pattern for boolean param", + "CSR field name 'MODE'", + "Description keyword 'MODE'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 479, + "line_text": "[#norm:mstatus_xpp_rdonly0]#If privilege mode _x_ is not implemented, then __x__PP must be read-only 0.#", + "context": " 477| \n 478| [#norm:mstatus_xpp_warl]#__x__PP fields are *WARL* fields that can hold only privilege mode _x_ and any implemented privilege mode lower than _x_.#\n>>> 479| [#norm:mstatus_xpp_rdonly0]#If privilege mode _x_ is not implemented, then __x__PP must be read-only 0.#\n 480| \n 481| [NOTE]" + }, + { + "score": 7, + "reasons": [ + "Optional/read-only pattern for boolean param", + "CSR field name 'MODE'", + "Description keyword 'MODE'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 577, + "line_text": "[#norm:mstatus_sxl_acc_mxlen64]#When MXLEN=64, if S-mode is not supported, then SXL is read-only zero.", + "context": " 575| When MXLEN=32, the SXL and UXL fields do not exist, and SXLEN=32 and UXLEN=32.\n 576| \n>>> 577| [#norm:mstatus_sxl_acc_mxlen64]#When MXLEN=64, if S-mode is not supported, then SXL is read-only zero.\n 578| Otherwise, it is a *WARL* field that encodes the current value of SXLEN.#\n 579| In particular, [#norm:mstatus_sxl_rdonly_mxlen64]#an implementation may make SXL be a read-only field whose" + } + ] + }, + { + "parameter_name": "STVEC_MODE_VECTORED", + "classification": "NORM_CSR_WARL", + "value_type": "binary", + "num_candidates": 10, + "best_score": 9, + "candidates": [ + { + "score": 9, + "reasons": [ + "Name segment 'VECTORED'", + "Description keyword 'MODE'", + "Description keyword 'vectored'", + "CSR field name 'MODE'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1256, + "line_text": "[#norm:mtvec_mode_vectored_op]#When MODE=Vectored, all synchronous exceptions into machine mode cause", + "context": " 1254| [#norm:mtvec_mode_direct_op]#When MODE=Direct, all traps into\n 1255| machine mode cause the `pc` to be set to the address in the BASE field.#\n>>> 1256| [#norm:mtvec_mode_vectored_op]#When MODE=Vectored, all synchronous exceptions into machine mode cause\n 1257| the `pc` to be set to the address in the BASE field, whereas interrupts\n 1258| cause the `pc` to be set to the address in the BASE field plus four" + }, + { + "score": 8, + "reasons": [ + "CSR field name 'MODE'", + "CSR name 'stvec' in backticks", + "Description keyword 'MODE'", + "Name segment 'STVEC'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1304, + "line_text": "VS-mode’s version of supervisor register `stvec`, formatted as shown in", + "context": " 1302| [[norm:vstvec_sz_acc_op]]\n 1303| The `vstvec` register is a VSXLEN-bit read/write register that is\n>>> 1304| VS-mode’s version of supervisor register `stvec`, formatted as shown in\n 1305| <>. When V=1, `vstvec` substitutes for\n 1306| the usual `stvec`, so instructions that normally read or modify `stvec`" + }, + { + "score": 8, + "reasons": [ + "CSR field name 'MODE'", + "CSR name 'stvec' in backticks", + "Description keyword 'MODE'", + "Name segment 'STVEC'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 340, + "line_text": ".Encoding of `stvec` MODE field.", + "context": " 338| \n 339| [[stvec-mode]]\n>>> 340| .Encoding of `stvec` MODE field.\n 341| [%autowidth,float=\"center\",align=\"center\",cols=\">,^,<\",options=\"header\",]\n 342| |===" + }, + { + "score": 7, + "reasons": [ + "Optional/read-only pattern for boolean param", + "CSR field name 'MODE'", + "Description keyword 'MODE'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 423, + "line_text": "[#norm:mstatus_sie_spie_rdonly0]#If supervisor mode is not implemented, then SIE and SPIE are read-only 0.#", + "context": " 421| to disable selected higher-privilege-mode interrupts before ceding\n 422| control to a lower-privilege mode.\n>>> 423| [#norm:mstatus_sie_spie_rdonly0]#If supervisor mode is not implemented, then SIE and SPIE are read-only 0.#\n 424| \n 425| [NOTE]" + }, + { + "score": 7, + "reasons": [ + "Optional/read-only pattern for boolean param", + "CSR field name 'MODE'", + "Description keyword 'MODE'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 479, + "line_text": "[#norm:mstatus_xpp_rdonly0]#If privilege mode _x_ is not implemented, then __x__PP must be read-only 0.#", + "context": " 477| \n 478| [#norm:mstatus_xpp_warl]#__x__PP fields are *WARL* fields that can hold only privilege mode _x_ and any implemented privilege mode lower than _x_.#\n>>> 479| [#norm:mstatus_xpp_rdonly0]#If privilege mode _x_ is not implemented, then __x__PP must be read-only 0.#\n 480| \n 481| [NOTE]" + } + ] + }, + { + "parameter_name": "SV32X4_TRANSLATION", + "classification": "NORM_CSR_WARL", + "value_type": "binary", + "num_candidates": 10, + "best_score": 9, + "candidates": [ + { + "score": 9, + "reasons": [ + "CSR field name 'MODE'", + "Name segment 'SV32X4'", + "Name segment 'TRANSLATION'", + "Description keyword 'translation'", + "CSR name 'hgatp' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1915, + "line_text": "When `hgatp`.MODE specifies a translation scheme of Sv32x4, Sv39x4,", + "context": " 1913| \n 1914| [[norm:hgatp-mode_x4]]\n>>> 1915| When `hgatp`.MODE specifies a translation scheme of Sv32x4, Sv39x4,\n 1916| Sv48x4, or Sv57x4, G-stage address translation is a variation on the\n 1917| usual page-based virtual address translation scheme of Sv32, Sv39, Sv48," + }, + { + "score": 8, + "reasons": [ + "CSR field name 'MODE'", + "Description keyword 'translation'", + "Name segment 'TRANSLATION'", + "CSR name 'hgatp' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1007, + "line_text": ".Hypervisor guest address translation and protection register `hgatp` when HSXLEN=64 for MODE values Bare, Sv39x4, Sv48x4, and Sv57x4.", + "context": " 1005| \n 1006| [[rv64hgatp]]\n>>> 1007| .Hypervisor guest address translation and protection register `hgatp` when HSXLEN=64 for MODE values Bare, Sv39x4, Sv48x4, and Sv57x4.\n 1008| include::images/bytefield/rv64hgatp.edn[]\n 1009| " + }, + { + "score": 8, + "reasons": [ + "WARL + CSR 'hgatp'", + "CSR name 'hgatp' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1075, + "line_text": "is for `satp`. Instead, the fields of `hgatp` are *WARL* in the normal way,", + "context": " 1073| [[norm:hgatp-mode_warl]]\n 1074| A write to `hgatp` with an unsupported MODE value is not ignored as it\n>>> 1075| is for `satp`. Instead, the fields of `hgatp` are *WARL* in the normal way,\n 1076| when so indicated.\n 1077| " + }, + { + "score": 8, + "reasons": [ + "CSR field name 'MODE'", + "Description keyword 'translation'", + "Name segment 'TRANSLATION'", + "CSR name 'hgatp' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2152, + "line_text": "is less than GPA width supported by the `hgatp` translation mode of that guest.", + "context": " 2150| supported by `hgatp.MODE`, hypervisors should execute an `HFENCE.GVMA` with\n 2151| _rs1_=`x0` if the `henvcfg.PMM` is changed from or to a value where (XLEN-PMLEN)\n>>> 2152| is less than GPA width supported by the `hgatp` translation mode of that guest.\n 2153| Specifically, these cases are:\n 2154| " + }, + { + "score": 6, + "reasons": [ + "Description keyword 'translation'", + "Name segment 'TRANSLATION'", + "CSR name 'hgatp' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 987, + "line_text": "==== Hypervisor Guest Address Translation and Protection (`hgatp`) Register", + "context": " 985| \n 986| [[hgatp]]\n>>> 987| ==== Hypervisor Guest Address Translation and Protection (`hgatp`) Register\n 988| \n 989| [#norm:hgatp_sz_acc_op]#The `hgatp` register is an HSXLEN-bit read/write register, formatted as" + } + ] + }, + { + "parameter_name": "SV32_VSMODE_TRANSLATION", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 5, + "candidates": [ + { + "score": 5, + "reasons": [ + "Description keyword 'translation'", + "Name segment 'TRANSLATION'" + ], + "is_normative": true, + "in_note": false, + "file": "cmo.adoc", + "line_number": 365, + "line_text": "otherwise.# [#norm:cbm_unperm_translate]#During address translation, the instruction also checks the accessed", + "context": " 363| raises a store page-fault or store guest-page-fault exception if address\n 364| translation does not permit any access or raises a store access-fault exception\n>>> 365| otherwise.# [#norm:cbm_unperm_translate]#During address translation, the instruction also checks the accessed\n 366| bit and may either raise an exception or set the bit as required.#\n 367| " + }, + { + "score": 5, + "reasons": [ + "Description keyword 'translation'", + "Name segment 'TRANSLATION'" + ], + "is_normative": true, + "in_note": false, + "file": "cmo.adoc", + "line_number": 383, + "line_text": "access-fault exception otherwise.# [#norm:cbz_unperm_translate]#During address translation, the instruction", + "context": " 381| cache-block zero instruction raises a store page-fault or store guest-page-fault\n 382| exception if address translation does not permit write access or raises a store\n>>> 383| access-fault exception otherwise.# [#norm:cbz_unperm_translate]#During address translation, the instruction\n 384| also checks the accessed and dirty bits and may either raise an exception or set\n 385| the bits as required.#" + }, + { + "score": 5, + "reasons": [ + "Description keyword 'translation'", + "Name segment 'TRANSLATION'", + "Description keyword 'VS'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 730, + "line_text": "in VS-stage address translation. When PBMTE=1, Svpbmt is available for", + "context": " 728| [[norm:henvcfg-pbmte_op]]\n 729| The PBMTE bit controls whether the Svpbmt extension is available for use\n>>> 730| in VS-stage address translation. When PBMTE=1, Svpbmt is available for\n 731| VS-stage address translation. When PBMTE=0, the implementation behaves\n 732| as though Svpbmt were not implemented for VS-stage address translation." + }, + { + "score": 5, + "reasons": [ + "Description keyword 'translation'", + "Name segment 'TRANSLATION'", + "Description keyword 'VS'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 731, + "line_text": "VS-stage address translation. When PBMTE=0, the implementation behaves", + "context": " 729| The PBMTE bit controls whether the Svpbmt extension is available for use\n 730| in VS-stage address translation. When PBMTE=1, Svpbmt is available for\n>>> 731| VS-stage address translation. When PBMTE=0, the implementation behaves\n 732| as though Svpbmt were not implemented for VS-stage address translation.\n 733| If Svpbmt is not implemented, PBMTE is read-only zero." + }, + { + "score": 5, + "reasons": [ + "Description keyword 'translation'", + "Name segment 'TRANSLATION'", + "Description keyword 'VS'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 732, + "line_text": "as though Svpbmt were not implemented for VS-stage address translation.", + "context": " 730| in VS-stage address translation. When PBMTE=1, Svpbmt is available for\n 731| VS-stage address translation. When PBMTE=0, the implementation behaves\n>>> 732| as though Svpbmt were not implemented for VS-stage address translation.\n 733| If Svpbmt is not implemented, PBMTE is read-only zero.\n 734| " + } + ] + }, + { + "parameter_name": "SV39X4_TRANSLATION", + "classification": "NORM_CSR_WARL", + "value_type": "binary", + "num_candidates": 10, + "best_score": 9, + "candidates": [ + { + "score": 9, + "reasons": [ + "CSR field name 'MODE'", + "Name segment 'TRANSLATION'", + "Description keyword 'translation'", + "Name segment 'SV39X4'", + "CSR name 'hgatp' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1007, + "line_text": ".Hypervisor guest address translation and protection register `hgatp` when HSXLEN=64 for MODE values Bare, Sv39x4, Sv48x4, and Sv57x4.", + "context": " 1005| \n 1006| [[rv64hgatp]]\n>>> 1007| .Hypervisor guest address translation and protection register `hgatp` when HSXLEN=64 for MODE values Bare, Sv39x4, Sv48x4, and Sv57x4.\n 1008| include::images/bytefield/rv64hgatp.edn[]\n 1009| " + }, + { + "score": 9, + "reasons": [ + "CSR field name 'MODE'", + "Name segment 'TRANSLATION'", + "Description keyword 'translation'", + "Name segment 'SV39X4'", + "CSR name 'hgatp' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1915, + "line_text": "When `hgatp`.MODE specifies a translation scheme of Sv32x4, Sv39x4,", + "context": " 1913| \n 1914| [[norm:hgatp-mode_x4]]\n>>> 1915| When `hgatp`.MODE specifies a translation scheme of Sv32x4, Sv39x4,\n 1916| Sv48x4, or Sv57x4, G-stage address translation is a variation on the\n 1917| usual page-based virtual address translation scheme of Sv32, Sv39, Sv48," + }, + { + "score": 8, + "reasons": [ + "WARL + CSR 'hgatp'", + "CSR name 'hgatp' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1075, + "line_text": "is for `satp`. Instead, the fields of `hgatp` are *WARL* in the normal way,", + "context": " 1073| [[norm:hgatp-mode_warl]]\n 1074| A write to `hgatp` with an unsupported MODE value is not ignored as it\n>>> 1075| is for `satp`. Instead, the fields of `hgatp` are *WARL* in the normal way,\n 1076| when so indicated.\n 1077| " + }, + { + "score": 8, + "reasons": [ + "CSR field name 'MODE'", + "Description keyword 'translation'", + "Name segment 'TRANSLATION'", + "CSR name 'hgatp' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2152, + "line_text": "is less than GPA width supported by the `hgatp` translation mode of that guest.", + "context": " 2150| supported by `hgatp.MODE`, hypervisors should execute an `HFENCE.GVMA` with\n 2151| _rs1_=`x0` if the `henvcfg.PMM` is changed from or to a value where (XLEN-PMLEN)\n>>> 2152| is less than GPA width supported by the `hgatp` translation mode of that guest.\n 2153| Specifically, these cases are:\n 2154| " + }, + { + "score": 6, + "reasons": [ + "Description keyword 'translation'", + "Name segment 'TRANSLATION'", + "CSR name 'hgatp' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 987, + "line_text": "==== Hypervisor Guest Address Translation and Protection (`hgatp`) Register", + "context": " 985| \n 986| [[hgatp]]\n>>> 987| ==== Hypervisor Guest Address Translation and Protection (`hgatp`) Register\n 988| \n 989| [#norm:hgatp_sz_acc_op]#The `hgatp` register is an HSXLEN-bit read/write register, formatted as" + } + ] + }, + { + "parameter_name": "SV39_VSMODE_TRANSLATION", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 5, + "candidates": [ + { + "score": 5, + "reasons": [ + "Description keyword 'translation'", + "Name segment 'TRANSLATION'" + ], + "is_normative": true, + "in_note": false, + "file": "cmo.adoc", + "line_number": 365, + "line_text": "otherwise.# [#norm:cbm_unperm_translate]#During address translation, the instruction also checks the accessed", + "context": " 363| raises a store page-fault or store guest-page-fault exception if address\n 364| translation does not permit any access or raises a store access-fault exception\n>>> 365| otherwise.# [#norm:cbm_unperm_translate]#During address translation, the instruction also checks the accessed\n 366| bit and may either raise an exception or set the bit as required.#\n 367| " + }, + { + "score": 5, + "reasons": [ + "Description keyword 'translation'", + "Name segment 'TRANSLATION'" + ], + "is_normative": true, + "in_note": false, + "file": "cmo.adoc", + "line_number": 383, + "line_text": "access-fault exception otherwise.# [#norm:cbz_unperm_translate]#During address translation, the instruction", + "context": " 381| cache-block zero instruction raises a store page-fault or store guest-page-fault\n 382| exception if address translation does not permit write access or raises a store\n>>> 383| access-fault exception otherwise.# [#norm:cbz_unperm_translate]#During address translation, the instruction\n 384| also checks the accessed and dirty bits and may either raise an exception or set\n 385| the bits as required.#" + }, + { + "score": 5, + "reasons": [ + "Description keyword 'translation'", + "Name segment 'TRANSLATION'", + "Description keyword 'VS'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 730, + "line_text": "in VS-stage address translation. When PBMTE=1, Svpbmt is available for", + "context": " 728| [[norm:henvcfg-pbmte_op]]\n 729| The PBMTE bit controls whether the Svpbmt extension is available for use\n>>> 730| in VS-stage address translation. When PBMTE=1, Svpbmt is available for\n 731| VS-stage address translation. When PBMTE=0, the implementation behaves\n 732| as though Svpbmt were not implemented for VS-stage address translation." + }, + { + "score": 5, + "reasons": [ + "Description keyword 'translation'", + "Name segment 'TRANSLATION'", + "Description keyword 'VS'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 731, + "line_text": "VS-stage address translation. When PBMTE=0, the implementation behaves", + "context": " 729| The PBMTE bit controls whether the Svpbmt extension is available for use\n 730| in VS-stage address translation. When PBMTE=1, Svpbmt is available for\n>>> 731| VS-stage address translation. When PBMTE=0, the implementation behaves\n 732| as though Svpbmt were not implemented for VS-stage address translation.\n 733| If Svpbmt is not implemented, PBMTE is read-only zero." + }, + { + "score": 5, + "reasons": [ + "Description keyword 'translation'", + "Name segment 'TRANSLATION'", + "Description keyword 'VS'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 732, + "line_text": "as though Svpbmt were not implemented for VS-stage address translation.", + "context": " 730| in VS-stage address translation. When PBMTE=1, Svpbmt is available for\n 731| VS-stage address translation. When PBMTE=0, the implementation behaves\n>>> 732| as though Svpbmt were not implemented for VS-stage address translation.\n 733| If Svpbmt is not implemented, PBMTE is read-only zero.\n 734| " + } + ] + }, + { + "parameter_name": "SV48X4_TRANSLATION", + "classification": "NORM_CSR_WARL", + "value_type": "binary", + "num_candidates": 10, + "best_score": 9, + "candidates": [ + { + "score": 9, + "reasons": [ + "CSR field name 'MODE'", + "Name segment 'TRANSLATION'", + "Description keyword 'translation'", + "CSR name 'hgatp' in backticks", + "Name segment 'SV48X4'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1007, + "line_text": ".Hypervisor guest address translation and protection register `hgatp` when HSXLEN=64 for MODE values Bare, Sv39x4, Sv48x4, and Sv57x4.", + "context": " 1005| \n 1006| [[rv64hgatp]]\n>>> 1007| .Hypervisor guest address translation and protection register `hgatp` when HSXLEN=64 for MODE values Bare, Sv39x4, Sv48x4, and Sv57x4.\n 1008| include::images/bytefield/rv64hgatp.edn[]\n 1009| " + }, + { + "score": 8, + "reasons": [ + "WARL + CSR 'hgatp'", + "CSR name 'hgatp' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1075, + "line_text": "is for `satp`. Instead, the fields of `hgatp` are *WARL* in the normal way,", + "context": " 1073| [[norm:hgatp-mode_warl]]\n 1074| A write to `hgatp` with an unsupported MODE value is not ignored as it\n>>> 1075| is for `satp`. Instead, the fields of `hgatp` are *WARL* in the normal way,\n 1076| when so indicated.\n 1077| " + }, + { + "score": 8, + "reasons": [ + "CSR field name 'MODE'", + "Description keyword 'translation'", + "Name segment 'TRANSLATION'", + "CSR name 'hgatp' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1915, + "line_text": "When `hgatp`.MODE specifies a translation scheme of Sv32x4, Sv39x4,", + "context": " 1913| \n 1914| [[norm:hgatp-mode_x4]]\n>>> 1915| When `hgatp`.MODE specifies a translation scheme of Sv32x4, Sv39x4,\n 1916| Sv48x4, or Sv57x4, G-stage address translation is a variation on the\n 1917| usual page-based virtual address translation scheme of Sv32, Sv39, Sv48," + }, + { + "score": 8, + "reasons": [ + "CSR field name 'MODE'", + "Description keyword 'translation'", + "Name segment 'TRANSLATION'", + "CSR name 'hgatp' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2152, + "line_text": "is less than GPA width supported by the `hgatp` translation mode of that guest.", + "context": " 2150| supported by `hgatp.MODE`, hypervisors should execute an `HFENCE.GVMA` with\n 2151| _rs1_=`x0` if the `henvcfg.PMM` is changed from or to a value where (XLEN-PMLEN)\n>>> 2152| is less than GPA width supported by the `hgatp` translation mode of that guest.\n 2153| Specifically, these cases are:\n 2154| " + }, + { + "score": 6, + "reasons": [ + "Description keyword 'translation'", + "Name segment 'TRANSLATION'", + "CSR name 'hgatp' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 987, + "line_text": "==== Hypervisor Guest Address Translation and Protection (`hgatp`) Register", + "context": " 985| \n 986| [[hgatp]]\n>>> 987| ==== Hypervisor Guest Address Translation and Protection (`hgatp`) Register\n 988| \n 989| [#norm:hgatp_sz_acc_op]#The `hgatp` register is an HSXLEN-bit read/write register, formatted as" + } + ] + }, + { + "parameter_name": "SV48_VSMODE_TRANSLATION", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 5, + "candidates": [ + { + "score": 5, + "reasons": [ + "Description keyword 'translation'", + "Name segment 'TRANSLATION'" + ], + "is_normative": true, + "in_note": false, + "file": "cmo.adoc", + "line_number": 365, + "line_text": "otherwise.# [#norm:cbm_unperm_translate]#During address translation, the instruction also checks the accessed", + "context": " 363| raises a store page-fault or store guest-page-fault exception if address\n 364| translation does not permit any access or raises a store access-fault exception\n>>> 365| otherwise.# [#norm:cbm_unperm_translate]#During address translation, the instruction also checks the accessed\n 366| bit and may either raise an exception or set the bit as required.#\n 367| " + }, + { + "score": 5, + "reasons": [ + "Description keyword 'translation'", + "Name segment 'TRANSLATION'" + ], + "is_normative": true, + "in_note": false, + "file": "cmo.adoc", + "line_number": 383, + "line_text": "access-fault exception otherwise.# [#norm:cbz_unperm_translate]#During address translation, the instruction", + "context": " 381| cache-block zero instruction raises a store page-fault or store guest-page-fault\n 382| exception if address translation does not permit write access or raises a store\n>>> 383| access-fault exception otherwise.# [#norm:cbz_unperm_translate]#During address translation, the instruction\n 384| also checks the accessed and dirty bits and may either raise an exception or set\n 385| the bits as required.#" + }, + { + "score": 5, + "reasons": [ + "Description keyword 'translation'", + "Name segment 'TRANSLATION'", + "Description keyword 'VS'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 730, + "line_text": "in VS-stage address translation. When PBMTE=1, Svpbmt is available for", + "context": " 728| [[norm:henvcfg-pbmte_op]]\n 729| The PBMTE bit controls whether the Svpbmt extension is available for use\n>>> 730| in VS-stage address translation. When PBMTE=1, Svpbmt is available for\n 731| VS-stage address translation. When PBMTE=0, the implementation behaves\n 732| as though Svpbmt were not implemented for VS-stage address translation." + }, + { + "score": 5, + "reasons": [ + "Description keyword 'translation'", + "Name segment 'TRANSLATION'", + "Description keyword 'VS'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 731, + "line_text": "VS-stage address translation. When PBMTE=0, the implementation behaves", + "context": " 729| The PBMTE bit controls whether the Svpbmt extension is available for use\n 730| in VS-stage address translation. When PBMTE=1, Svpbmt is available for\n>>> 731| VS-stage address translation. When PBMTE=0, the implementation behaves\n 732| as though Svpbmt were not implemented for VS-stage address translation.\n 733| If Svpbmt is not implemented, PBMTE is read-only zero." + }, + { + "score": 5, + "reasons": [ + "Description keyword 'translation'", + "Name segment 'TRANSLATION'", + "Description keyword 'VS'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 732, + "line_text": "as though Svpbmt were not implemented for VS-stage address translation.", + "context": " 730| in VS-stage address translation. When PBMTE=1, Svpbmt is available for\n 731| VS-stage address translation. When PBMTE=0, the implementation behaves\n>>> 732| as though Svpbmt were not implemented for VS-stage address translation.\n 733| If Svpbmt is not implemented, PBMTE is read-only zero.\n 734| " + } + ] + }, + { + "parameter_name": "SV57X4_TRANSLATION", + "classification": "NORM_CSR_WARL", + "value_type": "binary", + "num_candidates": 10, + "best_score": 9, + "candidates": [ + { + "score": 9, + "reasons": [ + "CSR field name 'MODE'", + "Name segment 'TRANSLATION'", + "Description keyword 'translation'", + "CSR name 'hgatp' in backticks", + "Name segment 'SV57X4'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1007, + "line_text": ".Hypervisor guest address translation and protection register `hgatp` when HSXLEN=64 for MODE values Bare, Sv39x4, Sv48x4, and Sv57x4.", + "context": " 1005| \n 1006| [[rv64hgatp]]\n>>> 1007| .Hypervisor guest address translation and protection register `hgatp` when HSXLEN=64 for MODE values Bare, Sv39x4, Sv48x4, and Sv57x4.\n 1008| include::images/bytefield/rv64hgatp.edn[]\n 1009| " + }, + { + "score": 8, + "reasons": [ + "WARL + CSR 'hgatp'", + "CSR name 'hgatp' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1075, + "line_text": "is for `satp`. Instead, the fields of `hgatp` are *WARL* in the normal way,", + "context": " 1073| [[norm:hgatp-mode_warl]]\n 1074| A write to `hgatp` with an unsupported MODE value is not ignored as it\n>>> 1075| is for `satp`. Instead, the fields of `hgatp` are *WARL* in the normal way,\n 1076| when so indicated.\n 1077| " + }, + { + "score": 8, + "reasons": [ + "CSR field name 'MODE'", + "Description keyword 'translation'", + "Name segment 'TRANSLATION'", + "CSR name 'hgatp' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1915, + "line_text": "When `hgatp`.MODE specifies a translation scheme of Sv32x4, Sv39x4,", + "context": " 1913| \n 1914| [[norm:hgatp-mode_x4]]\n>>> 1915| When `hgatp`.MODE specifies a translation scheme of Sv32x4, Sv39x4,\n 1916| Sv48x4, or Sv57x4, G-stage address translation is a variation on the\n 1917| usual page-based virtual address translation scheme of Sv32, Sv39, Sv48," + }, + { + "score": 8, + "reasons": [ + "CSR field name 'MODE'", + "Description keyword 'translation'", + "Name segment 'TRANSLATION'", + "CSR name 'hgatp' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2152, + "line_text": "is less than GPA width supported by the `hgatp` translation mode of that guest.", + "context": " 2150| supported by `hgatp.MODE`, hypervisors should execute an `HFENCE.GVMA` with\n 2151| _rs1_=`x0` if the `henvcfg.PMM` is changed from or to a value where (XLEN-PMLEN)\n>>> 2152| is less than GPA width supported by the `hgatp` translation mode of that guest.\n 2153| Specifically, these cases are:\n 2154| " + }, + { + "score": 6, + "reasons": [ + "Description keyword 'translation'", + "Name segment 'TRANSLATION'", + "CSR name 'hgatp' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 987, + "line_text": "==== Hypervisor Guest Address Translation and Protection (`hgatp`) Register", + "context": " 985| \n 986| [[hgatp]]\n>>> 987| ==== Hypervisor Guest Address Translation and Protection (`hgatp`) Register\n 988| \n 989| [#norm:hgatp_sz_acc_op]#The `hgatp` register is an HSXLEN-bit read/write register, formatted as" + } + ] + }, + { + "parameter_name": "SV57_VSMODE_TRANSLATION", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 5, + "candidates": [ + { + "score": 5, + "reasons": [ + "Description keyword 'translation'", + "Name segment 'TRANSLATION'" + ], + "is_normative": true, + "in_note": false, + "file": "cmo.adoc", + "line_number": 365, + "line_text": "otherwise.# [#norm:cbm_unperm_translate]#During address translation, the instruction also checks the accessed", + "context": " 363| raises a store page-fault or store guest-page-fault exception if address\n 364| translation does not permit any access or raises a store access-fault exception\n>>> 365| otherwise.# [#norm:cbm_unperm_translate]#During address translation, the instruction also checks the accessed\n 366| bit and may either raise an exception or set the bit as required.#\n 367| " + }, + { + "score": 5, + "reasons": [ + "Description keyword 'translation'", + "Name segment 'TRANSLATION'" + ], + "is_normative": true, + "in_note": false, + "file": "cmo.adoc", + "line_number": 383, + "line_text": "access-fault exception otherwise.# [#norm:cbz_unperm_translate]#During address translation, the instruction", + "context": " 381| cache-block zero instruction raises a store page-fault or store guest-page-fault\n 382| exception if address translation does not permit write access or raises a store\n>>> 383| access-fault exception otherwise.# [#norm:cbz_unperm_translate]#During address translation, the instruction\n 384| also checks the accessed and dirty bits and may either raise an exception or set\n 385| the bits as required.#" + }, + { + "score": 5, + "reasons": [ + "Description keyword 'translation'", + "Name segment 'TRANSLATION'", + "Description keyword 'VS'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 730, + "line_text": "in VS-stage address translation. When PBMTE=1, Svpbmt is available for", + "context": " 728| [[norm:henvcfg-pbmte_op]]\n 729| The PBMTE bit controls whether the Svpbmt extension is available for use\n>>> 730| in VS-stage address translation. When PBMTE=1, Svpbmt is available for\n 731| VS-stage address translation. When PBMTE=0, the implementation behaves\n 732| as though Svpbmt were not implemented for VS-stage address translation." + }, + { + "score": 5, + "reasons": [ + "Description keyword 'translation'", + "Name segment 'TRANSLATION'", + "Description keyword 'VS'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 731, + "line_text": "VS-stage address translation. When PBMTE=0, the implementation behaves", + "context": " 729| The PBMTE bit controls whether the Svpbmt extension is available for use\n 730| in VS-stage address translation. When PBMTE=1, Svpbmt is available for\n>>> 731| VS-stage address translation. When PBMTE=0, the implementation behaves\n 732| as though Svpbmt were not implemented for VS-stage address translation.\n 733| If Svpbmt is not implemented, PBMTE is read-only zero." + }, + { + "score": 5, + "reasons": [ + "Description keyword 'translation'", + "Name segment 'TRANSLATION'", + "Description keyword 'VS'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 732, + "line_text": "as though Svpbmt were not implemented for VS-stage address translation.", + "context": " 730| in VS-stage address translation. When PBMTE=1, Svpbmt is available for\n 731| VS-stage address translation. When PBMTE=0, the implementation behaves\n>>> 732| as though Svpbmt were not implemented for VS-stage address translation.\n 733| If Svpbmt is not implemented, PBMTE is read-only zero.\n 734| " + } + ] + }, + { + "parameter_name": "SXLEN", + "classification": "NORM_DIRECT", + "value_type": "set", + "num_candidates": 10, + "best_score": 11, + "candidates": [ + { + "score": 11, + "reasons": [ + "Description keyword 'SXL'", + "Name segment 'SXLEN'", + "Exact parameter name 'SXLEN'", + "CSR field name 'SXL'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 575, + "line_text": "When MXLEN=32, the SXL and UXL fields do not exist, and SXLEN=32 and UXLEN=32.", + "context": " 573| \n 574| [[norm:mstatus_sxl_uxl_sxlen_uxlen_mxlen32]]\n>>> 575| When MXLEN=32, the SXL and UXL fields do not exist, and SXLEN=32 and UXLEN=32.\n 576| \n 577| [#norm:mstatus_sxl_acc_mxlen64]#When MXLEN=64, if S-mode is not supported, then SXL is read-only zero." + }, + { + "score": 9, + "reasons": [ + "CSR name 'mstatus' in backticks", + "Description keyword 'SXL'", + "CSR field name 'SXL'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 393, + "line_text": "[#norm:mstatush_enc]#Bits 30:4 of `mstatush` generally contain the same fields found in bits 62:36 of `mstatus` for RV64. Fields SD, SXL, and UXL do not exist in `mstatush`.#", + "context": " 391| \n 392| [#norm:mstatush_sz_acc]#For RV32 only, `mstatush` is a 32-bit read/write register formatted as shown in <>.#\n>>> 393| [#norm:mstatush_enc]#Bits 30:4 of `mstatush` generally contain the same fields found in bits 62:36 of `mstatus` for RV64. Fields SD, SXL, and UXL do not exist in `mstatush`.#\n 394| \n 395| [[mstatushreg]]" + }, + { + "score": 8, + "reasons": [ + "Parameter name in emphasis '_SXLEN_'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 572, + "line_text": "[#norm:sxlen_uxlen]#The effective XLEN in S-mode and U-mode are termed _SXLEN_ and _UXLEN_, respectively.#", + "context": " 570| value of XLEN for S-mode and U-mode, respectively.#\n 571| [#norm:mstatus_sxl_uxl_enc]#The encoding of these fields is the same as the MXL field of `misa`, shown in <>.#\n>>> 572| [#norm:sxlen_uxlen]#The effective XLEN in S-mode and U-mode are termed _SXLEN_ and _UXLEN_, respectively.#\n 573| \n 574| [[norm:mstatus_sxl_uxl_sxlen_uxlen_mxlen32]]" + }, + { + "score": 7, + "reasons": [ + "Name segment 'SXLEN'", + "Exact parameter name 'SXLEN'" + ], + "is_normative": false, + "in_note": false, + "file": "indirect-csr.adoc", + "line_number": 201, + "line_text": "current XLEN rather than SXLEN. Hence, for example, if MXLEN = 64 and", + "context": " 199| \n 200| Note that the widths of `siselect` and `sireg*` are always the\n>>> 201| current XLEN rather than SXLEN. Hence, for example, if MXLEN = 64 and\n 202| SXLEN = 32, then these registers are 64 bits when the current privilege\n 203| mode is M (running RV64 code) but 32 bits when the privilege mode is S" + }, + { + "score": 7, + "reasons": [ + "Name segment 'SXLEN'", + "Exact parameter name 'SXLEN'" + ], + "is_normative": false, + "in_note": false, + "file": "indirect-csr.adoc", + "line_number": 202, + "line_text": "SXLEN = 32, then these registers are 64 bits when the current privilege", + "context": " 200| Note that the widths of `siselect` and `sireg*` are always the\n 201| current XLEN rather than SXLEN. Hence, for example, if MXLEN = 64 and\n>>> 202| SXLEN = 32, then these registers are 64 bits when the current privilege\n 203| mode is M (running RV64 code) but 32 bits when the privilege mode is S\n 204| (RV32 code)." + } + ] + }, + { + "parameter_name": "S_MODE_ENDIANNESS", + "classification": "NORM_CSR_RW", + "value_type": "enum", + "num_candidates": 10, + "best_score": 22, + "candidates": [ + { + "score": 22, + "reasons": [ + "WARL + CSR 'mstatush'", + "CSR field name 'SBE'", + "CSR name 'mstatus' in backticks", + "Description keyword 'SBE'", + "CSR name 'mstatush' in backticks", + "WARL + CSR 'mstatus'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 679, + "line_text": "[#norm:mstatus_mstatush_xbe_warl]#The MBE, SBE, and UBE bits in `mstatus` and `mstatush` are *WARL* fields# that", + "context": " 677| ===== Endianness Control in `mstatus` and `mstatush` Registers\n 678| \n>>> 679| [#norm:mstatus_mstatush_xbe_warl]#The MBE, SBE, and UBE bits in `mstatus` and `mstatush` are *WARL* fields# that\n 680| control the endianness of memory accesses other than instruction fetches.\n 681| [#norm:endianness_inst_fetch_little]#Instruction fetches are always little-endian.#" + }, + { + "score": 8, + "reasons": [ + "CSR name 'mstatus' in backticks", + "CSR name 'mstatush' in backticks" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 393, + "line_text": "[#norm:mstatush_enc]#Bits 30:4 of `mstatush` generally contain the same fields found in bits 62:36 of `mstatus` for RV64. Fields SD, SXL, and UXL do not exist in `mstatush`.#", + "context": " 391| \n 392| [#norm:mstatush_sz_acc]#For RV32 only, `mstatush` is a 32-bit read/write register formatted as shown in <>.#\n>>> 393| [#norm:mstatush_enc]#Bits 30:4 of `mstatush` generally contain the same fields found in bits 62:36 of `mstatus` for RV64. Fields SD, SXL, and UXL do not exist in `mstatush`.#\n 394| \n 395| [[mstatushreg]]" + }, + { + "score": 8, + "reasons": [ + "WARL + CSR 'mstatus'", + "CSR name 'mstatus' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "priv-preface.adoc", + "line_number": 501, + "line_text": "* Made the `mstatus`.MPP field *WARL*, rather than *WLRL*.", + "context": " 499| the possibility of a future global-ASID extension.\n 500| * SFENCE.VMA semantics have been clarified.\n>>> 501| * Made the `mstatus`.MPP field *WARL*, rather than *WLRL*.\n 502| * Made the unused `__x__ip` fields *WPRI*, rather than *WIRI*.\n 503| * Made the unused `misa` fields *WARL*, rather than *WIRI*." + }, + { + "score": 7, + "reasons": [ + "CSR name 'mstatus' in backticks", + "Name segment 'ENDIANNESS'", + "CSR name 'mstatush' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 677, + "line_text": "===== Endianness Control in `mstatus` and `mstatush` Registers", + "context": " 675| whether access-fault exceptions are raised due to PMAs or PMP.\n 676| \n>>> 677| ===== Endianness Control in `mstatus` and `mstatush` Registers\n 678| \n 679| [#norm:mstatus_mstatush_xbe_warl]#The MBE, SBE, and UBE bits in `mstatus` and `mstatush` are *WARL* fields# that" + }, + { + "score": 6, + "reasons": [ + "CSR name 'mstatus' in backticks", + "CSR name 'mstatush' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1658, + "line_text": "==== Machine Status (`mstatus` and `mstatush`) Registers", + "context": " 1656| `mtinst`.\n 1657| \n>>> 1658| ==== Machine Status (`mstatus` and `mstatush`) Registers\n 1659| \n 1660| The hypervisor extension adds two fields, MPV and GVA, to the" + } + ] + }, + { + "parameter_name": "TIME_CSR_IMPLEMENTED", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 25, + "candidates": [ + { + "score": 25, + "reasons": [ + "Name segment 'TIME'", + "CSR name 'time' in backticks", + "Description keyword 'time'", + "CSR name 'timeh' in backticks", + "Description keyword 'timeh'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 2621, + "line_text": "When `mtime` changes, it is guaranteed to be reflected in `time` and `timeh`", + "context": " 2619| memory-mapped `mtime` register, while `time` shadows only the lower 32 bits of\n 2620| `mtime`.\n>>> 2621| When `mtime` changes, it is guaranteed to be reflected in `time` and `timeh`\n 2622| eventually, but not necessarily immediately.\n 2623| " + }, + { + "score": 19, + "reasons": [ + "Description keyword 'implemented'", + "Name segment 'TIME'", + "Description keyword 'time'", + "CSR name 'time' in backticks", + "Name segment 'IMPLEMENTED'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 901, + "line_text": "If the `time` CSR is implemented, `htimedelta` (and `htimedeltah` for XLEN=32)", + "context": " 899| \n 900| [[norm:time_htimedelta_req]]\n>>> 901| If the `time` CSR is implemented, `htimedelta` (and `htimedeltah` for XLEN=32)\n 902| must be implemented.\n 903| " + }, + { + "score": 18, + "reasons": [ + "Description keyword 'time'", + "Name segment 'TIME'", + "CSR name 'time' in backticks" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1642, + "line_text": "[#norm:time_op_rdonly]#The `time` CSR is a read-only shadow of the memory-mapped `mtime` register.#", + "context": " 1640| \n 1641| [#norm:cycle_instret_hpmcounter_op_rdonly]#The `cycle`, `instret`, and `hpmcountern` CSRs are read-only shadows of `mcycle`, `minstret`, and `mhpmcounter n`, respectively.#\n>>> 1642| [#norm:time_op_rdonly]#The `time` CSR is a read-only shadow of the memory-mapped `mtime` register.#\n 1643| Analogously, [#norm:cycleh_instreth_hpmcounternh_op_rdonly]#when XLEN=32, the `cycleh`, `instreth` and `hpmcounternh` CSRs\n 1644| are read-only shadows of `mcycleh`, `minstreth` and `mhpmcounternh`, respectively.#" + }, + { + "score": 16, + "reasons": [ + "Description keyword 'time'", + "Name segment 'TIME'", + "CSR name 'time' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "counters.adoc", + "line_number": 36, + "line_text": "`time`, and `instret` counters.", + "context": " 34| the full 64-bit CSRs directly. In particular, the RDCYCLE, RDTIME, and\n 35| RDINSTRET pseudoinstructions read the full 64 bits of the `cycle`,\n>>> 36| `time`, and `instret` counters.\n 37| \n 38| [NOTE]" + }, + { + "score": 16, + "reasons": [ + "Description keyword 'time'", + "Name segment 'TIME'", + "CSR name 'time' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 581, + "line_text": "`vstimecmp` with a value that is less than or equal to the sum of `time` and", + "context": " 579| timer interrupt signal resulting from `vstimecmp`. The `hip`.VSTIP bit, in\n 580| response to timer interrupts generated by `vstimecmp`, is set by writing\n>>> 581| `vstimecmp` with a value that is less than or equal to the sum of `time` and\n 582| `htimedelta`, truncated to 64 bits; it is cleared by writing `vstimecmp` with a\n 583| greater value. The `hip`.VSTIP bit remains defined while V=0 as well as V=1." + } + ] + }, + { + "parameter_name": "TINST_VALUE_ON_BREAKPOINT", + "classification": "NORM_CSR_RW", + "value_type": "binary", + "num_candidates": 10, + "best_score": 8, + "candidates": [ + { + "score": 8, + "reasons": [ + "WARL + CSR 'htinst'", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 983, + "line_text": "`htinst` is a *WARL* register that need only be able to hold the values that", + "context": " 981| \n 982| [[norm:htinst_val]]\n>>> 983| `htinst` is a *WARL* register that need only be able to hold the values that\n 984| the implementation may automatically write to it on a trap.\n 985| " + }, + { + "score": 8, + "reasons": [ + "CSR name 'mtinst' in backticks", + "WARL + CSR 'mtinst'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1866, + "line_text": "`mtinst` is a *WARL* register that need only be able to hold the values that", + "context": " 1864| \n 1865| [[norm:mtinst_val]]\n>>> 1866| `mtinst` is a *WARL* register that need only be able to hold the values that\n 1867| the implementation may automatically write to it on a trap.\n 1868| " + }, + { + "score": 8, + "reasons": [ + "CSR name 'mtinst' in backticks", + "CSR field name 'VALUE'", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2581, + "line_text": "value written to `mtinst` or `htinst` may always be zero, indicating", + "context": " 2579| \n 2580| Except when a pseudoinstruction value is required (described later), the\n>>> 2581| value written to `mtinst` or `htinst` may always be zero, indicating\n 2582| that the hardware is providing no information in the register for this\n 2583| particular trap." + }, + { + "score": 7, + "reasons": [ + "Description keyword 'breakpoint'", + "Name segment 'BREAKPOINT'", + "Description keyword 'VS'" + ], + "is_normative": true, + "in_note": false, + "file": "smctr.adoc", + "line_number": 168, + "line_text": "|BPFRZ |[#norm:vsctrctl-bpfrz_op]#Set `sctrstatus`.FROZEN on a breakpoint exception that traps to VS-mode.# See <>.", + "context": " 166| |U |[#norm:vsctrctl-u_op]#Enable transfer recording in VU-mode.#\n 167| |STE |[#norm:vsctrctl-ste_op]#Enables recording of traps to VS-mode when S=0.# See <>.\n>>> 168| |BPFRZ |[#norm:vsctrctl-bpfrz_op]#Set `sctrstatus`.FROZEN on a breakpoint exception that traps to VS-mode.# See <>.\n 169| |LCOFIFRZ |[#norm:vsctrctl-lcofifrz_op]#Set `sctrstatus`.FROZEN on local-counter-overflow interrupt (LCOFI) that traps to VS-mode.# See <>.\n 170| 2+|Other field definitions match those of `sctrctl`. The optional fields implemented in `vsctrctl` should match those implemented in `sctrctl`." + }, + { + "score": 7, + "reasons": [ + "Description keyword 'breakpoint'", + "Name segment 'BREAKPOINT'", + "Description keyword 'VS'" + ], + "is_normative": true, + "in_note": false, + "file": "smctr.adoc", + "line_number": 752, + "line_text": "[#norm:freeze_vs]#If the H extension is implemented, freeze behavior for LCOFIs and breakpoint exceptions that trap to VS-mode is determined by the LCOFIFRZ and BPFRZ values, respectively, in `vsctrctl`. This includes virtual LCOFIs pended by a hypervisor.#", + "context": " 750| ====\n 751| \n>>> 752| [#norm:freeze_vs]#If the H extension is implemented, freeze behavior for LCOFIs and breakpoint exceptions that trap to VS-mode is determined by the LCOFIFRZ and BPFRZ values, respectively, in `vsctrctl`. This includes virtual LCOFIs pended by a hypervisor.#\n 753| \n 754| [NOTE]" + } + ] + }, + { + "parameter_name": "TINST_VALUE_ON_FINAL_INSTRUCTION_GUEST_PAGE_FAULT", + "classification": "NORM_CSR_RW", + "value_type": "binary", + "num_candidates": 10, + "best_score": 9, + "candidates": [ + { + "score": 9, + "reasons": [ + "CSR name 'mtinst' in backticks", + "Name segment 'INSTRUCTION'", + "CSR name 'htinst' in backticks", + "Description keyword 'instruction'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2567, + "line_text": "==== Transformed Instruction or Pseudoinstruction for `mtinst` or `htinst`", + "context": " 2565| \n 2566| [[tinst-vals]]\n>>> 2567| ==== Transformed Instruction or Pseudoinstruction for `mtinst` or `htinst`\n 2568| \n 2569| [[norm:H_trap_xtinst]]" + }, + { + "score": 9, + "reasons": [ + "CSR name 'mtinst' in backticks", + "Name segment 'INSTRUCTION'", + "CSR name 'htinst' in backticks", + "Description keyword 'instruction'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2669, + "line_text": ".Values that may be automatically written to the trap instruction (`mtinst` or `htinst`) register on an exception trap.", + "context": " 2667| \n 2668| [[tinst-values]]\n>>> 2669| .Values that may be automatically written to the trap instruction (`mtinst` or `htinst`) register on an exception trap.\n 2670| [float=\"center\",align=\"center\",cols=\"2,^,^,^,^\",options=\"header\"]\n 2671| |===" + }, + { + "score": 8, + "reasons": [ + "WARL + CSR 'htinst'", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 983, + "line_text": "`htinst` is a *WARL* register that need only be able to hold the values that", + "context": " 981| \n 982| [[norm:htinst_val]]\n>>> 983| `htinst` is a *WARL* register that need only be able to hold the values that\n 984| the implementation may automatically write to it on a trap.\n 985| " + }, + { + "score": 8, + "reasons": [ + "CSR name 'mtinst' in backticks", + "WARL + CSR 'mtinst'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1866, + "line_text": "`mtinst` is a *WARL* register that need only be able to hold the values that", + "context": " 1864| \n 1865| [[norm:mtinst_val]]\n>>> 1866| `mtinst` is a *WARL* register that need only be able to hold the values that\n 1867| the implementation may automatically write to it on a trap.\n 1868| " + }, + { + "score": 8, + "reasons": [ + "CSR name 'mtinst' in backticks", + "CSR field name 'VALUE'", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2581, + "line_text": "value written to `mtinst` or `htinst` may always be zero, indicating", + "context": " 2579| \n 2580| Except when a pseudoinstruction value is required (described later), the\n>>> 2581| value written to `mtinst` or `htinst` may always be zero, indicating\n 2582| that the hardware is providing no information in the register for this\n 2583| particular trap." + } + ] + }, + { + "parameter_name": "TINST_VALUE_ON_FINAL_LOAD_GUEST_PAGE_FAULT", + "classification": "NORM_CSR_RW", + "value_type": "enum", + "num_candidates": 10, + "best_score": 8, + "candidates": [ + { + "score": 8, + "reasons": [ + "WARL + CSR 'htinst'", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 983, + "line_text": "`htinst` is a *WARL* register that need only be able to hold the values that", + "context": " 981| \n 982| [[norm:htinst_val]]\n>>> 983| `htinst` is a *WARL* register that need only be able to hold the values that\n 984| the implementation may automatically write to it on a trap.\n 985| " + }, + { + "score": 8, + "reasons": [ + "CSR name 'mtinst' in backticks", + "WARL + CSR 'mtinst'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1866, + "line_text": "`mtinst` is a *WARL* register that need only be able to hold the values that", + "context": " 1864| \n 1865| [[norm:mtinst_val]]\n>>> 1866| `mtinst` is a *WARL* register that need only be able to hold the values that\n 1867| the implementation may automatically write to it on a trap.\n 1868| " + }, + { + "score": 8, + "reasons": [ + "CSR name 'mtinst' in backticks", + "CSR field name 'VALUE'", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2581, + "line_text": "value written to `mtinst` or `htinst` may always be zero, indicating", + "context": " 2579| \n 2580| Except when a pseudoinstruction value is required (described later), the\n>>> 2581| value written to `mtinst` or `htinst` may always be zero, indicating\n 2582| that the hardware is providing no information in the register for this\n 2583| particular trap." + }, + { + "score": 6, + "reasons": [ + "CSR name 'mtinst' in backticks", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "cmo.adoc", + "line_number": 483, + "line_text": "For the purposes of writing the `mtinst` or `htinst` register on a trap, the", + "context": " 481| \n 482| [[norm:h_trans_cache]]\n>>> 483| For the purposes of writing the `mtinst` or `htinst` register on a trap, the\n 484| following standard transformation is defined for cache-block management\n 485| instructions and cache-block zero instructions:" + }, + { + "score": 6, + "reasons": [ + "CSR name 'mtinst' in backticks", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2049, + "line_text": "shifted right by 2 bits. CSR `mtinst` or `htinst` may also be written", + "context": " 2047| faulting guest virtual address as usual, and `mtval2` or `htval` is\n 2048| written either with zero or with the faulting guest physical address,\n>>> 2049| shifted right by 2 bits. CSR `mtinst` or `htinst` may also be written\n 2050| with information about the faulting instruction or other reason for the\n 2051| access, as explained in <>." + } + ] + }, + { + "parameter_name": "TINST_VALUE_ON_FINAL_STORE_AMO_GUEST_PAGE_FAULT", + "classification": "NORM_CSR_RW", + "value_type": "enum", + "num_candidates": 10, + "best_score": 8, + "candidates": [ + { + "score": 8, + "reasons": [ + "WARL + CSR 'htinst'", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 983, + "line_text": "`htinst` is a *WARL* register that need only be able to hold the values that", + "context": " 981| \n 982| [[norm:htinst_val]]\n>>> 983| `htinst` is a *WARL* register that need only be able to hold the values that\n 984| the implementation may automatically write to it on a trap.\n 985| " + }, + { + "score": 8, + "reasons": [ + "CSR name 'mtinst' in backticks", + "WARL + CSR 'mtinst'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1866, + "line_text": "`mtinst` is a *WARL* register that need only be able to hold the values that", + "context": " 1864| \n 1865| [[norm:mtinst_val]]\n>>> 1866| `mtinst` is a *WARL* register that need only be able to hold the values that\n 1867| the implementation may automatically write to it on a trap.\n 1868| " + }, + { + "score": 8, + "reasons": [ + "CSR name 'mtinst' in backticks", + "CSR field name 'VALUE'", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2581, + "line_text": "value written to `mtinst` or `htinst` may always be zero, indicating", + "context": " 2579| \n 2580| Except when a pseudoinstruction value is required (described later), the\n>>> 2581| value written to `mtinst` or `htinst` may always be zero, indicating\n 2582| that the hardware is providing no information in the register for this\n 2583| particular trap." + }, + { + "score": 6, + "reasons": [ + "CSR name 'mtinst' in backticks", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "cmo.adoc", + "line_number": 483, + "line_text": "For the purposes of writing the `mtinst` or `htinst` register on a trap, the", + "context": " 481| \n 482| [[norm:h_trans_cache]]\n>>> 483| For the purposes of writing the `mtinst` or `htinst` register on a trap, the\n 484| following standard transformation is defined for cache-block management\n 485| instructions and cache-block zero instructions:" + }, + { + "score": 6, + "reasons": [ + "CSR name 'mtinst' in backticks", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2049, + "line_text": "shifted right by 2 bits. CSR `mtinst` or `htinst` may also be written", + "context": " 2047| faulting guest virtual address as usual, and `mtval2` or `htval` is\n 2048| written either with zero or with the faulting guest physical address,\n>>> 2049| shifted right by 2 bits. CSR `mtinst` or `htinst` may also be written\n 2050| with information about the faulting instruction or other reason for the\n 2051| access, as explained in <>." + } + ] + }, + { + "parameter_name": "TINST_VALUE_ON_INSTRUCTION_ADDRESS_MISALIGNED", + "classification": "NORM_CSR_RW", + "value_type": "binary", + "num_candidates": 10, + "best_score": 9, + "candidates": [ + { + "score": 9, + "reasons": [ + "CSR name 'mtinst' in backticks", + "Name segment 'INSTRUCTION'", + "CSR name 'htinst' in backticks", + "Description keyword 'instruction'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2567, + "line_text": "==== Transformed Instruction or Pseudoinstruction for `mtinst` or `htinst`", + "context": " 2565| \n 2566| [[tinst-vals]]\n>>> 2567| ==== Transformed Instruction or Pseudoinstruction for `mtinst` or `htinst`\n 2568| \n 2569| [[norm:H_trap_xtinst]]" + }, + { + "score": 9, + "reasons": [ + "CSR name 'mtinst' in backticks", + "Name segment 'INSTRUCTION'", + "CSR name 'htinst' in backticks", + "Description keyword 'instruction'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2669, + "line_text": ".Values that may be automatically written to the trap instruction (`mtinst` or `htinst`) register on an exception trap.", + "context": " 2667| \n 2668| [[tinst-values]]\n>>> 2669| .Values that may be automatically written to the trap instruction (`mtinst` or `htinst`) register on an exception trap.\n 2670| [float=\"center\",align=\"center\",cols=\"2,^,^,^,^\",options=\"header\"]\n 2671| |===" + }, + { + "score": 9, + "reasons": [ + "Description keyword 'misaligned'", + "Name segment 'MISALIGNED'", + "Description keyword 'instruction'", + "Name segment 'INSTRUCTION'", + "Name segment 'ADDRESS'" + ], + "is_normative": true, + "in_note": false, + "file": "rv32.adoc", + "line_number": 139, + "line_text": "[#norm:taken_cti_misaligned_exc]#An instruction-address-misaligned exception is generated on a taken branch", + "context": " 137| (R/I/S/U), as shown in <>. All are a fixed 32 bits in length.\n 138| The base ISA has `IALIGN=32`, meaning that instructions must be aligned on a four-byte boundary in memory.\n>>> 139| [#norm:taken_cti_misaligned_exc]#An instruction-address-misaligned exception is generated on a taken branch\n 140| or unconditional jump if the target address is not `IALIGN-bit` aligned.\n 141| This exception is reported on the branch or jump instruction, not on the target instruction.#" + }, + { + "score": 9, + "reasons": [ + "Description keyword 'misaligned'", + "Name segment 'MISALIGNED'", + "Description keyword 'instruction'", + "Name segment 'INSTRUCTION'", + "Name segment 'ADDRESS'" + ], + "is_normative": true, + "in_note": false, + "file": "rv32.adoc", + "line_number": 142, + "line_text": "[#norm:cond_br_no_ia_misaligned_exc_not_taken]#No instruction-address-misaligned exception is generated", + "context": " 140| or unconditional jump if the target address is not `IALIGN-bit` aligned.\n 141| This exception is reported on the branch or jump instruction, not on the target instruction.#\n>>> 142| [#norm:cond_br_no_ia_misaligned_exc_not_taken]#No instruction-address-misaligned exception is generated\n 143| for a conditional branch that is not taken.#\n 144| " + }, + { + "score": 8, + "reasons": [ + "WARL + CSR 'htinst'", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 983, + "line_text": "`htinst` is a *WARL* register that need only be able to hold the values that", + "context": " 981| \n 982| [[norm:htinst_val]]\n>>> 983| `htinst` is a *WARL* register that need only be able to hold the values that\n 984| the implementation may automatically write to it on a trap.\n 985| " + } + ] + }, + { + "parameter_name": "TINST_VALUE_ON_LOAD_ACCESS_FAULT", + "classification": "NORM_CSR_RW", + "value_type": "enum", + "num_candidates": 10, + "best_score": 8, + "candidates": [ + { + "score": 8, + "reasons": [ + "WARL + CSR 'htinst'", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 983, + "line_text": "`htinst` is a *WARL* register that need only be able to hold the values that", + "context": " 981| \n 982| [[norm:htinst_val]]\n>>> 983| `htinst` is a *WARL* register that need only be able to hold the values that\n 984| the implementation may automatically write to it on a trap.\n 985| " + }, + { + "score": 8, + "reasons": [ + "CSR name 'mtinst' in backticks", + "WARL + CSR 'mtinst'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1866, + "line_text": "`mtinst` is a *WARL* register that need only be able to hold the values that", + "context": " 1864| \n 1865| [[norm:mtinst_val]]\n>>> 1866| `mtinst` is a *WARL* register that need only be able to hold the values that\n 1867| the implementation may automatically write to it on a trap.\n 1868| " + }, + { + "score": 8, + "reasons": [ + "CSR name 'mtinst' in backticks", + "CSR field name 'VALUE'", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2581, + "line_text": "value written to `mtinst` or `htinst` may always be zero, indicating", + "context": " 2579| \n 2580| Except when a pseudoinstruction value is required (described later), the\n>>> 2581| value written to `mtinst` or `htinst` may always be zero, indicating\n 2582| that the hardware is providing no information in the register for this\n 2583| particular trap." + }, + { + "score": 7, + "reasons": [ + "Description keyword 'VU'", + "Description keyword 'VS'", + "Name segment 'ACCESS'" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2370, + "line_text": "* [#norm:H_virtinst_vu_vs_nonhigh_allowedhs_tvm0]#in VS-mode or VU-mode, attempts to access an implemented non-high-half", + "context": " 2368| (HLV, HLVX, HSV, or HFENCE);#\n 2369| \n>>> 2370| * [#norm:H_virtinst_vu_vs_nonhigh_allowedhs_tvm0]#in VS-mode or VU-mode, attempts to access an implemented non-high-half\n 2371| hypervisor CSR or VS CSR when the same access (read/write) would be\n 2372| allowed in HS-mode, assuming `mstatus`.TVM=0;#" + }, + { + "score": 7, + "reasons": [ + "Description keyword 'VU'", + "Description keyword 'VS'", + "Name segment 'ACCESS'" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2374, + "line_text": "* [#norm:H_virtinst_vu_vs32_high_allowedhs_tvm0]#in VS-mode or VU-mode, if XLEN=32, attempts to access an implemented", + "context": " 2372| allowed in HS-mode, assuming `mstatus`.TVM=0;#\n 2373| \n>>> 2374| * [#norm:H_virtinst_vu_vs32_high_allowedhs_tvm0]#in VS-mode or VU-mode, if XLEN=32, attempts to access an implemented\n 2375| high-half hypervisor CSR or high-half VS CSR when the same access\n 2376| (read/write) to the CSR\"s low-half partner would be allowed in HS-mode," + } + ] + }, + { + "parameter_name": "TINST_VALUE_ON_LOAD_ADDRESS_MISALIGNED", + "classification": "NORM_CSR_RW", + "value_type": "enum", + "num_candidates": 10, + "best_score": 8, + "candidates": [ + { + "score": 8, + "reasons": [ + "WARL + CSR 'htinst'", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 983, + "line_text": "`htinst` is a *WARL* register that need only be able to hold the values that", + "context": " 981| \n 982| [[norm:htinst_val]]\n>>> 983| `htinst` is a *WARL* register that need only be able to hold the values that\n 984| the implementation may automatically write to it on a trap.\n 985| " + }, + { + "score": 8, + "reasons": [ + "CSR name 'mtinst' in backticks", + "WARL + CSR 'mtinst'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1866, + "line_text": "`mtinst` is a *WARL* register that need only be able to hold the values that", + "context": " 1864| \n 1865| [[norm:mtinst_val]]\n>>> 1866| `mtinst` is a *WARL* register that need only be able to hold the values that\n 1867| the implementation may automatically write to it on a trap.\n 1868| " + }, + { + "score": 8, + "reasons": [ + "CSR name 'mtinst' in backticks", + "CSR field name 'VALUE'", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2581, + "line_text": "value written to `mtinst` or `htinst` may always be zero, indicating", + "context": " 2579| \n 2580| Except when a pseudoinstruction value is required (described later), the\n>>> 2581| value written to `mtinst` or `htinst` may always be zero, indicating\n 2582| that the hardware is providing no information in the register for this\n 2583| particular trap." + }, + { + "score": 7, + "reasons": [ + "Name segment 'LOAD'", + "Name segment 'MISALIGNED'", + "Description keyword 'misaligned'", + "Name segment 'ADDRESS'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1976, + "line_text": "[#norm:mcause_exccode_pri2]#Load/store/AMO address-misaligned exceptions may have either higher or", + "context": " 1974| raised.\n 1975| \n>>> 1976| [#norm:mcause_exccode_pri2]#Load/store/AMO address-misaligned exceptions may have either higher or\n 1977| lower priority than load/store/AMO page-fault and access-fault exceptions.#\n 1978| " + }, + { + "score": 6, + "reasons": [ + "CSR name 'mtinst' in backticks", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "cmo.adoc", + "line_number": 483, + "line_text": "For the purposes of writing the `mtinst` or `htinst` register on a trap, the", + "context": " 481| \n 482| [[norm:h_trans_cache]]\n>>> 483| For the purposes of writing the `mtinst` or `htinst` register on a trap, the\n 484| following standard transformation is defined for cache-block management\n 485| instructions and cache-block zero instructions:" + } + ] + }, + { + "parameter_name": "TINST_VALUE_ON_LOAD_PAGE_FAULT", + "classification": "NORM_CSR_RW", + "value_type": "enum", + "num_candidates": 10, + "best_score": 8, + "candidates": [ + { + "score": 8, + "reasons": [ + "WARL + CSR 'htinst'", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 983, + "line_text": "`htinst` is a *WARL* register that need only be able to hold the values that", + "context": " 981| \n 982| [[norm:htinst_val]]\n>>> 983| `htinst` is a *WARL* register that need only be able to hold the values that\n 984| the implementation may automatically write to it on a trap.\n 985| " + }, + { + "score": 8, + "reasons": [ + "CSR name 'mtinst' in backticks", + "WARL + CSR 'mtinst'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1866, + "line_text": "`mtinst` is a *WARL* register that need only be able to hold the values that", + "context": " 1864| \n 1865| [[norm:mtinst_val]]\n>>> 1866| `mtinst` is a *WARL* register that need only be able to hold the values that\n 1867| the implementation may automatically write to it on a trap.\n 1868| " + }, + { + "score": 8, + "reasons": [ + "CSR name 'mtinst' in backticks", + "CSR field name 'VALUE'", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2581, + "line_text": "value written to `mtinst` or `htinst` may always be zero, indicating", + "context": " 2579| \n 2580| Except when a pseudoinstruction value is required (described later), the\n>>> 2581| value written to `mtinst` or `htinst` may always be zero, indicating\n 2582| that the hardware is providing no information in the register for this\n 2583| particular trap." + }, + { + "score": 6, + "reasons": [ + "CSR name 'mtinst' in backticks", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "cmo.adoc", + "line_number": 483, + "line_text": "For the purposes of writing the `mtinst` or `htinst` register on a trap, the", + "context": " 481| \n 482| [[norm:h_trans_cache]]\n>>> 483| For the purposes of writing the `mtinst` or `htinst` register on a trap, the\n 484| following standard transformation is defined for cache-block management\n 485| instructions and cache-block zero instructions:" + }, + { + "score": 6, + "reasons": [ + "CSR name 'mtinst' in backticks", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2049, + "line_text": "shifted right by 2 bits. CSR `mtinst` or `htinst` may also be written", + "context": " 2047| faulting guest virtual address as usual, and `mtval2` or `htval` is\n 2048| written either with zero or with the faulting guest physical address,\n>>> 2049| shifted right by 2 bits. CSR `mtinst` or `htinst` may also be written\n 2050| with information about the faulting instruction or other reason for the\n 2051| access, as explained in <>." + } + ] + }, + { + "parameter_name": "TINST_VALUE_ON_MCALL", + "classification": "NORM_CSR_RW", + "value_type": "binary", + "num_candidates": 10, + "best_score": 8, + "candidates": [ + { + "score": 8, + "reasons": [ + "WARL + CSR 'htinst'", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 983, + "line_text": "`htinst` is a *WARL* register that need only be able to hold the values that", + "context": " 981| \n 982| [[norm:htinst_val]]\n>>> 983| `htinst` is a *WARL* register that need only be able to hold the values that\n 984| the implementation may automatically write to it on a trap.\n 985| " + }, + { + "score": 8, + "reasons": [ + "CSR name 'mtinst' in backticks", + "WARL + CSR 'mtinst'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1866, + "line_text": "`mtinst` is a *WARL* register that need only be able to hold the values that", + "context": " 1864| \n 1865| [[norm:mtinst_val]]\n>>> 1866| `mtinst` is a *WARL* register that need only be able to hold the values that\n 1867| the implementation may automatically write to it on a trap.\n 1868| " + }, + { + "score": 8, + "reasons": [ + "CSR name 'mtinst' in backticks", + "CSR field name 'VALUE'", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2581, + "line_text": "value written to `mtinst` or `htinst` may always be zero, indicating", + "context": " 2579| \n 2580| Except when a pseudoinstruction value is required (described later), the\n>>> 2581| value written to `mtinst` or `htinst` may always be zero, indicating\n 2582| that the hardware is providing no information in the register for this\n 2583| particular trap." + }, + { + "score": 6, + "reasons": [ + "CSR name 'mtinst' in backticks", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "cmo.adoc", + "line_number": 483, + "line_text": "For the purposes of writing the `mtinst` or `htinst` register on a trap, the", + "context": " 481| \n 482| [[norm:h_trans_cache]]\n>>> 483| For the purposes of writing the `mtinst` or `htinst` register on a trap, the\n 484| following standard transformation is defined for cache-block management\n 485| instructions and cache-block zero instructions:" + }, + { + "score": 6, + "reasons": [ + "CSR name 'mtinst' in backticks", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2049, + "line_text": "shifted right by 2 bits. CSR `mtinst` or `htinst` may also be written", + "context": " 2047| faulting guest virtual address as usual, and `mtval2` or `htval` is\n 2048| written either with zero or with the faulting guest physical address,\n>>> 2049| shifted right by 2 bits. CSR `mtinst` or `htinst` may also be written\n 2050| with information about the faulting instruction or other reason for the\n 2051| access, as explained in <>." + } + ] + }, + { + "parameter_name": "TINST_VALUE_ON_SCALL", + "classification": "NORM_CSR_RW", + "value_type": "binary", + "num_candidates": 10, + "best_score": 8, + "candidates": [ + { + "score": 8, + "reasons": [ + "WARL + CSR 'htinst'", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 983, + "line_text": "`htinst` is a *WARL* register that need only be able to hold the values that", + "context": " 981| \n 982| [[norm:htinst_val]]\n>>> 983| `htinst` is a *WARL* register that need only be able to hold the values that\n 984| the implementation may automatically write to it on a trap.\n 985| " + }, + { + "score": 8, + "reasons": [ + "CSR name 'mtinst' in backticks", + "WARL + CSR 'mtinst'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1866, + "line_text": "`mtinst` is a *WARL* register that need only be able to hold the values that", + "context": " 1864| \n 1865| [[norm:mtinst_val]]\n>>> 1866| `mtinst` is a *WARL* register that need only be able to hold the values that\n 1867| the implementation may automatically write to it on a trap.\n 1868| " + }, + { + "score": 8, + "reasons": [ + "CSR name 'mtinst' in backticks", + "CSR field name 'VALUE'", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2581, + "line_text": "value written to `mtinst` or `htinst` may always be zero, indicating", + "context": " 2579| \n 2580| Except when a pseudoinstruction value is required (described later), the\n>>> 2581| value written to `mtinst` or `htinst` may always be zero, indicating\n 2582| that the hardware is providing no information in the register for this\n 2583| particular trap." + }, + { + "score": 6, + "reasons": [ + "CSR name 'mtinst' in backticks", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "cmo.adoc", + "line_number": 483, + "line_text": "For the purposes of writing the `mtinst` or `htinst` register on a trap, the", + "context": " 481| \n 482| [[norm:h_trans_cache]]\n>>> 483| For the purposes of writing the `mtinst` or `htinst` register on a trap, the\n 484| following standard transformation is defined for cache-block management\n 485| instructions and cache-block zero instructions:" + }, + { + "score": 6, + "reasons": [ + "CSR name 'mtinst' in backticks", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2049, + "line_text": "shifted right by 2 bits. CSR `mtinst` or `htinst` may also be written", + "context": " 2047| faulting guest virtual address as usual, and `mtval2` or `htval` is\n 2048| written either with zero or with the faulting guest physical address,\n>>> 2049| shifted right by 2 bits. CSR `mtinst` or `htinst` may also be written\n 2050| with information about the faulting instruction or other reason for the\n 2051| access, as explained in <>." + } + ] + }, + { + "parameter_name": "TINST_VALUE_ON_STORE_AMO_ACCESS_FAULT", + "classification": "NORM_CSR_RW", + "value_type": "enum", + "num_candidates": 10, + "best_score": 8, + "candidates": [ + { + "score": 8, + "reasons": [ + "WARL + CSR 'htinst'", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 983, + "line_text": "`htinst` is a *WARL* register that need only be able to hold the values that", + "context": " 981| \n 982| [[norm:htinst_val]]\n>>> 983| `htinst` is a *WARL* register that need only be able to hold the values that\n 984| the implementation may automatically write to it on a trap.\n 985| " + }, + { + "score": 8, + "reasons": [ + "CSR name 'mtinst' in backticks", + "WARL + CSR 'mtinst'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1866, + "line_text": "`mtinst` is a *WARL* register that need only be able to hold the values that", + "context": " 1864| \n 1865| [[norm:mtinst_val]]\n>>> 1866| `mtinst` is a *WARL* register that need only be able to hold the values that\n 1867| the implementation may automatically write to it on a trap.\n 1868| " + }, + { + "score": 8, + "reasons": [ + "CSR name 'mtinst' in backticks", + "CSR field name 'VALUE'", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2581, + "line_text": "value written to `mtinst` or `htinst` may always be zero, indicating", + "context": " 2579| \n 2580| Except when a pseudoinstruction value is required (described later), the\n>>> 2581| value written to `mtinst` or `htinst` may always be zero, indicating\n 2582| that the hardware is providing no information in the register for this\n 2583| particular trap." + }, + { + "score": 7, + "reasons": [ + "Description keyword 'VU'", + "Description keyword 'VS'", + "Name segment 'ACCESS'" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2370, + "line_text": "* [#norm:H_virtinst_vu_vs_nonhigh_allowedhs_tvm0]#in VS-mode or VU-mode, attempts to access an implemented non-high-half", + "context": " 2368| (HLV, HLVX, HSV, or HFENCE);#\n 2369| \n>>> 2370| * [#norm:H_virtinst_vu_vs_nonhigh_allowedhs_tvm0]#in VS-mode or VU-mode, attempts to access an implemented non-high-half\n 2371| hypervisor CSR or VS CSR when the same access (read/write) would be\n 2372| allowed in HS-mode, assuming `mstatus`.TVM=0;#" + }, + { + "score": 7, + "reasons": [ + "Description keyword 'VU'", + "Description keyword 'VS'", + "Name segment 'ACCESS'" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2374, + "line_text": "* [#norm:H_virtinst_vu_vs32_high_allowedhs_tvm0]#in VS-mode or VU-mode, if XLEN=32, attempts to access an implemented", + "context": " 2372| allowed in HS-mode, assuming `mstatus`.TVM=0;#\n 2373| \n>>> 2374| * [#norm:H_virtinst_vu_vs32_high_allowedhs_tvm0]#in VS-mode or VU-mode, if XLEN=32, attempts to access an implemented\n 2375| high-half hypervisor CSR or high-half VS CSR when the same access\n 2376| (read/write) to the CSR\"s low-half partner would be allowed in HS-mode," + } + ] + }, + { + "parameter_name": "TINST_VALUE_ON_STORE_AMO_ADDRESS_MISALIGNED", + "classification": "NORM_CSR_RW", + "value_type": "enum", + "num_candidates": 10, + "best_score": 8, + "candidates": [ + { + "score": 8, + "reasons": [ + "WARL + CSR 'htinst'", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 983, + "line_text": "`htinst` is a *WARL* register that need only be able to hold the values that", + "context": " 981| \n 982| [[norm:htinst_val]]\n>>> 983| `htinst` is a *WARL* register that need only be able to hold the values that\n 984| the implementation may automatically write to it on a trap.\n 985| " + }, + { + "score": 8, + "reasons": [ + "CSR name 'mtinst' in backticks", + "WARL + CSR 'mtinst'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1866, + "line_text": "`mtinst` is a *WARL* register that need only be able to hold the values that", + "context": " 1864| \n 1865| [[norm:mtinst_val]]\n>>> 1866| `mtinst` is a *WARL* register that need only be able to hold the values that\n 1867| the implementation may automatically write to it on a trap.\n 1868| " + }, + { + "score": 8, + "reasons": [ + "CSR name 'mtinst' in backticks", + "CSR field name 'VALUE'", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2581, + "line_text": "value written to `mtinst` or `htinst` may always be zero, indicating", + "context": " 2579| \n 2580| Except when a pseudoinstruction value is required (described later), the\n>>> 2581| value written to `mtinst` or `htinst` may always be zero, indicating\n 2582| that the hardware is providing no information in the register for this\n 2583| particular trap." + }, + { + "score": 7, + "reasons": [ + "Name segment 'STORE'", + "Name segment 'MISALIGNED'", + "Description keyword 'misaligned'", + "Name segment 'ADDRESS'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1976, + "line_text": "[#norm:mcause_exccode_pri2]#Load/store/AMO address-misaligned exceptions may have either higher or", + "context": " 1974| raised.\n 1975| \n>>> 1976| [#norm:mcause_exccode_pri2]#Load/store/AMO address-misaligned exceptions may have either higher or\n 1977| lower priority than load/store/AMO page-fault and access-fault exceptions.#\n 1978| " + }, + { + "score": 6, + "reasons": [ + "CSR name 'mtinst' in backticks", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "cmo.adoc", + "line_number": 483, + "line_text": "For the purposes of writing the `mtinst` or `htinst` register on a trap, the", + "context": " 481| \n 482| [[norm:h_trans_cache]]\n>>> 483| For the purposes of writing the `mtinst` or `htinst` register on a trap, the\n 484| following standard transformation is defined for cache-block management\n 485| instructions and cache-block zero instructions:" + } + ] + }, + { + "parameter_name": "TINST_VALUE_ON_STORE_AMO_PAGE_FAULT", + "classification": "NORM_CSR_RW", + "value_type": "enum", + "num_candidates": 10, + "best_score": 8, + "candidates": [ + { + "score": 8, + "reasons": [ + "WARL + CSR 'htinst'", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 983, + "line_text": "`htinst` is a *WARL* register that need only be able to hold the values that", + "context": " 981| \n 982| [[norm:htinst_val]]\n>>> 983| `htinst` is a *WARL* register that need only be able to hold the values that\n 984| the implementation may automatically write to it on a trap.\n 985| " + }, + { + "score": 8, + "reasons": [ + "CSR name 'mtinst' in backticks", + "WARL + CSR 'mtinst'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1866, + "line_text": "`mtinst` is a *WARL* register that need only be able to hold the values that", + "context": " 1864| \n 1865| [[norm:mtinst_val]]\n>>> 1866| `mtinst` is a *WARL* register that need only be able to hold the values that\n 1867| the implementation may automatically write to it on a trap.\n 1868| " + }, + { + "score": 8, + "reasons": [ + "CSR name 'mtinst' in backticks", + "CSR field name 'VALUE'", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2581, + "line_text": "value written to `mtinst` or `htinst` may always be zero, indicating", + "context": " 2579| \n 2580| Except when a pseudoinstruction value is required (described later), the\n>>> 2581| value written to `mtinst` or `htinst` may always be zero, indicating\n 2582| that the hardware is providing no information in the register for this\n 2583| particular trap." + }, + { + "score": 6, + "reasons": [ + "CSR name 'mtinst' in backticks", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "cmo.adoc", + "line_number": 483, + "line_text": "For the purposes of writing the `mtinst` or `htinst` register on a trap, the", + "context": " 481| \n 482| [[norm:h_trans_cache]]\n>>> 483| For the purposes of writing the `mtinst` or `htinst` register on a trap, the\n 484| following standard transformation is defined for cache-block management\n 485| instructions and cache-block zero instructions:" + }, + { + "score": 6, + "reasons": [ + "CSR name 'mtinst' in backticks", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2049, + "line_text": "shifted right by 2 bits. CSR `mtinst` or `htinst` may also be written", + "context": " 2047| faulting guest virtual address as usual, and `mtval2` or `htval` is\n 2048| written either with zero or with the faulting guest physical address,\n>>> 2049| shifted right by 2 bits. CSR `mtinst` or `htinst` may also be written\n 2050| with information about the faulting instruction or other reason for the\n 2051| access, as explained in <>." + } + ] + }, + { + "parameter_name": "TINST_VALUE_ON_UCALL", + "classification": "NORM_CSR_RW", + "value_type": "binary", + "num_candidates": 10, + "best_score": 8, + "candidates": [ + { + "score": 8, + "reasons": [ + "WARL + CSR 'htinst'", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 983, + "line_text": "`htinst` is a *WARL* register that need only be able to hold the values that", + "context": " 981| \n 982| [[norm:htinst_val]]\n>>> 983| `htinst` is a *WARL* register that need only be able to hold the values that\n 984| the implementation may automatically write to it on a trap.\n 985| " + }, + { + "score": 8, + "reasons": [ + "CSR name 'mtinst' in backticks", + "WARL + CSR 'mtinst'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1866, + "line_text": "`mtinst` is a *WARL* register that need only be able to hold the values that", + "context": " 1864| \n 1865| [[norm:mtinst_val]]\n>>> 1866| `mtinst` is a *WARL* register that need only be able to hold the values that\n 1867| the implementation may automatically write to it on a trap.\n 1868| " + }, + { + "score": 8, + "reasons": [ + "CSR name 'mtinst' in backticks", + "CSR field name 'VALUE'", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2581, + "line_text": "value written to `mtinst` or `htinst` may always be zero, indicating", + "context": " 2579| \n 2580| Except when a pseudoinstruction value is required (described later), the\n>>> 2581| value written to `mtinst` or `htinst` may always be zero, indicating\n 2582| that the hardware is providing no information in the register for this\n 2583| particular trap." + }, + { + "score": 6, + "reasons": [ + "CSR name 'mtinst' in backticks", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "cmo.adoc", + "line_number": 483, + "line_text": "For the purposes of writing the `mtinst` or `htinst` register on a trap, the", + "context": " 481| \n 482| [[norm:h_trans_cache]]\n>>> 483| For the purposes of writing the `mtinst` or `htinst` register on a trap, the\n 484| following standard transformation is defined for cache-block management\n 485| instructions and cache-block zero instructions:" + }, + { + "score": 6, + "reasons": [ + "CSR name 'mtinst' in backticks", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2049, + "line_text": "shifted right by 2 bits. CSR `mtinst` or `htinst` may also be written", + "context": " 2047| faulting guest virtual address as usual, and `mtval2` or `htval` is\n 2048| written either with zero or with the faulting guest physical address,\n>>> 2049| shifted right by 2 bits. CSR `mtinst` or `htinst` may also be written\n 2050| with information about the faulting instruction or other reason for the\n 2051| access, as explained in <>." + } + ] + }, + { + "parameter_name": "TINST_VALUE_ON_VIRTUAL_INSTRUCTION", + "classification": "NORM_CSR_RW", + "value_type": "binary", + "num_candidates": 10, + "best_score": 10, + "candidates": [ + { + "score": 10, + "reasons": [ + "Name segment 'VIRTUAL'", + "Description keyword 'VU'", + "Description keyword 'instruction'", + "Name segment 'INSTRUCTION'", + "Description keyword 'VS'" + ], + "is_normative": true, + "in_note": false, + "file": "smctr.adoc", + "line_number": 218, + "line_text": "[#norm:sctrdepth_mode]#Attempts to access `sctrdepth` from VS-mode or VU-mode raise a virtual-instruction exception, unless CTR state enable access restrictions apply.# See <>.", + "context": " 216| |===\n 217| \n>>> 218| [#norm:sctrdepth_mode]#Attempts to access `sctrdepth` from VS-mode or VU-mode raise a virtual-instruction exception, unless CTR state enable access restrictions apply.# See <>.\n 219| \n 220| [NOTE]" + }, + { + "score": 9, + "reasons": [ + "Name segment 'INSTRUCTION'", + "Description keyword 'VU'", + "Description keyword 'instruction'", + "Description keyword 'VS'" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2367, + "line_text": "* [#norm:H_virtinst_vu_vs_hinst]#in VS-mode or VU-mode, attempts to execute a hypervisor instruction", + "context": " 2365| and the same bit in `mcounteren` is 1;#\n 2366| \n>>> 2367| * [#norm:H_virtinst_vu_vs_hinst]#in VS-mode or VU-mode, attempts to execute a hypervisor instruction\n 2368| (HLV, HLVX, HSV, or HFENCE);#\n 2369| " + }, + { + "score": 9, + "reasons": [ + "CSR name 'mtinst' in backticks", + "Name segment 'INSTRUCTION'", + "CSR name 'htinst' in backticks", + "Description keyword 'instruction'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2567, + "line_text": "==== Transformed Instruction or Pseudoinstruction for `mtinst` or `htinst`", + "context": " 2565| \n 2566| [[tinst-vals]]\n>>> 2567| ==== Transformed Instruction or Pseudoinstruction for `mtinst` or `htinst`\n 2568| \n 2569| [[norm:H_trap_xtinst]]" + }, + { + "score": 9, + "reasons": [ + "CSR name 'mtinst' in backticks", + "Name segment 'INSTRUCTION'", + "CSR name 'htinst' in backticks", + "Description keyword 'instruction'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2669, + "line_text": ".Values that may be automatically written to the trap instruction (`mtinst` or `htinst`) register on an exception trap.", + "context": " 2667| \n 2668| [[tinst-values]]\n>>> 2669| .Values that may be automatically written to the trap instruction (`mtinst` or `htinst`) register on an exception trap.\n 2670| [float=\"center\",align=\"center\",cols=\"2,^,^,^,^\",options=\"header\"]\n 2671| |===" + }, + { + "score": 8, + "reasons": [ + "WARL + CSR 'htinst'", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 983, + "line_text": "`htinst` is a *WARL* register that need only be able to hold the values that", + "context": " 981| \n 982| [[norm:htinst_val]]\n>>> 983| `htinst` is a *WARL* register that need only be able to hold the values that\n 984| the implementation may automatically write to it on a trap.\n 985| " + } + ] + }, + { + "parameter_name": "TINST_VALUE_ON_VSCALL", + "classification": "NORM_CSR_RW", + "value_type": "binary", + "num_candidates": 10, + "best_score": 8, + "candidates": [ + { + "score": 8, + "reasons": [ + "WARL + CSR 'htinst'", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 983, + "line_text": "`htinst` is a *WARL* register that need only be able to hold the values that", + "context": " 981| \n 982| [[norm:htinst_val]]\n>>> 983| `htinst` is a *WARL* register that need only be able to hold the values that\n 984| the implementation may automatically write to it on a trap.\n 985| " + }, + { + "score": 8, + "reasons": [ + "CSR name 'mtinst' in backticks", + "WARL + CSR 'mtinst'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1866, + "line_text": "`mtinst` is a *WARL* register that need only be able to hold the values that", + "context": " 1864| \n 1865| [[norm:mtinst_val]]\n>>> 1866| `mtinst` is a *WARL* register that need only be able to hold the values that\n 1867| the implementation may automatically write to it on a trap.\n 1868| " + }, + { + "score": 8, + "reasons": [ + "CSR name 'mtinst' in backticks", + "CSR field name 'VALUE'", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2581, + "line_text": "value written to `mtinst` or `htinst` may always be zero, indicating", + "context": " 2579| \n 2580| Except when a pseudoinstruction value is required (described later), the\n>>> 2581| value written to `mtinst` or `htinst` may always be zero, indicating\n 2582| that the hardware is providing no information in the register for this\n 2583| particular trap." + }, + { + "score": 6, + "reasons": [ + "CSR name 'mtinst' in backticks", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "cmo.adoc", + "line_number": 483, + "line_text": "For the purposes of writing the `mtinst` or `htinst` register on a trap, the", + "context": " 481| \n 482| [[norm:h_trans_cache]]\n>>> 483| For the purposes of writing the `mtinst` or `htinst` register on a trap, the\n 484| following standard transformation is defined for cache-block management\n 485| instructions and cache-block zero instructions:" + }, + { + "score": 6, + "reasons": [ + "CSR name 'mtinst' in backticks", + "CSR name 'htinst' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2049, + "line_text": "shifted right by 2 bits. CSR `mtinst` or `htinst` may also be written", + "context": " 2047| faulting guest virtual address as usual, and `mtval2` or `htval` is\n 2048| written either with zero or with the faulting guest physical address,\n>>> 2049| shifted right by 2 bits. CSR `mtinst` or `htinst` may also be written\n 2050| with information about the faulting instruction or other reason for the\n 2051| access, as explained in <>." + } + ] + }, + { + "parameter_name": "TRAP_ON_EBREAK", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 4, + "candidates": [ + { + "score": 4, + "reasons": [ + "Description keyword 'EEI'" + ], + "is_normative": true, + "in_note": false, + "file": "rv32.adoc", + "line_number": 684, + "line_text": "[#norm:ENDIANNESS_LITTLE_OR_BIG]#The EEI will define whether the memory system is little-endian or big-endian.#", + "context": " 682| even though the load value is discarded.#\n 683| \n>>> 684| [#norm:ENDIANNESS_LITTLE_OR_BIG]#The EEI will define whether the memory system is little-endian or big-endian.#\n 685| [#norm:ldst_endian_byte_invariant]#In RISC-V, endianness is byte-address invariant.#\n 686| " + }, + { + "score": 4, + "reasons": [ + "Description keyword 'EEI'" + ], + "is_normative": true, + "in_note": false, + "file": "rv32.adoc", + "line_number": 730, + "line_text": "Regardless of EEI, [#norm:ldst_no_exc_aligned]#loads and stores whose effective addresses are", + "context": " 728| 8-bit values from the low bits of register _rs2_ to memory.#\n 729| \n>>> 730| Regardless of EEI, [#norm:ldst_no_exc_aligned]#loads and stores whose effective addresses are\n 731| naturally aligned shall not raise an address-misaligned exception.#\n 732| [#norm:MISALIGNED_LDST_EEI_DEPENDENT_BEHAVIOR]#Loads and stores whose effective address is not naturally aligned to the" + }, + { + "score": 4, + "reasons": [ + "Description keyword 'EEI'" + ], + "is_normative": true, + "in_note": false, + "file": "rv32.adoc", + "line_number": 753, + "line_text": "[#norm:MISALIGNED_LDST_CONTAINED_OR_FATAL_TRAP]#When an EEI does not guarantee misaligned loads and", + "context": " 751| access should not be emulated, e.g., if accesses to the memory region\n 752| have side effects.#\n>>> 753| [#norm:MISALIGNED_LDST_CONTAINED_OR_FATAL_TRAP]#When an EEI does not guarantee misaligned loads and\n 754| stores are handled invisibly, the EEI must define if exceptions caused\n 755| by address misalignment result in a contained trap (allowing software" + }, + { + "score": 3, + "reasons": [ + "Name segment 'EBREAK'" + ], + "is_normative": true, + "in_note": false, + "file": "c-st-ext.adoc", + "line_number": 788, + "line_text": "[#norm:c-ebreak_op]#Debuggers can use the `C.EBREAK` instruction, which expands to `ebreak`,", + "context": " 786| ((((compressed. C.BREAKPOINTINSTR))))\n 787| \n>>> 788| [#norm:c-ebreak_op]#Debuggers can use the `C.EBREAK` instruction, which expands to `ebreak`,\n 789| to cause control to be transferred back to the debugging environment.\n 790| `C.EBREAK` shares the opcode with the `C.ADD` instruction, but with _rd_ and" + }, + { + "score": 3, + "reasons": [ + "Optional/read-only pattern for boolean param" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 25, + "line_text": "registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and", + "context": " 23| The hypervisor extension depends on an \"I\" base integer ISA with 32\n 24| `x` registers (RV32I or RV64I), not RV32E or RV64E, which have only 16 `x`\n>>> 25| registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and\n 26| [#norm:H_vm_supported]#standard\n 27| page-based address translation must be supported, either Sv32 for RV32," + } + ] + }, + { + "parameter_name": "TRAP_ON_ECALL_FROM_M", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 4, + "candidates": [ + { + "score": 4, + "reasons": [ + "Description keyword 'EEI'" + ], + "is_normative": true, + "in_note": false, + "file": "rv32.adoc", + "line_number": 684, + "line_text": "[#norm:ENDIANNESS_LITTLE_OR_BIG]#The EEI will define whether the memory system is little-endian or big-endian.#", + "context": " 682| even though the load value is discarded.#\n 683| \n>>> 684| [#norm:ENDIANNESS_LITTLE_OR_BIG]#The EEI will define whether the memory system is little-endian or big-endian.#\n 685| [#norm:ldst_endian_byte_invariant]#In RISC-V, endianness is byte-address invariant.#\n 686| " + }, + { + "score": 4, + "reasons": [ + "Description keyword 'EEI'" + ], + "is_normative": true, + "in_note": false, + "file": "rv32.adoc", + "line_number": 730, + "line_text": "Regardless of EEI, [#norm:ldst_no_exc_aligned]#loads and stores whose effective addresses are", + "context": " 728| 8-bit values from the low bits of register _rs2_ to memory.#\n 729| \n>>> 730| Regardless of EEI, [#norm:ldst_no_exc_aligned]#loads and stores whose effective addresses are\n 731| naturally aligned shall not raise an address-misaligned exception.#\n 732| [#norm:MISALIGNED_LDST_EEI_DEPENDENT_BEHAVIOR]#Loads and stores whose effective address is not naturally aligned to the" + }, + { + "score": 4, + "reasons": [ + "Description keyword 'EEI'" + ], + "is_normative": true, + "in_note": false, + "file": "rv32.adoc", + "line_number": 753, + "line_text": "[#norm:MISALIGNED_LDST_CONTAINED_OR_FATAL_TRAP]#When an EEI does not guarantee misaligned loads and", + "context": " 751| access should not be emulated, e.g., if accesses to the memory region\n 752| have side effects.#\n>>> 753| [#norm:MISALIGNED_LDST_CONTAINED_OR_FATAL_TRAP]#When an EEI does not guarantee misaligned loads and\n 754| stores are handled invisibly, the EEI must define if exceptions caused\n 755| by address misalignment result in a contained trap (allowing software" + }, + { + "score": 3, + "reasons": [ + "Name segment 'FROM'" + ], + "is_normative": true, + "in_note": false, + "file": "c-st-ext.adoc", + "line_number": 304, + "line_text": "[#norm:c-lwsp_op]#C.LWSP loads a 32-bit value from memory into register _rd_. It computes", + "context": " 302| These instructions use the CI format.\n 303| \n>>> 304| [#norm:c-lwsp_op]#C.LWSP loads a 32-bit value from memory into register _rd_. It computes\n 305| an effective address by adding the _zero_-extended offset, scaled by 4,\n 306| to the stack pointer, `x2`. It expands to `lw rd, offset(x2)`.#" + }, + { + "score": 3, + "reasons": [ + "Name segment 'FROM'" + ], + "is_normative": true, + "in_note": false, + "file": "c-st-ext.adoc", + "line_number": 406, + "line_text": "[#norm:c-lw_op]#C.LW loads a 32-bit value from memory into register", + "context": " 404| These instructions use the CL format.\n 405| \n>>> 406| [#norm:c-lw_op]#C.LW loads a 32-bit value from memory into register\n 407| `_rd′_`. It computes an effective address by adding the\n 408| _zero_-extended offset, scaled by 4, to the base address in register" + } + ] + }, + { + "parameter_name": "TRAP_ON_ECALL_FROM_S", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 5, + "candidates": [ + { + "score": 5, + "reasons": [ + "Name segment 'ECALL'", + "Description keyword 'ECALL'" + ], + "is_normative": true, + "in_note": false, + "file": "rv32.adoc", + "line_number": 925, + "line_text": "[#norm:ecall_op]#The `ECALL` instruction is used to make a service request to the execution environment.#", + "context": " 923| execution environment.\n 924| \n>>> 925| [#norm:ecall_op]#The `ECALL` instruction is used to make a service request to the execution environment.#\n 926| The `EEI` will define how parameters for the service request\n 927| are passed, but usually these will be in defined locations in the" + }, + { + "score": 4, + "reasons": [ + "Description keyword 'EEI'" + ], + "is_normative": true, + "in_note": false, + "file": "rv32.adoc", + "line_number": 684, + "line_text": "[#norm:ENDIANNESS_LITTLE_OR_BIG]#The EEI will define whether the memory system is little-endian or big-endian.#", + "context": " 682| even though the load value is discarded.#\n 683| \n>>> 684| [#norm:ENDIANNESS_LITTLE_OR_BIG]#The EEI will define whether the memory system is little-endian or big-endian.#\n 685| [#norm:ldst_endian_byte_invariant]#In RISC-V, endianness is byte-address invariant.#\n 686| " + }, + { + "score": 4, + "reasons": [ + "Description keyword 'EEI'" + ], + "is_normative": true, + "in_note": false, + "file": "rv32.adoc", + "line_number": 730, + "line_text": "Regardless of EEI, [#norm:ldst_no_exc_aligned]#loads and stores whose effective addresses are", + "context": " 728| 8-bit values from the low bits of register _rs2_ to memory.#\n 729| \n>>> 730| Regardless of EEI, [#norm:ldst_no_exc_aligned]#loads and stores whose effective addresses are\n 731| naturally aligned shall not raise an address-misaligned exception.#\n 732| [#norm:MISALIGNED_LDST_EEI_DEPENDENT_BEHAVIOR]#Loads and stores whose effective address is not naturally aligned to the" + }, + { + "score": 4, + "reasons": [ + "Description keyword 'EEI'" + ], + "is_normative": true, + "in_note": false, + "file": "rv32.adoc", + "line_number": 753, + "line_text": "[#norm:MISALIGNED_LDST_CONTAINED_OR_FATAL_TRAP]#When an EEI does not guarantee misaligned loads and", + "context": " 751| access should not be emulated, e.g., if accesses to the memory region\n 752| have side effects.#\n>>> 753| [#norm:MISALIGNED_LDST_CONTAINED_OR_FATAL_TRAP]#When an EEI does not guarantee misaligned loads and\n 754| stores are handled invisibly, the EEI must define if exceptions caused\n 755| by address misalignment result in a contained trap (allowing software" + }, + { + "score": 3, + "reasons": [ + "Name segment 'FROM'" + ], + "is_normative": true, + "in_note": false, + "file": "c-st-ext.adoc", + "line_number": 304, + "line_text": "[#norm:c-lwsp_op]#C.LWSP loads a 32-bit value from memory into register _rd_. It computes", + "context": " 302| These instructions use the CI format.\n 303| \n>>> 304| [#norm:c-lwsp_op]#C.LWSP loads a 32-bit value from memory into register _rd_. It computes\n 305| an effective address by adding the _zero_-extended offset, scaled by 4,\n 306| to the stack pointer, `x2`. It expands to `lw rd, offset(x2)`.#" + } + ] + }, + { + "parameter_name": "TRAP_ON_ECALL_FROM_U", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 5, + "candidates": [ + { + "score": 5, + "reasons": [ + "Name segment 'ECALL'", + "Description keyword 'ECALL'" + ], + "is_normative": true, + "in_note": false, + "file": "rv32.adoc", + "line_number": 925, + "line_text": "[#norm:ecall_op]#The `ECALL` instruction is used to make a service request to the execution environment.#", + "context": " 923| execution environment.\n 924| \n>>> 925| [#norm:ecall_op]#The `ECALL` instruction is used to make a service request to the execution environment.#\n 926| The `EEI` will define how parameters for the service request\n 927| are passed, but usually these will be in defined locations in the" + }, + { + "score": 4, + "reasons": [ + "Description keyword 'EEI'" + ], + "is_normative": true, + "in_note": false, + "file": "rv32.adoc", + "line_number": 684, + "line_text": "[#norm:ENDIANNESS_LITTLE_OR_BIG]#The EEI will define whether the memory system is little-endian or big-endian.#", + "context": " 682| even though the load value is discarded.#\n 683| \n>>> 684| [#norm:ENDIANNESS_LITTLE_OR_BIG]#The EEI will define whether the memory system is little-endian or big-endian.#\n 685| [#norm:ldst_endian_byte_invariant]#In RISC-V, endianness is byte-address invariant.#\n 686| " + }, + { + "score": 4, + "reasons": [ + "Description keyword 'EEI'" + ], + "is_normative": true, + "in_note": false, + "file": "rv32.adoc", + "line_number": 730, + "line_text": "Regardless of EEI, [#norm:ldst_no_exc_aligned]#loads and stores whose effective addresses are", + "context": " 728| 8-bit values from the low bits of register _rs2_ to memory.#\n 729| \n>>> 730| Regardless of EEI, [#norm:ldst_no_exc_aligned]#loads and stores whose effective addresses are\n 731| naturally aligned shall not raise an address-misaligned exception.#\n 732| [#norm:MISALIGNED_LDST_EEI_DEPENDENT_BEHAVIOR]#Loads and stores whose effective address is not naturally aligned to the" + }, + { + "score": 4, + "reasons": [ + "Description keyword 'EEI'" + ], + "is_normative": true, + "in_note": false, + "file": "rv32.adoc", + "line_number": 753, + "line_text": "[#norm:MISALIGNED_LDST_CONTAINED_OR_FATAL_TRAP]#When an EEI does not guarantee misaligned loads and", + "context": " 751| access should not be emulated, e.g., if accesses to the memory region\n 752| have side effects.#\n>>> 753| [#norm:MISALIGNED_LDST_CONTAINED_OR_FATAL_TRAP]#When an EEI does not guarantee misaligned loads and\n 754| stores are handled invisibly, the EEI must define if exceptions caused\n 755| by address misalignment result in a contained trap (allowing software" + }, + { + "score": 3, + "reasons": [ + "Name segment 'FROM'" + ], + "is_normative": true, + "in_note": false, + "file": "c-st-ext.adoc", + "line_number": 304, + "line_text": "[#norm:c-lwsp_op]#C.LWSP loads a 32-bit value from memory into register _rd_. It computes", + "context": " 302| These instructions use the CI format.\n 303| \n>>> 304| [#norm:c-lwsp_op]#C.LWSP loads a 32-bit value from memory into register _rd_. It computes\n 305| an effective address by adding the _zero_-extended offset, scaled by 4,\n 306| to the stack pointer, `x2`. It expands to `lw rd, offset(x2)`.#" + } + ] + }, + { + "parameter_name": "TRAP_ON_ECALL_FROM_VS", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 5, + "candidates": [ + { + "score": 5, + "reasons": [ + "Optional/read-only pattern for boolean param", + "Description keyword 'VS'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 932, + "line_text": "[#norm:mstatus_sd_rdonly0]#If FS, XS, and VS are all read-only zero, then SD is also always zero.#", + "context": " 930| or XS fields signal the presence of some dirty state that will require\n 931| saving extended user context to memory.#\n>>> 932| [#norm:mstatus_sd_rdonly0]#If FS, XS, and VS are all read-only zero, then SD is also always zero.#\n 933| \n 934| [#norm:mstatus_fs_vs_xs_off_op]#When an extension's status is set to Off, any instruction that attempts" + }, + { + "score": 5, + "reasons": [ + "Name segment 'ECALL'", + "Description keyword 'ECALL'" + ], + "is_normative": true, + "in_note": false, + "file": "rv32.adoc", + "line_number": 925, + "line_text": "[#norm:ecall_op]#The `ECALL` instruction is used to make a service request to the execution environment.#", + "context": " 923| execution environment.\n 924| \n>>> 925| [#norm:ecall_op]#The `ECALL` instruction is used to make a service request to the execution environment.#\n 926| The `EEI` will define how parameters for the service request\n 927| are passed, but usually these will be in defined locations in the" + }, + { + "score": 5, + "reasons": [ + "Name segment 'FROM'", + "Description keyword 'VS'" + ], + "is_normative": true, + "in_note": false, + "file": "smctr.adoc", + "line_number": 218, + "line_text": "[#norm:sctrdepth_mode]#Attempts to access `sctrdepth` from VS-mode or VU-mode raise a virtual-instruction exception, unless CTR state enable access restrictions apply.# See <>.", + "context": " 216| |===\n 217| \n>>> 218| [#norm:sctrdepth_mode]#Attempts to access `sctrdepth` from VS-mode or VU-mode raise a virtual-instruction exception, unless CTR state enable access restrictions apply.# See <>.\n 219| \n 220| [NOTE]" + }, + { + "score": 5, + "reasons": [ + "Name segment 'FROM'", + "Description keyword 'VS'" + ], + "is_normative": true, + "in_note": false, + "file": "smctr.adoc", + "line_number": 507, + "line_text": "[#norm:exttrap_def]#External traps are traps from a privilege mode enabled for CTR recording to a privilege mode that is not enabled for CTR recording. By default external traps are not recorded, but privileged software running in the target mode of the trap can opt-in to allowing CTR to record external traps into that mode. The `__x__ctrctl`.__x__TE bits allow M-mode, S-mode, and VS-mode to opt-in separately.#", + "context": " 505| ===== External Traps\n 506| \n>>> 507| [#norm:exttrap_def]#External traps are traps from a privilege mode enabled for CTR recording to a privilege mode that is not enabled for CTR recording. By default external traps are not recorded, but privileged software running in the target mode of the trap can opt-in to allowing CTR to record external traps into that mode. The `__x__ctrctl`.__x__TE bits allow M-mode, S-mode, and VS-mode to opt-in separately.#\n 508| \n 509| [#norm:exttrap_requirements]#External trap recording depends not only on the target mode, but on any intervening modes, which are modes that are more privileged than the source mode but less privileged than the target mode. Not only must the external trap enable bit for the target mode be set, but the external trap enable bit(s) for any intervening modes must also be set.# See the table below for details." + }, + { + "score": 5, + "reasons": [ + "Name segment 'FROM'", + "Description keyword 'VS'" + ], + "is_normative": true, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 133, + "line_text": "[#norm:hw_mstatus_vs_dirty_update_param]#Implementations may also change `mstatus.VS` or `vsstatus.VS` from Initial or", + "context": " 131| any instruction that changes vector state, including the vector CSRs, will\n 132| change both `mstatus.VS` and `vsstatus.VS` to Dirty.#\n>>> 133| [#norm:hw_mstatus_vs_dirty_update_param]#Implementations may also change `mstatus.VS` or `vsstatus.VS` from Initial or\n 134| Clean to Dirty at any time, even when there is no change in vector state.#\n 135| " + } + ] + }, + { + "parameter_name": "TRAP_ON_ILLEGAL_WLRL", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 3, + "candidates": [ + { + "score": 3, + "reasons": [ + "Optional/read-only pattern for boolean param" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 25, + "line_text": "registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and", + "context": " 23| The hypervisor extension depends on an \"I\" base integer ISA with 32\n 24| `x` registers (RV32I or RV64I), not RV32E or RV64E, which have only 16 `x`\n>>> 25| registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and\n 26| [#norm:H_vm_supported]#standard\n 27| page-based address translation must be supported, either Sv32 for RV32," + }, + { + "score": 3, + "reasons": [ + "Optional/read-only pattern for boolean param" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 231, + "line_text": "[#norm:misa_e_not_i]#Unless `misa` is all read-only zero, the", + "context": " 229| \n 230| [#norm:misa_e_acc]#The \"E\" bit is read-only.#\n>>> 231| [#norm:misa_e_not_i]#Unless `misa` is all read-only zero, the\n 232| \"E\" bit always reads as the complement of the \"I\" bit.#\n 233| If an execution environment supports both RV32E and RV32I, software can select" + }, + { + "score": 3, + "reasons": [ + "Optional/read-only pattern for boolean param" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 423, + "line_text": "[#norm:mstatus_sie_spie_rdonly0]#If supervisor mode is not implemented, then SIE and SPIE are read-only 0.#", + "context": " 421| to disable selected higher-privilege-mode interrupts before ceding\n 422| control to a lower-privilege mode.\n>>> 423| [#norm:mstatus_sie_spie_rdonly0]#If supervisor mode is not implemented, then SIE and SPIE are read-only 0.#\n 424| \n 425| [NOTE]" + }, + { + "score": 3, + "reasons": [ + "Optional/read-only pattern for boolean param" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 479, + "line_text": "[#norm:mstatus_xpp_rdonly0]#If privilege mode _x_ is not implemented, then __x__PP must be read-only 0.#", + "context": " 477| \n 478| [#norm:mstatus_xpp_warl]#__x__PP fields are *WARL* fields that can hold only privilege mode _x_ and any implemented privilege mode lower than _x_.#\n>>> 479| [#norm:mstatus_xpp_rdonly0]#If privilege mode _x_ is not implemented, then __x__PP must be read-only 0.#\n 480| \n 481| [NOTE]" + }, + { + "score": 3, + "reasons": [ + "Optional/read-only pattern for boolean param" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 577, + "line_text": "[#norm:mstatus_sxl_acc_mxlen64]#When MXLEN=64, if S-mode is not supported, then SXL is read-only zero.", + "context": " 575| When MXLEN=32, the SXL and UXL fields do not exist, and SXLEN=32 and UXLEN=32.\n 576| \n>>> 577| [#norm:mstatus_sxl_acc_mxlen64]#When MXLEN=64, if S-mode is not supported, then SXL is read-only zero.\n 578| Otherwise, it is a *WARL* field that encodes the current value of SXLEN.#\n 579| In particular, [#norm:mstatus_sxl_rdonly_mxlen64]#an implementation may make SXL be a read-only field whose" + } + ] + }, + { + "parameter_name": "TRAP_ON_RESERVED_INSTRUCTION", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 6, + "candidates": [ + { + "score": 6, + "reasons": [ + "Name segment 'INSTRUCTION'", + "Name segment 'RESERVED'", + "Description keyword 'instruction'" + ], + "is_normative": true, + "in_note": false, + "file": "c-st-ext.adoc", + "line_number": 756, + "line_text": "[#norm:Zca_illegal]#A 16-bit instruction with all bits zero is permanently reserved as an", + "context": " 754| ((((compressed. C.DIINST))))\n 755| \n>>> 756| [#norm:Zca_illegal]#A 16-bit instruction with all bits zero is permanently reserved as an\n 757| illegal instruction.#\n 758| " + }, + { + "score": 6, + "reasons": [ + "Name segment 'INSTRUCTION'", + "Name segment 'RESERVED'", + "Description keyword 'instruction'" + ], + "is_normative": true, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 1553, + "line_text": "EMUL<1/8), the instruction encoding is reserved.# [#norm:vector_ls_emul_offgroup_rsv]#The vector register", + "context": " 1551| instruction. The corresponding EMUL is calculated as EMUL =\n 1552| (EEW/SEW)*LMUL.# [#norm:vector_ls_emul_rsv]#If the EMUL would be out of range (EMUL>8 or\n>>> 1553| EMUL<1/8), the instruction encoding is reserved.# [#norm:vector_ls_emul_offgroup_rsv]#The vector register\n 1554| groups must have legal register specifiers for the selected EMUL,\n 1555| otherwise the instruction encoding is reserved.#" + }, + { + "score": 6, + "reasons": [ + "Name segment 'INSTRUCTION'", + "Name segment 'RESERVED'", + "Description keyword 'instruction'" + ], + "is_normative": true, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 2089, + "line_text": "otherwise the instruction encoding is reserved. [#norm:vector_ls_seg_wholereg_op]#NFIELDS", + "context": " 2087| The encoded number of registers must be a power of 2 and the vector\n 2088| register numbers must be aligned as with a vector register group,\n>>> 2089| otherwise the instruction encoding is reserved. [#norm:vector_ls_seg_wholereg_op]#NFIELDS\n 2090| indicates the number of vector registers to transfer, numbered\n 2091| successively after the base.# [#norm:vector_ls_seg_wholereg_nf_rsv]#Only NFIELDS values of 1, 2, 4, 8 are" + }, + { + "score": 6, + "reasons": [ + "Name segment 'INSTRUCTION'", + "Name segment 'RESERVED'", + "Description keyword 'instruction'" + ], + "is_normative": true, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 2631, + "line_text": "[#norm:vadc_vsbc_vd_v0_rsv]#For `vadc` and `vsbc`, the instruction encoding is reserved if the", + "context": " 2629| truncation, is negative.#\n 2630| \n>>> 2631| [#norm:vadc_vsbc_vd_v0_rsv]#For `vadc` and `vsbc`, the instruction encoding is reserved if the\n 2632| destination vector register is `v0`.#\n 2633| " + }, + { + "score": 5, + "reasons": [ + "Name segment 'INSTRUCTION'", + "Description keyword 'instruction'" + ], + "is_normative": true, + "in_note": false, + "file": "c-st-ext.adoc", + "line_number": 310, + "line_text": "[#norm:c-ldsp_op]#C.LDSP is an RV64C-only instruction that loads a 64-bit value", + "context": " 308| valid only when _rd_≠`x0`; the code points with _rd_=`x0` are reserved.#\n 309| \n>>> 310| [#norm:c-ldsp_op]#C.LDSP is an RV64C-only instruction that loads a 64-bit value\n 311| from memory into register _rd_. It computes its effective address by\n 312| adding the zero-extended offset, scaled by 8, to the stack pointer," + } + ] + }, + { + "parameter_name": "TRAP_ON_SFENCE_VMA_WHEN_SATP_MODE_IS_READ_ONLY", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 9, + "candidates": [ + { + "score": 9, + "reasons": [ + "Name segment 'SATP'", + "Name segment 'SFENCE'", + "Description keyword 'SFENCE.VMA'", + "Description keyword 'satp'", + "Description keyword 'MODE'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 250, + "line_text": "VS-mode to execute SFENCE.VMA or SINVAL.VMA or to access CSR `satp`", + "context": " 248| interrupts when the instruction is executed.#\n 249| [#norm:hstatus-vtvm_op]#When VTVM=1, an attempt in\n>>> 250| VS-mode to execute SFENCE.VMA or SINVAL.VMA or to access CSR `satp`\n 251| raises a virtual-instruction exception.#\n 252| " + }, + { + "score": 9, + "reasons": [ + "Optional/read-only pattern for boolean param", + "Name segment 'SATP'", + "Description keyword 'satp'", + "Description keyword 'MODE'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 670, + "line_text": "[#norm:mstatus_sum_rdonly0]#SUM is read-only 0 if S-mode is not supported or if `satp`.MODE is read-only 0.#", + "context": " 668| Note that, [#norm:mstatus_sum_op_mprv_mpp]#while SUM is ordinarily ignored when not\n 669| executing in S-mode, it _is_ in effect when MPRV=1 and MPP=S.#\n>>> 670| [#norm:mstatus_sum_rdonly0]#SUM is read-only 0 if S-mode is not supported or if `satp`.MODE is read-only 0.#\n 671| \n 672| [[norm:mstatus_mxr_sum_op_acc_fault]]" + }, + { + "score": 8, + "reasons": [ + "Name segment 'SATP'", + "Description keyword 'satp'", + "Description keyword 'MODE'" + ], + "is_normative": true, + "in_note": false, + "file": "priv-cfi.adoc", + "line_number": 216, + "line_text": "[#norm:satp-mode_bare]#If `satp.MODE` (or `vsatp.MODE` when `V=1`) is set to `Bare` and the effective", + "context": " 214| `henvcfg.SSE=0`, this encoding remains reserved at `VS` and `VU` levels.#\n 215| \n>>> 216| [#norm:satp-mode_bare]#If `satp.MODE` (or `vsatp.MODE` when `V=1`) is set to `Bare` and the effective\n 217| privilege mode is less than M, shadow stack instructions raise a store/AMO access-fault exception.#\n 218| [#norm:ssmp_ssamoswap]#When the effective privilege mode is M, memory access" + }, + { + "score": 8, + "reasons": [ + "Name segment 'SATP'", + "Description keyword 'satp'", + "Description keyword 'MODE'" + ], + "is_normative": true, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 1008, + "line_text": "[[norm:satp-mode]]", + "context": " 1006| ====\n 1007| \n>>> 1008| [[norm:satp-mode]]\n 1009| <> shows the encodings of the MODE field when\n 1010| SXLEN=32 and SXLEN=64. When MODE=Bare, supervisor virtual addresses are" + }, + { + "score": 7, + "reasons": [ + "Name segment 'SFENCE'", + "Description keyword 'SFENCE.VMA'", + "Description keyword 'MODE'" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2397, + "line_text": "* [#norm:H_virtinst_vs_sfence_sinval_satp_vtvm1]#in VS-mode, attempts to execute an SFENCE.VMA or SINVAL.VMA", + "context": " 2395| * [#norm:H_virtinst_vs_sret_vtsr1]#in VS-mode, attempts to execute SRET when `hstatus`.VTSR=1#; and\n 2396| \n>>> 2397| * [#norm:H_virtinst_vs_sfence_sinval_satp_vtvm1]#in VS-mode, attempts to execute an SFENCE.VMA or SINVAL.VMA\n 2398| instruction or to access `satp`, when `hstatus`.VTVM=1.#\n 2399| " + } + ] + }, + { + "parameter_name": "TRAP_ON_UNIMPLEMENTED_CSR", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 8, + "candidates": [ + { + "score": 8, + "reasons": [ + "Description keyword 'Zicsr'" + ], + "is_normative": true, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 5140, + "line_text": "[#norm:Zve32x_dependent_Zicsr]#The Zve32x extension depends on the Zicsr extension.#", + "context": " 5138| with EEW=64 floating-point operands.#\n 5139| \n>>> 5140| [#norm:Zve32x_dependent_Zicsr]#The Zve32x extension depends on the Zicsr extension.#\n 5141| [#norm:Zve32f_Zve64f_dependent_F]#The Zve32f and Zve64f extensions depend upon the F extension,\n 5142| and implement all" + }, + { + "score": 6, + "reasons": [ + "Description keyword 'Zicsr'" + ], + "is_normative": false, + "in_note": false, + "file": "counters.adoc", + "line_number": 16, + "line_text": "The Zicntr extension depends on the Zicsr extension.", + "context": " 14| counters (CYCLE, TIME, and INSTRET), which have dedicated functions\n 15| (cycle count, real-time clock, and instructions retired, respectively).\n>>> 16| The Zicntr extension depends on the Zicsr extension.\n 17| \n 18| [NOTE]" + }, + { + "score": 6, + "reasons": [ + "Description keyword 'Zicsr'" + ], + "is_normative": false, + "in_note": false, + "file": "counters.adoc", + "line_number": 197, + "line_text": "depends on the Zicsr extension.", + "context": " 195| XLEN=32, the upper 32 bits of these performance counters are accessible\n 196| via additional CSRs `hpmcounter3h- hpmcounter31h`.# The Zihpm extension\n>>> 197| depends on the Zicsr extension.\n 198| [NOTE]\n 199| ====" + }, + { + "score": 6, + "reasons": [ + "Description keyword 'Zicsr'" + ], + "is_normative": false, + "in_note": false, + "file": "f-st-ext.adoc", + "line_number": 10, + "line_text": "with the IEEE 754-2008 arithmetic standard cite:[ieee754-2008]. The F extension depends on the \"Zicsr\" extension for control and status register access.", + "context": " 8| single-precision floating-point, which is named \"F\" and adds\n 9| single-precision floating-point computational instructions compliant\n>>> 10| with the IEEE 754-2008 arithmetic standard cite:[ieee754-2008]. The F extension depends on the \"Zicsr\" extension for control and status register access.\n 11| \n 12| === F Register State" + }, + { + "score": 6, + "reasons": [ + "Description keyword 'Zicsr'" + ], + "is_normative": false, + "in_note": false, + "file": "naming.adoc", + "line_number": 44, + "line_text": "\"D\" depends on \"F\" and \"F\" depends on \"Zicsr\". These dependencies", + "context": " 42| \n 43| Some ISA extensions depend on the presence of other extensions, e.g.,\n>>> 44| \"D\" depends on \"F\" and \"F\" depends on \"Zicsr\". These dependencies\n 45| may be implicit in the ISA name: for example, RV32IF is equivalent to\n 46| RV32IFZicsr, and RV32ID is equivalent to RV32IFD and RV32IFDZicsr." + } + ] + }, + { + "parameter_name": "TRAP_ON_UNIMPLEMENTED_INSTRUCTION", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 5, + "candidates": [ + { + "score": 5, + "reasons": [ + "Name segment 'INSTRUCTION'", + "Description keyword 'instruction'" + ], + "is_normative": true, + "in_note": false, + "file": "c-st-ext.adoc", + "line_number": 310, + "line_text": "[#norm:c-ldsp_op]#C.LDSP is an RV64C-only instruction that loads a 64-bit value", + "context": " 308| valid only when _rd_≠`x0`; the code points with _rd_=`x0` are reserved.#\n 309| \n>>> 310| [#norm:c-ldsp_op]#C.LDSP is an RV64C-only instruction that loads a 64-bit value\n 311| from memory into register _rd_. It computes its effective address by\n 312| adding the zero-extended offset, scaled by 8, to the stack pointer," + }, + { + "score": 5, + "reasons": [ + "Name segment 'INSTRUCTION'", + "Description keyword 'instruction'" + ], + "is_normative": true, + "in_note": false, + "file": "c-st-ext.adoc", + "line_number": 318, + "line_text": "[#norm:c-flwsp_op]#C.FLWSP is an RV32FC-only instruction that loads a single-precision", + "context": " 316| _rd_=`x0` are reserved.#\n 317| \n>>> 318| [#norm:c-flwsp_op]#C.FLWSP is an RV32FC-only instruction that loads a single-precision\n 319| floating-point value from memory into floating-point register _rd_. It\n 320| computes its effective address by adding the _zero_-extended offset," + }, + { + "score": 5, + "reasons": [ + "Name segment 'INSTRUCTION'", + "Description keyword 'instruction'" + ], + "is_normative": true, + "in_note": false, + "file": "c-st-ext.adoc", + "line_number": 324, + "line_text": "[#norm:c-fldsp_op]#C.FLDSP is an RV32DC/RV64DC-only instruction that loads a", + "context": " 322| `flw rd, offset(x2)`.#\n 323| \n>>> 324| [#norm:c-fldsp_op]#C.FLDSP is an RV32DC/RV64DC-only instruction that loads a\n 325| double-precision floating-point value from memory into floating-point\n 326| register _rd_. It computes its effective address by adding the" + }, + { + "score": 5, + "reasons": [ + "Name segment 'INSTRUCTION'", + "Description keyword 'instruction'" + ], + "is_normative": true, + "in_note": false, + "file": "c-st-ext.adoc", + "line_number": 340, + "line_text": "[#norm:c-sdsp_op]#C.SDSP is an RV64C-only instruction that stores a 64-bit value in", + "context": " 338| the stack pointer, `x2`. It expands to `sw rs2, offset(x2)`.#\n 339| \n>>> 340| [#norm:c-sdsp_op]#C.SDSP is an RV64C-only instruction that stores a 64-bit value in\n 341| register _rs2_ to memory. It computes an effective address by adding the\n 342| _zero_-extended offset, scaled by 8, to the stack pointer, `x2`. It" + }, + { + "score": 5, + "reasons": [ + "Name segment 'INSTRUCTION'", + "Description keyword 'instruction'" + ], + "is_normative": true, + "in_note": false, + "file": "c-st-ext.adoc", + "line_number": 345, + "line_text": "[#norm:c-fswsp_op]#C.FSWSP is an RV32FC-only instruction that stores a single-precision", + "context": " 343| expands to `sd rs2, offset(x2)`.#\n 344| \n>>> 345| [#norm:c-fswsp_op]#C.FSWSP is an RV32FC-only instruction that stores a single-precision\n 346| floating-point value in floating-point register _rs2_ to memory. It\n 347| computes an effective address by adding the _zero_-extended offset," + } + ] + }, + { + "parameter_name": "UXLEN", + "classification": "NORM_DIRECT", + "value_type": "set", + "num_candidates": 10, + "best_score": 11, + "candidates": [ + { + "score": 11, + "reasons": [ + "CSR field name 'UXL'", + "Name segment 'UXLEN'", + "Exact parameter name 'UXLEN'", + "Description keyword 'UXL'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 575, + "line_text": "When MXLEN=32, the SXL and UXL fields do not exist, and SXLEN=32 and UXLEN=32.", + "context": " 573| \n 574| [[norm:mstatus_sxl_uxl_sxlen_uxlen_mxlen32]]\n>>> 575| When MXLEN=32, the SXL and UXL fields do not exist, and SXLEN=32 and UXLEN=32.\n 576| \n 577| [#norm:mstatus_sxl_acc_mxlen64]#When MXLEN=64, if S-mode is not supported, then SXL is read-only zero." + }, + { + "score": 11, + "reasons": [ + "CSR field name 'UXL'", + "Name segment 'UXLEN'", + "Exact parameter name 'UXLEN'", + "Description keyword 'UXL'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 143, + "line_text": "When SXLEN=32, the UXL field does not exist, and UXLEN=32. When", + "context": " 141| \n 142| [[norm:sstatus-uxl_sz]]\n>>> 143| When SXLEN=32, the UXL field does not exist, and UXLEN=32. When\n 144| SXLEN=64, it is a *WARL* field that encodes the current value of UXLEN. In\n 145| particular, an implementation may make UXL be a read-only field whose" + }, + { + "score": 10, + "reasons": [ + "CSR field name 'UXL'", + "Description keyword 'UXL'", + "Parameter name in emphasis '_UXLEN_'" + ], + "is_normative": false, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 137, + "line_text": "The UXL field controls the value of XLEN for U-mode, termed _UXLEN_,", + "context": " 135| \n 136| [[norm:sstatus-uxl]]\n>>> 137| The UXL field controls the value of XLEN for U-mode, termed _UXLEN_,\n 138| which may differ from the value of XLEN for S-mode, termed _SXLEN_. The\n 139| encoding of UXL is the same as that of the MXL field of `misa`, shown in" + }, + { + "score": 9, + "reasons": [ + "CSR name 'mstatus' in backticks", + "CSR field name 'UXL'", + "Description keyword 'UXL'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 393, + "line_text": "[#norm:mstatush_enc]#Bits 30:4 of `mstatush` generally contain the same fields found in bits 62:36 of `mstatus` for RV64. Fields SD, SXL, and UXL do not exist in `mstatush`.#", + "context": " 391| \n 392| [#norm:mstatush_sz_acc]#For RV32 only, `mstatush` is a 32-bit read/write register formatted as shown in <>.#\n>>> 393| [#norm:mstatush_enc]#Bits 30:4 of `mstatush` generally contain the same fields found in bits 62:36 of `mstatus` for RV64. Fields SD, SXL, and UXL do not exist in `mstatush`.#\n 394| \n 395| [[mstatushreg]]" + }, + { + "score": 8, + "reasons": [ + "Parameter name in emphasis '_UXLEN_'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 572, + "line_text": "[#norm:sxlen_uxlen]#The effective XLEN in S-mode and U-mode are termed _SXLEN_ and _UXLEN_, respectively.#", + "context": " 570| value of XLEN for S-mode and U-mode, respectively.#\n 571| [#norm:mstatus_sxl_uxl_enc]#The encoding of these fields is the same as the MXL field of `misa`, shown in <>.#\n>>> 572| [#norm:sxlen_uxlen]#The effective XLEN in S-mode and U-mode are termed _SXLEN_ and _UXLEN_, respectively.#\n 573| \n 574| [[norm:mstatus_sxl_uxl_sxlen_uxlen_mxlen32]]" + } + ] + }, + { + "parameter_name": "U_MODE_ENDIANNESS", + "classification": "NORM_CSR_RW", + "value_type": "enum", + "num_candidates": 10, + "best_score": 14, + "candidates": [ + { + "score": 14, + "reasons": [ + "CSR field name 'UBE'", + "WARL + CSR 'mstatus'", + "CSR name 'mstatus' in backticks", + "Description keyword 'UBE'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 679, + "line_text": "[#norm:mstatus_mstatush_xbe_warl]#The MBE, SBE, and UBE bits in `mstatus` and `mstatush` are *WARL* fields# that", + "context": " 677| ===== Endianness Control in `mstatus` and `mstatush` Registers\n 678| \n>>> 679| [#norm:mstatus_mstatush_xbe_warl]#The MBE, SBE, and UBE bits in `mstatus` and `mstatush` are *WARL* fields# that\n 680| control the endianness of memory accesses other than instruction fetches.\n 681| [#norm:endianness_inst_fetch_little]#Instruction fetches are always little-endian.#" + }, + { + "score": 8, + "reasons": [ + "WARL + CSR 'mstatus'", + "CSR name 'mstatus' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "priv-preface.adoc", + "line_number": 501, + "line_text": "* Made the `mstatus`.MPP field *WARL*, rather than *WLRL*.", + "context": " 499| the possibility of a future global-ASID extension.\n 500| * SFENCE.VMA semantics have been clarified.\n>>> 501| * Made the `mstatus`.MPP field *WARL*, rather than *WLRL*.\n 502| * Made the unused `__x__ip` fields *WPRI*, rather than *WIRI*.\n 503| * Made the unused `misa` fields *WARL*, rather than *WIRI*." + }, + { + "score": 6, + "reasons": [ + "CSR field name 'UBE'", + "Description keyword 'endian'", + "Description keyword 'UBE'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 696, + "line_text": "little-endian (UBE=0) or big-endian (UBE=1).", + "context": " 694| If U-mode is not supported, UBE is read-only 0. Otherwise, UBE controls\n 695| whether explicit load and store memory accesses made from U-mode are\n>>> 696| little-endian (UBE=0) or big-endian (UBE=1).\n 697| \n 698| [#norm:mstatus_sbe_implicit]#For _implicit_ accesses to supervisor-level memory management data" + }, + { + "score": 6, + "reasons": [ + "CSR field name 'UBE'", + "Description keyword 'UBE'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 718, + "line_text": "[#norm:mstatus_ube_rocopy]#If U-mode is supported, an implementation may make UBE be a", + "context": " 716| [#norm:mstatus_sbe_rocopy]#If S-mode is supported, an implementation may make SBE be a read-only\n 717| copy of MBE.#\n>>> 718| [#norm:mstatus_ube_rocopy]#If U-mode is supported, an implementation may make UBE be a\n 719| read-only copy of either MBE or SBE.#\n 720| " + }, + { + "score": 6, + "reasons": [ + "CSR field name 'UBE'", + "Description keyword 'UBE'" + ], + "is_normative": true, + "in_note": false, + "file": "supervisor.adoc", + "line_number": 224, + "line_text": "[[norm:sstatus-ube]]", + "context": " 222| ===== Endianness Control in `sstatus` Register\n 223| \n>>> 224| [[norm:sstatus-ube]]\n 225| The UBE bit is a *WARL* field that controls the endianness of explicit memory\n 226| accesses made from U-mode, which may differ from the endianness of" + } + ] + }, + { + "parameter_name": "VENDOR_ID_BANK", + "classification": "NORM_DIRECT", + "value_type": "range", + "num_candidates": 10, + "best_score": 12, + "candidates": [ + { + "score": 12, + "reasons": [ + "Description keyword 'mvendorid'", + "Description keyword 'JEDEC'", + "CSR name 'mvendorid' in backticks" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 263, + "line_text": "[#norm:mvendorid_sz_acc_op]#The `mvendorid` CSR is a 32-bit read-only register providing the JEDEC", + "context": " 261| ==== Machine Vendor ID (`mvendorid`) Register\n 262| \n>>> 263| [#norm:mvendorid_sz_acc_op]#The `mvendorid` CSR is a 32-bit read-only register providing the JEDEC\n 264| manufacturer ID of the provider of the core.#\n 265| [#norm:mvendorid_always_rd]#This register must be readable in any implementation, but a value of 0 can be returned to" + }, + { + "score": 10, + "reasons": [ + "Description keyword 'mvendorid'", + "Description keyword 'JEDEC'", + "CSR name 'mvendorid' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "priv-preface.adoc", + "line_number": 531, + "line_text": "* The `mvendorid` register now contains the JEDEC code of the core", + "context": " 529| * The explicit convention on shadow CSR addresses has been removed to\n 530| reclaim CSR space. Shadow CSRs can still be added as needed.\n>>> 531| * The `mvendorid` register now contains the JEDEC code of the core\n 532| provider as opposed to a code supplied by the Foundation. This avoids\n 533| redundancy and offloads work from the Foundation." + }, + { + "score": 7, + "reasons": [ + "Description keyword 'mvendorid'", + "Name segment 'VENDOR'", + "CSR name 'mvendorid' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 261, + "line_text": "==== Machine Vendor ID (`mvendorid`) Register", + "context": " 259| reserved, not necessarily illegal.\n 260| \n>>> 261| ==== Machine Vendor ID (`mvendorid`) Register\n 262| \n 263| [#norm:mvendorid_sz_acc_op]#The `mvendorid` CSR is a 32-bit read-only register providing the JEDEC" + }, + { + "score": 7, + "reasons": [ + "Description keyword 'mvendorid'", + "Name segment 'VENDOR'", + "CSR name 'mvendorid' in backticks" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 271, + "line_text": ".Vendor ID register (`mvendorid`)", + "context": " 269| //image::png/mvendorid.png[align=\"center\"]\n 270| \n>>> 271| .Vendor ID register (`mvendorid`)\n 272| include::images/bytefield/mvendorid.edn[]\n 273| " + }, + { + "score": 6, + "reasons": [ + "Description keyword 'JEDEC'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 274, + "line_text": "[#norm:mvendorid_enc]#JEDEC manufacturer IDs are ordinarily encoded as a sequence of one-byte", + "context": " 272| include::images/bytefield/mvendorid.edn[]\n 273| \n>>> 274| [#norm:mvendorid_enc]#JEDEC manufacturer IDs are ordinarily encoded as a sequence of one-byte\n 275| continuation codes `0x7f`, terminated by a one-byte ID not equal to\n 276| `0x7f`, with an odd parity bit in the most-significant bit of each byte." + } + ] + }, + { + "parameter_name": "VENDOR_ID_OFFSET", + "classification": "NORM_DIRECT", + "value_type": "range", + "num_candidates": 10, + "best_score": 7, + "candidates": [ + { + "score": 7, + "reasons": [ + "Description keyword 'JEDEC'", + "CSR name 'mvendorid' in backticks" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 263, + "line_text": "[#norm:mvendorid_sz_acc_op]#The `mvendorid` CSR is a 32-bit read-only register providing the JEDEC", + "context": " 261| ==== Machine Vendor ID (`mvendorid`) Register\n 262| \n>>> 263| [#norm:mvendorid_sz_acc_op]#The `mvendorid` CSR is a 32-bit read-only register providing the JEDEC\n 264| manufacturer ID of the provider of the core.#\n 265| [#norm:mvendorid_always_rd]#This register must be readable in any implementation, but a value of 0 can be returned to" + }, + { + "score": 6, + "reasons": [ + "Name segment 'VENDOR'", + "CSR name 'mvendorid' in backticks", + "Description keyword 'ID'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 261, + "line_text": "==== Machine Vendor ID (`mvendorid`) Register", + "context": " 259| reserved, not necessarily illegal.\n 260| \n>>> 261| ==== Machine Vendor ID (`mvendorid`) Register\n 262| \n 263| [#norm:mvendorid_sz_acc_op]#The `mvendorid` CSR is a 32-bit read-only register providing the JEDEC" + }, + { + "score": 6, + "reasons": [ + "Name segment 'VENDOR'", + "CSR name 'mvendorid' in backticks", + "Description keyword 'ID'" + ], + "is_normative": false, + "in_note": false, + "file": "machine.adoc", + "line_number": 271, + "line_text": ".Vendor ID register (`mvendorid`)", + "context": " 269| //image::png/mvendorid.png[align=\"center\"]\n 270| \n>>> 271| .Vendor ID register (`mvendorid`)\n 272| include::images/bytefield/mvendorid.edn[]\n 273| " + }, + { + "score": 5, + "reasons": [ + "CSR field name 'Offset'", + "Name segment 'OFFSET'" + ], + "is_normative": true, + "in_note": false, + "file": "c-st-ext.adoc", + "line_number": 476, + "line_text": "[#norm:c-j_op]#C.J performs an unconditional control transfer. The offset is", + "context": " 474| These instructions use the CJ format.\n 475| \n>>> 476| [#norm:c-j_op]#C.J performs an unconditional control transfer. The offset is\n 477| sign-extended and added to the `pc` to form the jump target address. C.J\n 478| can therefore target a {pm}2 KiB range. C.J expands to" + }, + { + "score": 5, + "reasons": [ + "CSR field name 'Offset'", + "Name segment 'OFFSET'" + ], + "is_normative": true, + "in_note": false, + "file": "c-st-ext.adoc", + "line_number": 523, + "line_text": "[#norm:c-beqz_op]#C.BEQZ performs conditional control transfers. The offset is", + "context": " 521| These instructions use the CB format.\n 522| \n>>> 523| [#norm:c-beqz_op]#C.BEQZ performs conditional control transfers. The offset is\n 524| sign-extended and added to the `pc` to form the branch target address.\n 525| It can therefore target a {pm}256 B range. C.BEQZ takes the" + } + ] + }, + { + "parameter_name": "VLEN", + "classification": "NORM_DIRECT", + "value_type": "value", + "num_candidates": 10, + "best_score": 12, + "candidates": [ + { + "score": 12, + "reasons": [ + "Name segment 'VLEN'", + "CSR name 'vlenb' in backticks", + "CSR field name 'VALUE'", + "Exact parameter name 'VLEN'" + ], + "is_normative": false, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 511, + "line_text": "The _XLEN_-bit-wide read-only CSR `vlenb` holds the value VLEN/8,", + "context": " 509| \n 510| [[norm:vlenb_acc_op]]\n>>> 511| The _XLEN_-bit-wide read-only CSR `vlenb` holds the value VLEN/8,\n 512| i.e., the vector register length in bytes.\n 513| " + }, + { + "score": 12, + "reasons": [ + "Name segment 'VLEN'", + "CSR name 'vstart' in backticks", + "Exact parameter name 'VLEN'" + ], + "is_normative": true, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 4521, + "line_text": "register ( 0 < index < VLEN/SEW) are treated as tail elements using the current tail agnostic/undisturbed policy.# [#norm:vmv-s-x_vstart_ge_vl]#If `vstart` {ge} `vl`, no", + "context": " 4519| are copied and the upper XLEN-SEW bits are ignored. If SEW > XLEN, the value\n 4520| is sign-extended to SEW bits. The other elements in the destination vector\n>>> 4521| register ( 0 < index < VLEN/SEW) are treated as tail elements using the current tail agnostic/undisturbed policy.# [#norm:vmv-s-x_vstart_ge_vl]#If `vstart` {ge} `vl`, no\n 4522| operation is performed and the destination register is not updated.#\n 4523| " + }, + { + "score": 10, + "reasons": [ + "Name segment 'VLEN'", + "CSR name 'vstart' in backticks", + "Exact parameter name 'VLEN'" + ], + "is_normative": false, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 550, + "line_text": "setting (8) and the smallest SEW setting (8), so VLMAX_max = 8*VLEN/8 = VLEN. For example, for VLEN=256, `vstart` would have 8 bits to", + "context": " 548| \n 549| NOTE: The maximum vector length is obtained with the largest LMUL\n>>> 550| setting (8) and the smallest SEW setting (8), so VLMAX_max = 8*VLEN/8 = VLEN. For example, for VLEN=256, `vstart` would have 8 bits to\n 551| represent indices from 0 through 255.\n 552| " + }, + { + "score": 9, + "reasons": [ + "Name segment 'VLEN'", + "CSR field name 'VALUE'", + "Exact parameter name 'VLEN'" + ], + "is_normative": false, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 320, + "line_text": "The derived value VLMAX = LMUL*VLEN/SEW represents the maximum number", + "context": " 318| \n 319| [[norm:vlmax]]\n>>> 320| The derived value VLMAX = LMUL*VLEN/SEW represents the maximum number\n 321| of elements that can be operated on with a single vector instruction\n 322| given the current SEW and LMUL settings as shown in the table below." + }, + { + "score": 9, + "reasons": [ + "Name segment 'VLEN'", + "CSR field name 'VALUE'", + "Exact parameter name 'VLEN'" + ], + "is_normative": false, + "in_note": false, + "file": "v-st-ext.adoc", + "line_number": 4876, + "line_text": "VLEN bits) and can copy whole vector register groups. The `nr` value", + "context": " 4874| \n 4875| [#norm:vmv-nr-r_op]#The `vmvr.v` instructions copy whole vector registers (i.e., all\n>>> 4876| VLEN bits) and can copy whole vector register groups. The `nr` value\n 4877| in the opcode is the number of individual vector registers, NREG, to\n 4878| copy. The instructions operate as if EEW=SEW, EMUL = NREG, effective" + } + ] + }, + { + "parameter_name": "VMID_WIDTH", + "classification": "NORM_DIRECT", + "value_type": "conditional", + "num_candidates": 10, + "best_score": 8, + "candidates": [ + { + "score": 8, + "reasons": [ + "CSR field name 'VMID'", + "Description keyword 'VMID'", + "CSR name 'hgatp' in backticks", + "Name segment 'VMID'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1089, + "line_text": "bit position in the VMID field, then reading back the value in `hgatp`", + "context": " 1087| [#norm:hgatp-vmid_param]#The number of VMID bits is UNSPECIFIED and may be zero.# The number of implemented\n 1088| VMID bits, termed _VMIDLEN_, may be determined by writing one to every\n>>> 1089| bit position in the VMID field, then reading back the value in `hgatp`\n 1090| to see which bit positions in the VMID field hold a one. [#norm:hgatp-vmid_lsbs]#The\n 1091| least-significant bits of VMID are implemented first: that is, if" + }, + { + "score": 8, + "reasons": [ + "CSR field name 'VMID'", + "Description keyword 'VMID'", + "CSR name 'hgatp' in backticks", + "Name segment 'VMID'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1554, + "line_text": "* execute when `hgatp`.VMID has the same setting as it did when", + "context": " 1552| \n 1553| * are subsequent to the HFENCE.VVMA, and\n>>> 1554| * execute when `hgatp`.VMID has the same setting as it did when\n 1555| HFENCE.VVMA executed.\n 1556| " + }, + { + "score": 8, + "reasons": [ + "CSR field name 'VMID'", + "Description keyword 'VMID'", + "CSR name 'hgatp' in backticks", + "Name segment 'VMID'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1558, + "line_text": "Implicit reads need not be ordered when `hgatp`.VMID is different than", + "context": " 1556| \n 1557| [[norm:hfence-vvma_limits]]\n>>> 1558| Implicit reads need not be ordered when `hgatp`.VMID is different than\n 1559| at the time HFENCE.VVMA executed. If operand __rs1__≠`x0`, it specifies a single guest virtual address, and if operand __rs2__≠`x0`, it specifies a single guest address-space identifier (ASID).\n 1560| " + }, + { + "score": 8, + "reasons": [ + "CSR field name 'VMID'", + "Description keyword 'VMID'", + "CSR name 'hgatp' in backticks", + "Name segment 'VMID'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1641, + "line_text": "If `hgatp`.MODE is changed for a given VMID, an HFENCE.GVMA with", + "context": " 1639| \n 1640| [[norm:hfence-gvma_mode]]\n>>> 1641| If `hgatp`.MODE is changed for a given VMID, an HFENCE.GVMA with\n 1642| _rs1_=`x0` (and _rs2_ set to either `x0` or the VMID) must be executed\n 1643| to order subsequent guest translations with the MODE change—even if the" + }, + { + "score": 8, + "reasons": [ + "CSR field name 'VMID'", + "Description keyword 'VMID'", + "CSR name 'hgatp' in backticks", + "Name segment 'VMID'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2083, + "line_text": "machine is identified by the VMID field of CSR `hgatp`, and the", + "context": " 2081| address within the current virtual machine, and the ASID argument is a\n 2082| VS-level ASID within the current virtual machine. The current virtual\n>>> 2083| machine is identified by the VMID field of CSR `hgatp`, and the\n 2084| effective ASID can be considered to be the combination of this VMID with\n 2085| the VS-level ASID. The SFENCE.VMA instruction orders stores only to the" + } + ] + }, + { + "parameter_name": "VSSTAGE_MODE_BARE", + "classification": "NORM_DIRECT", + "value_type": "binary", + "num_candidates": 10, + "best_score": 6, + "candidates": [ + { + "score": 6, + "reasons": [ + "Name segment 'BARE'", + "Description keyword 'vsatp'" + ], + "is_normative": true, + "in_note": false, + "file": "priv-cfi.adoc", + "line_number": 216, + "line_text": "[#norm:satp-mode_bare]#If `satp.MODE` (or `vsatp.MODE` when `V=1`) is set to `Bare` and the effective", + "context": " 214| `henvcfg.SSE=0`, this encoding remains reserved at `VS` and `VU` levels.#\n 215| \n>>> 216| [#norm:satp-mode_bare]#If `satp.MODE` (or `vsatp.MODE` when `V=1`) is set to `Bare` and the effective\n 217| privilege mode is less than M, shadow stack instructions raise a store/AMO access-fault exception.#\n 218| [#norm:ssmp_ssamoswap]#When the effective privilege mode is M, memory access" + }, + { + "score": 5, + "reasons": [ + "Description keyword 'vsatp'" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1415, + "line_text": "[#norm:vsatp_mode_unsupported_v0]#When V=0, a write to `vsatp` with an unsupported MODE value is either", + "context": " 1413| ====\n 1414| \n>>> 1415| [#norm:vsatp_mode_unsupported_v0]#When V=0, a write to `vsatp` with an unsupported MODE value is either\n 1416| ignored as it is for `satp`, or the fields of `vsatp` are treated as *WARL* in\n 1417| the normal way.# [#norm:vsatp_mode_unsupported_v1]#However, when V=1, a write to `satp` with an unsupported" + }, + { + "score": 4, + "reasons": [ + "Name segment 'BARE'", + "Description keyword 'vsatp'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2134, + "line_text": "with `vsatp.MODE` = Bare, this means that those two bits may be subject to", + "context": " 2132| Sv32x4, Sv39x4, Sv48x4, and Sv57x4 for translating guest physical addresses to\n 2133| supervisor physical addresses. When running with virtualization in VS/VU mode\n>>> 2134| with `vsatp.MODE` = Bare, this means that those two bits may be subject to\n 2135| pointer masking, depending on `hgatp.MODE` and `senvcfg.PMM`/`henvcfg.PMM` (for\n 2136| VU/VS mode). If `vsatp.MODE` != BARE, this issue does *not* apply." + }, + { + "score": 4, + "reasons": [ + "Name segment 'BARE'", + "Description keyword 'vsatp'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2136, + "line_text": "VU/VS mode). If `vsatp.MODE` != BARE, this issue does *not* apply.", + "context": " 2134| with `vsatp.MODE` = Bare, this means that those two bits may be subject to\n 2135| pointer masking, depending on `hgatp.MODE` and `senvcfg.PMM`/`henvcfg.PMM` (for\n>>> 2136| VU/VS mode). If `vsatp.MODE` != BARE, this issue does *not* apply.\n 2137| \n 2138| [NOTE]" + }, + { + "score": 3, + "reasons": [ + "Optional/read-only pattern for boolean param" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 25, + "line_text": "registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and", + "context": " 23| The hypervisor extension depends on an \"I\" base integer ISA with 32\n 24| `x` registers (RV32I or RV64I), not RV32E or RV64E, which have only 16 `x`\n>>> 25| registers. [#norm:H_mtval_nrz]#CSR `mtval` must not be read-only zero#, and\n 26| [#norm:H_vm_supported]#standard\n 27| page-based address translation must be supported, either Sv32 for RV32," + } + ] + }, + { + "parameter_name": "VSTVEC_MODE_DIRECT", + "classification": "NORM_CSR_WARL", + "value_type": "binary", + "num_candidates": 10, + "best_score": 7, + "candidates": [ + { + "score": 7, + "reasons": [ + "Optional/read-only pattern for boolean param", + "CSR field name 'MODE'", + "Description keyword 'MODE'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 423, + "line_text": "[#norm:mstatus_sie_spie_rdonly0]#If supervisor mode is not implemented, then SIE and SPIE are read-only 0.#", + "context": " 421| to disable selected higher-privilege-mode interrupts before ceding\n 422| control to a lower-privilege mode.\n>>> 423| [#norm:mstatus_sie_spie_rdonly0]#If supervisor mode is not implemented, then SIE and SPIE are read-only 0.#\n 424| \n 425| [NOTE]" + }, + { + "score": 7, + "reasons": [ + "Optional/read-only pattern for boolean param", + "CSR field name 'MODE'", + "Description keyword 'MODE'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 479, + "line_text": "[#norm:mstatus_xpp_rdonly0]#If privilege mode _x_ is not implemented, then __x__PP must be read-only 0.#", + "context": " 477| \n 478| [#norm:mstatus_xpp_warl]#__x__PP fields are *WARL* fields that can hold only privilege mode _x_ and any implemented privilege mode lower than _x_.#\n>>> 479| [#norm:mstatus_xpp_rdonly0]#If privilege mode _x_ is not implemented, then __x__PP must be read-only 0.#\n 480| \n 481| [NOTE]" + }, + { + "score": 7, + "reasons": [ + "Optional/read-only pattern for boolean param", + "CSR field name 'MODE'", + "Description keyword 'MODE'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 577, + "line_text": "[#norm:mstatus_sxl_acc_mxlen64]#When MXLEN=64, if S-mode is not supported, then SXL is read-only zero.", + "context": " 575| When MXLEN=32, the SXL and UXL fields do not exist, and SXLEN=32 and UXLEN=32.\n 576| \n>>> 577| [#norm:mstatus_sxl_acc_mxlen64]#When MXLEN=64, if S-mode is not supported, then SXL is read-only zero.\n 578| Otherwise, it is a *WARL* field that encodes the current value of SXLEN.#\n 579| In particular, [#norm:mstatus_sxl_rdonly_mxlen64]#an implementation may make SXL be a read-only field whose" + }, + { + "score": 7, + "reasons": [ + "Optional/read-only pattern for boolean param", + "CSR field name 'MODE'", + "Description keyword 'MODE'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 582, + "line_text": "[#norm:mstatus_uxl_acc_mxlen64]#When MXLEN=64, if U-mode is not supported, then UXL is read-only zero.", + "context": " 580| value always ensures that SXLEN=MXLEN.#\n 581| \n>>> 582| [#norm:mstatus_uxl_acc_mxlen64]#When MXLEN=64, if U-mode is not supported, then UXL is read-only zero.\n 583| Otherwise, it is a *WARL* field that encodes the current value of UXLEN.#\n 584| In particular, [#norm:mstatus_uxl_rdonly_mxlen64]#an implementation may make UXL be a read-only field whose" + }, + { + "score": 7, + "reasons": [ + "Optional/read-only pattern for boolean param", + "CSR field name 'MODE'", + "Description keyword 'MODE'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 639, + "line_text": "[#norm:mstatus_mprv_rdonly0_no_umode]#MPRV is read-only 0 if U-mode is not supported.#", + "context": " 637| [#norm:mstatus_mprv_inst_xlat_op]#Instruction address-translation and protection are unaffected by the\n 638| setting of MPRV.#\n>>> 639| [#norm:mstatus_mprv_rdonly0_no_umode]#MPRV is read-only 0 if U-mode is not supported.#\n 640| \n 641| [#norm:mstatus_mprv_clr_mret_sret_less_priv]#An MRET or SRET instruction that changes the privilege mode to a mode" + } + ] + }, + { + "parameter_name": "VSTVEC_MODE_VECTORED", + "classification": "NORM_CSR_WARL", + "value_type": "binary", + "num_candidates": 10, + "best_score": 9, + "candidates": [ + { + "score": 9, + "reasons": [ + "Name segment 'VECTORED'", + "Description keyword 'MODE'", + "Description keyword 'vectored'", + "CSR field name 'MODE'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 1256, + "line_text": "[#norm:mtvec_mode_vectored_op]#When MODE=Vectored, all synchronous exceptions into machine mode cause", + "context": " 1254| [#norm:mtvec_mode_direct_op]#When MODE=Direct, all traps into\n 1255| machine mode cause the `pc` to be set to the address in the BASE field.#\n>>> 1256| [#norm:mtvec_mode_vectored_op]#When MODE=Vectored, all synchronous exceptions into machine mode cause\n 1257| the `pc` to be set to the address in the BASE field, whereas interrupts\n 1258| cause the `pc` to be set to the address in the BASE field plus four" + }, + { + "score": 7, + "reasons": [ + "Optional/read-only pattern for boolean param", + "CSR field name 'MODE'", + "Description keyword 'MODE'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 423, + "line_text": "[#norm:mstatus_sie_spie_rdonly0]#If supervisor mode is not implemented, then SIE and SPIE are read-only 0.#", + "context": " 421| to disable selected higher-privilege-mode interrupts before ceding\n 422| control to a lower-privilege mode.\n>>> 423| [#norm:mstatus_sie_spie_rdonly0]#If supervisor mode is not implemented, then SIE and SPIE are read-only 0.#\n 424| \n 425| [NOTE]" + }, + { + "score": 7, + "reasons": [ + "Optional/read-only pattern for boolean param", + "CSR field name 'MODE'", + "Description keyword 'MODE'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 479, + "line_text": "[#norm:mstatus_xpp_rdonly0]#If privilege mode _x_ is not implemented, then __x__PP must be read-only 0.#", + "context": " 477| \n 478| [#norm:mstatus_xpp_warl]#__x__PP fields are *WARL* fields that can hold only privilege mode _x_ and any implemented privilege mode lower than _x_.#\n>>> 479| [#norm:mstatus_xpp_rdonly0]#If privilege mode _x_ is not implemented, then __x__PP must be read-only 0.#\n 480| \n 481| [NOTE]" + }, + { + "score": 7, + "reasons": [ + "Optional/read-only pattern for boolean param", + "CSR field name 'MODE'", + "Description keyword 'MODE'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 577, + "line_text": "[#norm:mstatus_sxl_acc_mxlen64]#When MXLEN=64, if S-mode is not supported, then SXL is read-only zero.", + "context": " 575| When MXLEN=32, the SXL and UXL fields do not exist, and SXLEN=32 and UXLEN=32.\n 576| \n>>> 577| [#norm:mstatus_sxl_acc_mxlen64]#When MXLEN=64, if S-mode is not supported, then SXL is read-only zero.\n 578| Otherwise, it is a *WARL* field that encodes the current value of SXLEN.#\n 579| In particular, [#norm:mstatus_sxl_rdonly_mxlen64]#an implementation may make SXL be a read-only field whose" + }, + { + "score": 7, + "reasons": [ + "Optional/read-only pattern for boolean param", + "CSR field name 'MODE'", + "Description keyword 'MODE'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 582, + "line_text": "[#norm:mstatus_uxl_acc_mxlen64]#When MXLEN=64, if U-mode is not supported, then UXL is read-only zero.", + "context": " 580| value always ensures that SXLEN=MXLEN.#\n 581| \n>>> 582| [#norm:mstatus_uxl_acc_mxlen64]#When MXLEN=64, if U-mode is not supported, then UXL is read-only zero.\n 583| Otherwise, it is a *WARL* field that encodes the current value of UXLEN.#\n 584| In particular, [#norm:mstatus_uxl_rdonly_mxlen64]#an implementation may make UXL be a read-only field whose" + } + ] + }, + { + "parameter_name": "VSXLEN", + "classification": "NORM_DIRECT", + "value_type": "set", + "num_candidates": 10, + "best_score": 20, + "candidates": [ + { + "score": 20, + "reasons": [ + "CSR field name 'VSXL'", + "CSR name 'hstatus' in backticks", + "Name segment 'VSXLEN'", + "Description keyword 'VSXLEN'", + "Description keyword 'VSXL'", + "Exact parameter name 'VSXLEN'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1184, + "line_text": "encoded the same as the MXL field of `misa`, shown in <>. In particular, an implementation may make UXL be a read-only copy of field VSXL of `hstatus`, forcing VU-mode XLEN=VSXLEN.", + "context": " 1182| from the XLEN for VS-mode (VSXLEN). When VSXLEN=32, the UXL field does\n 1183| not exist, and VU-mode XLEN=32. When VSXLEN=64, UXL is a *WARL* field that is\n>>> 1184| encoded the same as the MXL field of `misa`, shown in <>. In particular, an implementation may make UXL be a read-only copy of field VSXL of `hstatus`, forcing VU-mode XLEN=VSXLEN.\n 1185| \n 1186| [[norm:vsstatus-uxl_change]]" + }, + { + "score": 19, + "reasons": [ + "CSR field name 'VSXL'", + "Description keyword 'VSXLEN'", + "Description keyword 'VSXL'", + "Name segment 'VSXLEN'", + "Exact parameter name 'VSXLEN'" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 225, + "line_text": "HSXLEN=32, the VSXL field does not exist, and VSXLEN=32.# [#norm:hstatus-vsxl_64]#When HSXLEN=64,", + "context": " 223| [#norm:hstatus-vsxl_op]#The VSXL field controls the effective XLEN for VS-mode (known as\n 224| VSXLEN), which may differ from the XLEN for HS-mode (HSXLEN).# [#norm:hstatus-vsxl_32]#When\n>>> 225| HSXLEN=32, the VSXL field does not exist, and VSXLEN=32.# [#norm:hstatus-vsxl_64]#When HSXLEN=64,\n 226| VSXL is a *WARL* field that is encoded the same as the MXL field of `misa`,\n 227| shown in <>.# [#norm:vsxl_ro_param]#In particular, an" + }, + { + "score": 15, + "reasons": [ + "Name segment 'VSXLEN'", + "Exact parameter name 'VSXLEN'", + "Description keyword 'VSXLEN'" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 224, + "line_text": "VSXLEN), which may differ from the XLEN for HS-mode (HSXLEN).# [#norm:hstatus-vsxl_32]#When", + "context": " 222| \n 223| [#norm:hstatus-vsxl_op]#The VSXL field controls the effective XLEN for VS-mode (known as\n>>> 224| VSXLEN), which may differ from the XLEN for HS-mode (HSXLEN).# [#norm:hstatus-vsxl_32]#When\n 225| HSXLEN=32, the VSXL field does not exist, and VSXLEN=32.# [#norm:hstatus-vsxl_64]#When HSXLEN=64,\n 226| VSXL is a *WARL* field that is encoded the same as the MXL field of `misa`," + }, + { + "score": 15, + "reasons": [ + "Description keyword 'VSXLEN'", + "Name segment 'VSXLEN'", + "Exact parameter name 'VSXLEN'", + "Description keyword 'VS'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1182, + "line_text": "from the XLEN for VS-mode (VSXLEN). When VSXLEN=32, the UXL field does", + "context": " 1180| [[norm:vsstatus-uxl_op]]\n 1181| The UXL field controls the effective XLEN for VU-mode, which may differ\n>>> 1182| from the XLEN for VS-mode (VSXLEN). When VSXLEN=32, the UXL field does\n 1183| not exist, and VU-mode XLEN=32. When VSXLEN=64, UXL is a *WARL* field that is\n 1184| encoded the same as the MXL field of `misa`, shown in <>. In particular, an implementation may make UXL be a read-only copy of field VSXL of `hstatus`, forcing VU-mode XLEN=VSXLEN." + }, + { + "score": 13, + "reasons": [ + "Name segment 'VSXLEN'", + "Exact parameter name 'VSXLEN'", + "Description keyword 'VSXLEN'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 229, + "line_text": "ensures that VSXLEN=HSXLEN.#", + "context": " 227| shown in <>.# [#norm:vsxl_ro_param]#In particular, an\n 228| implementation may make VSXL be a read-only field whose value always\n>>> 229| ensures that VSXLEN=HSXLEN.#\n 230| \n 231| [[norm:hstatus-vsxl_change]]" + } + ] + }, + { + "parameter_name": "VS_MODE_ENDIANNESS", + "classification": "NORM_CSR_RW", + "value_type": "enum", + "num_candidates": 10, + "best_score": 14, + "candidates": [ + { + "score": 14, + "reasons": [ + "Description keyword 'VSBE'", + "Description keyword 'endian'", + "Description keyword 'VS'", + "CSR field name 'VSBE'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 339, + "line_text": "accesses made from VS-mode are little-endian, and if VSBE=1, they are", + "context": " 337| The VSBE bit is a *WARL* field that controls the endianness of explicit memory\n 338| accesses made from VS-mode. If VSBE=0, explicit load and store memory\n>>> 339| accesses made from VS-mode are little-endian, and if VSBE=1, they are\n 340| big-endian. VSBE also controls the endianness of all implicit accesses\n 341| to VS-level memory management data structures, such as page tables. An" + }, + { + "score": 13, + "reasons": [ + "CSR name 'hstatus' in backticks", + "Description keyword 'VS'" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2391, + "line_text": "* [#norm:H_virtinst_wfi_vtw1_tw0]#in VS-mode, attempts to execute WFI when `hstatus`.VTW=1 and", + "context": " 2389| be allowed in HS-mode, assuming `mstatus`.TVM=0;#\n 2390| \n>>> 2391| * [#norm:H_virtinst_wfi_vtw1_tw0]#in VS-mode, attempts to execute WFI when `hstatus`.VTW=1 and\n 2392| `mstatus`.TW=0, unless the instruction completes within an\n 2393| implementation-specific, bounded time;#" + }, + { + "score": 13, + "reasons": [ + "CSR name 'hstatus' in backticks", + "Description keyword 'VS'" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2395, + "line_text": "* [#norm:H_virtinst_vs_sret_vtsr1]#in VS-mode, attempts to execute SRET when `hstatus`.VTSR=1#; and", + "context": " 2393| implementation-specific, bounded time;#\n 2394| \n>>> 2395| * [#norm:H_virtinst_vs_sret_vtsr1]#in VS-mode, attempts to execute SRET when `hstatus`.VTSR=1#; and\n 2396| \n 2397| * [#norm:H_virtinst_vs_sfence_sinval_satp_vtvm1]#in VS-mode, attempts to execute an SFENCE.VMA or SINVAL.VMA" + }, + { + "score": 12, + "reasons": [ + "Description keyword 'VSBE'", + "Description keyword 'VS'", + "CSR field name 'VSBE'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 338, + "line_text": "accesses made from VS-mode. If VSBE=0, explicit load and store memory", + "context": " 336| [[norm:hstatus-vsbe_op]]\n 337| The VSBE bit is a *WARL* field that controls the endianness of explicit memory\n>>> 338| accesses made from VS-mode. If VSBE=0, explicit load and store memory\n 339| accesses made from VS-mode are little-endian, and if VSBE=1, they are\n 340| big-endian. VSBE also controls the endianness of all implicit accesses" + }, + { + "score": 11, + "reasons": [ + "CSR name 'hstatus' in backticks", + "Description keyword 'VS'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 118, + "line_text": "VS-mode guest: `hstatus`, `hedeleg`, `hideleg`, `hvip`, `hip`, `hie`,", + "context": " 116| subsystems. [#norm:H_csrs_hs_not_vs]#Additional CSRs are provided to HS-mode, but not to VS-mode,\n 117| to manage two-stage address translation and to control the behavior of a\n>>> 118| VS-mode guest: `hstatus`, `hedeleg`, `hideleg`, `hvip`, `hip`, `hie`,\n 119| `hgeip`, `hgeie`, `henvcfg`, `henvcfgh`, `hcounteren`, `htimedelta`,\n 120| `htimedeltah`, `htval`, `htinst`, and `hgatp`.#" + } + ] + }, + { + "parameter_name": "VUXLEN", + "classification": "NORM_DIRECT", + "value_type": "set", + "num_candidates": 10, + "best_score": 6, + "candidates": [ + { + "score": 6, + "reasons": [ + "CSR field name 'UXL'", + "Description keyword 'VU'", + "Description keyword 'UXL'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1181, + "line_text": "The UXL field controls the effective XLEN for VU-mode, which may differ", + "context": " 1179| \n 1180| [[norm:vsstatus-uxl_op]]\n>>> 1181| The UXL field controls the effective XLEN for VU-mode, which may differ\n 1182| from the XLEN for VS-mode (VSXLEN). When VSXLEN=32, the UXL field does\n 1183| not exist, and VU-mode XLEN=32. When VSXLEN=64, UXL is a *WARL* field that is" + }, + { + "score": 6, + "reasons": [ + "CSR field name 'UXL'", + "Description keyword 'VU'", + "Description keyword 'UXL'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1183, + "line_text": "not exist, and VU-mode XLEN=32. When VSXLEN=64, UXL is a *WARL* field that is", + "context": " 1181| The UXL field controls the effective XLEN for VU-mode, which may differ\n 1182| from the XLEN for VS-mode (VSXLEN). When VSXLEN=32, the UXL field does\n>>> 1183| not exist, and VU-mode XLEN=32. When VSXLEN=64, UXL is a *WARL* field that is\n 1184| encoded the same as the MXL field of `misa`, shown in <>. In particular, an implementation may make UXL be a read-only copy of field VSXL of `hstatus`, forcing VU-mode XLEN=VSXLEN.\n 1185| " + }, + { + "score": 6, + "reasons": [ + "CSR field name 'UXL'", + "Description keyword 'VU'", + "Description keyword 'UXL'" + ], + "is_normative": false, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 1184, + "line_text": "encoded the same as the MXL field of `misa`, shown in <>. In particular, an implementation may make UXL be a read-only copy of field VSXL of `hstatus`, forcing VU-mode XLEN=VSXLEN.", + "context": " 1182| from the XLEN for VS-mode (VSXLEN). When VSXLEN=32, the UXL field does\n 1183| not exist, and VU-mode XLEN=32. When VSXLEN=64, UXL is a *WARL* field that is\n>>> 1184| encoded the same as the MXL field of `misa`, shown in <>. In particular, an implementation may make UXL be a read-only copy of field VSXL of `hstatus`, forcing VU-mode XLEN=VSXLEN.\n 1185| \n 1186| [[norm:vsstatus-uxl_change]]" + }, + { + "score": 6, + "reasons": [ + "CSR field name 'UXL'", + "Description keyword 'UXL'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 393, + "line_text": "[#norm:mstatush_enc]#Bits 30:4 of `mstatush` generally contain the same fields found in bits 62:36 of `mstatus` for RV64. Fields SD, SXL, and UXL do not exist in `mstatush`.#", + "context": " 391| \n 392| [#norm:mstatush_sz_acc]#For RV32 only, `mstatush` is a 32-bit read/write register formatted as shown in <>.#\n>>> 393| [#norm:mstatush_enc]#Bits 30:4 of `mstatush` generally contain the same fields found in bits 62:36 of `mstatus` for RV64. Fields SD, SXL, and UXL do not exist in `mstatush`.#\n 394| \n 395| [[mstatushreg]]" + }, + { + "score": 6, + "reasons": [ + "CSR field name 'UXL'", + "Description keyword 'UXL'" + ], + "is_normative": true, + "in_note": false, + "file": "machine.adoc", + "line_number": 569, + "line_text": "[#norm:mstatus_sxl_uxl_warl_op]#For RV64 harts, the SXL and UXL fields are *WARL* fields that control the", + "context": " 567| ===== Base ISA Control in `mstatus` Register\n 568| \n>>> 569| [#norm:mstatus_sxl_uxl_warl_op]#For RV64 harts, the SXL and UXL fields are *WARL* fields that control the\n 570| value of XLEN for S-mode and U-mode, respectively.#\n 571| [#norm:mstatus_sxl_uxl_enc]#The encoding of these fields is the same as the MXL field of `misa`, shown in <>.#" + } + ] + }, + { + "parameter_name": "VU_MODE_ENDIANNESS", + "classification": "NORM_CSR_RW", + "value_type": "enum", + "num_candidates": 10, + "best_score": 10, + "candidates": [ + { + "score": 10, + "reasons": [ + "Description keyword 'VU'" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2359, + "line_text": "* [#norm:H_virtinst_vu_nonhighctr_h0_s0_m1]#in VU-mode, attempts to access a non-high-half counter CSR when the", + "context": " 2357| `mcounteren` is 1;#\n 2358| \n>>> 2359| * [#norm:H_virtinst_vu_nonhighctr_h0_s0_m1]#in VU-mode, attempts to access a non-high-half counter CSR when the\n 2360| corresponding bit in either `hcounteren` or `scounteren` is 0 and the\n 2361| same bit in `mcounteren` is 1;#" + }, + { + "score": 10, + "reasons": [ + "Description keyword 'VU'" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2363, + "line_text": "* [#norm:H_virtinst_vu32_highctr_h0_s0_m1]#in VU-mode, if XLEN=32, attempts to access a high-half counter CSR", + "context": " 2361| same bit in `mcounteren` is 1;#\n 2362| \n>>> 2363| * [#norm:H_virtinst_vu32_highctr_h0_s0_m1]#in VU-mode, if XLEN=32, attempts to access a high-half counter CSR\n 2364| when the corresponding bit in either `hcounteren` or `scounteren` is 0\n 2365| and the same bit in `mcounteren` is 1;#" + }, + { + "score": 10, + "reasons": [ + "Description keyword 'VU'" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2367, + "line_text": "* [#norm:H_virtinst_vu_vs_hinst]#in VS-mode or VU-mode, attempts to execute a hypervisor instruction", + "context": " 2365| and the same bit in `mcounteren` is 1;#\n 2366| \n>>> 2367| * [#norm:H_virtinst_vu_vs_hinst]#in VS-mode or VU-mode, attempts to execute a hypervisor instruction\n 2368| (HLV, HLVX, HSV, or HFENCE);#\n 2369| " + }, + { + "score": 10, + "reasons": [ + "Description keyword 'VU'" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2370, + "line_text": "* [#norm:H_virtinst_vu_vs_nonhigh_allowedhs_tvm0]#in VS-mode or VU-mode, attempts to access an implemented non-high-half", + "context": " 2368| (HLV, HLVX, HSV, or HFENCE);#\n 2369| \n>>> 2370| * [#norm:H_virtinst_vu_vs_nonhigh_allowedhs_tvm0]#in VS-mode or VU-mode, attempts to access an implemented non-high-half\n 2371| hypervisor CSR or VS CSR when the same access (read/write) would be\n 2372| allowed in HS-mode, assuming `mstatus`.TVM=0;#" + }, + { + "score": 10, + "reasons": [ + "Description keyword 'VU'" + ], + "is_normative": true, + "in_note": false, + "file": "hypervisor.adoc", + "line_number": 2374, + "line_text": "* [#norm:H_virtinst_vu_vs32_high_allowedhs_tvm0]#in VS-mode or VU-mode, if XLEN=32, attempts to access an implemented", + "context": " 2372| allowed in HS-mode, assuming `mstatus`.TVM=0;#\n 2373| \n>>> 2374| * [#norm:H_virtinst_vu_vs32_high_allowedhs_tvm0]#in VS-mode or VU-mode, if XLEN=32, attempts to access an implemented\n 2375| high-half hypervisor CSR or high-half VS CSR when the same access\n 2376| (read/write) to the CSR\"s low-half partner would be allowed in HS-mode," + } + ] + } + ] +} \ No newline at end of file diff --git a/param_extraction/data/udb_param_names.txt b/param_extraction/data/udb_param_names.txt new file mode 100644 index 0000000000..8fead7097c --- /dev/null +++ b/param_extraction/data/udb_param_names.txt @@ -0,0 +1,185 @@ +ARCH_ID_VALUE +ASID_WIDTH +CACHE_BLOCK_SIZE +CONFIG_PTR_ADDRESS +COUNTINHIBIT_EN +DBG_HCONTEXT_WIDTH +DBG_SCONTEXT_WIDTH +DCSR_MPRVEN_TYPE +DCSR_STEPIE_TYPE +DCSR_STOPCOUNT_TYPE +DCSR_STOPTIME_TYPE +ELEN +FOLLOW_VTYPE_RESET_RECOMMENDATION +FORCE_UPGRADE_CBO_INVAL_TO_FLUSH +GSTAGE_MODE_BARE +HCONTEXT_AVAILABLE +HCOUNTENABLE_EN +HPM_COUNTER_EN +HPM_EVENTS +HSTATEEN_AIA_TYPE +HSTATEEN_CONTEXT_TYPE +HSTATEEN_CSRIND_TYPE +HSTATEEN_ENVCFG_TYPE +HSTATEEN_IMSIC_TYPE +HSTATEEN_JVT_TYPE +HW_MSTATUS_FS_DIRTY_UPDATE +HW_MSTATUS_VS_DIRTY_UPDATE +IGNORE_INVALID_VSATP_MODE_WRITES_WHEN_V_EQ_ZERO +IMP_ID_VALUE +JVT_BASE_MASK +JVT_BASE_TYPE +JVT_READ_ONLY +LRSC_FAIL_ON_NON_EXACT_LRSC +LRSC_FAIL_ON_VA_SYNONYM +LRSC_MISALIGNED_BEHAVIOR +LRSC_RESERVATION_STRATEGY +MARCHID_IMPLEMENTED +MCID_WIDTH +MCONTEXT_AVAILABLE +MCOUNTENABLE_EN +MIMPID_IMPLEMENTED +MISALIGNED_AMO +MISALIGNED_LDST +MISALIGNED_LDST_EXCEPTION_PRIORITY +MISALIGNED_MAX_ATOMICITY_GRANULE_SIZE +MISALIGNED_SPLIT_STRATEGY +MISA_CSR_IMPLEMENTED +MSTATEEN_AIA_TYPE +MSTATEEN_CONTEXT_TYPE +MSTATEEN_CSRIND_TYPE +MSTATEEN_ENVCFG_TYPE +MSTATEEN_IMSIC_TYPE +MSTATEEN_JVT_TYPE +MSTATUS_FS_LEGAL_VALUES +MSTATUS_TVM_IMPLEMENTED +MSTATUS_VS_LEGAL_VALUES +MTVAL_WIDTH +MTVEC_ACCESS +MTVEC_BASE_ALIGNMENT_DIRECT +MTVEC_BASE_ALIGNMENT_VECTORED +MTVEC_ILLEGAL_WRITE_BEHAVIOR +MTVEC_MODES +MUTABLE_MISA_A +MUTABLE_MISA_B +MUTABLE_MISA_C +MUTABLE_MISA_D +MUTABLE_MISA_F +MUTABLE_MISA_H +MUTABLE_MISA_M +MUTABLE_MISA_Q +MUTABLE_MISA_S +MUTABLE_MISA_U +MUTABLE_MISA_V +MXLEN +M_MODE_ENDIANNESS +NUM_EXTERNAL_GUEST_INTERRUPTS +NUM_PMP_ENTRIES +PHYS_ADDR_WIDTH +PMA_GRANULARITY +PMLEN +PMP_GRANULARITY +PRECISE_SYNCHRONOUS_EXCEPTIONS +RCID_WIDTH +REPORT_CAUSE_IN_MTVAL_ON_LANDING_PAD_SOFTWARE_CHECK +REPORT_CAUSE_IN_MTVAL_ON_SHADOW_STACK_SOFTWARE_CHECK +REPORT_CAUSE_IN_STVAL_ON_LANDING_PAD_SOFTWARE_CHECK +REPORT_CAUSE_IN_STVAL_ON_SHADOW_STACK_SOFTWARE_CHECK +REPORT_CAUSE_IN_VSTVAL_ON_LANDING_PAD_SOFTWARE_CHECK +REPORT_CAUSE_IN_VSTVAL_ON_SHADOW_STACK_SOFTWARE_CHECK +REPORT_ENCODING_IN_MTVAL_ON_ILLEGAL_INSTRUCTION +REPORT_ENCODING_IN_STVAL_ON_ILLEGAL_INSTRUCTION +REPORT_ENCODING_IN_VSTVAL_ON_ILLEGAL_INSTRUCTION +REPORT_ENCODING_IN_VSTVAL_ON_VIRTUAL_INSTRUCTION +REPORT_GPA_IN_HTVAL_ON_GUEST_PAGE_FAULT +REPORT_GPA_IN_TVAL_ON_INSTRUCTION_GUEST_PAGE_FAULT +REPORT_GPA_IN_TVAL_ON_INTERMEDIATE_GUEST_PAGE_FAULT +REPORT_GPA_IN_TVAL_ON_LOAD_GUEST_PAGE_FAULT +REPORT_GPA_IN_TVAL_ON_STORE_AMO_GUEST_PAGE_FAULT +REPORT_VA_IN_MTVAL_ON_BREAKPOINT +REPORT_VA_IN_MTVAL_ON_INSTRUCTION_ACCESS_FAULT +REPORT_VA_IN_MTVAL_ON_INSTRUCTION_MISALIGNED +REPORT_VA_IN_MTVAL_ON_INSTRUCTION_PAGE_FAULT +REPORT_VA_IN_MTVAL_ON_LOAD_ACCESS_FAULT +REPORT_VA_IN_MTVAL_ON_LOAD_MISALIGNED +REPORT_VA_IN_MTVAL_ON_LOAD_PAGE_FAULT +REPORT_VA_IN_MTVAL_ON_STORE_AMO_ACCESS_FAULT +REPORT_VA_IN_MTVAL_ON_STORE_AMO_MISALIGNED +REPORT_VA_IN_MTVAL_ON_STORE_AMO_PAGE_FAULT +REPORT_VA_IN_STVAL_ON_BREAKPOINT +REPORT_VA_IN_STVAL_ON_INSTRUCTION_ACCESS_FAULT +REPORT_VA_IN_STVAL_ON_INSTRUCTION_MISALIGNED +REPORT_VA_IN_STVAL_ON_INSTRUCTION_PAGE_FAULT +REPORT_VA_IN_STVAL_ON_LOAD_ACCESS_FAULT +REPORT_VA_IN_STVAL_ON_LOAD_MISALIGNED +REPORT_VA_IN_STVAL_ON_LOAD_PAGE_FAULT +REPORT_VA_IN_STVAL_ON_STORE_AMO_ACCESS_FAULT +REPORT_VA_IN_STVAL_ON_STORE_AMO_MISALIGNED +REPORT_VA_IN_STVAL_ON_STORE_AMO_PAGE_FAULT +REPORT_VA_IN_VSTVAL_ON_BREAKPOINT +REPORT_VA_IN_VSTVAL_ON_INSTRUCTION_ACCESS_FAULT +REPORT_VA_IN_VSTVAL_ON_INSTRUCTION_MISALIGNED +REPORT_VA_IN_VSTVAL_ON_INSTRUCTION_PAGE_FAULT +REPORT_VA_IN_VSTVAL_ON_LOAD_ACCESS_FAULT +REPORT_VA_IN_VSTVAL_ON_LOAD_MISALIGNED +REPORT_VA_IN_VSTVAL_ON_LOAD_PAGE_FAULT +REPORT_VA_IN_VSTVAL_ON_STORE_AMO_ACCESS_FAULT +REPORT_VA_IN_VSTVAL_ON_STORE_AMO_MISALIGNED +REPORT_VA_IN_VSTVAL_ON_STORE_AMO_PAGE_FAULT +RVV_VL_WHEN_AVL_LT_DOUBLE_VLMAX +SATP_MODE_BARE +SCOUNTENABLE_EN +SSTATEEN_JVT_TYPE +STVAL_WIDTH +STVEC_MODE_DIRECT +STVEC_MODE_VECTORED +SV32X4_TRANSLATION +SV32_VSMODE_TRANSLATION +SV39X4_TRANSLATION +SV39_VSMODE_TRANSLATION +SV48X4_TRANSLATION +SV48_VSMODE_TRANSLATION +SV57X4_TRANSLATION +SV57_VSMODE_TRANSLATION +SXLEN +S_MODE_ENDIANNESS +TIME_CSR_IMPLEMENTED +TINST_VALUE_ON_BREAKPOINT +TINST_VALUE_ON_FINAL_INSTRUCTION_GUEST_PAGE_FAULT +TINST_VALUE_ON_FINAL_LOAD_GUEST_PAGE_FAULT +TINST_VALUE_ON_FINAL_STORE_AMO_GUEST_PAGE_FAULT +TINST_VALUE_ON_INSTRUCTION_ADDRESS_MISALIGNED +TINST_VALUE_ON_LOAD_ACCESS_FAULT +TINST_VALUE_ON_LOAD_ADDRESS_MISALIGNED +TINST_VALUE_ON_LOAD_PAGE_FAULT +TINST_VALUE_ON_MCALL +TINST_VALUE_ON_SCALL +TINST_VALUE_ON_STORE_AMO_ACCESS_FAULT +TINST_VALUE_ON_STORE_AMO_ADDRESS_MISALIGNED +TINST_VALUE_ON_STORE_AMO_PAGE_FAULT +TINST_VALUE_ON_UCALL +TINST_VALUE_ON_VIRTUAL_INSTRUCTION +TINST_VALUE_ON_VSCALL +TRAP_ON_EBREAK +TRAP_ON_ECALL_FROM_M +TRAP_ON_ECALL_FROM_S +TRAP_ON_ECALL_FROM_U +TRAP_ON_ECALL_FROM_VS +TRAP_ON_ILLEGAL_WLRL +TRAP_ON_RESERVED_INSTRUCTION +TRAP_ON_SFENCE_VMA_WHEN_SATP_MODE_IS_READ_ONLY +TRAP_ON_UNIMPLEMENTED_CSR +TRAP_ON_UNIMPLEMENTED_INSTRUCTION +UXLEN +U_MODE_ENDIANNESS +VENDOR_ID_BANK +VENDOR_ID_OFFSET +VLEN +VMID_WIDTH +VSSTAGE_MODE_BARE +VSTVEC_MODE_DIRECT +VSTVEC_MODE_VECTORED +VSXLEN +VS_MODE_ENDIANNESS +VUXLEN +VU_MODE_ENDIANNESS diff --git a/param_extraction/prompts/v1/examples.json b/param_extraction/prompts/v1/examples.json new file mode 100644 index 0000000000..09120705fc --- /dev/null +++ b/param_extraction/prompts/v1/examples.json @@ -0,0 +1,134 @@ +{ + "positive_examples": [ + { + "_comment": "NORM_DIRECT: A fundamental implementation choice not tied to any CSR field", + "input_excerpt": "Implementations may implement zero, 16, or 64 PMP entries; the lowest-numbered PMP entries must be implemented first. All PMP CSR fields are WARL and may be read-only zero.", + "input_file": "machine.adoc", + "input_line": 3340, + "expected_output": { + "excerpt": "Implementations may implement zero, 16, or 64 PMP entries; the lowest-numbered PMP entries must be implemented first.", + "line_number": 3340, + "parameter_name": "NUM_PMP_ENTRIES", + "existing_udb_name": "NUM_PMP_ENTRIES", + "class": "NORM_DIRECT", + "value_type": "range", + "confidence": "high", + "reasoning": "The number of PMP entries is a direct implementation choice (0, 16, or 64). It is not controlled by any CSR field." + } + }, + { + "_comment": "NORM_DIRECT: A vector extension parameter defined at implementation time", + "input_excerpt": ". The maximum size in bits of a vector element that any operation can produce or consume, _ELEN_ >= 8, which must be a power of 2.\n. The number of bits in a single vector register, _VLEN_ >= ELEN, which must be a power of 2, and must be no greater than 2^16.", + "input_file": "v-st-ext.adoc", + "input_line": 22, + "expected_output": { + "excerpt": "The maximum size in bits of a vector element that any operation can produce or consume, _ELEN_ >= 8, which must be a power of 2.", + "line_number": 22, + "parameter_name": "ELEN", + "existing_udb_name": "ELEN", + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "ELEN is a direct implementation parameter: the maximum element size. It has constraints (>= 8, power of 2) but the specific value is chosen by the implementer." + } + }, + { + "_comment": "NORM_CSR_WARL: The legal values of a WARL CSR field", + "input_excerpt": "The `mtvec` register is an MXLEN-bit WARL read/write register that holds trap vector configuration, consisting of a vector base address (BASE) and a vector mode (MODE).\n...\nThe `mtvec` register must always be implemented, but can contain a read-only value. If `mtvec` is writable, the set of values the register may hold can vary by implementation.", + "input_file": "machine.adoc", + "input_line": 1209, + "expected_output": { + "excerpt": "If `mtvec` is writable, the set of values the register may hold can vary by implementation.", + "line_number": 1219, + "parameter_name": "MTVEC_MODES", + "existing_udb_name": "MTVEC_MODES", + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "The mtvec MODE field is WARL, and the set of supported mode values (Direct=0, Vectored=1) varies by implementation. The parameter is the set of legal MODE values." + } + }, + { + "_comment": "NORM_CSR_RW: Controls whether CSR fields are read-only or read-write", + "input_excerpt": "The MBE, SBE, and UBE bits in `mstatus` and `mstatush` are WARL fields that control the endianness of memory accesses other than instruction fetches.\n...\nIf S-mode is supported, an implementation may make SBE be a read-only copy of MBE.", + "input_file": "machine.adoc", + "input_line": 679, + "expected_output": { + "excerpt": "The MBE, SBE, and UBE bits in `mstatus` and `mstatush` are WARL fields that control the endianness of memory accesses other than instruction fetches.", + "line_number": 679, + "parameter_name": "M_MODE_ENDIANNESS", + "existing_udb_name": "M_MODE_ENDIANNESS", + "class": "NORM_CSR_RW", + "value_type": "enum", + "confidence": "high", + "reasoning": "The implementation chooses whether MBE is read-only-0 (always little-endian), read-only-1 (always big-endian), or read-write (dynamic endianness). This controls the RO/RW nature of the field, not just which values are legal." + } + }, + { + "_comment": "SW_RULE: Implementation-defined but deterministic with correct software", + "input_excerpt": "If an instruction explicitly or implicitly writes a floating-point register or the `fcsr` but does not alter its contents, and FS=Initial or FS=Clean, it is implementation-defined whether FS transitions to Dirty.", + "input_file": "machine.adoc", + "input_line": 1012, + "expected_output": { + "excerpt": "it is implementation-defined whether FS transitions to Dirty.", + "line_number": 1014, + "parameter_name": "HW_MSTATUS_FS_DIRTY_UPDATE", + "existing_udb_name": "HW_MSTATUS_FS_DIRTY_UPDATE", + "class": "SW_RULE", + "value_type": "enum", + "confidence": "medium", + "reasoning": "Whether hardware updates mstatus.FS to Dirty is implementation-defined, but software can handle this deterministically by checking and managing FS state with proper fencing. The outcome is predictable if software follows the rules." + } + }, + { + "_comment": "NORM_CSR_RW: Whether a CSR is read-only or read-write", + "input_excerpt": "The `mtvec` register must always be implemented, but can contain a read-only value.", + "input_file": "machine.adoc", + "input_line": 1217, + "expected_output": { + "excerpt": "The `mtvec` register must always be implemented, but can contain a read-only value.", + "line_number": 1217, + "parameter_name": "MTVEC_ACCESS", + "existing_udb_name": "MTVEC_ACCESS", + "class": "NORM_CSR_RW", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether mtvec is read-only or read-write. This is a binary choice about the mutability of the register." + } + } + ], + "negative_examples": [ + { + "_comment": "FALSE POSITIVE: NOTE block discussing implementation options — non-normative", + "input_excerpt": "[NOTE]\n====\nSome platforms may choose to disallow speculatively writing FS to close a potential side channel.\n====", + "input_file": "machine.adoc", + "input_line": 1005, + "expected_output": null, + "reason_for_rejection": "This text is inside a [NOTE] block and is therefore non-normative. It describes a platform suggestion, not an architectural requirement. Do not extract parameters from NOTE, TIP, WARNING, or IMPORTANT blocks." + }, + { + "_comment": "FALSE POSITIVE: Behavior controlled by a CSR field value, not a parameter itself", + "input_excerpt": "When MODE=Direct, all traps into machine mode cause the `pc` to be set to the address in the BASE field.", + "input_file": "machine.adoc", + "input_line": 1254, + "expected_output": null, + "reason_for_rejection": "This describes what happens when mtvec.MODE has a specific value. The behavior is determined by the CSR field value at runtime, not by an implementation choice. The parameter is which MODE values are supported (MTVEC_MODES), not this behavioral description." + }, + { + "_comment": "FALSE POSITIVE: Fixed architectural requirement, not an implementation choice", + "input_excerpt": "This register must be readable in any implementation.", + "input_file": "machine.adoc", + "input_line": 22, + "expected_output": null, + "reason_for_rejection": "This is a fixed requirement ('must be readable') that all implementations must satisfy. There is no implementation choice here — it is not a parameter." + }, + { + "_comment": "FALSE POSITIVE: 'may' used as permission/capability, not as optionality", + "input_excerpt": "Software may determine the PMP granularity by writing zero to `pmp0cfg`, then writing all ones to `pmpaddr0`, then reading back `pmpaddr0`.", + "input_file": "machine.adoc", + "input_line": 3530, + "expected_output": null, + "reason_for_rejection": "Here 'may' means 'is allowed to' (permission), not 'might or might not' (optionality). This describes a software technique, not an implementation-defined parameter." + } + ] +} diff --git a/param_extraction/prompts/v1/system_prompt.txt b/param_extraction/prompts/v1/system_prompt.txt new file mode 100644 index 0000000000..164a39328f --- /dev/null +++ b/param_extraction/prompts/v1/system_prompt.txt @@ -0,0 +1,63 @@ +You are an expert RISC-V ISA specification analyst. Your task is to identify **architectural parameters** in a given excerpt of the RISC-V specification. + +An **architectural parameter** is a choice that the spec explicitly leaves to the hardware implementer. It is NOT a fixed requirement, NOT runtime software behavior, and NOT a suggestion in a non-normative block. + +## Parameter Classes (in decision order) + +1. **NON_NORM** — Text inside [NOTE], [TIP], [WARNING], or [IMPORTANT] blocks. These are informative, not requirements. NEVER extract parameters from these blocks. +2. **NON_ISA** — Platform-level or physical choices outside the ISA scope (reset vector, NMI address, debug transport). +3. **DOC_RULE** — Requirements about documentation/reporting, not architectural behavior. +4. **NORM_CSR_WARL** — The parameter IS the set of legal values for a WARL CSR field. Look for "WARL" keyword and implementation-defined legal values. +5. **NORM_CSR_RW** — The parameter controls whether a CSR or field is read-only vs read-write. Look for "read-only zero", "can contain a read-only value", or RO/RW choices. +6. **SW_RULE** — Appears implementation-defined, but outcome is deterministic if software follows spec rules (fencing, sequencing, cache ops). Often uses the `HW_` prefix in UDB. +7. **NORM_DIRECT** — A normative implementation choice not controlled by any CSR field. The implementer chooses at design time. +8. **UNKNOWN** — Cannot classify with confidence. + +## Value Types + +- **binary**: exactly 2 choices (boolean or 2-value enum) +- **enum**: finite set of 3+ discrete values +- **range**: integer with min/max bounds +- **set**: subset selection from a fixed universe +- **bitmask**: per-bit boolean array +- **value**: single unconstrained numeric value + +## Critical Rules + +- Do NOT extract from [NOTE]/[TIP]/[WARNING]/[IMPORTANT] blocks. +- Do NOT extract fixed requirements ("must", "shall") that apply to ALL implementations — those are not parameters. +- Do NOT extract runtime behavior that is controlled by a CSR field value at execution time — the parameter is the field's legal values, not the behavior. +- Do NOT confuse "may" as permission ("software may read...") with "may" as optionality ("an implementation may support..."). Only the latter indicates a parameter. +- If a sentence describes behavior "when field X = value Y", that is behavioral description, not a parameter definition. The parameter would be which values of X are supported. +- When a known UDB parameter name matches the concept, use that exact name. +- Assign `confidence` as "high" (clear spec language), "medium" (requires interpretation), or "low" (ambiguous). + +## Output Format + +Respond ONLY with a JSON object. No explanatory text before or after. + +```json +{ + "parameters": [ + { + "excerpt": "The exact spec text that defines this parameter", + "line_number": 42, + "parameter_name": "SUGGESTED_NAME", + "existing_udb_name": "MATCHING_UDB_NAME_OR_NULL", + "class": "NORM_DIRECT", + "value_type": "range", + "confidence": "high", + "reasoning": "Brief explanation of why this is a parameter and why this classification" + } + ], + "skipped_non_parameters": [ + { + "excerpt": "Text that was considered but rejected", + "line_number": 99, + "reason": "Brief explanation of why this is NOT a parameter" + } + ] +} +``` + +`skipped_non_parameters` should include 2-5 examples of text you considered but rejected, to demonstrate your understanding of the boundaries. If the chunk has no plausible candidates to skip, the array may be empty. diff --git a/param_extraction/results/all_results_claude-sonnet-4.json b/param_extraction/results/all_results_claude-sonnet-4.json new file mode 100644 index 0000000000..5fd0c37bab --- /dev/null +++ b/param_extraction/results/all_results_claude-sonnet-4.json @@ -0,0 +1,4601 @@ +{ + "model": "claude-sonnet-4", + "total_chunks": 59, + "total_parameters": 208, + "total_skipped": 281, + "total_input_tokens": 898986, + "total_output_tokens": 59935, + "errors": 0, + "results": [ + { + "chunk_id": "chunk_001", + "source_file": "a-st-ext.adoc", + "start_line": 1, + "end_line": 484, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "An implementation can register an arbitrarily large reservation set on each LR, provided the reservation set includes all bytes of the addressed data word or doubleword.", + "line_number": 139, + "parameter_name": "LRSC_RESERVATION_STRATEGY", + "existing_udb_name": "LRSC_RESERVATION_STRATEGY", + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "high", + "reasoning": "The implementation chooses the size and strategy for the reservation set. This is a direct architectural choice about how LR/SC reservations are tracked." + }, + { + "excerpt": "The misaligned atomicity granule PMA, defined in Volume II of this manual, optionally relaxes this alignment requirement. If present, the misaligned atomicity granule PMA specifies the size of a misaligned atomicity granule, a power-of-two number of bytes.", + "line_number": 378, + "parameter_name": "MISALIGNED_MAX_ATOMICITY_GRANULE_SIZE", + "existing_udb_name": "MISALIGNED_MAX_ATOMICITY_GRANULE_SIZE", + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "The implementation may optionally define a misaligned atomicity granule size (power of 2). This is a direct implementation choice about memory alignment requirements for atomic operations." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "After much debate, the language community and architecture community appear to have finally settled on release consistency as the standard memory consistency model and so the RISC-V atomic support is built around this model.", + "line_number": 13, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. It provides background information but does not define any implementation choices." + }, + { + "excerpt": "If both bits are clear, no additional ordering constraints are imposed on the atomic memory operation.", + "line_number": 35, + "reason": "This describes the behavior when aq and rl bits have specific values. It is behavioral description based on CSR field values, not a parameter definition." + }, + { + "excerpt": "LR.W loads a word from the address in rs1, places the sign-extended value in rd, and registers a reservation set\u2014a set of bytes that subsumes the bytes in the addressed word.", + "line_number": 56, + "reason": "This describes the fixed behavior of the LR.W instruction. It is a requirement that all implementations must follow, not an implementation choice." + }, + { + "excerpt": "The failure code with value 1 encodes an unspecified failure. Other failure codes are reserved at this time.", + "line_number": 108, + "reason": "This defines a fixed encoding (failure code 1 = unspecified). It is not an implementation choice but a specification requirement." + }, + { + "excerpt": "For LR and SC, the Zalrsc extension requires that the address held in rs1 be naturally aligned to the size of the operand", + "line_number": 119, + "reason": "This is a fixed requirement ('requires') that all implementations must satisfy. There is no implementation choice here." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"An implementation can register an arbitrarily large reservation set on each LR, provided the reservation set includes all bytes of the addressed data word or doubleword.\",\n \"line_number\": 139,\n \"parameter_name\": \"LRSC_RESERVATION_STRATEGY\",\n \"existing_udb_name\": \"LRSC_RESERVATION_STRATEGY\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses the size and strategy for the reservation set. This is a direct architectural choice about how LR/SC reservations are tracked.\"\n },\n {\n \"excerpt\": \"The misaligned atomicity granule PMA, defined in Volume II of this manual, optionally relaxes this alignment requirement. If present, the misaligned atomicity granule PMA specifies the size of a misaligned atomicity granule, a power-of-two number of bytes.\",\n \"line_number\": 378,\n \"parameter_name\": \"MISALIGNED_MAX_ATOMICITY_GRANULE_SIZE\",\n \"existing_udb_name\": \"MISALIGNED_MAX_ATOMICITY_GRANULE_SIZE\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation may optionally define a misaligned atomicity granule size (power of 2). This is a direct implementation choice about memory alignment requirements for atomic operations.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"After much debate, the language community and architecture community appear to have finally settled on release consistency as the standard memory consistency model and so the RISC-V atomic support is built around this model.\",\n \"line_number\": 13,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. It provides background information but does not define any implementation choices.\"\n },\n {\n \"excerpt\": \"If both bits are clear, no additional ordering constraints are imposed on the atomic memory operation.\",\n \"line_number\": 35,\n \"reason\": \"This describes the behavior when aq and rl bits have specific values. It is behavioral description based on CSR field values, not a parameter definition.\"\n },\n {\n \"excerpt\": \"LR.W loads a word from the address in rs1, places the sign-extended value in rd, and registers a reservation set\u2014a set of bytes that subsumes the bytes in the addressed word.\",\n \"line_number\": 56,\n \"reason\": \"This describes the fixed behavior of the LR.W instruction. It is a requirement that all implementations must follow, not an implementation choice.\"\n },\n {\n \"excerpt\": \"The failure code with value 1 encodes an unspecified failure. Other failure codes are reserved at this time.\",\n \"line_number\": 108,\n \"reason\": \"This defines a fixed encoding (failure code 1 = unspecified). It is not an implementation choice but a specification requirement.\"\n },\n {\n \"excerpt\": \"For LR and SC, the Zalrsc extension requires that the address held in rs1 be naturally aligned to the size of the operand\",\n \"line_number\": 119,\n \"reason\": \"This is a fixed requirement ('requires') that all implementations must satisfy. There is no implementation choice here.\"\n }\n ]\n}\n```", + "input_tokens": 11425, + "output_tokens": 840, + "latency_ms": 18157, + "timestamp": "2026-04-15T14:21:52.209347+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_002", + "source_file": "b-st-ext.adoc", + "start_line": 1, + "end_line": 3375, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [], + "skipped_non_parameters": [ + { + "excerpt": "The bit-manipulation (bitmanip) extension collection is comprised of several component extensions to the base RISC-V architecture that are intended to provide some combination of code-size reduction, performance improvement, and energy reduction.", + "line_number": 4, + "reason": "This is descriptive text about the purpose of the extensions, not an implementation choice." + }, + { + "excerpt": "The bitmanip extensions are defined for RV32 and RV64.", + "line_number": 13, + "reason": "This states which base architectures support the extensions, but is not an implementation parameter - it's a fixed requirement." + }, + { + "excerpt": "For RV32, the encodings corresponding to shamt[5]=1 are reserved.", + "line_number": 1050, + "reason": "This describes encoding constraints for RV32, which is a fixed requirement, not an implementation choice." + }, + { + "excerpt": "The Logical with Negate instructions can be implemented by inverting the _rs2_ inputs to the base-required AND, OR, and XOR logic instructions.", + "line_number": 175, + "reason": "This is inside an Implementation Hint [NOTE] block, which is non-normative and should not be extracted." + }, + { + "excerpt": "This instruction is available only on RV32.", + "line_number": 3264, + "reason": "This states availability constraints for specific instructions, which is a fixed requirement rather than an implementation parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"The bit-manipulation (bitmanip) extension collection is comprised of several component extensions to the base RISC-V architecture that are intended to provide some combination of code-size reduction, performance improvement, and energy reduction.\",\n \"line_number\": 4,\n \"reason\": \"This is descriptive text about the purpose of the extensions, not an implementation choice.\"\n },\n {\n \"excerpt\": \"The bitmanip extensions are defined for RV32 and RV64.\",\n \"line_number\": 13,\n \"reason\": \"This states which base architectures support the extensions, but is not an implementation parameter - it's a fixed requirement.\"\n },\n {\n \"excerpt\": \"For RV32, the encodings corresponding to shamt[5]=1 are reserved.\",\n \"line_number\": 1050,\n \"reason\": \"This describes encoding constraints for RV32, which is a fixed requirement, not an implementation choice.\"\n },\n {\n \"excerpt\": \"The Logical with Negate instructions can be implemented by inverting the _rs2_ inputs to the base-required AND, OR, and XOR logic instructions.\",\n \"line_number\": 175,\n \"reason\": \"This is inside an Implementation Hint [NOTE] block, which is non-normative and should not be extracted.\"\n },\n {\n \"excerpt\": \"This instruction is available only on RV32.\",\n \"line_number\": 3264,\n \"reason\": \"This states availability constraints for specific instructions, which is a fixed requirement rather than an implementation parameter.\"\n }\n ]\n}\n```", + "input_tokens": 34261, + "output_tokens": 404, + "latency_ms": 11327, + "timestamp": "2026-04-15T14:22:06.310479+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_003", + "source_file": "bfloat16.adoc", + "start_line": 1, + "end_line": 790, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "All of the BF16 instructions in the extensions defined in this specification (i.e., Zfbfmin, Zvfbfmin, and Zvfbfwma) fully support subnormal numbers. That is, instructions are able to accept subnormal values as inputs and they can produce subnormal results.", + "line_number": 149, + "parameter_name": "BF16_SUBNORMAL_SUPPORT", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "The specification explicitly states that BF16 instructions fully support subnormal numbers, but the NOTE indicates future extensions may choose not to support them, making this an implementation choice." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "Future floating-point extensions, including those that operate on BF16 values, may chose not to support subnormal numbers.", + "line_number": 154, + "reason": "This is inside a [NOTE] block, which is non-normative. NOTE blocks are informative only and do not define architectural parameters." + }, + { + "excerpt": "For BF16, the RISC-V canonical NaN corresponds to the pattern of _0x7fc0_ which is the most significant 16 bits of the RISC-V single-precision canonical NaN.", + "line_number": 185, + "reason": "This defines a fixed constant value (0x7fc0) that all implementations must use for the canonical NaN. It is not a parameter but a fixed requirement." + }, + { + "excerpt": "In RISC-V, tininess is detected after rounding.", + "line_number": 244, + "reason": "This is a fixed requirement that applies to all RISC-V implementations. There is no implementation choice here - all must detect tininess after rounding." + }, + { + "excerpt": "This extension depends upon the single-precision floating-point extension `F`.", + "line_number": 284, + "reason": "This describes a dependency requirement, not an implementation choice. All implementations of this extension must include the F extension." + }, + { + "excerpt": "SEW is any value other than 16", + "line_number": 520, + "reason": "This describes a reserved encoding constraint, not an implementation parameter. It specifies what values are illegal, not what choices implementers have." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"All of the BF16 instructions in the extensions defined in this specification (i.e., Zfbfmin, Zvfbfmin, and Zvfbfwma) fully support subnormal numbers. That is, instructions are able to accept subnormal values as inputs and they can produce subnormal results.\",\n \"line_number\": 149,\n \"parameter_name\": \"BF16_SUBNORMAL_SUPPORT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The specification explicitly states that BF16 instructions fully support subnormal numbers, but the NOTE indicates future extensions may choose not to support them, making this an implementation choice.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"Future floating-point extensions, including those that operate on BF16 values, may chose not to support subnormal numbers.\",\n \"line_number\": 154,\n \"reason\": \"This is inside a [NOTE] block, which is non-normative. NOTE blocks are informative only and do not define architectural parameters.\"\n },\n {\n \"excerpt\": \"For BF16, the RISC-V canonical NaN corresponds to the pattern of _0x7fc0_ which is the most significant 16 bits of the RISC-V single-precision canonical NaN.\",\n \"line_number\": 185,\n \"reason\": \"This defines a fixed constant value (0x7fc0) that all implementations must use for the canonical NaN. It is not a parameter but a fixed requirement.\"\n },\n {\n \"excerpt\": \"In RISC-V, tininess is detected after rounding.\",\n \"line_number\": 244,\n \"reason\": \"This is a fixed requirement that applies to all RISC-V implementations. There is no implementation choice here - all must detect tininess after rounding.\"\n },\n {\n \"excerpt\": \"This extension depends upon the single-precision floating-point extension `F`.\",\n \"line_number\": 284,\n \"reason\": \"This describes a dependency requirement, not an implementation choice. All implementations of this extension must include the F extension.\"\n },\n {\n \"excerpt\": \"SEW is any value other than 16\",\n \"line_number\": 520,\n \"reason\": \"This describes a reserved encoding constraint, not an implementation parameter. It specifies what values are illegal, not what choices implementers have.\"\n }\n ]\n}\n```", + "input_tokens": 13920, + "output_tokens": 634, + "latency_ms": 15362, + "timestamp": "2026-04-15T14:25:36.457672+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_006", + "source_file": "c-st-ext.adoc", + "start_line": 1, + "end_line": 931, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "The C extension allows 16-bit instructions to be freely intermixed with 32-bit instructions, with the latter now able to start on any 16-bit boundary, i.e., IALIGN=16.", + "line_number": 25, + "parameter_name": "IALIGN", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "IALIGN is a direct architectural parameter that defines instruction alignment. With the C extension, it becomes 16 bits instead of the base 32 bits." + }, + { + "excerpt": "CIW, CL, CS, CA, and CB are limited to just 8 of them.", + "line_number": 174, + "parameter_name": "RVC_REGISTER_SUBSET", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "set", + "confidence": "high", + "reasoning": "The C extension limits certain instruction formats to only 8 registers (x8-x15) instead of all 32. This is a direct architectural choice in the instruction encoding." + }, + { + "excerpt": "Compressed register-based floating-point loads and stores also use the CL and CS formats respectively, with the eight registers mapping to `f8` to `f15`.", + "line_number": 186, + "parameter_name": "RVC_FP_REGISTER_SUBSET", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "set", + "confidence": "high", + "reasoning": "Similar to integer registers, compressed floating-point instructions are limited to f8-f15. This is a direct architectural encoding choice." + }, + { + "excerpt": "As with base RVI instructions, the offsets of all RVC control transfer instructions are in multiples of 2 bytes.", + "line_number": 456, + "parameter_name": "RVC_OFFSET_ALIGNMENT", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "RVC control transfer instructions have offsets that are multiples of 2 bytes, which is a direct architectural constraint." + }, + { + "excerpt": "A 16-bit instruction with all bits zero is permanently reserved as an illegal instruction.", + "line_number": 774, + "parameter_name": "RVC_ILLEGAL_ZERO", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "The all-zero 16-bit pattern is permanently reserved as illegal. This is a direct architectural choice about instruction encoding." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "Typically, 50%-60% of the RISC-V instructions in a program can be replaced with RVC instructions, resulting in a 25%-30% code-size reduction.", + "line_number": 9, + "reason": "This describes typical compression ratios, which are empirical observations, not implementation-defined parameters." + }, + { + "excerpt": "C.LWSP loads a 32-bit value from memory into register _rd_. It computes an effective address by adding the _zero_-extended offset, scaled by 4, to the stack pointer, `x2`. It expands to `lw rd, offset(x2)`.", + "line_number": 295, + "reason": "This describes the behavior of a specific instruction, not an implementation choice. The instruction semantics are fixed." + }, + { + "excerpt": "C.LWSP is valid only when _rd_\u2260`x0`; the code points with _rd_=`x0` are reserved.", + "line_number": 298, + "reason": "This describes encoding constraints for a specific instruction, not an implementation parameter. The constraint is fixed by the specification." + }, + { + "excerpt": "Register save/restore code at function entry/exit represents a significant portion of static code size.", + "line_number": 370, + "reason": "This text is inside a NOTE block and describes rationale, not normative requirements." + }, + { + "excerpt": "The immediate fields are scrambled in the instruction formats instead of in sequential order so that as many bits as possible are in the same position in every instruction, thereby simplifying implementations.", + "line_number": 210, + "reason": "This text is inside a NOTE block explaining design rationale, not defining implementation parameters." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"The C extension allows 16-bit instructions to be freely intermixed with 32-bit instructions, with the latter now able to start on any 16-bit boundary, i.e., IALIGN=16.\",\n \"line_number\": 25,\n \"parameter_name\": \"IALIGN\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"IALIGN is a direct architectural parameter that defines instruction alignment. With the C extension, it becomes 16 bits instead of the base 32 bits.\"\n },\n {\n \"excerpt\": \"CIW, CL, CS, CA, and CB are limited to just 8 of them.\",\n \"line_number\": 174,\n \"parameter_name\": \"RVC_REGISTER_SUBSET\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"The C extension limits certain instruction formats to only 8 registers (x8-x15) instead of all 32. This is a direct architectural choice in the instruction encoding.\"\n },\n {\n \"excerpt\": \"Compressed register-based floating-point loads and stores also use the CL and CS formats respectively, with the eight registers mapping to `f8` to `f15`.\",\n \"line_number\": 186,\n \"parameter_name\": \"RVC_FP_REGISTER_SUBSET\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"Similar to integer registers, compressed floating-point instructions are limited to f8-f15. This is a direct architectural encoding choice.\"\n },\n {\n \"excerpt\": \"As with base RVI instructions, the offsets of all RVC control transfer instructions are in multiples of 2 bytes.\",\n \"line_number\": 456,\n \"parameter_name\": \"RVC_OFFSET_ALIGNMENT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"RVC control transfer instructions have offsets that are multiples of 2 bytes, which is a direct architectural constraint.\"\n },\n {\n \"excerpt\": \"A 16-bit instruction with all bits zero is permanently reserved as an illegal instruction.\",\n \"line_number\": 774,\n \"parameter_name\": \"RVC_ILLEGAL_ZERO\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The all-zero 16-bit pattern is permanently reserved as illegal. This is a direct architectural choice about instruction encoding.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"Typically, 50%-60% of the RISC-V instructions in a program can be replaced with RVC instructions, resulting in a 25%-30% code-size reduction.\",\n \"line_number\": 9,\n \"reason\": \"This describes typical compression ratios, which are empirical observations, not implementation-defined parameters.\"\n },\n {\n \"excerpt\": \"C.LWSP loads a 32-bit value from memory into register _rd_. It computes an effective address by adding the _zero_-extended offset, scaled by 4, to the stack pointer, `x2`. It expands to `lw rd, offset(x2)`.\",\n \"line_number\": 295,\n \"reason\": \"This describes the behavior of a specific instruction, not an implementation choice. The instruction semantics are fixed.\"\n },\n {\n \"excerpt\": \"C.LWSP is valid only when _rd_\u2260`x0`; the code points with _rd_=`x0` are reserved.\",\n \"line_number\": 298,\n \"reason\": \"This describes encoding constraints for a specific instruction, not an implementation parameter. The constraint is fixed by the specification.\"\n },\n {\n \"excerpt\": \"Register save/restore code at function entry/exit represents a significant portion of static code size.\",\n \"line_number\": 370,\n \"reason\": \"This text is inside a NOTE block and describes rationale, not normative requirements.\"\n },\n {\n \"excerpt\": \"The immediate fields are scrambled in the instruction formats instead of in sequential order so that as many bits as possible are in the same position in every instruction, thereby simplifying implementations.\",\n \"line_number\": 210,\n \"reason\": \"This text is inside a NOTE block explaining design rationale, not defining implementation parameters.\"\n }\n ]\n}\n```", + "input_tokens": 18031, + "output_tokens": 1198, + "latency_ms": 25143, + "timestamp": "2026-04-15T14:26:34.068428+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_008", + "source_file": "cmo.adoc", + "start_line": 1, + "end_line": 1094, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "If the above constraints are not met, the behavior of a CBO instruction is UNSPECIFIED.", + "line_number": 334, + "parameter_name": "CBO_UNSPECIFIED_BEHAVIOR", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "medium", + "reasoning": "When PMP/PMA constraints are not met for a cache block, the implementation can choose any behavior since it's UNSPECIFIED. This is a direct implementation choice." + }, + { + "excerpt": "If neither a load instruction nor store instruction is permitted to access the physical addresses, but an instruction fetch is permitted to access the physical addresses, whether a cache-block management instruction is permitted to access the cache block is UNSPECIFIED.", + "line_number": 361, + "parameter_name": "CBM_IFETCH_ONLY_ACCESS", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "When only instruction fetch is permitted but not load/store, the implementation chooses whether cache-block management instructions can access the block. This is explicitly UNSPECIFIED, making it a binary implementation choice." + }, + { + "excerpt": "Each `x{csrname}` register is WARL; however, software should determine the legal values from the execution environment discovery mechanism.", + "line_number": 598, + "parameter_name": "XENVCFG_LEGAL_VALUES", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "The xenvcfg registers are WARL, meaning implementations can choose which values are legal for the CBIE/CBCFE/CBZE fields. The parameter is the set of legal values for these CSR fields." + }, + { + "excerpt": "Unless otherwise defined by the debug architecture specification, the behavior of trigger modules with respect to CMO instructions is UNSPECIFIED.", + "line_number": 421, + "parameter_name": "CMO_TRIGGER_BEHAVIOR", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "medium", + "reasoning": "The behavior of trigger modules with CMO instructions is UNSPECIFIED, allowing implementations to choose how triggers interact with these instructions." + }, + { + "excerpt": "An implementation may or may not update the entire set of bytes atomically with a single store operation.", + "line_number": 149, + "parameter_name": "CBO_ZERO_ATOMICITY", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "For cache-block zero instructions, implementations can choose whether to update all bytes atomically or not. This is a direct binary implementation choice." + }, + { + "excerpt": "An implementation may or may not update the entire set of bytes atomically.", + "line_number": 1050, + "parameter_name": "CBO_ZERO_ATOMIC_UPDATE", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "This reiterates the atomicity choice for cbo.zero instruction - whether the implementation updates the cache block bytes atomically or not." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "The term CMO encompasses all operations on caches or resources related to caches. The term CBO represents a subset of CMOs that operate only on cache blocks. The first CMO extensions only define CBOs.", + "line_number": 44, + "reason": "This is inside a [NOTE] block, which is non-normative informational text." + }, + { + "excerpt": "In the initial set of CMO extensions, the size of a cache block shall be uniform throughout the system.", + "line_number": 95, + "reason": "This is a fixed requirement ('shall be uniform') that all implementations must satisfy, not an implementation choice." + }, + { + "excerpt": "When MODE=Direct, all traps into machine mode cause the `pc` to be set to the address in the BASE field.", + "line_number": 254, + "reason": "This describes behavior when a CSR field has a specific value, not an implementation parameter. The behavior is determined by runtime CSR state." + }, + { + "excerpt": "CMO instructions do _not_ generate address-misaligned exceptions.", + "line_number": 417, + "reason": "This is a fixed requirement that applies to ALL implementations - CMO instructions must not generate address-misaligned exceptions." + }, + { + "excerpt": "Software may determine the PMP granularity by writing zero to `pmp0cfg`, then writing all ones to `pmpaddr0`, then reading back `pmpaddr0`.", + "line_number": 330, + "reason": "Here 'may' means permission (software is allowed to do this), not optionality. This describes a software technique, not an implementation parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"If the above constraints are not met, the behavior of a CBO instruction is UNSPECIFIED.\",\n \"line_number\": 334,\n \"parameter_name\": \"CBO_UNSPECIFIED_BEHAVIOR\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"medium\",\n \"reasoning\": \"When PMP/PMA constraints are not met for a cache block, the implementation can choose any behavior since it's UNSPECIFIED. This is a direct implementation choice.\"\n },\n {\n \"excerpt\": \"If neither a load instruction nor store instruction is permitted to access the physical addresses, but an instruction fetch is permitted to access the physical addresses, whether a cache-block management instruction is permitted to access the cache block is UNSPECIFIED.\",\n \"line_number\": 361,\n \"parameter_name\": \"CBM_IFETCH_ONLY_ACCESS\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"When only instruction fetch is permitted but not load/store, the implementation chooses whether cache-block management instructions can access the block. This is explicitly UNSPECIFIED, making it a binary implementation choice.\"\n },\n {\n \"excerpt\": \"Each `x{csrname}` register is WARL; however, software should determine the legal values from the execution environment discovery mechanism.\",\n \"line_number\": 598,\n \"parameter_name\": \"XENVCFG_LEGAL_VALUES\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"The xenvcfg registers are WARL, meaning implementations can choose which values are legal for the CBIE/CBCFE/CBZE fields. The parameter is the set of legal values for these CSR fields.\"\n },\n {\n \"excerpt\": \"Unless otherwise defined by the debug architecture specification, the behavior of trigger modules with respect to CMO instructions is UNSPECIFIED.\",\n \"line_number\": 421,\n \"parameter_name\": \"CMO_TRIGGER_BEHAVIOR\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The behavior of trigger modules with CMO instructions is UNSPECIFIED, allowing implementations to choose how triggers interact with these instructions.\"\n },\n {\n \"excerpt\": \"An implementation may or may not update the entire set of bytes atomically with a single store operation.\",\n \"line_number\": 149,\n \"parameter_name\": \"CBO_ZERO_ATOMICITY\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"For cache-block zero instructions, implementations can choose whether to update all bytes atomically or not. This is a direct binary implementation choice.\"\n },\n {\n \"excerpt\": \"An implementation may or may not update the entire set of bytes atomically.\",\n \"line_number\": 1050,\n \"parameter_name\": \"CBO_ZERO_ATOMIC_UPDATE\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"This reiterates the atomicity choice for cbo.zero instruction - whether the implementation updates the cache block bytes atomically or not.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"The term CMO encompasses all operations on caches or resources related to caches. The term CBO represents a subset of CMOs that operate only on cache blocks. The first CMO extensions only define CBOs.\",\n \"line_number\": 44,\n \"reason\": \"This is inside a [NOTE] block, which is non-normative informational text.\"\n },\n {\n \"excerpt\": \"In the initial set of CMO extensions, the size of a cache block shall be uniform throughout the system.\",\n \"line_number\": 95,\n \"reason\": \"This is a fixed requirement ('shall be uniform') that all implementations must satisfy, not an implementation choice.\"\n },\n {\n \"excerpt\": \"When MODE=Direct, all traps into machine mode cause the `pc` to be set to the address in the BASE field.\",\n \"line_number\": 254,\n \"reason\": \"This describes behavior when a CSR field has a specific value, not an implementation parameter. The behavior is determined by runtime CSR state.\"\n },\n {\n \"excerpt\": \"CMO instructions do _not_ generate address-misaligned exceptions.\",\n \"line_number\": 417,\n \"reason\": \"This is a fixed requirement that applies to ALL implementations - CMO instructions must not generate address-misaligned exceptions.\"\n },\n {\n \"excerpt\": \"Software may determine the PMP granularity by writing zero to `pmp0cfg`, then writing all ones to `pmpaddr0`, then reading back `pmpaddr0`.\",\n \"line_number\": 330,\n \"reason\": \"Here 'may' means permission (software is allowed to do this), not optionality. This describes a software technique, not an implementation parameter.\"\n }\n ]\n}\n```", + "input_tokens": 17042, + "output_tokens": 1351, + "latency_ms": 111723, + "timestamp": "2026-04-15T14:24:56.995242+00:00", + "error": null, + "retry_count": 1 + }, + { + "chunk_id": "chunk_010", + "source_file": "counters.adoc", + "start_line": 1, + "end_line": 237, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "The implemented number and width of these additional counters, and the set of events they count, are platform-specific.", + "line_number": 201, + "parameter_name": "HPM_COUNTER_EN", + "existing_udb_name": "HPM_COUNTER_EN", + "class": "NORM_DIRECT", + "value_type": "set", + "confidence": "high", + "reasoning": "The number of implemented hardware performance counters (hpmcounter3-31) is a direct implementation choice. Implementations can choose which subset of the 29 possible counters to implement." + }, + { + "excerpt": "The implemented number and width of these additional counters, and the set of events they count, are platform-specific.", + "line_number": 201, + "parameter_name": "HPM_EVENTS", + "existing_udb_name": "HPM_EVENTS", + "class": "NORM_DIRECT", + "value_type": "set", + "confidence": "high", + "reasoning": "The set of events that each hardware performance counter can count is platform-specific. This is a direct implementation choice about which events are supported by each counter." + }, + { + "excerpt": "Accessing an unimplemented counter may cause an illegal-instruction exception or may return a constant value.", + "line_number": 203, + "parameter_name": "TRAP_ON_UNIMPLEMENTED_HPM_COUNTER", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "Implementation can choose whether accessing an unimplemented performance counter causes an illegal instruction exception or returns a constant value. This is a binary choice in behavior." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "We recommend provision of these basic counters in implementations as they are essential for basic performance analysis", + "line_number": 16, + "reason": "This is inside a [NOTE] block, which is non-normative. Recommendations in NOTE blocks are not architectural parameters." + }, + { + "excerpt": "The RDCYCLE pseudoinstruction reads the low XLEN bits of the `cycle` CSR which holds a count of the number of clock cycles executed by the processor core", + "line_number": 53, + "reason": "This describes the fixed behavior of RDCYCLE instruction. All implementations must provide this behavior - it's not a parameter." + }, + { + "excerpt": "The real-time clocks of all harts must be synchronized to within one tick of the real-time clock.", + "line_number": 118, + "reason": "This is a fixed requirement ('must be synchronized') that applies to all implementations. There is no implementation choice here." + }, + { + "excerpt": "Instructions that cause synchronous exceptions, including ECALL and EBREAK, are not considered to retire", + "line_number": 142, + "reason": "This is inside a [NOTE] block and describes fixed behavior for instruction retirement counting. It's not an implementation choice." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"The implemented number and width of these additional counters, and the set of events they count, are platform-specific.\",\n \"line_number\": 201,\n \"parameter_name\": \"HPM_COUNTER_EN\",\n \"existing_udb_name\": \"HPM_COUNTER_EN\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"The number of implemented hardware performance counters (hpmcounter3-31) is a direct implementation choice. Implementations can choose which subset of the 29 possible counters to implement.\"\n },\n {\n \"excerpt\": \"The implemented number and width of these additional counters, and the set of events they count, are platform-specific.\",\n \"line_number\": 201,\n \"parameter_name\": \"HPM_EVENTS\",\n \"existing_udb_name\": \"HPM_EVENTS\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"The set of events that each hardware performance counter can count is platform-specific. This is a direct implementation choice about which events are supported by each counter.\"\n },\n {\n \"excerpt\": \"Accessing an unimplemented counter may cause an illegal-instruction exception or may return a constant value.\",\n \"line_number\": 203,\n \"parameter_name\": \"TRAP_ON_UNIMPLEMENTED_HPM_COUNTER\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"Implementation can choose whether accessing an unimplemented performance counter causes an illegal instruction exception or returns a constant value. This is a binary choice in behavior.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"We recommend provision of these basic counters in implementations as they are essential for basic performance analysis\",\n \"line_number\": 16,\n \"reason\": \"This is inside a [NOTE] block, which is non-normative. Recommendations in NOTE blocks are not architectural parameters.\"\n },\n {\n \"excerpt\": \"The RDCYCLE pseudoinstruction reads the low XLEN bits of the `cycle` CSR which holds a count of the number of clock cycles executed by the processor core\",\n \"line_number\": 53,\n \"reason\": \"This describes the fixed behavior of RDCYCLE instruction. All implementations must provide this behavior - it's not a parameter.\"\n },\n {\n \"excerpt\": \"The real-time clocks of all harts must be synchronized to within one tick of the real-time clock.\",\n \"line_number\": 118,\n \"reason\": \"This is a fixed requirement ('must be synchronized') that applies to all implementations. There is no implementation choice here.\"\n },\n {\n \"excerpt\": \"Instructions that cause synchronous exceptions, including ECALL and EBREAK, are not considered to retire\",\n \"line_number\": 142,\n \"reason\": \"This is inside a [NOTE] block and describes fixed behavior for instruction retirement counting. It's not an implementation choice.\"\n }\n ]\n}\n```", + "input_tokens": 8549, + "output_tokens": 797, + "latency_ms": 13427, + "timestamp": "2026-04-15T14:24:41.343859+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_011", + "source_file": "d-st-ext.adoc", + "start_line": 1, + "end_line": 239, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "The D extension widens the 32 floating-point registers, `f0-f31`, to 64 bits (FLEN=64 in <>", + "line_number": 11, + "parameter_name": "FLEN", + "existing_udb_name": "FLEN", + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "FLEN is set to 64 when the D extension is implemented. This is a direct architectural parameter that determines the width of floating-point registers." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "FLEN can be 32, 64, or 128 depending on which of the F, D, and Q extensions are supported. There can be up to four different floating-point precisions supported, including H, F, D, and Q.", + "line_number": 17, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. It provides informative context about FLEN values but does not define an implementation choice." + }, + { + "excerpt": "The FLD instruction loads a double-precision floating-point value from memory into floating-point register _rd_", + "line_number": 95, + "reason": "This describes the fixed behavior of the FLD instruction. All implementations must support this behavior - it is not an implementation choice." + }, + { + "excerpt": "FLD and FSD are only guaranteed to execute atomically if the effective address is naturally aligned and XLEN\u226564.", + "line_number": 105, + "reason": "This describes a fixed requirement about when atomicity is guaranteed. It is not an implementation choice but a specification of when certain guarantees apply." + }, + { + "excerpt": "FCVT.L[U].D and FCVT.D.L[U] are RV64-only instructions.", + "line_number": 130, + "reason": "This is a fixed requirement that these instructions are only available on RV64. It is not an implementation choice but a specification constraint." + }, + { + "excerpt": "The double-precision floating-point compare instructions are defined analogously to their single-precision counterparts, but operate on double-precision operands.", + "line_number": 218, + "reason": "This describes the fixed behavior of compare instructions. All implementations must follow this specification - it is not a parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"The D extension widens the 32 floating-point registers, `f0-f31`, to 64 bits (FLEN=64 in <>\",\n \"line_number\": 11,\n \"parameter_name\": \"FLEN\",\n \"existing_udb_name\": \"FLEN\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"FLEN is set to 64 when the D extension is implemented. This is a direct architectural parameter that determines the width of floating-point registers.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"FLEN can be 32, 64, or 128 depending on which of the F, D, and Q extensions are supported. There can be up to four different floating-point precisions supported, including H, F, D, and Q.\",\n \"line_number\": 17,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. It provides informative context about FLEN values but does not define an implementation choice.\"\n },\n {\n \"excerpt\": \"The FLD instruction loads a double-precision floating-point value from memory into floating-point register _rd_\",\n \"line_number\": 95,\n \"reason\": \"This describes the fixed behavior of the FLD instruction. All implementations must support this behavior - it is not an implementation choice.\"\n },\n {\n \"excerpt\": \"FLD and FSD are only guaranteed to execute atomically if the effective address is naturally aligned and XLEN\u226564.\",\n \"line_number\": 105,\n \"reason\": \"This describes a fixed requirement about when atomicity is guaranteed. It is not an implementation choice but a specification of when certain guarantees apply.\"\n },\n {\n \"excerpt\": \"FCVT.L[U].D and FCVT.D.L[U] are RV64-only instructions.\",\n \"line_number\": 130,\n \"reason\": \"This is a fixed requirement that these instructions are only available on RV64. It is not an implementation choice but a specification constraint.\"\n },\n {\n \"excerpt\": \"The double-precision floating-point compare instructions are defined analogously to their single-precision counterparts, but operate on double-precision operands.\",\n \"line_number\": 218,\n \"reason\": \"This describes the fixed behavior of compare instructions. All implementations must follow this specification - it is not a parameter.\"\n }\n ]\n}\n```", + "input_tokens": 8888, + "output_tokens": 632, + "latency_ms": 28422, + "timestamp": "2026-04-15T14:26:09.828408+00:00", + "error": null, + "retry_count": 1 + }, + { + "chunk_id": "chunk_012", + "source_file": "f-st-ext.adoc", + "start_line": 1, + "end_line": 524, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "The behavior of floating-point instructions that depend on rounding mode when executed with a reserved rounding mode is _reserved_, including both static reserved rounding modes (101-110) and dynamic reserved rounding modes (101-111).", + "line_number": 130, + "parameter_name": "TRAP_ON_RESERVED_ROUNDING_MODE", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "The behavior when encountering reserved rounding modes is implementation-defined ('reserved'). Implementations may trap or handle it differently, making this a direct implementation choice." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "We considered a unified register file for both integer and floating-point values as this simplifies software register allocation and calling conventions, and reduces total user state.", + "line_number": 24, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. It describes design considerations, not architectural requirements." + }, + { + "excerpt": "The F extension adds 32 floating-point registers, `f0-f31`, each 32 bits wide", + "line_number": 11, + "reason": "This is a fixed requirement of the F extension - all implementations must provide exactly 32 floating-point registers of 32 bits each. There is no implementation choice here." + }, + { + "excerpt": "FADD.S and FMUL.S perform single-precision floating-point addition and multiplication respectively, between _rs1_ and _rs2_", + "line_number": 244, + "reason": "This describes the fixed behavior of specific instructions. The operation performed is defined by the instruction encoding, not by implementation choice." + }, + { + "excerpt": "FLW and FSW are only guaranteed to execute atomically if the effective address is naturally aligned.", + "line_number": 218, + "reason": "This is a fixed requirement about when atomicity is guaranteed. All implementations must follow this rule - there is no implementation choice." + }, + { + "excerpt": "As described in <>, the execution environment defines whether misaligned floating-point loads and stores are handled invisibly or raise a contained or fatal trap.", + "line_number": 224, + "reason": "This refers to execution environment behavior, which is outside the ISA scope. The ISA itself doesn't define this choice - it's a platform-level decision." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"The behavior of floating-point instructions that depend on rounding mode when executed with a reserved rounding mode is _reserved_, including both static reserved rounding modes (101-110) and dynamic reserved rounding modes (101-111).\",\n \"line_number\": 130,\n \"parameter_name\": \"TRAP_ON_RESERVED_ROUNDING_MODE\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The behavior when encountering reserved rounding modes is implementation-defined ('reserved'). Implementations may trap or handle it differently, making this a direct implementation choice.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"We considered a unified register file for both integer and floating-point values as this simplifies software register allocation and calling conventions, and reduces total user state.\",\n \"line_number\": 24,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. It describes design considerations, not architectural requirements.\"\n },\n {\n \"excerpt\": \"The F extension adds 32 floating-point registers, `f0-f31`, each 32 bits wide\",\n \"line_number\": 11,\n \"reason\": \"This is a fixed requirement of the F extension - all implementations must provide exactly 32 floating-point registers of 32 bits each. There is no implementation choice here.\"\n },\n {\n \"excerpt\": \"FADD.S and FMUL.S perform single-precision floating-point addition and multiplication respectively, between _rs1_ and _rs2_\",\n \"line_number\": 244,\n \"reason\": \"This describes the fixed behavior of specific instructions. The operation performed is defined by the instruction encoding, not by implementation choice.\"\n },\n {\n \"excerpt\": \"FLW and FSW are only guaranteed to execute atomically if the effective address is naturally aligned.\",\n \"line_number\": 218,\n \"reason\": \"This is a fixed requirement about when atomicity is guaranteed. All implementations must follow this rule - there is no implementation choice.\"\n },\n {\n \"excerpt\": \"As described in <>, the execution environment defines whether misaligned floating-point loads and stores are handled invisibly or raise a contained or fatal trap.\",\n \"line_number\": 224,\n \"reason\": \"This refers to execution environment behavior, which is outside the ISA scope. The ISA itself doesn't define this choice - it's a platform-level decision.\"\n }\n ]\n}\n```", + "input_tokens": 13070, + "output_tokens": 639, + "latency_ms": 15811, + "timestamp": "2026-04-15T14:27:24.342301+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_013", + "source_file": "fraclmul.adoc", + "start_line": 1, + "end_line": 175, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [], + "skipped_non_parameters": [ + { + "excerpt": "This appendix presents a non-normative example to help explain where compilers can make good use of the fractional LMUL feature.", + "line_number": 3, + "reason": "This is a non-normative example section that explains compiler usage patterns, not an architectural parameter definition." + }, + { + "excerpt": "Without fractional LMUL, the compiler would be forced to use LMUL=1 for the 8-bit computation and LMUL=8 for the 64-bit computation(s)", + "line_number": 26, + "reason": "This describes compiler behavior and usage patterns, not an implementation-defined architectural parameter." + }, + { + "excerpt": "If instead of using LMUL=1 for the 8-bit computation, the compiler is allowed to use a fractional LMUL=1/2", + "line_number": 103, + "reason": "This describes a compiler optimization strategy using existing architectural features, not a parameter that implementations choose." + }, + { + "excerpt": "vsetvli s1, zero, e8,mf2,ta,mu // LMUL=1/2 !", + "line_number": 110, + "reason": "This is assembly code showing usage of fractional LMUL values, which are runtime software choices, not implementation-defined parameters." + } + ], + "raw_response": "```json\n{\n \"parameters\": [],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"This appendix presents a non-normative example to help explain where compilers can make good use of the fractional LMUL feature.\",\n \"line_number\": 3,\n \"reason\": \"This is a non-normative example section that explains compiler usage patterns, not an architectural parameter definition.\"\n },\n {\n \"excerpt\": \"Without fractional LMUL, the compiler would be forced to use LMUL=1 for the 8-bit computation and LMUL=8 for the 64-bit computation(s)\",\n \"line_number\": 26,\n \"reason\": \"This describes compiler behavior and usage patterns, not an implementation-defined architectural parameter.\"\n },\n {\n \"excerpt\": \"If instead of using LMUL=1 for the 8-bit computation, the compiler is allowed to use a fractional LMUL=1/2\",\n \"line_number\": 103,\n \"reason\": \"This describes a compiler optimization strategy using existing architectural features, not a parameter that implementations choose.\"\n },\n {\n \"excerpt\": \"vsetvli s1, zero, e8,mf2,ta,mu // LMUL=1/2 !\",\n \"line_number\": 110,\n \"reason\": \"This is assembly code showing usage of fractional LMUL values, which are runtime software choices, not implementation-defined parameters.\"\n }\n ]\n}\n```", + "input_tokens": 8146, + "output_tokens": 370, + "latency_ms": 7094, + "timestamp": "2026-04-15T14:30:26.354359+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_014", + "source_file": "hypervisor.adoc", + "start_line": 1, + "end_line": 2932, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "CSR `mtval` must not be read-only zero", + "line_number": 24, + "parameter_name": "MTVAL_IMPLEMENTED", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation must choose whether mtval is implemented (not read-only zero) or not. This is a direct architectural choice." + }, + { + "excerpt": "standard page-based address translation must be supported, either Sv32 for RV32, or a minimum of Sv39 for RV64", + "line_number": 25, + "parameter_name": "H_VM_SUPPORTED", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "high", + "reasoning": "The implementation must choose which page-based translation modes to support when the H extension is enabled. This is a direct architectural requirement." + }, + { + "excerpt": "we use the term _HSXLEN_ to refer to the effective XLEN when executing in HS-mode", + "line_number": 139, + "parameter_name": "HSXLEN", + "existing_udb_name": "HSXLEN", + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "high", + "reasoning": "HSXLEN is an architectural parameter that determines the effective XLEN in HS-mode, similar to MXLEN." + }, + { + "excerpt": "_VSXLEN_ to refer to the effective XLEN when executing in VS-mode", + "line_number": 140, + "parameter_name": "VSXLEN", + "existing_udb_name": "VSXLEN", + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "high", + "reasoning": "VSXLEN is an architectural parameter that determines the effective XLEN in VS-mode." + }, + { + "excerpt": "an implementation may make VSXL be a read-only field whose value always ensures that VSXLEN=HSXLEN", + "line_number": 165, + "parameter_name": "VSXL_READ_ONLY", + "existing_udb_name": null, + "class": "NORM_CSR_RW", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether the VSXL field is read-only or writable, controlling whether VSXLEN can differ from HSXLEN." + }, + { + "excerpt": "An implementation may have WFI always raise a virtual-instruction exception in VS-mode when VTW=1 (and `mstatus`.TW=0), even if there are pending globally-disabled interrupts when the instruction is executed", + "line_number": 181, + "parameter_name": "VTW_VIRTINSTR_BEHAVIOR", + "existing_udb_name": "VTW_VIRTINSTR_PARAM", + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether WFI always raises a virtual-instruction exception when VTW=1, or only when it doesn't complete within a bounded time." + }, + { + "excerpt": "GEILEN may be zero, in which case VGEIN may be read-only zero", + "line_number": 192, + "parameter_name": "GEILEN", + "existing_udb_name": "GEILEN", + "class": "NORM_DIRECT", + "value_type": "range", + "confidence": "high", + "reasoning": "GEILEN is the maximum guest external interrupt number, which is an implementation-defined parameter that may be zero." + }, + { + "excerpt": "An implementation may make field UBE be a read-only copy of `hstatus`.VSBE", + "line_number": 1050, + "parameter_name": "VSSTATUS_UBE_READONLY", + "existing_udb_name": "VSSTATUS_UBE_PARAM", + "class": "NORM_CSR_RW", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether vsstatus.UBE is read-only (copying hstatus.VSBE) or independently writable." + }, + { + "excerpt": "The number of VMID bits is UNSPECIFIED and may be zero", + "line_number": 1421, + "parameter_name": "VMID_WIDTH", + "existing_udb_name": "VMID_WIDTH", + "class": "NORM_DIRECT", + "value_type": "range", + "confidence": "high", + "reasoning": "VMIDLEN is the number of implemented VMID bits, which is an implementation-defined parameter that may be zero." + }, + { + "excerpt": "The least-significant bits of VMID are implemented first: that is, if VMIDLEN > 0, VMID[VMIDLEN-1:0] is writable. The maximal value of VMIDLEN, termed VMIDMAX, is 7 for Sv32x4 or 14 for Sv39x4, Sv48x4, and Sv57x4", + "line_number": 1425, + "parameter_name": "VMIDLEN", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "range", + "confidence": "high", + "reasoning": "VMIDLEN is the actual number of implemented VMID bits, constrained by VMIDMAX but chosen by the implementation." + }, + { + "excerpt": "When a guest-page-fault trap is taken into HS-mode, `htval` is written with either zero or the guest physical address that faulted, shifted right by 2 bits", + "line_number": 1568, + "parameter_name": "HTVAL_TRAPVAL_PARAM", + "existing_udb_name": "HTVAL_TRAPVAL_PARAM", + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether to write the faulting guest physical address to htval or just write zero on guest-page faults." + }, + { + "excerpt": "When a guest-page-fault trap is taken into M-mode, `mtval2` is written with either zero or the guest physical address that faulted, shifted right by 2 bits", + "line_number": 2644, + "parameter_name": "MTVAL2_TRAPVAL_PARAM", + "existing_udb_name": "MTVAL2_TRAPVAL_PARAM", + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether to write the faulting guest physical address to mtval2 or just write zero on guest-page faults." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "The hypervisor extension is enabled by setting bit 7 in the `misa` CSR", + "line_number": 29, + "reason": "This describes how to enable the extension, not an implementation choice. All implementations must use bit 7 for the H extension." + }, + { + "excerpt": "When V=1, the VS CSRs substitute for the corresponding supervisor CSRs, taking over all functions of the usual supervisor CSRs except as specified otherwise", + "line_number": 95, + "reason": "This describes the behavioral effect of V=1, not an implementation parameter. The behavior is fixed by the specification." + }, + { + "excerpt": "When MODE=Direct, all traps into machine mode cause the `pc` to be set to the address in the BASE field", + "line_number": 1254, + "reason": "This describes what happens when mtvec.MODE has a specific value. The behavior is determined by the CSR field value at runtime, not by an implementation choice." + }, + { + "excerpt": "Software may determine the PMP granularity by writing zero to `pmp0cfg`, then writing all ones to `pmpaddr0`, then reading back `pmpaddr0`", + "line_number": 3530, + "reason": "Here 'may' means 'is allowed to' (permission), not 'might or might not' (optionality). This describes a software technique, not an implementation-defined parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"CSR `mtval` must not be read-only zero\",\n \"line_number\": 24,\n \"parameter_name\": \"MTVAL_IMPLEMENTED\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation must choose whether mtval is implemented (not read-only zero) or not. This is a direct architectural choice.\"\n },\n {\n \"excerpt\": \"standard page-based address translation must be supported, either Sv32 for RV32, or a minimum of Sv39 for RV64\",\n \"line_number\": 25,\n \"parameter_name\": \"H_VM_SUPPORTED\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation must choose which page-based translation modes to support when the H extension is enabled. This is a direct architectural requirement.\"\n },\n {\n \"excerpt\": \"we use the term _HSXLEN_ to refer to the effective XLEN when executing in HS-mode\",\n \"line_number\": 139,\n \"parameter_name\": \"HSXLEN\",\n \"existing_udb_name\": \"HSXLEN\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"HSXLEN is an architectural parameter that determines the effective XLEN in HS-mode, similar to MXLEN.\"\n },\n {\n \"excerpt\": \"_VSXLEN_ to refer to the effective XLEN when executing in VS-mode\",\n \"line_number\": 140,\n \"parameter_name\": \"VSXLEN\",\n \"existing_udb_name\": \"VSXLEN\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"VSXLEN is an architectural parameter that determines the effective XLEN in VS-mode.\"\n },\n {\n \"excerpt\": \"an implementation may make VSXL be a read-only field whose value always ensures that VSXLEN=HSXLEN\",\n \"line_number\": 165,\n \"parameter_name\": \"VSXL_READ_ONLY\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether the VSXL field is read-only or writable, controlling whether VSXLEN can differ from HSXLEN.\"\n },\n {\n \"excerpt\": \"An implementation may have WFI always raise a virtual-instruction exception in VS-mode when VTW=1 (and `mstatus`.TW=0), even if there are pending globally-disabled interrupts when the instruction is executed\",\n \"line_number\": 181,\n \"parameter_name\": \"VTW_VIRTINSTR_BEHAVIOR\",\n \"existing_udb_name\": \"VTW_VIRTINSTR_PARAM\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether WFI always raises a virtual-instruction exception when VTW=1, or only when it doesn't complete within a bounded time.\"\n },\n {\n \"excerpt\": \"GEILEN may be zero, in which case VGEIN may be read-only zero\",\n \"line_number\": 192,\n \"parameter_name\": \"GEILEN\",\n \"existing_udb_name\": \"GEILEN\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"range\",\n \"confidence\": \"high\",\n \"reasoning\": \"GEILEN is the maximum guest external interrupt number, which is an implementation-defined parameter that may be zero.\"\n },\n {\n \"excerpt\": \"An implementation may make field UBE be a read-only copy of `hstatus`.VSBE\",\n \"line_number\": 1050,\n \"parameter_name\": \"VSSTATUS_UBE_READONLY\",\n \"existing_udb_name\": \"VSSTATUS_UBE_PARAM\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether vsstatus.UBE is read-only (copying hstatus.VSBE) or independently writable.\"\n },\n {\n \"excerpt\": \"The number of VMID bits is UNSPECIFIED and may be zero\",\n \"line_number\": 1421,\n \"parameter_name\": \"VMID_WIDTH\",\n \"existing_udb_name\": \"VMID_WIDTH\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"range\",\n \"confidence\": \"high\",\n \"reasoning\": \"VMIDLEN is the number of implemented VMID bits, which is an implementation-defined parameter that may be zero.\"\n },\n {\n \"excerpt\": \"The least-significant bits of VMID are implemented first: that is, if VMIDLEN > 0, VMID[VMIDLEN-1:0] is writable. The maximal value of VMIDLEN, termed VMIDMAX, is 7 for Sv32x4 or 14 for Sv39x4, Sv48x4, and Sv57x4\",\n \"line_number\": 1425,\n \"parameter_name\": \"VMIDLEN\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"range\",\n \"confidence\": \"high\",\n \"reasoning\": \"VMIDLEN is the actual number of implemented VMID bits, constrained by VMIDMAX but chosen by the implementation.\"\n },\n {\n \"excerpt\": \"When a guest-page-fault trap is taken into HS-mode, `htval` is written with either zero or the guest physical address that faulted, shifted right by 2 bits\",\n \"line_number\": 1568,\n \"parameter_name\": \"HTVAL_TRAPVAL_PARAM\",\n \"existing_udb_name\": \"HTVAL_TRAPVAL_PARAM\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether to write the faulting guest physical address to htval or just write zero on guest-page faults.\"\n },\n {\n \"excerpt\": \"When a guest-page-fault trap is taken into M-mode, `mtval2` is written with either zero or the guest physical address that faulted, shifted right by 2 bits\",\n \"line_number\": 2644,\n \"parameter_name\": \"MTVAL2_TRAPVAL_PARAM\",\n \"existing_udb_name\": \"MTVAL2_TRAPVAL_PARAM\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether to write the faulting guest physical address to mtval2 or just write zero on guest-page faults.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"The hypervisor extension is enabled by setting bit 7 in the `misa` CSR\",\n \"line_number\": 29,\n \"reason\": \"This describes how to enable the extension, not an implementation choice. All implementations must use bit 7 for the H extension.\"\n },\n {\n \"excerpt\": \"When V=1, the VS CSRs substitute for the corresponding supervisor CSRs, taking over all functions of the usual supervisor CSRs except as specified otherwise\",\n \"line_number\": 95,\n \"reason\": \"This describes the behavioral effect of V=1, not an implementation parameter. The behavior is fixed by the specification.\"\n },\n {\n \"excerpt\": \"When MODE=Direct, all traps into machine mode cause the `pc` to be set to the address in the BASE field\",\n \"line_number\": 1254,\n \"reason\": \"This describes what happens when mtvec.MODE has a specific value. The behavior is determined by the CSR field value at runtime, not by an implementation choice.\"\n },\n {\n \"excerpt\": \"Software may determine the PMP granularity by writing zero to `pmp0cfg`, then writing all ones to `pmpaddr0`, then reading back `pmpaddr0`\",\n \"line_number\": 3530,\n \"reason\": \"Here 'may' means 'is allowed to' (permission), not 'might or might not' (optionality). This describes a software technique, not an implementation-defined parameter.\"\n }\n ]\n}\n```", + "input_tokens": 43015, + "output_tokens": 2247, + "latency_ms": 39566, + "timestamp": "2026-04-15T14:28:47.169712+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_016", + "source_file": "indirect-csr.adoc", + "start_line": 1, + "end_line": 333, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "`miselect` is a WARL register.", + "line_number": 67, + "parameter_name": "MISELECT_WARL_VALUES", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "miselect is explicitly stated to be WARL, meaning implementations can restrict which values are legal. The parameter is the set of supported miselect values." + }, + { + "excerpt": "The `miselect` register may be read-only zero if there are no extensions implemented that utilize it.", + "line_number": 72, + "parameter_name": "MISELECT_ACCESS", + "existing_udb_name": null, + "class": "NORM_CSR_RW", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether miselect is read-only zero or read-write, depending on whether extensions that use it are implemented." + }, + { + "excerpt": "The behavior upon accessing `mireg*` from M-mode, while `miselect` holds a value that is not implemented, is UNSPECIFIED.", + "line_number": 84, + "parameter_name": "MIREG_UNIMPLEMENTED_BEHAVIOR", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "high", + "reasoning": "The behavior when accessing mireg* with unimplemented miselect values is explicitly unspecified, giving implementations freedom to choose (e.g., illegal instruction exception, read-only zero, etc.)." + }, + { + "excerpt": "The `siselect` register will support the value range 0..0xFFF at a minimum. A future extension may define a value range outside of this minimum range. Only if such an extension is implemented will `siselect` be required to support larger values.", + "line_number": 119, + "parameter_name": "SISELECT_RANGE", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "range", + "confidence": "high", + "reasoning": "The siselect register must support at least 0..0xFFF, but implementations may support larger ranges if they implement extensions that require them. The actual supported range is an implementation choice." + }, + { + "excerpt": "The behavior upon accessing `sireg*` from M-mode or S-mode, while `siselect` holds a value that is not implemented at supervisor level, is UNSPECIFIED.", + "line_number": 137, + "parameter_name": "SIREG_UNIMPLEMENTED_BEHAVIOR", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "high", + "reasoning": "The behavior when accessing sireg* with unimplemented siselect values is explicitly unspecified, giving implementations freedom to choose the response." + }, + { + "excerpt": "The `vsiselect` register will support the value range 0..0xFFF at a minimum. A future extension may define a value range outside of this minimum range. Only if such an extension is implemented will `vsiselect` be required to support larger values.", + "line_number": 177, + "parameter_name": "VSISELECT_RANGE", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "range", + "confidence": "high", + "reasoning": "Similar to siselect, vsiselect must support at least 0..0xFFF, but implementations may support larger ranges based on implemented extensions." + }, + { + "excerpt": "The behavior upon accessing `vsireg*` from M-mode or HS-mode, or accessing `sireg*` (really `vsireg*`) from VS-mode, while `vsiselect` holds a value that is not implemented at HS level, is UNSPECIFIED.", + "line_number": 205, + "parameter_name": "VSIREG_UNIMPLEMENTED_BEHAVIOR", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "high", + "reasoning": "The behavior when accessing vsireg* with unimplemented vsiselect values is explicitly unspecified, allowing implementation-defined responses." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "CSRs are accessed indirectly via this extension using select values, in contrast to being accessed directly using standard CSR numbers.", + "line_number": 18, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks." + }, + { + "excerpt": "The `mireg*` CSR numbers are not consecutive because miph is CSR number 0x354.", + "line_number": 54, + "reason": "This text is inside a [NOTE] block explaining CSR numbering, which is informative rather than defining an implementation parameter." + }, + { + "excerpt": "When `mstateen0`[60]=0, an attempt to access one of these CSRs from a privilege mode less privileged than M-mode results in an illegal-instruction exception.", + "line_number": 237, + "reason": "This describes what happens when a CSR field has a specific value (mstateen0[60]=0). The behavior is determined by the field value at runtime, not by an implementation choice." + }, + { + "excerpt": "The CSRs in the table above are required if S-mode is implemented.", + "line_number": 117, + "reason": "This is a fixed requirement ('required if S-mode is implemented') that applies to all implementations with S-mode. There is no implementation choice here." + }, + { + "excerpt": "It is expected that implementations will typically raise an illegal-instruction exception for such accesses", + "line_number": 87, + "reason": "This text is inside a [NOTE] block describing expected behavior, which is informative guidance rather than a normative parameter definition." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"`miselect` is a WARL register.\",\n \"line_number\": 67,\n \"parameter_name\": \"MISELECT_WARL_VALUES\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"miselect is explicitly stated to be WARL, meaning implementations can restrict which values are legal. The parameter is the set of supported miselect values.\"\n },\n {\n \"excerpt\": \"The `miselect` register may be read-only zero if there are no extensions implemented that utilize it.\",\n \"line_number\": 72,\n \"parameter_name\": \"MISELECT_ACCESS\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether miselect is read-only zero or read-write, depending on whether extensions that use it are implemented.\"\n },\n {\n \"excerpt\": \"The behavior upon accessing `mireg*` from M-mode, while `miselect` holds a value that is not implemented, is UNSPECIFIED.\",\n \"line_number\": 84,\n \"parameter_name\": \"MIREG_UNIMPLEMENTED_BEHAVIOR\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"The behavior when accessing mireg* with unimplemented miselect values is explicitly unspecified, giving implementations freedom to choose (e.g., illegal instruction exception, read-only zero, etc.).\"\n },\n {\n \"excerpt\": \"The `siselect` register will support the value range 0..0xFFF at a minimum. A future extension may define a value range outside of this minimum range. Only if such an extension is implemented will `siselect` be required to support larger values.\",\n \"line_number\": 119,\n \"parameter_name\": \"SISELECT_RANGE\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"range\",\n \"confidence\": \"high\",\n \"reasoning\": \"The siselect register must support at least 0..0xFFF, but implementations may support larger ranges if they implement extensions that require them. The actual supported range is an implementation choice.\"\n },\n {\n \"excerpt\": \"The behavior upon accessing `sireg*` from M-mode or S-mode, while `siselect` holds a value that is not implemented at supervisor level, is UNSPECIFIED.\",\n \"line_number\": 137,\n \"parameter_name\": \"SIREG_UNIMPLEMENTED_BEHAVIOR\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"The behavior when accessing sireg* with unimplemented siselect values is explicitly unspecified, giving implementations freedom to choose the response.\"\n },\n {\n \"excerpt\": \"The `vsiselect` register will support the value range 0..0xFFF at a minimum. A future extension may define a value range outside of this minimum range. Only if such an extension is implemented will `vsiselect` be required to support larger values.\",\n \"line_number\": 177,\n \"parameter_name\": \"VSISELECT_RANGE\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"range\",\n \"confidence\": \"high\",\n \"reasoning\": \"Similar to siselect, vsiselect must support at least 0..0xFFF, but implementations may support larger ranges based on implemented extensions.\"\n },\n {\n \"excerpt\": \"The behavior upon accessing `vsireg*` from M-mode or HS-mode, or accessing `sireg*` (really `vsireg*`) from VS-mode, while `vsiselect` holds a value that is not implemented at HS level, is UNSPECIFIED.\",\n \"line_number\": 205,\n \"parameter_name\": \"VSIREG_UNIMPLEMENTED_BEHAVIOR\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"The behavior when accessing vsireg* with unimplemented vsiselect values is explicitly unspecified, allowing implementation-defined responses.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"CSRs are accessed indirectly via this extension using select values, in contrast to being accessed directly using standard CSR numbers.\",\n \"line_number\": 18,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks.\"\n },\n {\n \"excerpt\": \"The `mireg*` CSR numbers are not consecutive because miph is CSR number 0x354.\",\n \"line_number\": 54,\n \"reason\": \"This text is inside a [NOTE] block explaining CSR numbering, which is informative rather than defining an implementation parameter.\"\n },\n {\n \"excerpt\": \"When `mstateen0`[60]=0, an attempt to access one of these CSRs from a privilege mode less privileged than M-mode results in an illegal-instruction exception.\",\n \"line_number\": 237,\n \"reason\": \"This describes what happens when a CSR field has a specific value (mstateen0[60]=0). The behavior is determined by the field value at runtime, not by an implementation choice.\"\n },\n {\n \"excerpt\": \"The CSRs in the table above are required if S-mode is implemented.\",\n \"line_number\": 117,\n \"reason\": \"This is a fixed requirement ('required if S-mode is implemented') that applies to all implementations with S-mode. There is no implementation choice here.\"\n },\n {\n \"excerpt\": \"It is expected that implementations will typically raise an illegal-instruction exception for such accesses\",\n \"line_number\": 87,\n \"reason\": \"This text is inside a [NOTE] block describing expected behavior, which is informative guidance rather than a normative parameter definition.\"\n }\n ]\n}\n```", + "input_tokens": 10071, + "output_tokens": 1606, + "latency_ms": 72872, + "timestamp": "2026-04-15T14:30:07.069009+00:00", + "error": null, + "retry_count": 1 + }, + { + "chunk_id": "chunk_017", + "source_file": "intro.adoc", + "start_line": 1, + "end_line": 696, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "We use the term XLEN to refer to the width of an integer register in bits (either 32 or 64).", + "line_number": 217, + "parameter_name": "XLEN", + "existing_udb_name": "MXLEN", + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "high", + "reasoning": "XLEN is a fundamental architectural parameter that determines the width of integer registers and address space. The implementation chooses either 32 or 64 bits." + }, + { + "excerpt": "We use the term IALIGN (measured in bits) to refer to the instruction-address alignment constraint the implementation enforces. IALIGN is 32 bits in the base ISA, but some ISA extensions, including the compressed ISA extension, relax IALIGN to 16 bits. IALIGN may not take on any value other than 16 or 32.", + "line_number": 481, + "parameter_name": "IALIGN", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "high", + "reasoning": "IALIGN is an implementation choice for instruction alignment constraints. The spec explicitly states it may only be 16 or 32 bits, making this a direct architectural parameter." + }, + { + "excerpt": "We use the term ILEN (measured in bits) to refer to the maximum instruction length supported by an implementation, and which is always a multiple of IALIGN.", + "line_number": 487, + "parameter_name": "ILEN", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "ILEN is the maximum instruction length supported by an implementation. While constrained to be a multiple of IALIGN, the specific value is chosen by the implementer." + }, + { + "excerpt": "RISC-V base ISAs have either little-endian or big-endian memory systems, with the privileged architecture further defining bi-endian operation.", + "line_number": 548, + "parameter_name": "MEMORY_ENDIANNESS", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "high", + "reasoning": "The memory system endianness is an implementation choice between little-endian, big-endian, or bi-endian operation. This is a direct architectural parameter." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "Commentary on our design decisions is formatted as in this paragraph. This non-normative text can be skipped if the reader is only interested in the specification itself.", + "line_number": 35, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. Parameters should not be extracted from NOTE blocks." + }, + { + "excerpt": "The RISC-V ISA is defined avoiding implementation details as much as possible", + "line_number": 49, + "reason": "This describes the design philosophy of the specification itself, not an implementation choice or parameter." + }, + { + "excerpt": "A word of memory is defined as 32 bits (4 bytes). Correspondingly, a halfword is 16 bits (2 bytes), a doubleword is 64 bits (8 bytes), and a quadword is 128 bits (16 bytes).", + "line_number": 374, + "reason": "These are fixed definitions that apply to all implementations, not implementation choices. All RISC-V implementations must use these same definitions." + }, + { + "excerpt": "All the 32-bit instructions in the base ISA have their lowest two bits set to `11`.", + "line_number": 494, + "reason": "This is a fixed requirement that all implementations must follow, not an implementation choice." + }, + { + "excerpt": "The term UNSPECIFIED refers to a behavior or value that is intentionally unconstrained.", + "line_number": 686, + "reason": "This defines terminology used in the specification rather than describing an implementation parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"We use the term XLEN to refer to the width of an integer register in bits (either 32 or 64).\",\n \"line_number\": 217,\n \"parameter_name\": \"XLEN\",\n \"existing_udb_name\": \"MXLEN\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"XLEN is a fundamental architectural parameter that determines the width of integer registers and address space. The implementation chooses either 32 or 64 bits.\"\n },\n {\n \"excerpt\": \"We use the term IALIGN (measured in bits) to refer to the instruction-address alignment constraint the implementation enforces. IALIGN is 32 bits in the base ISA, but some ISA extensions, including the compressed ISA extension, relax IALIGN to 16 bits. IALIGN may not take on any value other than 16 or 32.\",\n \"line_number\": 481,\n \"parameter_name\": \"IALIGN\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"IALIGN is an implementation choice for instruction alignment constraints. The spec explicitly states it may only be 16 or 32 bits, making this a direct architectural parameter.\"\n },\n {\n \"excerpt\": \"We use the term ILEN (measured in bits) to refer to the maximum instruction length supported by an implementation, and which is always a multiple of IALIGN.\",\n \"line_number\": 487,\n \"parameter_name\": \"ILEN\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"ILEN is the maximum instruction length supported by an implementation. While constrained to be a multiple of IALIGN, the specific value is chosen by the implementer.\"\n },\n {\n \"excerpt\": \"RISC-V base ISAs have either little-endian or big-endian memory systems, with the privileged architecture further defining bi-endian operation.\",\n \"line_number\": 548,\n \"parameter_name\": \"MEMORY_ENDIANNESS\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"The memory system endianness is an implementation choice between little-endian, big-endian, or bi-endian operation. This is a direct architectural parameter.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"Commentary on our design decisions is formatted as in this paragraph. This non-normative text can be skipped if the reader is only interested in the specification itself.\",\n \"line_number\": 35,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. Parameters should not be extracted from NOTE blocks.\"\n },\n {\n \"excerpt\": \"The RISC-V ISA is defined avoiding implementation details as much as possible\",\n \"line_number\": 49,\n \"reason\": \"This describes the design philosophy of the specification itself, not an implementation choice or parameter.\"\n },\n {\n \"excerpt\": \"A word of memory is defined as 32 bits (4 bytes). Correspondingly, a halfword is 16 bits (2 bytes), a doubleword is 64 bits (8 bytes), and a quadword is 128 bits (16 bytes).\",\n \"line_number\": 374,\n \"reason\": \"These are fixed definitions that apply to all implementations, not implementation choices. All RISC-V implementations must use these same definitions.\"\n },\n {\n \"excerpt\": \"All the 32-bit instructions in the base ISA have their lowest two bits set to `11`.\",\n \"line_number\": 494,\n \"reason\": \"This is a fixed requirement that all implementations must follow, not an implementation choice.\"\n },\n {\n \"excerpt\": \"The term UNSPECIFIED refers to a behavior or value that is intentionally unconstrained.\",\n \"line_number\": 686,\n \"reason\": \"This defines terminology used in the specification rather than describing an implementation parameter.\"\n }\n ]\n}\n```", + "input_tokens": 14175, + "output_tokens": 1093, + "latency_ms": 46897, + "timestamp": "2026-04-15T14:32:01.646723+00:00", + "error": null, + "retry_count": 1 + }, + { + "chunk_id": "chunk_018", + "source_file": "m-st-ext.adoc", + "start_line": 1, + "end_line": 157, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [], + "skipped_non_parameters": [ + { + "excerpt": "We separate integer multiply and divide out from the base to simplify low-end implementations, or for applications where integer multiply and divide operations are either infrequent or better handled in attached accelerators.", + "line_number": 9, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. It explains design rationale but does not define any implementation choices." + }, + { + "excerpt": "MUL performs an XLEN-bit\u00d7XLEN-bit multiplication of `rs1` by `rs2` and places the lower XLEN bits in the destination register.", + "line_number": 23, + "reason": "This describes the fixed behavior of the MUL instruction that all implementations must follow. There is no implementation choice here." + }, + { + "excerpt": "The quotient of division by zero has all bits set, and the remainder of division by zero equals the dividend.", + "line_number": 85, + "reason": "This specifies the required behavior for division by zero that all implementations must follow. It is a fixed requirement, not a parameter." + }, + { + "excerpt": "Signed division overflow occurs only when the most-negative integer is divided by \u22121. The quotient of a signed division with overflow is equal to the dividend, and the remainder is zero.", + "line_number": 86, + "reason": "This defines the mandatory behavior for signed division overflow. All implementations must behave this way - there is no choice involved." + }, + { + "excerpt": "The `Zmmul` extension enables low-cost implementations that require multiplication operations but not division.", + "line_number": 135, + "reason": "This text is inside a [NOTE] block and is non-normative. It explains the motivation for the Zmmul extension but does not define any implementation parameters." + } + ], + "raw_response": "```json\n{\n \"parameters\": [],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"We separate integer multiply and divide out from the base to simplify low-end implementations, or for applications where integer multiply and divide operations are either infrequent or better handled in attached accelerators.\",\n \"line_number\": 9,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. It explains design rationale but does not define any implementation choices.\"\n },\n {\n \"excerpt\": \"MUL performs an XLEN-bit\u00d7XLEN-bit multiplication of `rs1` by `rs2` and places the lower XLEN bits in the destination register.\",\n \"line_number\": 23,\n \"reason\": \"This describes the fixed behavior of the MUL instruction that all implementations must follow. There is no implementation choice here.\"\n },\n {\n \"excerpt\": \"The quotient of division by zero has all bits set, and the remainder of division by zero equals the dividend.\",\n \"line_number\": 85,\n \"reason\": \"This specifies the required behavior for division by zero that all implementations must follow. It is a fixed requirement, not a parameter.\"\n },\n {\n \"excerpt\": \"Signed division overflow occurs only when the most-negative integer is divided by \u22121. The quotient of a signed division with overflow is equal to the dividend, and the remainder is zero.\",\n \"line_number\": 86,\n \"reason\": \"This defines the mandatory behavior for signed division overflow. All implementations must behave this way - there is no choice involved.\"\n },\n {\n \"excerpt\": \"The `Zmmul` extension enables low-cost implementations that require multiplication operations but not division.\",\n \"line_number\": 135,\n \"reason\": \"This text is inside a [NOTE] block and is non-normative. It explains the motivation for the Zmmul extension but does not define any implementation parameters.\"\n }\n ]\n}\n```", + "input_tokens": 7576, + "output_tokens": 474, + "latency_ms": 62507, + "timestamp": "2026-04-15T14:32:50.005533+00:00", + "error": null, + "retry_count": 1 + }, + { + "chunk_id": "chunk_019", + "source_file": "machine.adoc", + "start_line": 1, + "end_line": 3334, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "a value of zero can be returned to indicate the `misa` register has not been implemented", + "line_number": 23, + "parameter_name": "MISA_CSR_IMPLEMENTED", + "existing_udb_name": "MISA_CSR_IMPLEMENTED", + "class": "NORM_CSR_RW", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether the misa register is implemented (returns actual values) or not implemented (returns zero). This is a binary choice about the register's functionality." + }, + { + "excerpt": "The Extensions field is a *WARL* field that can contain writable bits where the implementation allows the supported ISA to be modified.", + "line_number": 60, + "parameter_name": "MUTABLE_MISA_EXTENSIONS", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "bitmask", + "confidence": "high", + "reasoning": "The Extensions field in misa is WARL, and implementations choose which extension bits are writable vs read-only. This defines the set of legal values for the Extensions field." + }, + { + "excerpt": "The `marchid` CSR is an MXLEN-bit read-only register encoding the base microarchitecture of the hart.", + "line_number": 217, + "parameter_name": "MARCHID_IMPLEMENTED", + "existing_udb_name": "MARCHID_IMPLEMENTED", + "class": "NORM_CSR_RW", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether marchid returns an actual architecture ID or zero to indicate it's not implemented. This is a binary choice about the register's functionality." + }, + { + "excerpt": "The `mimpid` CSR provides a unique encoding of the version of the processor implementation.", + "line_number": 248, + "parameter_name": "MIMPID_IMPLEMENTED", + "existing_udb_name": "MIMPID_IMPLEMENTED", + "class": "NORM_CSR_RW", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether mimpid returns an actual implementation ID or zero to indicate it's not implemented. This is a binary choice about the register's functionality." + }, + { + "excerpt": "The M-mode-disable-trap (`MDT`) bit is a WARL field introduced by the Smdbltrp extension.", + "line_number": 398, + "parameter_name": "SMDBLTRP_IMPLEMENTED", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "The implementation chooses whether to implement the Smdbltrp extension, which introduces the MDT bit. This is a direct implementation choice about extension support." + }, + { + "excerpt": "For RV64 harts, the SXL and UXL fields are *WARL* fields that control the value of XLEN for S-mode and U-mode, respectively.", + "line_number": 481, + "parameter_name": "SXLEN_UXLEN_CONTROL", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "enum", + "confidence": "high", + "reasoning": "The SXL and UXL fields are WARL, and implementations choose which XLEN values are supported for S-mode and U-mode. This defines the set of legal values for these fields." + }, + { + "excerpt": "The MBE, SBE, and UBE bits in `mstatus` and `mstatush` are *WARL* fields that control the endianness of memory accesses other than instruction fetches.", + "line_number": 679, + "parameter_name": "M_MODE_ENDIANNESS", + "existing_udb_name": "M_MODE_ENDIANNESS", + "class": "NORM_CSR_WARL", + "value_type": "enum", + "confidence": "high", + "reasoning": "The MBE field is WARL, and implementations choose which endianness values are supported (little-endian only, big-endian only, or both). This defines the set of legal values for the endianness control." + }, + { + "excerpt": "an implementation may make SBE be a read-only copy of MBE", + "line_number": 734, + "parameter_name": "S_MODE_ENDIANNESS", + "existing_udb_name": "S_MODE_ENDIANNESS", + "class": "NORM_CSR_RW", + "value_type": "enum", + "confidence": "high", + "reasoning": "The implementation chooses whether SBE is independently writable or a read-only copy of MBE. This controls the mutability and independence of the S-mode endianness control." + }, + { + "excerpt": "an implementation may make UBE be a read-only copy of either MBE or SBE", + "line_number": 735, + "parameter_name": "U_MODE_ENDIANNESS", + "existing_udb_name": "U_MODE_ENDIANNESS", + "class": "NORM_CSR_RW", + "value_type": "enum", + "confidence": "high", + "reasoning": "The implementation chooses whether UBE is independently writable or a read-only copy of MBE or SBE. This controls the mutability and independence of the U-mode endianness control." + }, + { + "excerpt": "The TVM (Trap Virtual Memory) bit is a *WARL* field that supports intercepting supervisor virtual-memory management operations.", + "line_number": 747, + "parameter_name": "MSTATUS_TVM_IMPLEMENTED", + "existing_udb_name": "MSTATUS_TVM_IMPLEMENTED", + "class": "NORM_CSR_WARL", + "value_type": "binary", + "confidence": "high", + "reasoning": "The TVM bit is WARL, and implementations choose whether to support trapping virtual memory operations. This defines whether TVM functionality is available." + }, + { + "excerpt": "The TW (Timeout Wait) bit is a *WARL* field that supports intercepting the WFI instruction", + "line_number": 760, + "parameter_name": "MSTATUS_TW_IMPLEMENTED", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "binary", + "confidence": "high", + "reasoning": "The TW bit is WARL, and implementations choose whether to support trapping WFI instructions. This defines whether TW functionality is available." + }, + { + "excerpt": "The TSR (Trap SRET) bit is a *WARL* field that supports intercepting the supervisor exception return instruction, SRET.", + "line_number": 779, + "parameter_name": "MSTATUS_TSR_IMPLEMENTED", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "binary", + "confidence": "high", + "reasoning": "The TSR bit is WARL, and implementations choose whether to support trapping SRET instructions. This defines whether TSR functionality is available." + }, + { + "excerpt": "The FS[1:0] and VS[1:0] *WARL* fields", + "line_number": 793, + "parameter_name": "MSTATUS_FS_LEGAL_VALUES", + "existing_udb_name": "MSTATUS_FS_LEGAL_VALUES", + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "The FS field is WARL, and implementations choose which status values are supported (Off, Initial, Clean, Dirty). This defines the set of legal values for floating-point state tracking." + }, + { + "excerpt": "The FS[1:0] and VS[1:0] *WARL* fields", + "line_number": 793, + "parameter_name": "MSTATUS_VS_LEGAL_VALUES", + "existing_udb_name": "MSTATUS_VS_LEGAL_VALUES", + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "The VS field is WARL, and implementations choose which status values are supported (Off, Initial, Clean, Dirty). This defines the set of legal values for vector state tracking." + }, + { + "excerpt": "it is implementation-defined whether FS transitions to Dirty", + "line_number": 1012, + "parameter_name": "HW_MSTATUS_FS_DIRTY_UPDATE", + "existing_udb_name": "HW_MSTATUS_FS_DIRTY_UPDATE", + "class": "SW_RULE", + "value_type": "enum", + "confidence": "high", + "reasoning": "Whether hardware updates mstatus.FS to Dirty is implementation-defined, but software can handle this deterministically by checking and managing FS state with proper fencing. The outcome is predictable if software follows the rules." + }, + { + "excerpt": "it is implementation-defined whether an instruction that writes a vector register or vector CSR but does not alter its contents causes VS to transition to Dirty", + "line_number": 1020, + "parameter_name": "HW_MSTATUS_VS_DIRTY_UPDATE", + "existing_udb_name": "HW_MSTATUS_VS_DIRTY_UPDATE", + "class": "SW_RULE", + "value_type": "enum", + "confidence": "high", + "reasoning": "Whether hardware updates mstatus.VS to Dirty is implementation-defined, but software can handle this deterministically by checking and managing VS state with proper fencing. The outcome is predictable if software follows the rules." + }, + { + "excerpt": "The `mtvec` register must always be implemented, but can contain a read-only value.", + "line_number": 1217, + "parameter_name": "MTVEC_ACCESS", + "existing_udb_name": "MTVEC_ACCESS", + "class": "NORM_CSR_RW", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether mtvec is read-only or read-write. This is a binary choice about the mutability of the register." + }, + { + "excerpt": "If `mtvec` is writable, the set of values the register may hold can vary by implementation.", + "line_number": 1219, + "parameter_name": "MTVEC_MODES", + "existing_udb_name": "MTVEC_MODES", + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "The mtvec MODE field is WARL, and the set of supported mode values (Direct=0, Vectored=1) varies by implementation. The parameter is the set of legal MODE values." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "This register must be readable in any implementation", + "line_number": 22, + "reason": "This is a fixed requirement ('must be readable') that all implementations must satisfy. There is no implementation choice here." + }, + { + "excerpt": "When MODE=Direct, all traps into machine mode cause the `pc` to be set to the address in the BASE field.", + "line_number": 1254, + "reason": "This describes what happens when mtvec.MODE has a specific value. The behavior is determined by the CSR field value at runtime, not by an implementation choice." + }, + { + "excerpt": "Software may determine the PMP granularity by writing zero to `pmp0cfg`, then writing all ones to `pmpaddr0`, then reading back `pmpaddr0`.", + "line_number": 3530, + "reason": "Here 'may' means 'is allowed to' (permission), not 'might or might not' (optionality). This describes a software technique, not an implementation-defined parameter." + }, + { + "excerpt": "The `misa` CSR is MXLEN bits wide.", + "line_number": 42, + "reason": "This is a fixed architectural requirement that the misa register width equals MXLEN. There is no implementation choice." + }, + { + "excerpt": "The MXL field is read-only.", + "line_number": 30, + "reason": "This is a fixed requirement that the MXL field is always read-only. There is no implementation choice about its mutability." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"a value of zero can be returned to indicate the `misa` register has not been implemented\",\n \"line_number\": 23,\n \"parameter_name\": \"MISA_CSR_IMPLEMENTED\",\n \"existing_udb_name\": \"MISA_CSR_IMPLEMENTED\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether the misa register is implemented (returns actual values) or not implemented (returns zero). This is a binary choice about the register's functionality.\"\n },\n {\n \"excerpt\": \"The Extensions field is a *WARL* field that can contain writable bits where the implementation allows the supported ISA to be modified.\",\n \"line_number\": 60,\n \"parameter_name\": \"MUTABLE_MISA_EXTENSIONS\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"bitmask\",\n \"confidence\": \"high\",\n \"reasoning\": \"The Extensions field in misa is WARL, and implementations choose which extension bits are writable vs read-only. This defines the set of legal values for the Extensions field.\"\n },\n {\n \"excerpt\": \"The `marchid` CSR is an MXLEN-bit read-only register encoding the base microarchitecture of the hart.\",\n \"line_number\": 217,\n \"parameter_name\": \"MARCHID_IMPLEMENTED\",\n \"existing_udb_name\": \"MARCHID_IMPLEMENTED\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether marchid returns an actual architecture ID or zero to indicate it's not implemented. This is a binary choice about the register's functionality.\"\n },\n {\n \"excerpt\": \"The `mimpid` CSR provides a unique encoding of the version of the processor implementation.\",\n \"line_number\": 248,\n \"parameter_name\": \"MIMPID_IMPLEMENTED\",\n \"existing_udb_name\": \"MIMPID_IMPLEMENTED\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether mimpid returns an actual implementation ID or zero to indicate it's not implemented. This is a binary choice about the register's functionality.\"\n },\n {\n \"excerpt\": \"The M-mode-disable-trap (`MDT`) bit is a WARL field introduced by the Smdbltrp extension.\",\n \"line_number\": 398,\n \"parameter_name\": \"SMDBLTRP_IMPLEMENTED\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The implementation chooses whether to implement the Smdbltrp extension, which introduces the MDT bit. This is a direct implementation choice about extension support.\"\n },\n {\n \"excerpt\": \"For RV64 harts, the SXL and UXL fields are *WARL* fields that control the value of XLEN for S-mode and U-mode, respectively.\",\n \"line_number\": 481,\n \"parameter_name\": \"SXLEN_UXLEN_CONTROL\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"The SXL and UXL fields are WARL, and implementations choose which XLEN values are supported for S-mode and U-mode. This defines the set of legal values for these fields.\"\n },\n {\n \"excerpt\": \"The MBE, SBE, and UBE bits in `mstatus` and `mstatush` are *WARL* fields that control the endianness of memory accesses other than instruction fetches.\",\n \"line_number\": 679,\n \"parameter_name\": \"M_MODE_ENDIANNESS\",\n \"existing_udb_name\": \"M_MODE_ENDIANNESS\",\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"The MBE field is WARL, and implementations choose which endianness values are supported (little-endian only, big-endian only, or both). This defines the set of legal values for the endianness control.\"\n },\n {\n \"excerpt\": \"an implementation may make SBE be a read-only copy of MBE\",\n \"line_number\": 734,\n \"parameter_name\": \"S_MODE_ENDIANNESS\",\n \"existing_udb_name\": \"S_MODE_ENDIANNESS\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether SBE is independently writable or a read-only copy of MBE. This controls the mutability and independence of the S-mode endianness control.\"\n },\n {\n \"excerpt\": \"an implementation may make UBE be a read-only copy of either MBE or SBE\",\n \"line_number\": 735,\n \"parameter_name\": \"U_MODE_ENDIANNESS\",\n \"existing_udb_name\": \"U_MODE_ENDIANNESS\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether UBE is independently writable or a read-only copy of MBE or SBE. This controls the mutability and independence of the U-mode endianness control.\"\n },\n {\n \"excerpt\": \"The TVM (Trap Virtual Memory) bit is a *WARL* field that supports intercepting supervisor virtual-memory management operations.\",\n \"line_number\": 747,\n \"parameter_name\": \"MSTATUS_TVM_IMPLEMENTED\",\n \"existing_udb_name\": \"MSTATUS_TVM_IMPLEMENTED\",\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The TVM bit is WARL, and implementations choose whether to support trapping virtual memory operations. This defines whether TVM functionality is available.\"\n },\n {\n \"excerpt\": \"The TW (Timeout Wait) bit is a *WARL* field that supports intercepting the WFI instruction\",\n \"line_number\": 760,\n \"parameter_name\": \"MSTATUS_TW_IMPLEMENTED\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The TW bit is WARL, and implementations choose whether to support trapping WFI instructions. This defines whether TW functionality is available.\"\n },\n {\n \"excerpt\": \"The TSR (Trap SRET) bit is a *WARL* field that supports intercepting the supervisor exception return instruction, SRET.\",\n \"line_number\": 779,\n \"parameter_name\": \"MSTATUS_TSR_IMPLEMENTED\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The TSR bit is WARL, and implementations choose whether to support trapping SRET instructions. This defines whether TSR functionality is available.\"\n },\n {\n \"excerpt\": \"The FS[1:0] and VS[1:0] *WARL* fields\",\n \"line_number\": 793,\n \"parameter_name\": \"MSTATUS_FS_LEGAL_VALUES\",\n \"existing_udb_name\": \"MSTATUS_FS_LEGAL_VALUES\",\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"The FS field is WARL, and implementations choose which status values are supported (Off, Initial, Clean, Dirty). This defines the set of legal values for floating-point state tracking.\"\n },\n {\n \"excerpt\": \"The FS[1:0] and VS[1:0] *WARL* fields\",\n \"line_number\": 793,\n \"parameter_name\": \"MSTATUS_VS_LEGAL_VALUES\",\n \"existing_udb_name\": \"MSTATUS_VS_LEGAL_VALUES\",\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"The VS field is WARL, and implementations choose which status values are supported (Off, Initial, Clean, Dirty). This defines the set of legal values for vector state tracking.\"\n },\n {\n \"excerpt\": \"it is implementation-defined whether FS transitions to Dirty\",\n \"line_number\": 1012,\n \"parameter_name\": \"HW_MSTATUS_FS_DIRTY_UPDATE\",\n \"existing_udb_name\": \"HW_MSTATUS_FS_DIRTY_UPDATE\",\n \"class\": \"SW_RULE\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"Whether hardware updates mstatus.FS to Dirty is implementation-defined, but software can handle this deterministically by checking and managing FS state with proper fencing. The outcome is predictable if software follows the rules.\"\n },\n {\n \"excerpt\": \"it is implementation-defined whether an instruction that writes a vector register or vector CSR but does not alter its contents causes VS to transition to Dirty\",\n \"line_number\": 1020,\n \"parameter_name\": \"HW_MSTATUS_VS_DIRTY_UPDATE\",\n \"existing_udb_name\": \"HW_MSTATUS_VS_DIRTY_UPDATE\",\n \"class\": \"SW_RULE\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"Whether hardware updates mstatus.VS to Dirty is implementation-defined, but software can handle this deterministically by checking and managing VS state with proper fencing. The outcome is predictable if software follows the rules.\"\n },\n {\n \"excerpt\": \"The `mtvec` register must always be implemented, but can contain a read-only value.\",\n \"line_number\": 1217,\n \"parameter_name\": \"MTVEC_ACCESS\",\n \"existing_udb_name\": \"MTVEC_ACCESS\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether mtvec is read-only or read-write. This is a binary choice about the mutability of the register.\"\n },\n {\n \"excerpt\": \"If `mtvec` is writable, the set of values the register may hold can vary by implementation.\",\n \"line_number\": 1219,\n \"parameter_name\": \"MTVEC_MODES\",\n \"existing_udb_name\": \"MTVEC_MODES\",\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"The mtvec MODE field is WARL, and the set of supported mode values (Direct=0, Vectored=1) varies by implementation. The parameter is the set of legal MODE values.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"This register must be readable in any implementation\",\n \"line_number\": 22,\n \"reason\": \"This is a fixed requirement ('must be readable') that all implementations must satisfy. There is no implementation choice here.\"\n },\n {\n \"excerpt\": \"When MODE=Direct, all traps into machine mode cause the `pc` to be set to the address in the BASE field.\",\n \"line_number\": 1254,\n \"reason\": \"This describes what happens when mtvec.MODE has a specific value. The behavior is determined by the CSR field value at runtime, not by an implementation choice.\"\n },\n {\n \"excerpt\": \"Software may determine the PMP granularity by writing zero to `pmp0cfg`, then writing all ones to `pmpaddr0`, then reading back `pmpaddr0`.\",\n \"line_number\": 3530,\n \"reason\": \"Here 'may' means 'is allowed to' (permission), not 'might or might not' (optionality). This describes a software technique, not an implementation-defined parameter.\"\n },\n {\n \"excerpt\": \"The `misa` CSR is MXLEN bits wide.\",\n \"line_number\": 42,\n \"reason\": \"This is a fixed architectural requirement that the misa register width equals MXLEN. There is no implementation choice.\"\n },\n {\n \"excerpt\": \"The MXL field is read-only.\",\n \"line_number\": 30,\n \"reason\": \"This is a fixed requirement that the MXL field is always read-only. There is no implementation choice about its mutability.\"\n }\n ]\n}\n```", + "input_tokens": 48136, + "output_tokens": 3365, + "latency_ms": 49161, + "timestamp": "2026-04-15T14:18:19.533071+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_020", + "source_file": "machine.adoc", + "start_line": 3305, + "end_line": 3629, + "content_start_line": 3335, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "Implementations may implement zero, 16, or 64 PMP entries; the lowest-numbered PMP entries must be implemented first.", + "line_number": 3340, + "parameter_name": "NUM_PMP_ENTRIES", + "existing_udb_name": "NUM_PMP_ENTRIES", + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "high", + "reasoning": "The number of PMP entries is a direct implementation choice with exactly three allowed values: 0, 16, or 64. This is not controlled by any CSR field." + }, + { + "excerpt": "All PMP CSR fields are WARL and may be read-only zero.", + "line_number": 3341, + "parameter_name": "PMP_CSR_WARL_VALUES", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "PMP CSR fields are WARL, meaning implementations can restrict which values are legal. The phrase 'may be read-only zero' indicates the set of legal values is implementation-defined." + }, + { + "excerpt": "The granularity of PMP access control settings are platform-specific, but the standard PMP encoding supports regions as small as four bytes.", + "line_number": 3308, + "parameter_name": "PMP_GRANULARITY", + "existing_udb_name": "PMP_GRANULARITY", + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "PMP granularity is explicitly stated as platform-specific, meaning it's an implementation choice. The granularity determines the minimum region size that can be protected." + }, + { + "excerpt": "Optionally, PMP checks may additionally apply to M-mode accesses, in which case the PMP registers themselves are locked, so that even M-mode software cannot change them until the hart is reset.", + "line_number": 3325, + "parameter_name": "PMP_CHECKS_ON_M_MODE", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "The word 'Optionally' indicates this is an implementation choice - whether PMP checks apply to M-mode accesses or not. This is a binary decision." + }, + { + "excerpt": "Not all physical address bits may be implemented, and so the `pmpaddr` registers are WARL.", + "line_number": 3370, + "parameter_name": "PMPADDR_WARL_VALUES", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "The pmpaddr registers are WARL because not all physical address bits may be implemented. This means the set of legal address values is implementation-defined." + }, + { + "excerpt": "The R, W, and X fields form a collective WARL field for which the combinations with R=0 and W=1 are reserved.", + "line_number": 3383, + "parameter_name": "PMP_RWX_WARL_VALUES", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "The R/W/X fields form a collective WARL field, meaning implementations can restrict which combinations are legal beyond just the reserved R=0,W=1 combination." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "Platforms vary widely in demands for physical memory protection, and some platforms may provide other PMP structures in addition to or instead of the scheme described in this section.", + "line_number": 3314, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks." + }, + { + "excerpt": "When MODE=Direct, all traps into machine mode cause the `pc` to be set to the address in the BASE field.", + "line_number": 3254, + "reason": "This describes behavior when a CSR field has a specific value, not an implementation choice. The parameter would be which MODE values are supported, not this behavioral description." + }, + { + "excerpt": "PMP violations are always trapped precisely at the processor.", + "line_number": 3330, + "reason": "This is a fixed requirement ('always trapped precisely') that all implementations must satisfy. There is no implementation choice here." + }, + { + "excerpt": "Software may determine the PMP granularity by writing zero to `pmp0cfg`, then writing all ones to `pmpaddr0`, then reading back `pmpaddr0`.", + "line_number": 3470, + "reason": "Here 'may' means 'is allowed to' (permission), not 'might or might not' (optionality). This describes a software technique for discovery, not an implementation-defined parameter." + }, + { + "excerpt": "When A=0, this PMP entry is disabled and matches no addresses.", + "line_number": 3400, + "reason": "This describes what happens when the A field has a specific value (0). This is behavioral description based on CSR field values, not an implementation choice." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"Implementations may implement zero, 16, or 64 PMP entries; the lowest-numbered PMP entries must be implemented first.\",\n \"line_number\": 3340,\n \"parameter_name\": \"NUM_PMP_ENTRIES\",\n \"existing_udb_name\": \"NUM_PMP_ENTRIES\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"The number of PMP entries is a direct implementation choice with exactly three allowed values: 0, 16, or 64. This is not controlled by any CSR field.\"\n },\n {\n \"excerpt\": \"All PMP CSR fields are WARL and may be read-only zero.\",\n \"line_number\": 3341,\n \"parameter_name\": \"PMP_CSR_WARL_VALUES\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"PMP CSR fields are WARL, meaning implementations can restrict which values are legal. The phrase 'may be read-only zero' indicates the set of legal values is implementation-defined.\"\n },\n {\n \"excerpt\": \"The granularity of PMP access control settings are platform-specific, but the standard PMP encoding supports regions as small as four bytes.\",\n \"line_number\": 3308,\n \"parameter_name\": \"PMP_GRANULARITY\",\n \"existing_udb_name\": \"PMP_GRANULARITY\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"PMP granularity is explicitly stated as platform-specific, meaning it's an implementation choice. The granularity determines the minimum region size that can be protected.\"\n },\n {\n \"excerpt\": \"Optionally, PMP checks may additionally apply to M-mode accesses, in which case the PMP registers themselves are locked, so that even M-mode software cannot change them until the hart is reset.\",\n \"line_number\": 3325,\n \"parameter_name\": \"PMP_CHECKS_ON_M_MODE\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The word 'Optionally' indicates this is an implementation choice - whether PMP checks apply to M-mode accesses or not. This is a binary decision.\"\n },\n {\n \"excerpt\": \"Not all physical address bits may be implemented, and so the `pmpaddr` registers are WARL.\",\n \"line_number\": 3370,\n \"parameter_name\": \"PMPADDR_WARL_VALUES\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"The pmpaddr registers are WARL because not all physical address bits may be implemented. This means the set of legal address values is implementation-defined.\"\n },\n {\n \"excerpt\": \"The R, W, and X fields form a collective WARL field for which the combinations with R=0 and W=1 are reserved.\",\n \"line_number\": 3383,\n \"parameter_name\": \"PMP_RWX_WARL_VALUES\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"The R/W/X fields form a collective WARL field, meaning implementations can restrict which combinations are legal beyond just the reserved R=0,W=1 combination.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"Platforms vary widely in demands for physical memory protection, and some platforms may provide other PMP structures in addition to or instead of the scheme described in this section.\",\n \"line_number\": 3314,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks.\"\n },\n {\n \"excerpt\": \"When MODE=Direct, all traps into machine mode cause the `pc` to be set to the address in the BASE field.\",\n \"line_number\": 3254,\n \"reason\": \"This describes behavior when a CSR field has a specific value, not an implementation choice. The parameter would be which MODE values are supported, not this behavioral description.\"\n },\n {\n \"excerpt\": \"PMP violations are always trapped precisely at the processor.\",\n \"line_number\": 3330,\n \"reason\": \"This is a fixed requirement ('always trapped precisely') that all implementations must satisfy. There is no implementation choice here.\"\n },\n {\n \"excerpt\": \"Software may determine the PMP granularity by writing zero to `pmp0cfg`, then writing all ones to `pmpaddr0`, then reading back `pmpaddr0`.\",\n \"line_number\": 3470,\n \"reason\": \"Here 'may' means 'is allowed to' (permission), not 'might or might not' (optionality). This describes a software technique for discovery, not an implementation-defined parameter.\"\n },\n {\n \"excerpt\": \"When A=0, this PMP entry is disabled and matches no addresses.\",\n \"line_number\": 3400,\n \"reason\": \"This describes what happens when the A field has a specific value (0). This is behavioral description based on CSR field values, not an implementation choice.\"\n }\n ]\n}\n```", + "input_tokens": 9523, + "output_tokens": 1416, + "latency_ms": 22837, + "timestamp": "2026-04-15T14:18:44.406115+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_025", + "source_file": "naming.adoc", + "start_line": 1, + "end_line": 222, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [], + "skipped_non_parameters": [ + { + "excerpt": "The RISC-V ISA is designed to support a wide variety of implementations with various experimental instruction-set extensions. We have found that an organized naming scheme simplifies software tools and documentation.", + "line_number": 9, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. It provides background information but does not define any architectural parameters." + }, + { + "excerpt": "The ISA naming strings are case insensitive.", + "line_number": 16, + "reason": "This is a fixed requirement that applies to all implementations - there is no implementation choice about case sensitivity." + }, + { + "excerpt": "RISC-V ISA strings begin with either RV32I, RV32E, RV64I, or RV64E, indicating the supported address space size in bits for the base integer ISA.", + "line_number": 20, + "reason": "This describes the naming convention format, not an implementation parameter. The choice of which base ISA to implement is covered by other parameters like MXLEN." + }, + { + "excerpt": "Standard ISA extensions are given a name consisting of a single letter.", + "line_number": 25, + "reason": "This is a documentation rule about how extensions are named, not an architectural implementation choice." + }, + { + "excerpt": "Many augmentations to the hypervisor-level architecture are more naturally defined as supervisor-level extensions, following the scheme described in the previous section.", + "line_number": 89, + "reason": "This text is inside a NOTE block and is therefore non-normative. It provides guidance but does not define any architectural parameters." + } + ], + "raw_response": "```json\n{\n \"parameters\": [],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"The RISC-V ISA is designed to support a wide variety of implementations with various experimental instruction-set extensions. We have found that an organized naming scheme simplifies software tools and documentation.\",\n \"line_number\": 9,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. It provides background information but does not define any architectural parameters.\"\n },\n {\n \"excerpt\": \"The ISA naming strings are case insensitive.\",\n \"line_number\": 16,\n \"reason\": \"This is a fixed requirement that applies to all implementations - there is no implementation choice about case sensitivity.\"\n },\n {\n \"excerpt\": \"RISC-V ISA strings begin with either RV32I, RV32E, RV64I, or RV64E, indicating the supported address space size in bits for the base integer ISA.\",\n \"line_number\": 20,\n \"reason\": \"This describes the naming convention format, not an implementation parameter. The choice of which base ISA to implement is covered by other parameters like MXLEN.\"\n },\n {\n \"excerpt\": \"Standard ISA extensions are given a name consisting of a single letter.\",\n \"line_number\": 25,\n \"reason\": \"This is a documentation rule about how extensions are named, not an architectural implementation choice.\"\n },\n {\n \"excerpt\": \"Many augmentations to the hypervisor-level architecture are more naturally defined as supervisor-level extensions, following the scheme described in the previous section.\",\n \"line_number\": 89,\n \"reason\": \"This text is inside a NOTE block and is therefore non-normative. It provides guidance but does not define any architectural parameters.\"\n }\n ]\n}\n```", + "input_tokens": 7850, + "output_tokens": 438, + "latency_ms": 8751, + "timestamp": "2026-04-15T14:32:26.654987+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_026", + "source_file": "priv-cfi.adoc", + "start_line": 1, + "end_line": 373, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "it is implementation-defined whether FS transitions to Dirty.", + "line_number": 1014, + "parameter_name": "REPORT_CAUSE_IN_MTVAL_ON_LANDING_PAD_SOFTWARE_CHECK", + "existing_udb_name": "REPORT_CAUSE_IN_MTVAL_ON_LANDING_PAD_SOFTWARE_CHECK", + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "The specification mentions software-check exceptions with mtval set to 'landing pad fault (code=2)' but doesn't explicitly state this is implementation-defined. However, based on the UDB parameter name pattern, this appears to be about whether the cause is reported in mtval for landing pad software checks." + }, + { + "excerpt": "The software-check exception due to the instruction not being an `LPAD` instruction when `ELP` is `LP_EXPECTED` or a software-check exception caused by the `LPAD` instruction itself leads to a trap being delivered to the same or to a higher privilege mode.", + "line_number": 78, + "parameter_name": "REPORT_CAUSE_IN_STVAL_ON_LANDING_PAD_SOFTWARE_CHECK", + "existing_udb_name": "REPORT_CAUSE_IN_STVAL_ON_LANDING_PAD_SOFTWARE_CHECK", + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "Similar to mtval case, this relates to reporting cause information in stval for landing pad software check exceptions, though not explicitly stated as implementation-defined in this text." + }, + { + "excerpt": "The software-check exception due to the instruction not being an `LPAD` instruction when `ELP` is `LP_EXPECTED` or a software-check exception caused by the `LPAD` instruction itself leads to a trap being delivered to the same or to a higher privilege mode.", + "line_number": 78, + "parameter_name": "REPORT_CAUSE_IN_VSTVAL_ON_LANDING_PAD_SOFTWARE_CHECK", + "existing_udb_name": "REPORT_CAUSE_IN_VSTVAL_ON_LANDING_PAD_SOFTWARE_CHECK", + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "Similar pattern for vstval reporting of landing pad software check exception causes." + }, + { + "excerpt": "If a shadow stack (SS) instruction raises an access-fault, page-fault, or guest-page-fault exception that is supposed to indicate the original instruction type (load or store/AMO), then the reported exception cause is respectively a store/AMO access fault (code 7), a store/AMO page fault (code 15), or a store/AMO guest-page fault (code 23).", + "line_number": 280, + "parameter_name": "REPORT_CAUSE_IN_MTVAL_ON_SHADOW_STACK_SOFTWARE_CHECK", + "existing_udb_name": "REPORT_CAUSE_IN_MTVAL_ON_SHADOW_STACK_SOFTWARE_CHECK", + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "This describes how shadow stack instruction exceptions are reported, which relates to cause reporting in mtval for shadow stack software checks." + }, + { + "excerpt": "If a shadow stack (SS) instruction raises an access-fault, page-fault, or guest-page-fault exception that is supposed to indicate the original instruction type (load or store/AMO), then the reported exception cause is respectively a store/AMO access fault (code 7), a store/AMO page fault (code 15), or a store/AMO guest-page fault (code 23).", + "line_number": 280, + "parameter_name": "REPORT_CAUSE_IN_STVAL_ON_SHADOW_STACK_SOFTWARE_CHECK", + "existing_udb_name": "REPORT_CAUSE_IN_STVAL_ON_SHADOW_STACK_SOFTWARE_CHECK", + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "Similar pattern for stval reporting of shadow stack software check exception causes." + }, + { + "excerpt": "If a shadow stack (SS) instruction raises an access-fault, page-fault, or guest-page-fault exception that is supposed to indicate the original instruction type (load or store/AMO), then the reported exception cause is respectively a store/AMO access fault (code 7), a store/AMO page fault (code 15), or a store/AMO guest-page fault (code 23).", + "line_number": 280, + "parameter_name": "REPORT_CAUSE_IN_VSTVAL_ON_SHADOW_STACK_SOFTWARE_CHECK", + "existing_udb_name": "REPORT_CAUSE_IN_VSTVAL_ON_SHADOW_STACK_SOFTWARE_CHECK", + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "Similar pattern for vstval reporting of shadow stack software check exception causes." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "The Zicfilp must be explicitly enabled for use at each privilege mode.", + "line_number": 44, + "reason": "This is inside a [NOTE] block, which is non-normative. Parameters should not be extracted from NOTE blocks." + }, + { + "excerpt": "When a trap is taken into privilege mode `x`, the `__x__PELP` is set to `ELP` and `ELP` is set to `NO_LP_EXPECTED`.", + "line_number": 89, + "reason": "This describes the required behavior when a trap occurs, not an implementation choice. All implementations must follow this behavior." + }, + { + "excerpt": "The encoding `R=0`, `W=1`, and `X=0`, is defined to represent an SS page.", + "line_number": 189, + "reason": "This defines a fixed encoding that all implementations must use, not an implementation choice." + }, + { + "excerpt": "Memory mapped as an SS page cannot be written to by instructions other than `SSAMOSWAP.W/D`, `SSPUSH`, and `C.SSPUSH`.", + "line_number": 198, + "reason": "This describes required behavior for SS pages, not an implementation choice. All implementations must enforce this restriction." + }, + { + "excerpt": "When S-mode is not implemented, then `xSSE` is 0 at both M and U privilege modes.", + "line_number": 165, + "reason": "This is a fixed requirement based on the presence/absence of S-mode, not an implementation choice." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"it is implementation-defined whether FS transitions to Dirty.\",\n \"line_number\": 1014,\n \"parameter_name\": \"REPORT_CAUSE_IN_MTVAL_ON_LANDING_PAD_SOFTWARE_CHECK\",\n \"existing_udb_name\": \"REPORT_CAUSE_IN_MTVAL_ON_LANDING_PAD_SOFTWARE_CHECK\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The specification mentions software-check exceptions with mtval set to 'landing pad fault (code=2)' but doesn't explicitly state this is implementation-defined. However, based on the UDB parameter name pattern, this appears to be about whether the cause is reported in mtval for landing pad software checks.\"\n },\n {\n \"excerpt\": \"The software-check exception due to the instruction not being an `LPAD` instruction when `ELP` is `LP_EXPECTED` or a software-check exception caused by the `LPAD` instruction itself leads to a trap being delivered to the same or to a higher privilege mode.\",\n \"line_number\": 78,\n \"parameter_name\": \"REPORT_CAUSE_IN_STVAL_ON_LANDING_PAD_SOFTWARE_CHECK\",\n \"existing_udb_name\": \"REPORT_CAUSE_IN_STVAL_ON_LANDING_PAD_SOFTWARE_CHECK\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"Similar to mtval case, this relates to reporting cause information in stval for landing pad software check exceptions, though not explicitly stated as implementation-defined in this text.\"\n },\n {\n \"excerpt\": \"The software-check exception due to the instruction not being an `LPAD` instruction when `ELP` is `LP_EXPECTED` or a software-check exception caused by the `LPAD` instruction itself leads to a trap being delivered to the same or to a higher privilege mode.\",\n \"line_number\": 78,\n \"parameter_name\": \"REPORT_CAUSE_IN_VSTVAL_ON_LANDING_PAD_SOFTWARE_CHECK\",\n \"existing_udb_name\": \"REPORT_CAUSE_IN_VSTVAL_ON_LANDING_PAD_SOFTWARE_CHECK\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"Similar pattern for vstval reporting of landing pad software check exception causes.\"\n },\n {\n \"excerpt\": \"If a shadow stack (SS) instruction raises an access-fault, page-fault, or guest-page-fault exception that is supposed to indicate the original instruction type (load or store/AMO), then the reported exception cause is respectively a store/AMO access fault (code 7), a store/AMO page fault (code 15), or a store/AMO guest-page fault (code 23).\",\n \"line_number\": 280,\n \"parameter_name\": \"REPORT_CAUSE_IN_MTVAL_ON_SHADOW_STACK_SOFTWARE_CHECK\",\n \"existing_udb_name\": \"REPORT_CAUSE_IN_MTVAL_ON_SHADOW_STACK_SOFTWARE_CHECK\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"This describes how shadow stack instruction exceptions are reported, which relates to cause reporting in mtval for shadow stack software checks.\"\n },\n {\n \"excerpt\": \"If a shadow stack (SS) instruction raises an access-fault, page-fault, or guest-page-fault exception that is supposed to indicate the original instruction type (load or store/AMO), then the reported exception cause is respectively a store/AMO access fault (code 7), a store/AMO page fault (code 15), or a store/AMO guest-page fault (code 23).\",\n \"line_number\": 280,\n \"parameter_name\": \"REPORT_CAUSE_IN_STVAL_ON_SHADOW_STACK_SOFTWARE_CHECK\",\n \"existing_udb_name\": \"REPORT_CAUSE_IN_STVAL_ON_SHADOW_STACK_SOFTWARE_CHECK\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"Similar pattern for stval reporting of shadow stack software check exception causes.\"\n },\n {\n \"excerpt\": \"If a shadow stack (SS) instruction raises an access-fault, page-fault, or guest-page-fault exception that is supposed to indicate the original instruction type (load or store/AMO), then the reported exception cause is respectively a store/AMO access fault (code 7), a store/AMO page fault (code 15), or a store/AMO guest-page fault (code 23).\",\n \"line_number\": 280,\n \"parameter_name\": \"REPORT_CAUSE_IN_VSTVAL_ON_SHADOW_STACK_SOFTWARE_CHECK\",\n \"existing_udb_name\": \"REPORT_CAUSE_IN_VSTVAL_ON_SHADOW_STACK_SOFTWARE_CHECK\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"Similar pattern for vstval reporting of shadow stack software check exception causes.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"The Zicfilp must be explicitly enabled for use at each privilege mode.\",\n \"line_number\": 44,\n \"reason\": \"This is inside a [NOTE] block, which is non-normative. Parameters should not be extracted from NOTE blocks.\"\n },\n {\n \"excerpt\": \"When a trap is taken into privilege mode `x`, the `__x__PELP` is set to `ELP` and `ELP` is set to `NO_LP_EXPECTED`.\",\n \"line_number\": 89,\n \"reason\": \"This describes the required behavior when a trap occurs, not an implementation choice. All implementations must follow this behavior.\"\n },\n {\n \"excerpt\": \"The encoding `R=0`, `W=1`, and `X=0`, is defined to represent an SS page.\",\n \"line_number\": 189,\n \"reason\": \"This defines a fixed encoding that all implementations must use, not an implementation choice.\"\n },\n {\n \"excerpt\": \"Memory mapped as an SS page cannot be written to by instructions other than `SSAMOSWAP.W/D`, `SSPUSH`, and `C.SSPUSH`.\",\n \"line_number\": 198,\n \"reason\": \"This describes required behavior for SS pages, not an implementation choice. All implementations must enforce this restriction.\"\n },\n {\n \"excerpt\": \"When S-mode is not implemented, then `xSSE` is 0 at both M and U privilege modes.\",\n \"line_number\": 165,\n \"reason\": \"This is a fixed requirement based on the presence/absence of S-mode, not an implementation choice.\"\n }\n ]\n}\n```", + "input_tokens": 10841, + "output_tokens": 1752, + "latency_ms": 55058, + "timestamp": "2026-04-15T14:34:15.692408+00:00", + "error": null, + "retry_count": 1 + }, + { + "chunk_id": "chunk_027", + "source_file": "priv-csrs.adoc", + "start_line": 1, + "end_line": 1272, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "Implementations are permitted but not required to raise an illegal-instruction exception if an instruction attempts to write a non-supported value to a *WLRL* field.", + "line_number": 1157, + "parameter_name": "TRAP_ON_ILLEGAL_WLRL", + "existing_udb_name": "TRAP_ON_ILLEGAL_WLRL", + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether to trap on illegal WLRL writes. This is a direct binary choice (trap or don't trap) not controlled by any CSR field." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "The CSR address convention uses the upper bits of the CSR address to encode default access privileges. This simplifies error checking in the hardware and provides a larger CSR space, but does constrain the mapping of CSRs into the address space.", + "line_number": 35, + "reason": "This is inside a [NOTE] block, which is non-normative informative text." + }, + { + "excerpt": "The top two bits (csr[11:10]) indicate whether the register is read/write (`00`,`01`, or `10`) or read-only (`11`).", + "line_number": 29, + "reason": "This describes a fixed encoding convention that all implementations must follow, not an implementation choice." + }, + { + "excerpt": "Instructions that access a non-existent CSR are reserved.", + "line_number": 46, + "reason": "This is a fixed requirement ('are reserved') that applies to all implementations, not a parameter." + }, + { + "excerpt": "For forward compatibility, implementations that do not furnish these fields must make them read-only zero.", + "line_number": 1120, + "reason": "This is a fixed requirement ('must make them read-only zero') for implementations that don't implement WPRI fields, not a choice." + }, + { + "excerpt": "Software should not write anything other than legal values to such a field, and should not assume a read will return a legal value unless the last write was of a legal value", + "line_number": 1140, + "reason": "This describes software behavior requirements, not implementation choices. The 'should' applies to software, not hardware implementation options." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"Implementations are permitted but not required to raise an illegal-instruction exception if an instruction attempts to write a non-supported value to a *WLRL* field.\",\n \"line_number\": 1157,\n \"parameter_name\": \"TRAP_ON_ILLEGAL_WLRL\",\n \"existing_udb_name\": \"TRAP_ON_ILLEGAL_WLRL\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether to trap on illegal WLRL writes. This is a direct binary choice (trap or don't trap) not controlled by any CSR field.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"The CSR address convention uses the upper bits of the CSR address to encode default access privileges. This simplifies error checking in the hardware and provides a larger CSR space, but does constrain the mapping of CSRs into the address space.\",\n \"line_number\": 35,\n \"reason\": \"This is inside a [NOTE] block, which is non-normative informative text.\"\n },\n {\n \"excerpt\": \"The top two bits (csr[11:10]) indicate whether the register is read/write (`00`,`01`, or `10`) or read-only (`11`).\",\n \"line_number\": 29,\n \"reason\": \"This describes a fixed encoding convention that all implementations must follow, not an implementation choice.\"\n },\n {\n \"excerpt\": \"Instructions that access a non-existent CSR are reserved.\",\n \"line_number\": 46,\n \"reason\": \"This is a fixed requirement ('are reserved') that applies to all implementations, not a parameter.\"\n },\n {\n \"excerpt\": \"For forward compatibility, implementations that do not furnish these fields must make them read-only zero.\",\n \"line_number\": 1120,\n \"reason\": \"This is a fixed requirement ('must make them read-only zero') for implementations that don't implement WPRI fields, not a choice.\"\n },\n {\n \"excerpt\": \"Software should not write anything other than legal values to such a field, and should not assume a read will return a legal value unless the last write was of a legal value\",\n \"line_number\": 1140,\n \"reason\": \"This describes software behavior requirements, not implementation choices. The 'should' applies to software, not hardware implementation options.\"\n }\n ]\n}\n```", + "input_tokens": 18597, + "output_tokens": 616, + "latency_ms": 13566, + "timestamp": "2026-04-15T14:36:17.903304+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_030", + "source_file": "priv-intro.adoc", + "start_line": 1, + "end_line": 217, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "Implementations might provide anywhere from 1 to 3 privilege modes", + "line_number": 135, + "parameter_name": "NUM_PRIVILEGE_MODES", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "range", + "confidence": "high", + "reasoning": "The number of privilege modes (1, 2, or 3) is a direct implementation choice that determines the protection model. This is not controlled by any CSR field." + }, + { + "excerpt": "Implementations may also include a debug mode to support off-chip debugging and/or manufacturing test.", + "line_number": 179, + "parameter_name": "DEBUG_MODE_IMPLEMENTED", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "Whether debug mode is implemented is an optional implementation choice. The use of 'may' indicates this is not mandatory for all implementations." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "Commentary on our design decisions is formatted as in this paragraph, and can be skipped if the reader is only interested in the specification itself.", + "line_number": 11, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks." + }, + { + "excerpt": "At any time, a RISC-V hardware thread (_hart_) is running at some privilege level encoded as a mode in one or more CSRs", + "line_number": 85, + "reason": "This describes a fixed requirement that applies to all implementations - every hart must be running at some privilege level. This is not an implementation choice." + }, + { + "excerpt": "Three RISC-V privilege levels are currently defined", + "line_number": 88, + "reason": "This states a fixed fact about the specification - there are exactly three defined privilege levels. This is not an implementation parameter." + }, + { + "excerpt": "All hardware implementations must provide M-mode", + "line_number": 145, + "reason": "This is a fixed requirement ('must provide') that applies to all implementations. M-mode is mandatory, not optional." + }, + { + "excerpt": "attempts to perform operations not permitted by the current privilege mode will cause an exception to be raised", + "line_number": 100, + "reason": "This describes required behavior that all implementations must follow when privilege violations occur. It is not an implementation choice." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"Implementations might provide anywhere from 1 to 3 privilege modes\",\n \"line_number\": 135,\n \"parameter_name\": \"NUM_PRIVILEGE_MODES\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"range\",\n \"confidence\": \"high\",\n \"reasoning\": \"The number of privilege modes (1, 2, or 3) is a direct implementation choice that determines the protection model. This is not controlled by any CSR field.\"\n },\n {\n \"excerpt\": \"Implementations may also include a debug mode to support off-chip debugging and/or manufacturing test.\",\n \"line_number\": 179,\n \"parameter_name\": \"DEBUG_MODE_IMPLEMENTED\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"Whether debug mode is implemented is an optional implementation choice. The use of 'may' indicates this is not mandatory for all implementations.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"Commentary on our design decisions is formatted as in this paragraph, and can be skipped if the reader is only interested in the specification itself.\",\n \"line_number\": 11,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks.\"\n },\n {\n \"excerpt\": \"At any time, a RISC-V hardware thread (_hart_) is running at some privilege level encoded as a mode in one or more CSRs\",\n \"line_number\": 85,\n \"reason\": \"This describes a fixed requirement that applies to all implementations - every hart must be running at some privilege level. This is not an implementation choice.\"\n },\n {\n \"excerpt\": \"Three RISC-V privilege levels are currently defined\",\n \"line_number\": 88,\n \"reason\": \"This states a fixed fact about the specification - there are exactly three defined privilege levels. This is not an implementation parameter.\"\n },\n {\n \"excerpt\": \"All hardware implementations must provide M-mode\",\n \"line_number\": 145,\n \"reason\": \"This is a fixed requirement ('must provide') that applies to all implementations. M-mode is mandatory, not optional.\"\n },\n {\n \"excerpt\": \"attempts to perform operations not permitted by the current privilege mode will cause an exception to be raised\",\n \"line_number\": 100,\n \"reason\": \"This describes required behavior that all implementations must follow when privilege violations occur. It is not an implementation choice.\"\n }\n ]\n}\n```", + "input_tokens": 7802, + "output_tokens": 668, + "latency_ms": 25216, + "timestamp": "2026-04-15T14:34:58.897142+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_033", + "source_file": "q-st-ext.adoc", + "start_line": 1, + "end_line": 120, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "The floating-point registers are now extended to hold either a single, double, or quad-precision floating-point value (FLEN=128).", + "line_number": 7, + "parameter_name": "FLEN", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "FLEN=128 is a direct architectural parameter that defines the width of floating-point registers when the Q extension is implemented. This is a design-time choice that affects register width." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "FLQ and FSQ are only guaranteed to execute atomically if the effective address is naturally aligned and XLEN=128.", + "line_number": 23, + "reason": "This describes a conditional guarantee about atomic execution based on alignment and XLEN value, not an implementation choice. The atomicity behavior is deterministic given the conditions." + }, + { + "excerpt": "FLQ and FSQ do not modify the bits being transferred; in particular, the payloads of non-canonical NaNs are preserved.", + "line_number": 26, + "reason": "This is a fixed requirement that all implementations must satisfy - bits must not be modified during transfer. There is no implementation choice here." + }, + { + "excerpt": "FCVT.L[U].Q and FCVT.Q.L[U] are RV64-only instructions.", + "line_number": 58, + "reason": "This states a fixed requirement about which instructions are available in RV64 vs RV32. It's not an implementation choice but a specification rule." + }, + { + "excerpt": "FMV.X.Q and FMV.Q.X instructions are not provided in RV32 or RV64, so quad-precision bit patterns must be moved to the integer registers via memory.", + "line_number": 82, + "reason": "This states that certain instructions are not provided in any base ISA width, which is a fixed specification rule, not an implementation parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"The floating-point registers are now extended to hold either a single, double, or quad-precision floating-point value (FLEN=128).\",\n \"line_number\": 7,\n \"parameter_name\": \"FLEN\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"FLEN=128 is a direct architectural parameter that defines the width of floating-point registers when the Q extension is implemented. This is a design-time choice that affects register width.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"FLQ and FSQ are only guaranteed to execute atomically if the effective address is naturally aligned and XLEN=128.\",\n \"line_number\": 23,\n \"reason\": \"This describes a conditional guarantee about atomic execution based on alignment and XLEN value, not an implementation choice. The atomicity behavior is deterministic given the conditions.\"\n },\n {\n \"excerpt\": \"FLQ and FSQ do not modify the bits being transferred; in particular, the payloads of non-canonical NaNs are preserved.\",\n \"line_number\": 26,\n \"reason\": \"This is a fixed requirement that all implementations must satisfy - bits must not be modified during transfer. There is no implementation choice here.\"\n },\n {\n \"excerpt\": \"FCVT.L[U].Q and FCVT.Q.L[U] are RV64-only instructions.\",\n \"line_number\": 58,\n \"reason\": \"This states a fixed requirement about which instructions are available in RV64 vs RV32. It's not an implementation choice but a specification rule.\"\n },\n {\n \"excerpt\": \"FMV.X.Q and FMV.Q.X instructions are not provided in RV32 or RV64, so quad-precision bit patterns must be moved to the integer registers via memory.\",\n \"line_number\": 82,\n \"reason\": \"This states that certain instructions are not provided in any base ISA width, which is a fixed specification rule, not an implementation parameter.\"\n }\n ]\n}\n```", + "input_tokens": 7196, + "output_tokens": 549, + "latency_ms": 48766, + "timestamp": "2026-04-15T14:35:50.697927+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_037", + "source_file": "rnmi.adoc", + "start_line": 1, + "end_line": 166, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "The RNMI interrupt trap handler address is implementation-defined.", + "line_number": 23, + "parameter_name": "RNMI_INTERRUPT_HANDLER_ADDRESS", + "existing_udb_name": null, + "class": "NON_ISA", + "value_type": "value", + "confidence": "high", + "reasoning": "This is a platform-level address choice outside the ISA scope, similar to reset vector or NMI addresses in the NON_ISA class." + }, + { + "excerpt": "RNMI also has an associated exception trap handler address, which is implementation defined.", + "line_number": 25, + "parameter_name": "RNMI_EXCEPTION_HANDLER_ADDRESS", + "existing_udb_name": null, + "class": "NON_ISA", + "value_type": "value", + "confidence": "high", + "reasoning": "This is another platform-level address choice outside the ISA scope, similar to the interrupt handler address." + }, + { + "excerpt": "`mnepc` is a *WARL* register that must be able to hold all valid virtual addresses. It need not be capable of holding all possible invalid addresses. Prior to writing `mnepc`, implementations may convert an invalid address into some other invalid address that `mnepc` is capable of holding.", + "line_number": 58, + "parameter_name": "MNEPC_WARL_VALUES", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "This defines the WARL behavior of mnepc - the set of legal values it can hold varies by implementation. The parameter is which invalid addresses can be held." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "For example, some implementations might use the address specified in `mtvec` as the RNMI exception trap handler.", + "line_number": 27, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. It's an example suggestion, not an architectural requirement." + }, + { + "excerpt": "RNMIs are masked out of reset to give software the opportunity to initialize data structures and devices for subsequent RNMI handling.", + "line_number": 95, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. It explains rationale but doesn't define a parameter." + }, + { + "excerpt": "Upon reset, NMIE contains the value 0.", + "line_number": 93, + "reason": "This is a fixed requirement that applies to all implementations - the reset value is always 0, not implementation-defined." + }, + { + "excerpt": "When an RNMI interrupt is detected, the interrupted PC is written to the `mnepc` CSR", + "line_number": 135, + "reason": "This describes the required behavior when an RNMI occurs. It's a fixed specification requirement, not an implementation choice." + }, + { + "excerpt": "Software can set NMIE to 1, but attempts to clear NMIE have no effect.", + "line_number": 97, + "reason": "This describes the required behavior of the NMIE bit - it's a fixed specification requirement that applies to all implementations, not a parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"The RNMI interrupt trap handler address is implementation-defined.\",\n \"line_number\": 23,\n \"parameter_name\": \"RNMI_INTERRUPT_HANDLER_ADDRESS\",\n \"existing_udb_name\": null,\n \"class\": \"NON_ISA\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"This is a platform-level address choice outside the ISA scope, similar to reset vector or NMI addresses in the NON_ISA class.\"\n },\n {\n \"excerpt\": \"RNMI also has an associated exception trap handler address, which is implementation defined.\",\n \"line_number\": 25,\n \"parameter_name\": \"RNMI_EXCEPTION_HANDLER_ADDRESS\", \n \"existing_udb_name\": null,\n \"class\": \"NON_ISA\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"This is another platform-level address choice outside the ISA scope, similar to the interrupt handler address.\"\n },\n {\n \"excerpt\": \"`mnepc` is a *WARL* register that must be able to hold all valid virtual addresses. It need not be capable of holding all possible invalid addresses. Prior to writing `mnepc`, implementations may convert an invalid address into some other invalid address that `mnepc` is capable of holding.\",\n \"line_number\": 58,\n \"parameter_name\": \"MNEPC_WARL_VALUES\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"This defines the WARL behavior of mnepc - the set of legal values it can hold varies by implementation. The parameter is which invalid addresses can be held.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"For example, some implementations might use the address specified in `mtvec` as the RNMI exception trap handler.\",\n \"line_number\": 27,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. It's an example suggestion, not an architectural requirement.\"\n },\n {\n \"excerpt\": \"RNMIs are masked out of reset to give software the opportunity to initialize data structures and devices for subsequent RNMI handling.\",\n \"line_number\": 95,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. It explains rationale but doesn't define a parameter.\"\n },\n {\n \"excerpt\": \"Upon reset, NMIE contains the value 0.\",\n \"line_number\": 93,\n \"reason\": \"This is a fixed requirement that applies to all implementations - the reset value is always 0, not implementation-defined.\"\n },\n {\n \"excerpt\": \"When an RNMI interrupt is detected, the interrupted PC is written to the `mnepc` CSR\",\n \"line_number\": 135,\n \"reason\": \"This describes the required behavior when an RNMI occurs. It's a fixed specification requirement, not an implementation choice.\"\n },\n {\n \"excerpt\": \"Software can set NMIE to 1, but attempts to clear NMIE have no effect.\",\n \"line_number\": 97,\n \"reason\": \"This describes the required behavior of the NMIE bit - it's a fixed specification requirement that applies to all implementations, not a parameter.\"\n }\n ]\n}\n```", + "input_tokens": 7656, + "output_tokens": 880, + "latency_ms": 14351, + "timestamp": "2026-04-15T14:37:33.299230+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_039", + "source_file": "rv32.adoc", + "start_line": 1, + "end_line": 1105, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "The EEI will define whether the memory system is little-endian or big-endian.", + "line_number": 651, + "parameter_name": "ENDIANNESS_LITTLE_OR_BIG", + "existing_udb_name": "ENDIANNESS_LITTLE_OR_BIG", + "class": "NON_ISA", + "value_type": "binary", + "confidence": "high", + "reasoning": "This is a platform-level choice about memory system endianness, which is outside the ISA scope and defined by the execution environment interface (EEI)." + }, + { + "excerpt": "Loads and stores whose effective address is not naturally aligned to the referenced datatype (i.e., the effective address is not divisible by the size of the access in bytes) have behavior dependent on the EEI.", + "line_number": 672, + "parameter_name": "MISALIGNED_LDST_EEI_DEPENDENT_BEHAVIOR", + "existing_udb_name": "MISALIGNED_LDST_EEI_DEPENDENT_BEHAVIOR", + "class": "NON_ISA", + "value_type": "enum", + "confidence": "high", + "reasoning": "The behavior of misaligned loads and stores is explicitly defined as EEI-dependent, making it a platform-level choice outside the ISA scope." + }, + { + "excerpt": "misaligned loads and stores can be handled in hardware", + "line_number": 678, + "parameter_name": "MISALIGNED_LDST_FULLY_HW_SUPPORTED", + "existing_udb_name": "MISALIGNED_LDST_FULLY_HW_SUPPORTED", + "class": "NON_ISA", + "value_type": "binary", + "confidence": "medium", + "reasoning": "This describes one possible EEI choice for handling misaligned accesses - whether they are supported in hardware or not." + }, + { + "excerpt": "via an invisible trap into the execution environment implementation", + "line_number": 679, + "parameter_name": "MISALIGNED_LDST_INVISIBLE_TRAP", + "existing_udb_name": "MISALIGNED_LDST_INVISIBLE_TRAP", + "class": "NON_ISA", + "value_type": "binary", + "confidence": "medium", + "reasoning": "This describes another EEI choice for handling misaligned accesses through invisible traps." + }, + { + "excerpt": "combination of hardware and invisible trap depending on address", + "line_number": 680, + "parameter_name": "MISALIGNED_LDST_HW_OR_INVISIBLE_TRAP_FUNC_OF_ADDR", + "existing_udb_name": "MISALIGNED_LDST_HW_OR_INVISIBLE_TRAP_FUNC_OF_ADDR", + "class": "NON_ISA", + "value_type": "binary", + "confidence": "medium", + "reasoning": "This describes a third EEI choice where misaligned access handling varies by address." + }, + { + "excerpt": "loads and stores that are not naturally aligned may either complete execution successfully or raise an exception", + "line_number": 683, + "parameter_name": "MISALIGNED_LDST_FULLY_HW_SUPPORTED_OR_VISIBLE_TRAP", + "existing_udb_name": "MISALIGNED_LDST_FULLY_HW_SUPPORTED_OR_VISIBLE_TRAP", + "class": "NON_ISA", + "value_type": "binary", + "confidence": "medium", + "reasoning": "This describes the EEI choice of whether misaligned accesses complete or trap when not guaranteed to be handled invisibly." + }, + { + "excerpt": "When an EEI does not guarantee misaligned loads and stores are handled invisibly, the EEI must define if exceptions caused by address misalignment result in a contained trap (allowing software running inside the execution environment to handle the trap) or a fatal trap (terminating execution).", + "line_number": 691, + "parameter_name": "MISALIGNED_LDST_CONTAINED_OR_FATAL_TRAP", + "existing_udb_name": "MISALIGNED_LDST_CONTAINED_OR_FATAL_TRAP", + "class": "NON_ISA", + "value_type": "binary", + "confidence": "high", + "reasoning": "This is an EEI-defined choice about whether misalignment exceptions are contained or fatal, which is a platform-level decision." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "For RV32I, the 32 `x` registers are each 32 bits wide, i.e., `XLEN=32`.", + "line_number": 39, + "reason": "This is a fixed requirement for RV32I - XLEN is always 32 for this ISA variant, not an implementation choice." + }, + { + "excerpt": "Register `x0` is hardwired with all bits equal to 0.", + "line_number": 40, + "reason": "This is a fixed architectural requirement that all implementations must satisfy - x0 must always be zero." + }, + { + "excerpt": "An instruction-address-misaligned exception is generated on a taken branch or unconditional jump if the target address is not `IALIGN-bit` aligned.", + "line_number": 149, + "reason": "This describes required behavior when a condition is met, not an implementation choice. The behavior is deterministic." + }, + { + "excerpt": "ADDI adds the sign-extended 12-bit immediate to register _rs1_.", + "line_number": 264, + "reason": "This describes the fixed operation of the ADDI instruction, which is the same across all implementations." + }, + { + "excerpt": "HINTs do not change any architecturally visible state, except for advancing the `pc` and any applicable performance counters.", + "line_number": 1026, + "reason": "This describes the required behavior of HINT instructions - they must not change architectural state. This is a fixed requirement, not a parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"The EEI will define whether the memory system is little-endian or big-endian.\",\n \"line_number\": 651,\n \"parameter_name\": \"ENDIANNESS_LITTLE_OR_BIG\",\n \"existing_udb_name\": \"ENDIANNESS_LITTLE_OR_BIG\",\n \"class\": \"NON_ISA\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"This is a platform-level choice about memory system endianness, which is outside the ISA scope and defined by the execution environment interface (EEI).\"\n },\n {\n \"excerpt\": \"Loads and stores whose effective address is not naturally aligned to the referenced datatype (i.e., the effective address is not divisible by the size of the access in bytes) have behavior dependent on the EEI.\",\n \"line_number\": 672,\n \"parameter_name\": \"MISALIGNED_LDST_EEI_DEPENDENT_BEHAVIOR\",\n \"existing_udb_name\": \"MISALIGNED_LDST_EEI_DEPENDENT_BEHAVIOR\",\n \"class\": \"NON_ISA\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"The behavior of misaligned loads and stores is explicitly defined as EEI-dependent, making it a platform-level choice outside the ISA scope.\"\n },\n {\n \"excerpt\": \"misaligned loads and stores can be handled in hardware\",\n \"line_number\": 678,\n \"parameter_name\": \"MISALIGNED_LDST_FULLY_HW_SUPPORTED\",\n \"existing_udb_name\": \"MISALIGNED_LDST_FULLY_HW_SUPPORTED\",\n \"class\": \"NON_ISA\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"This describes one possible EEI choice for handling misaligned accesses - whether they are supported in hardware or not.\"\n },\n {\n \"excerpt\": \"via an invisible trap into the execution environment implementation\",\n \"line_number\": 679,\n \"parameter_name\": \"MISALIGNED_LDST_INVISIBLE_TRAP\",\n \"existing_udb_name\": \"MISALIGNED_LDST_INVISIBLE_TRAP\",\n \"class\": \"NON_ISA\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"This describes another EEI choice for handling misaligned accesses through invisible traps.\"\n },\n {\n \"excerpt\": \"combination of hardware and invisible trap depending on address\",\n \"line_number\": 680,\n \"parameter_name\": \"MISALIGNED_LDST_HW_OR_INVISIBLE_TRAP_FUNC_OF_ADDR\",\n \"existing_udb_name\": \"MISALIGNED_LDST_HW_OR_INVISIBLE_TRAP_FUNC_OF_ADDR\",\n \"class\": \"NON_ISA\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"This describes a third EEI choice where misaligned access handling varies by address.\"\n },\n {\n \"excerpt\": \"loads and stores that are not naturally aligned may either complete execution successfully or raise an exception\",\n \"line_number\": 683,\n \"parameter_name\": \"MISALIGNED_LDST_FULLY_HW_SUPPORTED_OR_VISIBLE_TRAP\",\n \"existing_udb_name\": \"MISALIGNED_LDST_FULLY_HW_SUPPORTED_OR_VISIBLE_TRAP\",\n \"class\": \"NON_ISA\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"This describes the EEI choice of whether misaligned accesses complete or trap when not guaranteed to be handled invisibly.\"\n },\n {\n \"excerpt\": \"When an EEI does not guarantee misaligned loads and stores are handled invisibly, the EEI must define if exceptions caused by address misalignment result in a contained trap (allowing software running inside the execution environment to handle the trap) or a fatal trap (terminating execution).\",\n \"line_number\": 691,\n \"parameter_name\": \"MISALIGNED_LDST_CONTAINED_OR_FATAL_TRAP\",\n \"existing_udb_name\": \"MISALIGNED_LDST_CONTAINED_OR_FATAL_TRAP\",\n \"class\": \"NON_ISA\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"This is an EEI-defined choice about whether misalignment exceptions are contained or fatal, which is a platform-level decision.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"For RV32I, the 32 `x` registers are each 32 bits wide, i.e., `XLEN=32`.\",\n \"line_number\": 39,\n \"reason\": \"This is a fixed requirement for RV32I - XLEN is always 32 for this ISA variant, not an implementation choice.\"\n },\n {\n \"excerpt\": \"Register `x0` is hardwired with all bits equal to 0.\",\n \"line_number\": 40,\n \"reason\": \"This is a fixed architectural requirement that all implementations must satisfy - x0 must always be zero.\"\n },\n {\n \"excerpt\": \"An instruction-address-misaligned exception is generated on a taken branch or unconditional jump if the target address is not `IALIGN-bit` aligned.\",\n \"line_number\": 149,\n \"reason\": \"This describes required behavior when a condition is met, not an implementation choice. The behavior is deterministic.\"\n },\n {\n \"excerpt\": \"ADDI adds the sign-extended 12-bit immediate to register _rs1_.\",\n \"line_number\": 264,\n \"reason\": \"This describes the fixed operation of the ADDI instruction, which is the same across all implementations.\"\n },\n {\n \"excerpt\": \"HINTs do not change any architecturally visible state, except for advancing the `pc` and any applicable performance counters.\",\n \"line_number\": 1026,\n \"reason\": \"This describes the required behavior of HINT instructions - they must not change architectural state. This is a fixed requirement, not a parameter.\"\n }\n ]\n}\n```", + "input_tokens": 19338, + "output_tokens": 1604, + "latency_ms": 28120, + "timestamp": "2026-04-15T15:07:37.927340+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_040", + "source_file": "rv32e.adoc", + "start_line": 1, + "end_line": 47, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [], + "skipped_non_parameters": [ + { + "excerpt": "RV32E and RV64E reduce the integer register count to 16 general-purpose registers, (`x0-x15`), where `x0` is a dedicated zero register.", + "line_number": 21, + "reason": "This is a fixed requirement of the RV32E/RV64E specification, not an implementation choice. All RV32E/RV64E implementations must have exactly 16 registers." + }, + { + "excerpt": "RV32E and RV64E use the same instruction-set encoding as RV32I and RV64I respectively, except that only registers `x0-x15` are provided.", + "line_number": 33, + "reason": "This describes the fixed encoding rules for RV32E/RV64E, not an implementation parameter. The encoding is mandated by the specification." + }, + { + "excerpt": "All encodings specifying the other registers `x16-x31` are reserved.", + "line_number": 35, + "reason": "This is a fixed requirement that all implementations must follow - reserved encodings are not implementation-defined choices." + }, + { + "excerpt": "We have found that in the small RV32I core implementations, the upper 16 registers consume around one quarter of the total area of the core excluding memories, thus their removal saves around 25% core area with a corresponding core power reduction.", + "line_number": 25, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. It provides background information but does not define any architectural parameters." + }, + { + "excerpt": "The previous draft of this chapter made all encodings using the `x16-x31` registers available as custom. This version takes a more conservative approach, making these reserved so that they can be allocated between custom space or new standard encodings at a later date.", + "line_number": 38, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. It explains the rationale for the current approach but does not define implementation choices." + } + ], + "raw_response": "```json\n{\n \"parameters\": [],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"RV32E and RV64E reduce the integer register count to 16 general-purpose registers, (`x0-x15`), where `x0` is a dedicated zero register.\",\n \"line_number\": 21,\n \"reason\": \"This is a fixed requirement of the RV32E/RV64E specification, not an implementation choice. All RV32E/RV64E implementations must have exactly 16 registers.\"\n },\n {\n \"excerpt\": \"RV32E and RV64E use the same instruction-set encoding as RV32I and RV64I respectively, except that only registers `x0-x15` are provided.\",\n \"line_number\": 33,\n \"reason\": \"This describes the fixed encoding rules for RV32E/RV64E, not an implementation parameter. The encoding is mandated by the specification.\"\n },\n {\n \"excerpt\": \"All encodings specifying the other registers `x16-x31` are reserved.\",\n \"line_number\": 35,\n \"reason\": \"This is a fixed requirement that all implementations must follow - reserved encodings are not implementation-defined choices.\"\n },\n {\n \"excerpt\": \"We have found that in the small RV32I core implementations, the upper 16 registers consume around one quarter of the total area of the core excluding memories, thus their removal saves around 25% core area with a corresponding core power reduction.\",\n \"line_number\": 25,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. It provides background information but does not define any architectural parameters.\"\n },\n {\n \"excerpt\": \"The previous draft of this chapter made all encodings using the `x16-x31` registers available as custom. This version takes a more conservative approach, making these reserved so that they can be allocated between custom space or new standard encodings at a later date.\",\n \"line_number\": 38,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. It explains the rationale for the current approach but does not define implementation choices.\"\n }\n ]\n}\n```", + "input_tokens": 6125, + "output_tokens": 534, + "latency_ms": 16633, + "timestamp": "2026-04-15T14:38:15.761897+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_041", + "source_file": "rv64.adoc", + "start_line": 1, + "end_line": 260, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "RV64I widens the integer registers and supported user address space to 64 bits (XLEN=64 in <>).", + "line_number": 10, + "parameter_name": "XLEN", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "XLEN is a fundamental architectural parameter that defines the width of integer registers. In RV64I, it is fixed at 64 bits, but this represents an implementation choice between different ISA variants (RV32I vs RV64I)." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "These \"*W\" instructions ignore the upper 32 bits of their inputs and always produce 32-bit signed values, sign-extending them to 64 bits, i.e. bits XLEN-1 through 31 are equal.", + "line_number": 16, + "reason": "This describes the fixed behavior of W-suffix instructions in RV64I. It is a normative requirement that applies to all RV64I implementations, not an implementation choice." + }, + { + "excerpt": "ADDIW is an RV64I instruction that adds the sign-extended 12-bit immediate to register _rs1_ and produces the proper sign extension of a 32-bit result in _rd_.", + "line_number": 42, + "reason": "This describes the fixed operation of the ADDIW instruction. The behavior is defined by the ISA specification, not left to implementation choice." + }, + { + "excerpt": "SLLIW, SRLIW, and SRAIW encodings with _imm[5] {ne} 0_ are reserved.", + "line_number": 66, + "reason": "This states that certain encodings are reserved, which is a fixed specification requirement. Reserved encodings are not implementation-defined parameters." + }, + { + "excerpt": "The execution environment will define what portions of the address space are legal to access.", + "line_number": 130, + "reason": "This refers to execution environment choices, which are platform-level decisions outside the ISA scope. The ISA itself does not define which address ranges are legal." + }, + { + "excerpt": "91% of the HINT space is reserved for standard HINTs. The remainder of the HINT space is designated for custom HINTs; no standard HINTs will ever be defined in this subspace.", + "line_number": 150, + "reason": "This describes the allocation of HINT encoding space, which is a fixed specification decision. The percentages and designations are not implementation choices but specification design decisions." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"RV64I widens the integer registers and supported user address space to 64 bits (XLEN=64 in <>).\",\n \"line_number\": 10,\n \"parameter_name\": \"XLEN\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"XLEN is a fundamental architectural parameter that defines the width of integer registers. In RV64I, it is fixed at 64 bits, but this represents an implementation choice between different ISA variants (RV32I vs RV64I).\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"These \\\"*W\\\" instructions ignore the upper 32 bits of their inputs and always produce 32-bit signed values, sign-extending them to 64 bits, i.e. bits XLEN-1 through 31 are equal.\",\n \"line_number\": 16,\n \"reason\": \"This describes the fixed behavior of W-suffix instructions in RV64I. It is a normative requirement that applies to all RV64I implementations, not an implementation choice.\"\n },\n {\n \"excerpt\": \"ADDIW is an RV64I instruction that adds the sign-extended 12-bit immediate to register _rs1_ and produces the proper sign extension of a 32-bit result in _rd_.\",\n \"line_number\": 42,\n \"reason\": \"This describes the fixed operation of the ADDIW instruction. The behavior is defined by the ISA specification, not left to implementation choice.\"\n },\n {\n \"excerpt\": \"SLLIW, SRLIW, and SRAIW encodings with _imm[5] {ne} 0_ are reserved.\",\n \"line_number\": 66,\n \"reason\": \"This states that certain encodings are reserved, which is a fixed specification requirement. Reserved encodings are not implementation-defined parameters.\"\n },\n {\n \"excerpt\": \"The execution environment will define what portions of the address space are legal to access.\",\n \"line_number\": 130,\n \"reason\": \"This refers to execution environment choices, which are platform-level decisions outside the ISA scope. The ISA itself does not define which address ranges are legal.\"\n },\n {\n \"excerpt\": \"91% of the HINT space is reserved for standard HINTs. The remainder of the HINT space is designated for custom HINTs; no standard HINTs will ever be defined in this subspace.\",\n \"line_number\": 150,\n \"reason\": \"This describes the allocation of HINT encoding space, which is a fixed specification decision. The percentages and designations are not implementation choices but specification design decisions.\"\n }\n ]\n}\n```", + "input_tokens": 9275, + "output_tokens": 692, + "latency_ms": 12580, + "timestamp": "2026-04-15T14:38:31.362837+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_042", + "source_file": "rvwmo.adoc", + "start_line": 1, + "end_line": 817, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "A misaligned load or store instruction may be decomposed into a set of component memory operations of any granularity.", + "line_number": 95, + "parameter_name": "MISALIGNED_DECOMPOSITION_GRANULARITY", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "medium", + "reasoning": "The granularity of decomposition for misaligned memory operations is implementation-defined. The spec says 'any granularity', leaving the specific choice to the implementer." + }, + { + "excerpt": "A floating-point load or store of more than XLEN bits may also be decomposed into a set of component memory operations of any granularity.", + "line_number": 96, + "parameter_name": "FP_WIDE_DECOMPOSITION_GRANULARITY", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "medium", + "reasoning": "Similar to misaligned operations, the granularity for decomposing wide floating-point operations is implementation-defined ('any granularity')." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "This chapter defines the memory model for regular main memory operations. The interaction of the memory model with I/O memory, instruction fetches, FENCE.I, page-table walks, and SFENCE.VMA is not (yet) formalized.", + "line_number": 29, + "reason": "This text is inside a [NOTE] block, which is non-normative. Parameters should not be extracted from NOTE blocks." + }, + { + "excerpt": "Each aligned memory instruction that accesses XLEN or fewer bits gives rise to exactly one memory operation, unless specified otherwise.", + "line_number": 68, + "reason": "This is a fixed requirement that applies to all implementations - it defines what 'must' happen, not an implementation choice." + }, + { + "excerpt": "All memory operations are single-copy atomic: they can never be observed in a partially complete state.", + "line_number": 66, + "reason": "This is a fixed architectural requirement ('can never be observed') that all implementations must satisfy, not a parameter." + }, + { + "excerpt": "The global memory order is defined over the primitive load and store operations generated by memory instructions.", + "line_number": 52, + "reason": "This is a definitional statement about how the memory model works, not an implementation choice or parameter." + }, + { + "excerpt": "An execution of a RISC-V program obeys the RVWMO memory consistency model only if there exists a global memory order conforming to preserved program order", + "line_number": 295, + "reason": "This describes a requirement that all implementations must satisfy ('only if'), not an implementation-defined parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"A misaligned load or store instruction may be decomposed into a set of component memory operations of any granularity.\",\n \"line_number\": 95,\n \"parameter_name\": \"MISALIGNED_DECOMPOSITION_GRANULARITY\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The granularity of decomposition for misaligned memory operations is implementation-defined. The spec says 'any granularity', leaving the specific choice to the implementer.\"\n },\n {\n \"excerpt\": \"A floating-point load or store of more than XLEN bits may also be decomposed into a set of component memory operations of any granularity.\",\n \"line_number\": 96,\n \"parameter_name\": \"FP_WIDE_DECOMPOSITION_GRANULARITY\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"medium\",\n \"reasoning\": \"Similar to misaligned operations, the granularity for decomposing wide floating-point operations is implementation-defined ('any granularity').\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"This chapter defines the memory model for regular main memory operations. The interaction of the memory model with I/O memory, instruction fetches, FENCE.I, page-table walks, and SFENCE.VMA is not (yet) formalized.\",\n \"line_number\": 29,\n \"reason\": \"This text is inside a [NOTE] block, which is non-normative. Parameters should not be extracted from NOTE blocks.\"\n },\n {\n \"excerpt\": \"Each aligned memory instruction that accesses XLEN or fewer bits gives rise to exactly one memory operation, unless specified otherwise.\",\n \"line_number\": 68,\n \"reason\": \"This is a fixed requirement that applies to all implementations - it defines what 'must' happen, not an implementation choice.\"\n },\n {\n \"excerpt\": \"All memory operations are single-copy atomic: they can never be observed in a partially complete state.\",\n \"line_number\": 66,\n \"reason\": \"This is a fixed architectural requirement ('can never be observed') that all implementations must satisfy, not a parameter.\"\n },\n {\n \"excerpt\": \"The global memory order is defined over the primitive load and store operations generated by memory instructions.\",\n \"line_number\": 52,\n \"reason\": \"This is a definitional statement about how the memory model works, not an implementation choice or parameter.\"\n },\n {\n \"excerpt\": \"An execution of a RISC-V program obeys the RVWMO memory consistency model only if there exists a global memory order conforming to preserved program order\",\n \"line_number\": 295,\n \"reason\": \"This describes a requirement that all implementations must satisfy ('only if'), not an implementation-defined parameter.\"\n }\n ]\n}\n```", + "input_tokens": 14911, + "output_tokens": 749, + "latency_ms": 17038, + "timestamp": "2026-04-15T14:59:32.111622+00:00", + "error": null, + "retry_count": 1 + }, + { + "chunk_id": "chunk_043", + "source_file": "scalar-crypto.adoc", + "start_line": 1, + "end_line": 3448, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [], + "skipped_non_parameters": [ + { + "excerpt": "Detection of individual cryptography extensions uses the unified software-based RISC-V discovery method.", + "line_number": 179, + "reason": "This describes a software detection mechanism, not an architectural parameter that implementers choose." + }, + { + "excerpt": "This instruction must _always_ be implemented such that its execution latency does not depend on the data being operated on.", + "line_number": 1000, + "reason": "This is a fixed requirement ('must always') that applies to all implementations, not an implementation choice." + }, + { + "excerpt": "For RV32, the encodings corresponding to shamt[5]=1 are reserved.", + "line_number": 2800, + "reason": "This describes reserved encodings, which are fixed constraints rather than implementation parameters." + }, + { + "excerpt": "A core which implements `Zkn` must implement all of the above extensions.", + "line_number": 400, + "reason": "This is a fixed requirement for extension compliance, not an implementation choice." + }, + { + "excerpt": "Note that `rnum` must be in the range `0x0..0xA`. The values `0xB..0xF` are reserved.", + "line_number": 1500, + "reason": "This describes fixed constraints on instruction operands, not implementation parameters." + } + ], + "raw_response": "```json\n{\n \"parameters\": [],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"Detection of individual cryptography extensions uses the unified software-based RISC-V discovery method.\",\n \"line_number\": 179,\n \"reason\": \"This describes a software detection mechanism, not an architectural parameter that implementers choose.\"\n },\n {\n \"excerpt\": \"This instruction must _always_ be implemented such that its execution latency does not depend on the data being operated on.\",\n \"line_number\": 1000,\n \"reason\": \"This is a fixed requirement ('must always') that applies to all implementations, not an implementation choice.\"\n },\n {\n \"excerpt\": \"For RV32, the encodings corresponding to shamt[5]=1 are reserved.\",\n \"line_number\": 2800,\n \"reason\": \"This describes reserved encodings, which are fixed constraints rather than implementation parameters.\"\n },\n {\n \"excerpt\": \"A core which implements `Zkn` must implement all of the above extensions.\",\n \"line_number\": 400,\n \"reason\": \"This is a fixed requirement for extension compliance, not an implementation choice.\"\n },\n {\n \"excerpt\": \"Note that `rnum` must be in the range `0x0..0xA`. The values `0xB..0xF` are reserved.\",\n \"line_number\": 1500,\n \"reason\": \"This describes fixed constraints on instruction operands, not implementation parameters.\"\n }\n ]\n}\n```", + "input_tokens": 35038, + "output_tokens": 367, + "latency_ms": 9507, + "timestamp": "2026-04-15T14:39:54.247258+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_044", + "source_file": "scalar-crypto.adoc", + "start_line": 3419, + "end_line": 5590, + "content_start_line": 3449, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "The `seed` CSR is also access controlled by execution mode, and attempted read or write access will raise an illegal-instruction exception outside M mode unless access is explicitly granted.", + "line_number": 3549, + "parameter_name": "SEED_CSR_ACCESS_CONTROL", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether to grant access to the seed CSR from lower privilege modes or restrict it to M-mode only. This is a direct implementation choice about access control policy." + }, + { + "excerpt": "Implementations may implement `mseccfg` such that `[s,u]seed` is a read-only constant value `0`.", + "line_number": 3916, + "parameter_name": "MSECCFG_SEED_FIELDS_IMPLEMENTED", + "existing_udb_name": null, + "class": "NORM_CSR_RW", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether the mseccfg.[s,u]seed fields are read-only zero (not implemented) or read-write (implemented). This controls the mutability of these CSR fields." + }, + { + "excerpt": "An implementation of the entropy source should meet at least one of the following requirements sets in order to be considered a secure and safe design", + "line_number": 3635, + "parameter_name": "ENTROPY_SOURCE_STANDARD", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "medium", + "reasoning": "The implementation chooses which entropy source standard to follow (NIST SP 800-90B, AIS-31 PTG.2, or virtual source). This is a design-time choice that affects the entropy source behavior and requirements." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "This instruction is useful for implementing the SHA3 cryptographic hash function on a 32-bit architecture, as it implements the bit-interleaving operation used to speed up the 64-bit rotations directly.", + "line_number": 3475, + "reason": "This is inside a [NOTE] block, which is non-normative informational content, not an architectural requirement." + }, + { + "excerpt": "The 32-bit contents of `seed` are as follows:", + "line_number": 3497, + "reason": "This describes the fixed format of the seed CSR, which is a specification requirement that all implementations must follow, not a parameter." + }, + { + "excerpt": "Software normally uses the instruction `csrrw rd, seed, x0` to read the `seed` CSR.", + "line_number": 3527, + "reason": "This describes software usage patterns, not an implementation-defined architectural parameter." + }, + { + "excerpt": "Each returned `seed[15:0]` = `entropy` value represents unique randomness when `OPST`=`ES16`", + "line_number": 3565, + "reason": "This describes the required behavior when the CSR is in ES16 state, which is a fixed specification requirement, not an implementation choice." + }, + { + "excerpt": "When `OPST` is not `ES16`, `entropy` must be set to 0.", + "line_number": 3571, + "reason": "This is a fixed requirement ('must be set to 0') that all implementations must follow, not a parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"The `seed` CSR is also access controlled by execution mode, and attempted read or write access will raise an illegal-instruction exception outside M mode unless access is explicitly granted.\",\n \"line_number\": 3549,\n \"parameter_name\": \"SEED_CSR_ACCESS_CONTROL\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether to grant access to the seed CSR from lower privilege modes or restrict it to M-mode only. This is a direct implementation choice about access control policy.\"\n },\n {\n \"excerpt\": \"Implementations may implement `mseccfg` such that `[s,u]seed` is a read-only constant value `0`.\",\n \"line_number\": 3916,\n \"parameter_name\": \"MSECCFG_SEED_FIELDS_IMPLEMENTED\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether the mseccfg.[s,u]seed fields are read-only zero (not implemented) or read-write (implemented). This controls the mutability of these CSR fields.\"\n },\n {\n \"excerpt\": \"An implementation of the entropy source should meet at least one of the following requirements sets in order to be considered a secure and safe design\",\n \"line_number\": 3635,\n \"parameter_name\": \"ENTROPY_SOURCE_STANDARD\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The implementation chooses which entropy source standard to follow (NIST SP 800-90B, AIS-31 PTG.2, or virtual source). This is a design-time choice that affects the entropy source behavior and requirements.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"This instruction is useful for implementing the SHA3 cryptographic hash function on a 32-bit architecture, as it implements the bit-interleaving operation used to speed up the 64-bit rotations directly.\",\n \"line_number\": 3475,\n \"reason\": \"This is inside a [NOTE] block, which is non-normative informational content, not an architectural requirement.\"\n },\n {\n \"excerpt\": \"The 32-bit contents of `seed` are as follows:\",\n \"line_number\": 3497,\n \"reason\": \"This describes the fixed format of the seed CSR, which is a specification requirement that all implementations must follow, not a parameter.\"\n },\n {\n \"excerpt\": \"Software normally uses the instruction `csrrw rd, seed, x0` to read the `seed` CSR.\",\n \"line_number\": 3527,\n \"reason\": \"This describes software usage patterns, not an implementation-defined architectural parameter.\"\n },\n {\n \"excerpt\": \"Each returned `seed[15:0]` = `entropy` value represents unique randomness when `OPST`=`ES16`\",\n \"line_number\": 3565,\n \"reason\": \"This describes the required behavior when the CSR is in ES16 state, which is a fixed specification requirement, not an implementation choice.\"\n },\n {\n \"excerpt\": \"When `OPST` is not `ES16`, `entropy` must be set to 0.\",\n \"line_number\": 3571,\n \"reason\": \"This is a fixed requirement ('must be set to 0') that all implementations must follow, not a parameter.\"\n }\n ]\n}\n```", + "input_tokens": 36762, + "output_tokens": 931, + "latency_ms": 22565, + "timestamp": "2026-04-15T15:00:55.701126+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_045", + "source_file": "smcdeleg.adoc", + "start_line": 1, + "end_line": 147, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "It is optional whether the LCOFI bit (bit 13) in each of `mideleg` and `hideleg`, which allows all LCOFIs to be delegated to S-mode and VS-mode, respectively, is implemented and writable.", + "line_number": 145, + "parameter_name": "LCOFI_DELEGATION_SUPPORT", + "existing_udb_name": null, + "class": "NORM_CSR_RW", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether the LCOFI bits in mideleg and hideleg are implemented and writable. This is a binary choice about the mutability of specific CSR fields." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "NOTE: _The memory-mapped `mtime` register is not a performance monitoring counter to be managed by supervisor software, hence the special treatment of `siselect` value 0x41 described above._", + "line_number": 85, + "reason": "This is inside a [NOTE] block and is therefore non-normative explanatory text, not a parameter definition." + }, + { + "excerpt": "When `menvcfg`.CDE=0, attempts to access `scountinhibit` raise an illegal-instruction exception.", + "line_number": 108, + "reason": "This describes behavior when a CSR field has a specific value (CDE=0). The behavior is determined by the field value at runtime, not by an implementation choice." + }, + { + "excerpt": "For a RISC-V hardware platform, Smcdeleg and Ssccfg must always be implemented in tandem.", + "line_number": 28, + "reason": "This is a fixed requirement ('must always') that applies to all implementations supporting these extensions. There is no implementation choice here." + }, + { + "excerpt": "illegal-instruction exceptions are raised for the following cases", + "line_number": 70, + "reason": "This describes mandatory exception behavior that all implementations must follow. The conditions are fixed requirements, not implementation choices." + }, + { + "excerpt": "The `siselect` (and `vsiselect`) index range 0x40-0x5F is reserved for delegated counter access.", + "line_number": 35, + "reason": "This defines a fixed architectural mapping/reservation that all implementations must follow. It is not an implementation choice." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"It is optional whether the LCOFI bit (bit 13) in each of `mideleg` and `hideleg`, which allows all LCOFIs to be delegated to S-mode and VS-mode, respectively, is implemented and writable.\",\n \"line_number\": 145,\n \"parameter_name\": \"LCOFI_DELEGATION_SUPPORT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether the LCOFI bits in mideleg and hideleg are implemented and writable. This is a binary choice about the mutability of specific CSR fields.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"NOTE: _The memory-mapped `mtime` register is not a performance monitoring counter to be managed by supervisor software, hence the special treatment of `siselect` value 0x41 described above._\",\n \"line_number\": 85,\n \"reason\": \"This is inside a [NOTE] block and is therefore non-normative explanatory text, not a parameter definition.\"\n },\n {\n \"excerpt\": \"When `menvcfg`.CDE=0, attempts to access `scountinhibit` raise an illegal-instruction exception.\",\n \"line_number\": 108,\n \"reason\": \"This describes behavior when a CSR field has a specific value (CDE=0). The behavior is determined by the field value at runtime, not by an implementation choice.\"\n },\n {\n \"excerpt\": \"For a RISC-V hardware platform, Smcdeleg and Ssccfg must always be implemented in tandem.\",\n \"line_number\": 28,\n \"reason\": \"This is a fixed requirement ('must always') that applies to all implementations supporting these extensions. There is no implementation choice here.\"\n },\n {\n \"excerpt\": \"illegal-instruction exceptions are raised for the following cases\",\n \"line_number\": 70,\n \"reason\": \"This describes mandatory exception behavior that all implementations must follow. The conditions are fixed requirements, not implementation choices.\"\n },\n {\n \"excerpt\": \"The `siselect` (and `vsiselect`) index range 0x40-0x5F is reserved for delegated counter access.\",\n \"line_number\": 35,\n \"reason\": \"This defines a fixed architectural mapping/reservation that all implementations must follow. It is not an implementation choice.\"\n }\n ]\n}\n```", + "input_tokens": 8004, + "output_tokens": 635, + "latency_ms": 69171, + "timestamp": "2026-04-15T14:41:27.212626+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_046", + "source_file": "smcntrpmf.adoc", + "start_line": 1, + "end_line": 69, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "For each bit in 61:58, if the associated privilege mode is not implemented, the bit is read-only zero.", + "line_number": 35, + "parameter_name": "MCYCLECFG_PRIVILEGE_MODE_SUPPORT", + "existing_udb_name": null, + "class": "NORM_CSR_RW", + "value_type": "bitmask", + "confidence": "high", + "reasoning": "The implementation chooses which privilege modes are supported, which determines whether the corresponding INH bits in mcyclecfg/minstretcfg are read-only zero or read-write. This is a per-bit RO/RW choice based on privilege mode implementation." + }, + { + "excerpt": "the change of privilege mode may be reported as occurring in any one of those cycles (possibly different for each occurrence of a trap or trap return).", + "line_number": 46, + "parameter_name": "PRIVILEGE_MODE_TRANSITION_CYCLE_TIMING", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "medium", + "reasoning": "The implementation chooses in which cycle during a multi-cycle trap/return operation the privilege mode change is reported to occur. This affects cycle counter behavior and is an implementation-defined timing choice." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "The more natural CSR number for mcyclecfg would be 0x320, but that was allocated to mcountinhibit.", + "line_number": 40, + "reason": "This is inside a [NOTE] block, which is non-normative commentary about CSR numbering decisions, not an architectural parameter." + }, + { + "excerpt": "The RISC-V ISA has no requirement that the number of cycles for a trap or trap return be the same for all occurrences.", + "line_number": 48, + "reason": "This is inside a [NOTE] block describing what the ISA does NOT require, rather than defining an implementation parameter." + }, + { + "excerpt": "When all __x__INH bits are zero, event counting is enabled in all modes.", + "line_number": 33, + "reason": "This describes the behavior when CSR fields have specific values, not an implementation choice. The parameter is which modes are supported (affecting RO/RW nature of bits), not this behavioral description." + }, + { + "excerpt": "instructions that retire in a non-inhibited mode increment instret, and instructions that retire in an inhibited mode do not", + "line_number": 52, + "reason": "This describes the required behavior based on CSR field values at runtime, not an implementation-defined parameter. All implementations must follow this rule." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"For each bit in 61:58, if the associated privilege mode is not implemented, the bit is read-only zero.\",\n \"line_number\": 35,\n \"parameter_name\": \"MCYCLECFG_PRIVILEGE_MODE_SUPPORT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"bitmask\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses which privilege modes are supported, which determines whether the corresponding INH bits in mcyclecfg/minstretcfg are read-only zero or read-write. This is a per-bit RO/RW choice based on privilege mode implementation.\"\n },\n {\n \"excerpt\": \"the change of privilege mode may be reported as occurring in any one of those cycles (possibly different for each occurrence of a trap or trap return).\",\n \"line_number\": 46,\n \"parameter_name\": \"PRIVILEGE_MODE_TRANSITION_CYCLE_TIMING\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The implementation chooses in which cycle during a multi-cycle trap/return operation the privilege mode change is reported to occur. This affects cycle counter behavior and is an implementation-defined timing choice.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"The more natural CSR number for mcyclecfg would be 0x320, but that was allocated to mcountinhibit.\",\n \"line_number\": 40,\n \"reason\": \"This is inside a [NOTE] block, which is non-normative commentary about CSR numbering decisions, not an architectural parameter.\"\n },\n {\n \"excerpt\": \"The RISC-V ISA has no requirement that the number of cycles for a trap or trap return be the same for all occurrences.\",\n \"line_number\": 48,\n \"reason\": \"This is inside a [NOTE] block describing what the ISA does NOT require, rather than defining an implementation parameter.\"\n },\n {\n \"excerpt\": \"When all __x__INH bits are zero, event counting is enabled in all modes.\",\n \"line_number\": 33,\n \"reason\": \"This describes the behavior when CSR fields have specific values, not an implementation choice. The parameter is which modes are supported (affecting RO/RW nature of bits), not this behavioral description.\"\n },\n {\n \"excerpt\": \"instructions that retire in a non-inhibited mode increment instret, and instructions that retire in an inhibited mode do not\",\n \"line_number\": 52,\n \"reason\": \"This describes the required behavior based on CSR field values at runtime, not an implementation-defined parameter. All implementations must follow this rule.\"\n }\n ]\n}\n```", + "input_tokens": 6822, + "output_tokens": 716, + "latency_ms": 13446, + "timestamp": "2026-04-15T14:41:28.185793+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_047", + "source_file": "smctr.adoc", + "start_line": 1, + "end_line": 763, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "The number of records that can be held in the buffer depends upon both the implementation (the maximum supported depth) and the CTR configuration (the software selected depth).", + "line_number": 9, + "parameter_name": "CTR_MAX_DEPTH", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "The implementation chooses the maximum supported depth of the CTR buffer. This is a direct architectural parameter not controlled by any CSR field." + }, + { + "excerpt": "All fields are optional except for M, S, U, and BPFRZ. All unimplemented fields are read-only 0, while all implemented fields are writable. If the Sscofpmf extension is implemented, LCOFIFRZ must be writable.", + "line_number": 108, + "parameter_name": "MCTRCTL_FIELD_SUPPORT", + "existing_udb_name": null, + "class": "NORM_CSR_RW", + "value_type": "set", + "confidence": "high", + "reasoning": "The implementation chooses which mctrctl fields to implement as writable vs read-only-0. This controls the RW nature of CSR fields." + }, + { + "excerpt": "It is implementation-specific which DEPTH value(s) are supported.", + "line_number": 179, + "parameter_name": "SCTRDEPTH_SUPPORTED_VALUES", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "The DEPTH field is WARL and the implementation defines which depth values (16, 32, 64, 128, 256) are legal. This is the set of legal values for a WARL CSR field." + }, + { + "excerpt": "The optional MISP bit is set by the hardware when the recorded transfer is an instruction whose target or taken/not-taken direction was mispredicted by the branch predictor. MISP is read-only 0 when not implemented.", + "line_number": 244, + "parameter_name": "CTRTARGET_MISP_SUPPORT", + "existing_udb_name": null, + "class": "NORM_CSR_RW", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether to implement the MISP bit as functional or read-only-0. This is a binary choice about field implementation." + }, + { + "excerpt": "This register must be implemented, though all fields within it are optional. Unimplemented fields are read-only 0.", + "line_number": 260, + "parameter_name": "CTRDATA_FIELD_SUPPORT", + "existing_udb_name": null, + "class": "NORM_CSR_RW", + "value_type": "set", + "confidence": "high", + "reasoning": "The implementation chooses which ctrdata fields (TYPE, CCV, CC) to implement as functional vs read-only-0. This controls the RW nature of CSR fields." + }, + { + "excerpt": "The `ctrdata` register may optionally include a count of CPU cycles elapsed since the prior CTR record.", + "line_number": 456, + "parameter_name": "CTR_CYCLE_COUNTING_SUPPORT", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether to support cycle counting functionality in the ctrdata register. This is a direct implementation choice." + }, + { + "excerpt": "An implementation that supports cycle counting must implement CCV and all CCM bits, but may implement 0..4 exponent bits in CCE. Unimplemented CCE bits are read-only 0.", + "line_number": 472, + "parameter_name": "CTR_CCE_WIDTH", + "existing_udb_name": null, + "class": "NORM_CSR_RW", + "value_type": "range", + "confidence": "high", + "reasoning": "The implementation chooses how many CCE exponent bits (0-4) to implement, with unimplemented bits being read-only-0. This controls the width of a CSR field." + }, + { + "excerpt": "When the optional `__x__ctrctl`.RASEMU bit is implemented and set to 1, transfer recording behavior is altered to emulate the behavior of a return-address stack (RAS).", + "line_number": 507, + "parameter_name": "CTR_RASEMU_SUPPORT", + "existing_udb_name": null, + "class": "NORM_CSR_RW", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether to implement the RASEMU bit as functional or read-only-0. This is a binary choice about field implementation." + }, + { + "excerpt": "If external trap recording is implemented, `mctrctl`.MTE and `sctrctl`.STE must be implemented, while `vsctrctl`.STE must be implemented if the H extension is implemented.", + "line_number": 427, + "parameter_name": "CTR_EXTERNAL_TRAP_SUPPORT", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether to support external trap recording functionality. This is a direct implementation choice that affects which CSR fields must be implemented." + }, + { + "excerpt": "All transfer type filter bits are optional.", + "line_number": 432, + "parameter_name": "CTR_TRANSFER_TYPE_FILTER_SUPPORT", + "existing_udb_name": null, + "class": "NORM_CSR_RW", + "value_type": "set", + "confidence": "high", + "reasoning": "The implementation chooses which transfer type filter bits to implement as functional vs read-only-0. This controls which CSR fields are writable." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "Only qualified transfers are recorded. Qualified transfers are those that meet the filtering criteria, which include the privilege mode and the transfer type.", + "line_number": 11, + "reason": "This describes the behavior of qualified transfers, which is determined by CSR field values at runtime, not an implementation choice." + }, + { + "excerpt": "The machine-level extension, *Smctr*, encompasses all newly added Control Status Registers (CSRs), instructions, and behavior modifications for a hart across all privilege levels.", + "line_number": 17, + "reason": "This is a definition of what the Smctr extension includes, not an implementation-defined parameter." + }, + { + "excerpt": "Enable transfer recording in the selected privileged mode(s).", + "line_number": 60, + "reason": "This describes the behavior when M/S/U bits are set, which is runtime behavior controlled by CSR field values, not an implementation choice." + }, + { + "excerpt": "CTR records qualified control transfers. Control transfers are qualified if they meet the following criteria:", + "line_number": 598, + "reason": "This describes the behavioral criteria for recording transfers, which is determined by CSR configurations at runtime, not an implementation parameter." + }, + { + "excerpt": "Recording in Debug Mode is always inhibited. Transfers into and out of Debug Mode are never recorded.", + "line_number": 635, + "reason": "This is a fixed requirement ('always inhibited', 'never recorded') that applies to all implementations, not a parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"The number of records that can be held in the buffer depends upon both the implementation (the maximum supported depth) and the CTR configuration (the software selected depth).\",\n \"line_number\": 9,\n \"parameter_name\": \"CTR_MAX_DEPTH\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses the maximum supported depth of the CTR buffer. This is a direct architectural parameter not controlled by any CSR field.\"\n },\n {\n \"excerpt\": \"All fields are optional except for M, S, U, and BPFRZ. All unimplemented fields are read-only 0, while all implemented fields are writable. If the Sscofpmf extension is implemented, LCOFIFRZ must be writable.\",\n \"line_number\": 108,\n \"parameter_name\": \"MCTRCTL_FIELD_SUPPORT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses which mctrctl fields to implement as writable vs read-only-0. This controls the RW nature of CSR fields.\"\n },\n {\n \"excerpt\": \"It is implementation-specific which DEPTH value(s) are supported.\",\n \"line_number\": 179,\n \"parameter_name\": \"SCTRDEPTH_SUPPORTED_VALUES\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"The DEPTH field is WARL and the implementation defines which depth values (16, 32, 64, 128, 256) are legal. This is the set of legal values for a WARL CSR field.\"\n },\n {\n \"excerpt\": \"The optional MISP bit is set by the hardware when the recorded transfer is an instruction whose target or taken/not-taken direction was mispredicted by the branch predictor. MISP is read-only 0 when not implemented.\",\n \"line_number\": 244,\n \"parameter_name\": \"CTRTARGET_MISP_SUPPORT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether to implement the MISP bit as functional or read-only-0. This is a binary choice about field implementation.\"\n },\n {\n \"excerpt\": \"This register must be implemented, though all fields within it are optional. Unimplemented fields are read-only 0.\",\n \"line_number\": 260,\n \"parameter_name\": \"CTRDATA_FIELD_SUPPORT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses which ctrdata fields (TYPE, CCV, CC) to implement as functional vs read-only-0. This controls the RW nature of CSR fields.\"\n },\n {\n \"excerpt\": \"The `ctrdata` register may optionally include a count of CPU cycles elapsed since the prior CTR record.\",\n \"line_number\": 456,\n \"parameter_name\": \"CTR_CYCLE_COUNTING_SUPPORT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether to support cycle counting functionality in the ctrdata register. This is a direct implementation choice.\"\n },\n {\n \"excerpt\": \"An implementation that supports cycle counting must implement CCV and all CCM bits, but may implement 0..4 exponent bits in CCE. Unimplemented CCE bits are read-only 0.\",\n \"line_number\": 472,\n \"parameter_name\": \"CTR_CCE_WIDTH\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"range\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses how many CCE exponent bits (0-4) to implement, with unimplemented bits being read-only-0. This controls the width of a CSR field.\"\n },\n {\n \"excerpt\": \"When the optional `__x__ctrctl`.RASEMU bit is implemented and set to 1, transfer recording behavior is altered to emulate the behavior of a return-address stack (RAS).\",\n \"line_number\": 507,\n \"parameter_name\": \"CTR_RASEMU_SUPPORT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether to implement the RASEMU bit as functional or read-only-0. This is a binary choice about field implementation.\"\n },\n {\n \"excerpt\": \"If external trap recording is implemented, `mctrctl`.MTE and `sctrctl`.STE must be implemented, while `vsctrctl`.STE must be implemented if the H extension is implemented.\",\n \"line_number\": 427,\n \"parameter_name\": \"CTR_EXTERNAL_TRAP_SUPPORT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether to support external trap recording functionality. This is a direct implementation choice that affects which CSR fields must be implemented.\"\n },\n {\n \"excerpt\": \"All transfer type filter bits are optional.\",\n \"line_number\": 432,\n \"parameter_name\": \"CTR_TRANSFER_TYPE_FILTER_SUPPORT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses which transfer type filter bits to implement as functional vs read-only-0. This controls which CSR fields are writable.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"Only qualified transfers are recorded. Qualified transfers are those that meet the filtering criteria, which include the privilege mode and the transfer type.\",\n \"line_number\": 11,\n \"reason\": \"This describes the behavior of qualified transfers, which is determined by CSR field values at runtime, not an implementation choice.\"\n },\n {\n \"excerpt\": \"The machine-level extension, *Smctr*, encompasses all newly added Control Status Registers (CSRs), instructions, and behavior modifications for a hart across all privilege levels.\",\n \"line_number\": 17,\n \"reason\": \"This is a definition of what the Smctr extension includes, not an implementation-defined parameter.\"\n },\n {\n \"excerpt\": \"Enable transfer recording in the selected privileged mode(s).\",\n \"line_number\": 60,\n \"reason\": \"This describes the behavior when M/S/U bits are set, which is runtime behavior controlled by CSR field values, not an implementation choice.\"\n },\n {\n \"excerpt\": \"CTR records qualified control transfers. Control transfers are qualified if they meet the following criteria:\",\n \"line_number\": 598,\n \"reason\": \"This describes the behavioral criteria for recording transfers, which is determined by CSR configurations at runtime, not an implementation parameter.\"\n },\n {\n \"excerpt\": \"Recording in Debug Mode is always inhibited. Transfers into and out of Debug Mode are never recorded.\",\n \"line_number\": 635,\n \"reason\": \"This is a fixed requirement ('always inhibited', 'never recorded') that applies to all implementations, not a parameter.\"\n }\n ]\n}\n```", + "input_tokens": 20546, + "output_tokens": 2018, + "latency_ms": 60793, + "timestamp": "2026-04-15T14:42:31.996318+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_048", + "source_file": "smdbltrp.adoc", + "start_line": 1, + "end_line": 17, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "The extension introduces a mechanism to enter Debug Mode instead of asserting a critical-error signal to the platform when the hart is in a critical error state.", + "line_number": 13, + "parameter_name": "SMDBLTRP_DEBUG_MODE_ON_CRITICAL_ERROR", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "The extension 'introduces a mechanism' which implies an implementation choice between entering Debug Mode vs asserting a critical-error signal when in a critical error state. This is a binary choice for how to handle critical errors." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "The Smdbltrp extension addresses a double trap (See <>) in M-mode.", + "line_number": 4, + "reason": "This describes what the extension does, not an implementation choice. It's a fixed functional requirement." + }, + { + "excerpt": "When the Smrnmi extension (<>) is implemented, it enables invocation of the RNMI handler on a double trap in M-mode to handle the critical error.", + "line_number": 5, + "reason": "This describes conditional behavior based on whether another extension is present, but doesn't define an implementation parameter within Smdbltrp itself." + }, + { + "excerpt": "If the Smrnmi extension is not implemented or if a double trap occurs during the RNMI handler's execution, this extension helps transition the hart to a critical error state", + "line_number": 7, + "reason": "This describes what happens in specific conditions, but is a fixed behavioral requirement rather than an implementation choice." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"The extension introduces a mechanism to enter Debug Mode instead of asserting a critical-error signal to the platform when the hart is in a critical error state.\",\n \"line_number\": 13,\n \"parameter_name\": \"SMDBLTRP_DEBUG_MODE_ON_CRITICAL_ERROR\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The extension 'introduces a mechanism' which implies an implementation choice between entering Debug Mode vs asserting a critical-error signal when in a critical error state. This is a binary choice for how to handle critical errors.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"The Smdbltrp extension addresses a double trap (See <>) in M-mode.\",\n \"line_number\": 4,\n \"reason\": \"This describes what the extension does, not an implementation choice. It's a fixed functional requirement.\"\n },\n {\n \"excerpt\": \"When the Smrnmi extension (<>) is implemented, it enables invocation of the RNMI handler on a double trap in M-mode to handle the critical error.\",\n \"line_number\": 5,\n \"reason\": \"This describes conditional behavior based on whether another extension is present, but doesn't define an implementation parameter within Smdbltrp itself.\"\n },\n {\n \"excerpt\": \"If the Smrnmi extension is not implemented or if a double trap occurs during the RNMI handler's execution, this extension helps transition the hart to a critical error state\",\n \"line_number\": 7,\n \"reason\": \"This describes what happens in specific conditions, but is a fixed behavioral requirement rather than an implementation choice.\"\n }\n ]\n}\n```", + "input_tokens": 5822, + "output_tokens": 463, + "latency_ms": 8725, + "timestamp": "2026-04-15T14:43:37.228381+00:00", + "error": null, + "retry_count": 1 + }, + { + "chunk_id": "chunk_049", + "source_file": "smepmp.adoc", + "start_line": 1, + "end_line": 77, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [], + "skipped_non_parameters": [ + { + "excerpt": "Terms: * *PMP Entry*: A pair of ``pmpcfg[i]`` / ``pmpaddr[i]`` registers. * *PMP Rule*: The contents of a pmpcfg register and its associated pmpaddr register(s), that encode a valid protected physical memory region...", + "line_number": 14, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. It provides definitions and explanations but does not define architectural parameters." + }, + { + "excerpt": "Without the Smepmp extension, it is not possible for a PMP rule to be *enforced* only on non-Machine modes and *denied* on Machine mode", + "line_number": 30, + "reason": "This describes the behavior without the extension, explaining the motivation for the extension rather than defining implementation choices." + }, + { + "excerpt": "The physical memory protection rules when `mseccfg.MML` is set to 1 are summarized in the truth table below.", + "line_number": 42, + "reason": "This describes the behavior when a CSR field has a specific value (MML=1). The behavior is determined by the CSR field value at runtime, not by an implementation choice." + }, + { + "excerpt": "Since all fields defined in ``mseccfg`` as part of this extension are locked when set (``MMWP``/``MML``) or locked when cleared (``RLB``), software can't poll them for determining the presence of Smepmp.", + "line_number": 69, + "reason": "This describes the behavior of the CSR fields and software discovery mechanisms, but does not define any implementation-defined choices or parameters." + }, + { + "excerpt": "It is expected that BootROM will set ``mseccfg.MMWP`` and/or ``mseccfg.MML`` during early boot, before jumping to the firmware", + "line_number": 69, + "reason": "This describes expected software behavior and boot sequence, not an architectural parameter that implementers choose." + } + ], + "raw_response": "```json\n{\n \"parameters\": [],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"Terms: * *PMP Entry*: A pair of ``pmpcfg[i]`` / ``pmpaddr[i]`` registers. * *PMP Rule*: The contents of a pmpcfg register and its associated pmpaddr register(s), that encode a valid protected physical memory region...\",\n \"line_number\": 14,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. It provides definitions and explanations but does not define architectural parameters.\"\n },\n {\n \"excerpt\": \"Without the Smepmp extension, it is not possible for a PMP rule to be *enforced* only on non-Machine modes and *denied* on Machine mode\",\n \"line_number\": 30,\n \"reason\": \"This describes the behavior without the extension, explaining the motivation for the extension rather than defining implementation choices.\"\n },\n {\n \"excerpt\": \"The physical memory protection rules when `mseccfg.MML` is set to 1 are summarized in the truth table below.\",\n \"line_number\": 42,\n \"reason\": \"This describes the behavior when a CSR field has a specific value (MML=1). The behavior is determined by the CSR field value at runtime, not by an implementation choice.\"\n },\n {\n \"excerpt\": \"Since all fields defined in ``mseccfg`` as part of this extension are locked when set (``MMWP``/``MML``) or locked when cleared (``RLB``), software can't poll them for determining the presence of Smepmp.\",\n \"line_number\": 69,\n \"reason\": \"This describes the behavior of the CSR fields and software discovery mechanisms, but does not define any implementation-defined choices or parameters.\"\n },\n {\n \"excerpt\": \"It is expected that BootROM will set ``mseccfg.MMWP`` and/or ``mseccfg.MML`` during early boot, before jumping to the firmware\",\n \"line_number\": 69,\n \"reason\": \"This describes expected software behavior and boot sequence, not an architectural parameter that implementers choose.\"\n }\n ]\n}\n```", + "input_tokens": 7291, + "output_tokens": 540, + "latency_ms": 9735, + "timestamp": "2026-04-15T14:43:25.400747+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_050", + "source_file": "smstateen.adoc", + "start_line": 1, + "end_line": 373, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.", + "line_number": 127, + "parameter_name": "MSTATEEN_AIA_TYPE", + "existing_udb_name": "MSTATEEN_AIA_TYPE", + "class": "NORM_CSR_RW", + "value_type": "enum", + "confidence": "high", + "reasoning": "Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal." + }, + { + "excerpt": "Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.", + "line_number": 127, + "parameter_name": "MSTATEEN_CONTEXT_TYPE", + "existing_udb_name": "MSTATEEN_CONTEXT_TYPE", + "class": "NORM_CSR_RW", + "value_type": "enum", + "confidence": "high", + "reasoning": "Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal." + }, + { + "excerpt": "Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.", + "line_number": 127, + "parameter_name": "MSTATEEN_CSRIND_TYPE", + "existing_udb_name": "MSTATEEN_CSRIND_TYPE", + "class": "NORM_CSR_RW", + "value_type": "enum", + "confidence": "high", + "reasoning": "Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal." + }, + { + "excerpt": "Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.", + "line_number": 127, + "parameter_name": "MSTATEEN_ENVCFG_TYPE", + "existing_udb_name": "MSTATEEN_ENVCFG_TYPE", + "class": "NORM_CSR_RW", + "value_type": "enum", + "confidence": "high", + "reasoning": "Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal." + }, + { + "excerpt": "Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.", + "line_number": 127, + "parameter_name": "MSTATEEN_IMSIC_TYPE", + "existing_udb_name": "MSTATEEN_IMSIC_TYPE", + "class": "NORM_CSR_RW", + "value_type": "enum", + "confidence": "high", + "reasoning": "Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal." + }, + { + "excerpt": "Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.", + "line_number": 127, + "parameter_name": "MSTATEEN_JVT_TYPE", + "existing_udb_name": "MSTATEEN_JVT_TYPE", + "class": "NORM_CSR_RW", + "value_type": "enum", + "confidence": "high", + "reasoning": "Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal." + }, + { + "excerpt": "Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.", + "line_number": 127, + "parameter_name": "HSTATEEN_AIA_TYPE", + "existing_udb_name": "HSTATEEN_AIA_TYPE", + "class": "NORM_CSR_RW", + "value_type": "enum", + "confidence": "high", + "reasoning": "Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal." + }, + { + "excerpt": "Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.", + "line_number": 127, + "parameter_name": "HSTATEEN_CONTEXT_TYPE", + "existing_udb_name": "HSTATEEN_CONTEXT_TYPE", + "class": "NORM_CSR_RW", + "value_type": "enum", + "confidence": "high", + "reasoning": "Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal." + }, + { + "excerpt": "Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.", + "line_number": 127, + "parameter_name": "HSTATEEN_CSRIND_TYPE", + "existing_udb_name": "HSTATEEN_CSRIND_TYPE", + "class": "NORM_CSR_RW", + "value_type": "enum", + "confidence": "high", + "reasoning": "Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal." + }, + { + "excerpt": "Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.", + "line_number": 127, + "parameter_name": "HSTATEEN_ENVCFG_TYPE", + "existing_udb_name": "HSTATEEN_ENVCFG_TYPE", + "class": "NORM_CSR_RW", + "value_type": "enum", + "confidence": "high", + "reasoning": "Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal." + }, + { + "excerpt": "Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.", + "line_number": 127, + "parameter_name": "HSTATEEN_IMSIC_TYPE", + "existing_udb_name": "HSTATEEN_IMSIC_TYPE", + "class": "NORM_CSR_RW", + "value_type": "enum", + "confidence": "high", + "reasoning": "Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal." + }, + { + "excerpt": "Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.", + "line_number": 127, + "parameter_name": "SSTATEEN_JVT_TYPE", + "existing_udb_name": "SSTATEEN_JVT_TYPE", + "class": "NORM_CSR_RW", + "value_type": "enum", + "confidence": "high", + "reasoning": "Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal." + }, + { + "excerpt": "When a `stateen` CSR prevents access to state for a privilege mode, attempting to execute in that privilege mode an instruction that _implicitly_ updates the state without reading it may or may not raise an illegal-instruction or virtual-instruction exception.", + "line_number": 95, + "parameter_name": "STATEEN_IMPLICIT_UPDATE_EXCEPTION", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "The implementation chooses whether implicit state updates raise exceptions when stateen bits block access. This is a direct implementation choice about exception behavior." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "The requirements that non-standard extensions must meet to be conforming are not relaxed due solely to changes in the value of this bit.", + "line_number": 201, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks." + }, + { + "excerpt": "Setting the IMSIC bit in `hstateen0` to zero prevents a virtual machine from accessing the hart's IMSIC the same as setting `hstatus`.VGEIN = 0.", + "line_number": 244, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks." + }, + { + "excerpt": "When this extension is not implemented, all state added by an extension is accessible as defined by that extension.", + "line_number": 89, + "reason": "This describes what happens when the extension is not implemented - it's a fixed requirement, not an implementation choice." + }, + { + "excerpt": "The C bit controls access to any and all custom state.", + "line_number": 195, + "reason": "This describes the behavior controlled by a CSR bit value, not an implementation parameter. The parameter would be whether the C bit is read-only or read-write." + }, + { + "excerpt": "On reset, all writable `mstateen` bits are initialized by the hardware to zeros.", + "line_number": 142, + "reason": "This is a fixed requirement ('are initialized') that all implementations must satisfy. There is no implementation choice here." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.\",\n \"line_number\": 127,\n \"parameter_name\": \"MSTATEEN_AIA_TYPE\",\n \"existing_udb_name\": \"MSTATEEN_AIA_TYPE\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal.\"\n },\n {\n \"excerpt\": \"Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.\",\n \"line_number\": 127,\n \"parameter_name\": \"MSTATEEN_CONTEXT_TYPE\",\n \"existing_udb_name\": \"MSTATEEN_CONTEXT_TYPE\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal.\"\n },\n {\n \"excerpt\": \"Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.\",\n \"line_number\": 127,\n \"parameter_name\": \"MSTATEEN_CSRIND_TYPE\",\n \"existing_udb_name\": \"MSTATEEN_CSRIND_TYPE\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal.\"\n },\n {\n \"excerpt\": \"Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.\",\n \"line_number\": 127,\n \"parameter_name\": \"MSTATEEN_ENVCFG_TYPE\",\n \"existing_udb_name\": \"MSTATEEN_ENVCFG_TYPE\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal.\"\n },\n {\n \"excerpt\": \"Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.\",\n \"line_number\": 127,\n \"parameter_name\": \"MSTATEEN_IMSIC_TYPE\",\n \"existing_udb_name\": \"MSTATEEN_IMSIC_TYPE\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal.\"\n },\n {\n \"excerpt\": \"Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.\",\n \"line_number\": 127,\n \"parameter_name\": \"MSTATEEN_JVT_TYPE\",\n \"existing_udb_name\": \"MSTATEEN_JVT_TYPE\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal.\"\n },\n {\n \"excerpt\": \"Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.\",\n \"line_number\": 127,\n \"parameter_name\": \"HSTATEEN_AIA_TYPE\",\n \"existing_udb_name\": \"HSTATEEN_AIA_TYPE\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal.\"\n },\n {\n \"excerpt\": \"Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.\",\n \"line_number\": 127,\n \"parameter_name\": \"HSTATEEN_CONTEXT_TYPE\",\n \"existing_udb_name\": \"HSTATEEN_CONTEXT_TYPE\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal.\"\n },\n {\n \"excerpt\": \"Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.\",\n \"line_number\": 127,\n \"parameter_name\": \"HSTATEEN_CSRIND_TYPE\",\n \"existing_udb_name\": \"HSTATEEN_CSRIND_TYPE\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal.\"\n },\n {\n \"excerpt\": \"Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.\",\n \"line_number\": 127,\n \"parameter_name\": \"HSTATEEN_ENVCFG_TYPE\",\n \"existing_udb_name\": \"HSTATEEN_ENVCFG_TYPE\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal.\"\n },\n {\n \"excerpt\": \"Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.\",\n \"line_number\": 127,\n \"parameter_name\": \"HSTATEEN_IMSIC_TYPE\",\n \"existing_udb_name\": \"HSTATEEN_IMSIC_TYPE\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal.\"\n },\n {\n \"excerpt\": \"Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.\",\n \"line_number\": 127,\n \"parameter_name\": \"SSTATEEN_JVT_TYPE\",\n \"existing_udb_name\": \"SSTATEEN_JVT_TYPE\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal.\"\n },\n {\n \"excerpt\": \"When a `stateen` CSR prevents access to state for a privilege mode, attempting to execute in that privilege mode an instruction that _implicitly_ updates the state without reading it may or may not raise an illegal-instruction or virtual-instruction exception.\",\n \"line_number\": 95,\n \"parameter_name\": \"STATEEN_IMPLICIT_UPDATE_EXCEPTION\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The implementation chooses whether implicit state updates raise exceptions when stateen bits block access. This is a direct implementation choice about exception behavior.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"The requirements that non-standard extensions must meet to be conforming are not relaxed due solely to changes in the value of this bit.\",\n \"line_number\": 201,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks.\"\n },\n {\n \"excerpt\": \"Setting the IMSIC bit in `hstateen0` to zero prevents a virtual machine from accessing the hart's IMSIC the same as setting `hstatus`.VGEIN = 0.\",\n \"line_number\": 244,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks.\"\n },\n {\n \"excerpt\": \"When this extension is not implemented, all state added by an extension is accessible as defined by that extension.\",\n \"line_number\": 89,\n \"reason\": \"This describes what happens when the extension is not implemented - it's a fixed requirement, not an implementation choice.\"\n },\n {\n \"excerpt\": \"The C bit controls access to any and all custom state.\",\n \"line_number\": 195,\n \"reason\": \"This describes the behavior controlled by a CSR bit value, not an implementation parameter. The parameter would be whether the C bit is read-only or read-write.\"\n },\n {\n \"excerpt\": \"On reset, all writable `mstateen` bits are initialized by the hardware to zeros.\",\n \"line_number\": 142,\n \"reason\": \"This is a fixed requirement ('are initialized') that all implementations must satisfy. There is no implementation choice here.\"\n }\n ]\n}\n```", + "input_tokens": 11058, + "output_tokens": 2766, + "latency_ms": 59851, + "timestamp": "2026-04-15T14:44:28.358422+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_051", + "source_file": "sscofpmf.adoc", + "start_line": 1, + "end_line": 126, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "For each ``x``INH bit, if the associated privilege mode is not implemented, the bit is read-only zero.", + "line_number": 47, + "parameter_name": "MHPMEVENT_INH_BITS_IMPLEMENTATION", + "existing_udb_name": null, + "class": "NORM_CSR_RW", + "value_type": "bitmask", + "confidence": "high", + "reasoning": "The implementation chooses which privilege modes are supported, which determines whether each INH bit is read-only zero or read-write. This controls the RO/RW nature of specific CSR fields based on architectural choices." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "Note that the new count overflow interrupt will be treated as a standard local interrupt that is assigned to bit 13 in the mip/mie/sip/sie registers.", + "line_number": 24, + "reason": "This is a fixed assignment specification - bit 13 is always used for this interrupt, not an implementation choice." + }, + { + "excerpt": "The OF bit is set when the corresponding hpmcounter overflows, and remains set until written by software.", + "line_number": 53, + "reason": "This describes the required behavior of the OF bit - all implementations must behave this way, not a parameter." + }, + { + "excerpt": "If an hpmcounter overflows while the associated OF bit is zero, then a \"count overflow interrupt request\" is generated.", + "line_number": 60, + "reason": "This describes mandatory behavior when certain conditions are met - not an implementation choice." + }, + { + "excerpt": "There are not separate overflow status and overflow interrupt enable bits.", + "line_number": 82, + "reason": "This text is inside a [NOTE] block and is therefore non-normative informational content." + }, + { + "excerpt": "In M-mode, scountovf bit _X_ is always readable.", + "line_number": 108, + "reason": "This is a fixed requirement that applies to all implementations - M-mode always has read access, not a parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"For each ``x``INH bit, if the associated privilege mode is not implemented, the bit is read-only zero.\",\n \"line_number\": 47,\n \"parameter_name\": \"MHPMEVENT_INH_BITS_IMPLEMENTATION\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"bitmask\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses which privilege modes are supported, which determines whether each INH bit is read-only zero or read-write. This controls the RO/RW nature of specific CSR fields based on architectural choices.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"Note that the new count overflow interrupt will be treated as a standard local interrupt that is assigned to bit 13 in the mip/mie/sip/sie registers.\",\n \"line_number\": 24,\n \"reason\": \"This is a fixed assignment specification - bit 13 is always used for this interrupt, not an implementation choice.\"\n },\n {\n \"excerpt\": \"The OF bit is set when the corresponding hpmcounter overflows, and remains set until written by software.\",\n \"line_number\": 53,\n \"reason\": \"This describes the required behavior of the OF bit - all implementations must behave this way, not a parameter.\"\n },\n {\n \"excerpt\": \"If an hpmcounter overflows while the associated OF bit is zero, then a \\\"count overflow interrupt request\\\" is generated.\",\n \"line_number\": 60,\n \"reason\": \"This describes mandatory behavior when certain conditions are met - not an implementation choice.\"\n },\n {\n \"excerpt\": \"There are not separate overflow status and overflow interrupt enable bits.\",\n \"line_number\": 82,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative informational content.\"\n },\n {\n \"excerpt\": \"In M-mode, scountovf bit _X_ is always readable.\",\n \"line_number\": 108,\n \"reason\": \"This is a fixed requirement that applies to all implementations - M-mode always has read access, not a parameter.\"\n }\n ]\n}\n```", + "input_tokens": 7226, + "output_tokens": 564, + "latency_ms": 22359, + "timestamp": "2026-04-15T14:44:53.758617+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_052", + "source_file": "ssdbltrp.adoc", + "start_line": 1, + "end_line": 15, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [], + "skipped_non_parameters": [ + { + "excerpt": "It enables HS-mode to invoke a critical error handler in a virtual machine on a double trap in VS-mode.", + "line_number": 5, + "reason": "This describes the functionality/purpose of the extension, not an implementation choice. All implementations of Ssdbltrp must provide this capability." + }, + { + "excerpt": "It also allows M-mode to invoke a critical error handler in the OS/Hypervisor on a double trap in S/HS-mode.", + "line_number": 6, + "reason": "This describes required functionality of the extension, not a parameter. The behavior is fixed for all implementations." + }, + { + "excerpt": "The Ssdbltrp extension adds the `menvcfg`.DTE", + "line_number": 10, + "reason": "This states that the extension adds a CSR field, which is a fixed requirement. It doesn't specify any implementation choices about the field's behavior or legal values." + }, + { + "excerpt": "If the hypervisor extension is additionally implemented, then the extension adds the `henvcfg`.DTE", + "line_number": 11, + "reason": "This is a conditional requirement based on hypervisor extension presence, but not an implementation choice. If H-ext is present, these fields must be added." + } + ], + "raw_response": "```json\n{\n \"parameters\": [],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"It enables HS-mode to invoke a critical error handler in a virtual machine on a double trap in VS-mode.\",\n \"line_number\": 5,\n \"reason\": \"This describes the functionality/purpose of the extension, not an implementation choice. All implementations of Ssdbltrp must provide this capability.\"\n },\n {\n \"excerpt\": \"It also allows M-mode to invoke a critical error handler in the OS/Hypervisor on a double trap in S/HS-mode.\",\n \"line_number\": 6,\n \"reason\": \"This describes required functionality of the extension, not a parameter. The behavior is fixed for all implementations.\"\n },\n {\n \"excerpt\": \"The Ssdbltrp extension adds the `menvcfg`.DTE\",\n \"line_number\": 10,\n \"reason\": \"This states that the extension adds a CSR field, which is a fixed requirement. It doesn't specify any implementation choices about the field's behavior or legal values.\"\n },\n {\n \"excerpt\": \"If the hypervisor extension is additionally implemented, then the extension adds the `henvcfg`.DTE\",\n \"line_number\": 11,\n \"reason\": \"This is a conditional requirement based on hypervisor extension presence, but not an implementation choice. If H-ext is present, these fields must be added.\"\n }\n ]\n}\n```", + "input_tokens": 5888, + "output_tokens": 357, + "latency_ms": 7002, + "timestamp": "2026-04-15T15:02:03.742495+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_053", + "source_file": "sstc.adoc", + "start_line": 1, + "end_line": 24, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [], + "skipped_non_parameters": [ + { + "excerpt": "The current Privileged arch specification only defines a hardware mechanism for generating machine-mode timer interrupts (based on the mtime and mtimecmp registers).", + "line_number": 4, + "reason": "This describes the existing specification requirements, not an implementation choice." + }, + { + "excerpt": "This extension serves to provide supervisor mode with its own CSR-based timer interrupt facility that it can directly manage to provide its own timer service", + "line_number": 13, + "reason": "This describes the purpose and functionality of the extension, not an implementation-defined parameter." + }, + { + "excerpt": "This extension adds the S-level `stimecmp` CSR (<>) and the VS-level `vstimecmp` CSR (<>).", + "line_number": 21, + "reason": "This states what CSRs are added by the extension, which is a fixed requirement, not an implementation choice." + }, + { + "excerpt": "This extension adds the `STCE` bit to the `menvcfg` (<>) and `henvcfg` (<>) CSRs.", + "line_number": 22, + "reason": "This describes what bits are added to existing CSRs, which is a specification requirement, not a parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"The current Privileged arch specification only defines a hardware mechanism for generating machine-mode timer interrupts (based on the mtime and mtimecmp registers).\",\n \"line_number\": 4,\n \"reason\": \"This describes the existing specification requirements, not an implementation choice.\"\n },\n {\n \"excerpt\": \"This extension serves to provide supervisor mode with its own CSR-based timer interrupt facility that it can directly manage to provide its own timer service\",\n \"line_number\": 13,\n \"reason\": \"This describes the purpose and functionality of the extension, not an implementation-defined parameter.\"\n },\n {\n \"excerpt\": \"This extension adds the S-level `stimecmp` CSR (<>) and the VS-level `vstimecmp` CSR (<>).\",\n \"line_number\": 21,\n \"reason\": \"This states what CSRs are added by the extension, which is a fixed requirement, not an implementation choice.\"\n },\n {\n \"excerpt\": \"This extension adds the `STCE` bit to the `menvcfg` (<>) and `henvcfg` (<>) CSRs.\",\n \"line_number\": 22,\n \"reason\": \"This describes what bits are added to existing CSRs, which is a specification requirement, not a parameter.\"\n }\n ]\n}\n```", + "input_tokens": 5983, + "output_tokens": 372, + "latency_ms": 5912, + "timestamp": "2026-04-15T14:45:11.654133+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_054", + "source_file": "supervisor.adoc", + "start_line": 1, + "end_line": 2630, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "When SXLEN=64, it is a *WARL* field that encodes the current value of UXLEN. In particular, an implementation may make UXL be a read-only field whose value always ensures that UXLEN=SXLEN.", + "line_number": 119, + "parameter_name": "SSTATUS_UXL_LEGAL_VALUES", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "The UXL field is WARL and implementations may make it read-only or allow different values. The parameter is the set of legal UXL values the implementation supports." + }, + { + "excerpt": "When such a HINT is executed with XLEN < SXLEN and bits SXLEN..XLEN of the destination register not all equal to bit XLEN-1, it is implementation-defined whether bits SXLEN..XLEN of the destination register are unchanged or are overwritten with copies of bit XLEN-1.", + "line_number": 133, + "parameter_name": "HINT_SXLEN_PARAM", + "existing_udb_name": "HINT_SXLEN_PARAM", + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "Implementation-defined choice of whether to preserve or sign-extend upper bits in HINT instructions when XLEN < SXLEN. This is a direct architectural choice." + }, + { + "excerpt": "SUM is read-only 0 if `satp`.MODE is read-only 0.", + "line_number": 169, + "parameter_name": "SSTATUS_SUM_ACCESS", + "existing_udb_name": null, + "class": "NORM_CSR_RW", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether SUM is read-only zero or read-write, depending on whether satp.MODE is read-only zero. This controls the mutability of the SUM field." + }, + { + "excerpt": "The UBE bit is a *WARL* field that controls the endianness of explicit memory accesses made from U-mode, which may differ from the endianness of memory accesses in S-mode. An implementation may make UBE be a read-only field that always specifies the same endianness as for S-mode.", + "line_number": 194, + "parameter_name": "U_MODE_ENDIANNESS", + "existing_udb_name": "U_MODE_ENDIANNESS", + "class": "NORM_CSR_RW", + "value_type": "enum", + "confidence": "high", + "reasoning": "The UBE field can be read-only-0 (little-endian), read-only-1 (big-endian), or read-write (dynamic). This controls the RO/RW nature and legal values of the endianness field." + }, + { + "excerpt": "The S-mode-disable-trap (`SDT`) bit is a WARL field introduced by the Ssdbltrp extension", + "line_number": 218, + "parameter_name": "SSTATUS_SDT_LEGAL_VALUES", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "medium", + "reasoning": "SDT is described as a WARL field, meaning implementations can restrict which values are legal. The parameter would be the set of supported values." + }, + { + "excerpt": "When MODE=Vectored, all synchronous exceptions into supervisor mode cause the `pc` to be set to the address in the BASE field, whereas interrupts cause the `pc` to be set to the address in the BASE field plus four times the interrupt cause number.", + "line_number": 295, + "parameter_name": "STVEC_MODE_VECTORED", + "existing_udb_name": "STVEC_MODE_VECTORED", + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "Implementation choice of whether to support Vectored mode in stvec. The text shows this is an optional mode (value 1 in the encoding table)." + }, + { + "excerpt": "Each individual bit in register `sip` may be writable or may be read-only.", + "line_number": 334, + "parameter_name": "SIP_BITS_ACCESS", + "existing_udb_name": null, + "class": "NORM_CSR_RW", + "value_type": "bitmask", + "confidence": "high", + "reasoning": "Each bit in sip can independently be writable or read-only. This is a per-bit RW/RO choice for the register." + }, + { + "excerpt": "A bit in `sie` must be writable if the corresponding interrupt can ever become pending. Bits of `sie` that are not writable are read-only zero.", + "line_number": 341, + "parameter_name": "SIE_BITS_ACCESS", + "existing_udb_name": null, + "class": "NORM_CSR_RW", + "value_type": "bitmask", + "confidence": "high", + "reasoning": "Each bit in sie can be writable or read-only zero, depending on whether the corresponding interrupt can become pending. This is a per-bit RW/RO choice." + }, + { + "excerpt": "Each standard interrupt type (SEI, STI, SSI, or LCOFI) may not be implemented, in which case the corresponding interrupt-pending and interrupt-enable bits are read-only zeros. All bits in `sip` and `sie` are *WARL* fields.", + "line_number": 408, + "parameter_name": "SIP_SIE_INTERRUPT_SUPPORT", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "Implementation chooses which standard interrupt types to implement. The WARL nature means the set of legal values varies by implementation based on which interrupts are supported." + }, + { + "excerpt": "`scounteren` must be implemented. However, any of the bits may be read-only zero, indicating reads to the corresponding counter will cause an exception when executing in U-mode. Hence, they are effectively *WARL* fields.", + "line_number": 448, + "parameter_name": "SCOUNTEREN_BITS_ACCESS", + "existing_udb_name": null, + "class": "NORM_CSR_RW", + "value_type": "bitmask", + "confidence": "high", + "reasoning": "Each bit in scounteren can be writable or read-only zero. This controls whether U-mode can access the corresponding counter, making it a per-bit RW/RO choice." + }, + { + "excerpt": "`sepc` is a *WARL* register that must be able to hold all valid virtual addresses. It need not be capable of holding all possible invalid addresses.", + "line_number": 485, + "parameter_name": "SEPC_WARL_VALUES", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "medium", + "reasoning": "sepc is WARL and need not hold all possible invalid addresses. The parameter is the set of addresses sepc can hold, which may exclude some invalid addresses." + }, + { + "excerpt": "The Exception Code is a *WLRL* field. It is required to hold the values 0\u201331 (i.e., bits 4\u20130 must be implemented), but otherwise it is only guaranteed to hold supported exception codes.", + "line_number": 508, + "parameter_name": "SCAUSE_EXCEPTION_CODE_LEGAL_VALUES", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "The Exception Code field is WLRL and only guaranteed to hold supported exception codes beyond the required 0-31 range. The parameter is the set of legal exception codes." + }, + { + "excerpt": "`stval` is a *WARL* register that must be able to hold all valid virtual addresses and the value 0. It need not be capable of holding all possible invalid addresses.", + "line_number": 618, + "parameter_name": "STVAL_WARL_VALUES", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "medium", + "reasoning": "stval is WARL and need not hold all possible invalid addresses. The parameter is the set of values stval can hold, which may exclude some invalid addresses." + }, + { + "excerpt": "If `satp`.MODE is read-only zero (always Bare), the implementation may make FIOM read-only zero.", + "line_number": 665, + "parameter_name": "SENVCFG_FIOM_ACCESS", + "existing_udb_name": null, + "class": "NORM_CSR_RW", + "value_type": "binary", + "confidence": "high", + "reasoning": "Implementation choice of whether FIOM is read-only zero or read-write, depending on satp.MODE support. This controls the mutability of the FIOM field." + }, + { + "excerpt": "The `CBIE` (Cache Block Invalidate instruction Enable) WARL field to `senvcfg` to control execution of the `CBO.INVAL` instruction in U-mode.", + "line_number": 720, + "parameter_name": "SENVCFG_CBIE_LEGAL_VALUES", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "CBIE is explicitly described as a WARL field, meaning implementations can restrict which values are legal. The parameter is the set of supported CBIE values." + }, + { + "excerpt": "If the Ssnpm extension is implemented, the `PMM` field enables or disables pointer masking (see <>) for the next-lower privilege mode (U/VU), according to the values in <>. If Ssnpm is not implemented, `PMM` is read-only zero.", + "line_number": 738, + "parameter_name": "SENVCFG_PMM_LEGAL_VALUES", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "PMM field has specific legal values defined in a table, and is read-only zero if Ssnpm is not implemented. This is a WARL field with implementation-defined legal values." + }, + { + "excerpt": "Implementations are not required to support all MODE settings, and if `satp` is written with an unsupported MODE, the entire write has no effect; no fields in `satp` are modified.", + "line_number": 825, + "parameter_name": "SATP_MODE_SUPPORT", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "Implementations choose which satp MODE values to support. Unsupported modes cause writes to have no effect, making this a WARL field with implementation-defined legal values." + }, + { + "excerpt": "The number of ASID bits is UNSPECIFIED and may be zero. The number of implemented ASID bits, termed _ASIDLEN_, may be determined by writing one to every bit position in the ASID field, then reading back the value in `satp` to see which bit positions in the ASID field hold a one.", + "line_number": 831, + "parameter_name": "ASID_WIDTH", + "existing_udb_name": "ASID_WIDTH", + "class": "NORM_DIRECT", + "value_type": "range", + "confidence": "high", + "reasoning": "ASIDLEN is implementation-defined and can range from 0 to ASIDMAX (9 for Sv32, 16 for others). This is a direct implementation choice of how many ASID bits to implement." + }, + { + "excerpt": "For implementations that make `satp`.MODE read-only zero (always Bare), attempts to execute an SFENCE.VMA instruction might raise an illegal-instruction exception.", + "line_number": 1169, + "parameter_name": "TRAP_ON_SFENCE_VMA_WHEN_SATP_MODE_IS_READ_ONLY", + "existing_udb_name": "TRAP_ON_SFENCE_VMA_WHEN_SATP_MODE_IS_READ_ONLY", + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "Implementation choice of whether to trap on SFENCE.VMA when satp.MODE is read-only zero. The word 'might' indicates this is optional behavior." + }, + { + "excerpt": "The 20-bit VPN is translated into a 22-bit physical page number (PPN)", + "line_number": 1207, + "parameter_name": "SATP_PPN_SV32_SIZE", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "The PPN size for Sv32 is specified as 22 bits. This is a fixed architectural parameter for Sv32 implementations." + }, + { + "excerpt": "The 27-bit VPN is translated into a 44-bit PPN via a three-level page table", + "line_number": 1598, + "parameter_name": "SATP_PPN_SV39_SV48_SV57_SIZE", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "The PPN size for Sv39, Sv48, and Sv57 is specified as 44 bits. This is a fixed architectural parameter for these implementations." + }, + { + "excerpt": "Both `RCID` and `MCID` are WARL fields.", + "line_number": 2583, + "parameter_name": "SRMCFG_RCID_MCID_LEGAL_VALUES", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "Both RCID and MCID fields in srmcfg are explicitly described as WARL, meaning implementations can restrict which values are legal for each field." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "Supervisor mode is deliberately restricted in terms of interactions with underlying physical hardware, such as physical memory and device interrupts, to support clean virtualization.", + "line_number": 8, + "reason": "This is in a [NOTE] block, which is non-normative. Parameters are never extracted from NOTE blocks." + }, + { + "excerpt": "When a trap is taken, SPP is set to 0 if the trap originated from user mode, or 1 otherwise.", + "line_number": 77, + "reason": "This describes fixed behavior that occurs when a trap is taken. It is not an implementation choice but a required specification." + }, + { + "excerpt": "When MODE=Direct, all traps into supervisor mode cause the `pc` to be set to the address in the BASE field.", + "line_number": 293, + "reason": "This describes what happens when stvec.MODE has a specific value. The behavior is determined by the CSR field value at runtime, not by an implementation choice." + }, + { + "excerpt": "Software may determine the PMP granularity by writing zero to `pmp0cfg`, then writing all ones to `pmpaddr0`, then reading back `pmpaddr0`.", + "line_number": 831, + "reason": "Here 'may' means 'is allowed to' (permission), not 'might or might not' (optionality). This describes a software technique, not an implementation-defined parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"When SXLEN=64, it is a *WARL* field that encodes the current value of UXLEN. In particular, an implementation may make UXL be a read-only field whose value always ensures that UXLEN=SXLEN.\",\n \"line_number\": 119,\n \"parameter_name\": \"SSTATUS_UXL_LEGAL_VALUES\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"The UXL field is WARL and implementations may make it read-only or allow different values. The parameter is the set of legal UXL values the implementation supports.\"\n },\n {\n \"excerpt\": \"When such a HINT is executed with XLEN < SXLEN and bits SXLEN..XLEN of the destination register not all equal to bit XLEN-1, it is implementation-defined whether bits SXLEN..XLEN of the destination register are unchanged or are overwritten with copies of bit XLEN-1.\",\n \"line_number\": 133,\n \"parameter_name\": \"HINT_SXLEN_PARAM\",\n \"existing_udb_name\": \"HINT_SXLEN_PARAM\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"Implementation-defined choice of whether to preserve or sign-extend upper bits in HINT instructions when XLEN < SXLEN. This is a direct architectural choice.\"\n },\n {\n \"excerpt\": \"SUM is read-only 0 if `satp`.MODE is read-only 0.\",\n \"line_number\": 169,\n \"parameter_name\": \"SSTATUS_SUM_ACCESS\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether SUM is read-only zero or read-write, depending on whether satp.MODE is read-only zero. This controls the mutability of the SUM field.\"\n },\n {\n \"excerpt\": \"The UBE bit is a *WARL* field that controls the endianness of explicit memory accesses made from U-mode, which may differ from the endianness of memory accesses in S-mode. An implementation may make UBE be a read-only field that always specifies the same endianness as for S-mode.\",\n \"line_number\": 194,\n \"parameter_name\": \"U_MODE_ENDIANNESS\",\n \"existing_udb_name\": \"U_MODE_ENDIANNESS\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"The UBE field can be read-only-0 (little-endian), read-only-1 (big-endian), or read-write (dynamic). This controls the RO/RW nature and legal values of the endianness field.\"\n },\n {\n \"excerpt\": \"The S-mode-disable-trap (`SDT`) bit is a WARL field introduced by the Ssdbltrp extension\",\n \"line_number\": 218,\n \"parameter_name\": \"SSTATUS_SDT_LEGAL_VALUES\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"medium\",\n \"reasoning\": \"SDT is described as a WARL field, meaning implementations can restrict which values are legal. The parameter would be the set of supported values.\"\n },\n {\n \"excerpt\": \"When MODE=Vectored, all synchronous exceptions into supervisor mode cause the `pc` to be set to the address in the BASE field, whereas interrupts cause the `pc` to be set to the address in the BASE field plus four times the interrupt cause number.\",\n \"line_number\": 295,\n \"parameter_name\": \"STVEC_MODE_VECTORED\",\n \"existing_udb_name\": \"STVEC_MODE_VECTORED\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"Implementation choice of whether to support Vectored mode in stvec. The text shows this is an optional mode (value 1 in the encoding table).\"\n },\n {\n \"excerpt\": \"Each individual bit in register `sip` may be writable or may be read-only.\",\n \"line_number\": 334,\n \"parameter_name\": \"SIP_BITS_ACCESS\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"bitmask\",\n \"confidence\": \"high\",\n \"reasoning\": \"Each bit in sip can independently be writable or read-only. This is a per-bit RW/RO choice for the register.\"\n },\n {\n \"excerpt\": \"A bit in `sie` must be writable if the corresponding interrupt can ever become pending. Bits of `sie` that are not writable are read-only zero.\",\n \"line_number\": 341,\n \"parameter_name\": \"SIE_BITS_ACCESS\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"bitmask\",\n \"confidence\": \"high\",\n \"reasoning\": \"Each bit in sie can be writable or read-only zero, depending on whether the corresponding interrupt can become pending. This is a per-bit RW/RO choice.\"\n },\n {\n \"excerpt\": \"Each standard interrupt type (SEI, STI, SSI, or LCOFI) may not be implemented, in which case the corresponding interrupt-pending and interrupt-enable bits are read-only zeros. All bits in `sip` and `sie` are *WARL* fields.\",\n \"line_number\": 408,\n \"parameter_name\": \"SIP_SIE_INTERRUPT_SUPPORT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"Implementation chooses which standard interrupt types to implement. The WARL nature means the set of legal values varies by implementation based on which interrupts are supported.\"\n },\n {\n \"excerpt\": \"`scounteren` must be implemented. However, any of the bits may be read-only zero, indicating reads to the corresponding counter will cause an exception when executing in U-mode. Hence, they are effectively *WARL* fields.\",\n \"line_number\": 448,\n \"parameter_name\": \"SCOUNTEREN_BITS_ACCESS\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"bitmask\",\n \"confidence\": \"high\",\n \"reasoning\": \"Each bit in scounteren can be writable or read-only zero. This controls whether U-mode can access the corresponding counter, making it a per-bit RW/RO choice.\"\n },\n {\n \"excerpt\": \"`sepc` is a *WARL* register that must be able to hold all valid virtual addresses. It need not be capable of holding all possible invalid addresses.\",\n \"line_number\": 485,\n \"parameter_name\": \"SEPC_WARL_VALUES\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"medium\",\n \"reasoning\": \"sepc is WARL and need not hold all possible invalid addresses. The parameter is the set of addresses sepc can hold, which may exclude some invalid addresses.\"\n },\n {\n \"excerpt\": \"The Exception Code is a *WLRL* field. It is required to hold the values 0\u201331 (i.e., bits 4\u20130 must be implemented), but otherwise it is only guaranteed to hold supported exception codes.\",\n \"line_number\": 508,\n \"parameter_name\": \"SCAUSE_EXCEPTION_CODE_LEGAL_VALUES\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"The Exception Code field is WLRL and only guaranteed to hold supported exception codes beyond the required 0-31 range. The parameter is the set of legal exception codes.\"\n },\n {\n \"excerpt\": \"`stval` is a *WARL* register that must be able to hold all valid virtual addresses and the value 0. It need not be capable of holding all possible invalid addresses.\",\n \"line_number\": 618,\n \"parameter_name\": \"STVAL_WARL_VALUES\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"medium\",\n \"reasoning\": \"stval is WARL and need not hold all possible invalid addresses. The parameter is the set of values stval can hold, which may exclude some invalid addresses.\"\n },\n {\n \"excerpt\": \"If `satp`.MODE is read-only zero (always Bare), the implementation may make FIOM read-only zero.\",\n \"line_number\": 665,\n \"parameter_name\": \"SENVCFG_FIOM_ACCESS\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"Implementation choice of whether FIOM is read-only zero or read-write, depending on satp.MODE support. This controls the mutability of the FIOM field.\"\n },\n {\n \"excerpt\": \"The `CBIE` (Cache Block Invalidate instruction Enable) WARL field to `senvcfg` to control execution of the `CBO.INVAL` instruction in U-mode.\",\n \"line_number\": 720,\n \"parameter_name\": \"SENVCFG_CBIE_LEGAL_VALUES\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"CBIE is explicitly described as a WARL field, meaning implementations can restrict which values are legal. The parameter is the set of supported CBIE values.\"\n },\n {\n \"excerpt\": \"If the Ssnpm extension is implemented, the `PMM` field enables or disables pointer masking (see <>) for the next-lower privilege mode (U/VU), according to the values in <>. If Ssnpm is not implemented, `PMM` is read-only zero.\",\n \"line_number\": 738,\n \"parameter_name\": \"SENVCFG_PMM_LEGAL_VALUES\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"PMM field has specific legal values defined in a table, and is read-only zero if Ssnpm is not implemented. This is a WARL field with implementation-defined legal values.\"\n },\n {\n \"excerpt\": \"Implementations are not required to support all MODE settings, and if `satp` is written with an unsupported MODE, the entire write has no effect; no fields in `satp` are modified.\",\n \"line_number\": 825,\n \"parameter_name\": \"SATP_MODE_SUPPORT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"Implementations choose which satp MODE values to support. Unsupported modes cause writes to have no effect, making this a WARL field with implementation-defined legal values.\"\n },\n {\n \"excerpt\": \"The number of ASID bits is UNSPECIFIED and may be zero. The number of implemented ASID bits, termed _ASIDLEN_, may be determined by writing one to every bit position in the ASID field, then reading back the value in `satp` to see which bit positions in the ASID field hold a one.\",\n \"line_number\": 831,\n \"parameter_name\": \"ASID_WIDTH\",\n \"existing_udb_name\": \"ASID_WIDTH\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"range\",\n \"confidence\": \"high\",\n \"reasoning\": \"ASIDLEN is implementation-defined and can range from 0 to ASIDMAX (9 for Sv32, 16 for others). This is a direct implementation choice of how many ASID bits to implement.\"\n },\n {\n \"excerpt\": \"For implementations that make `satp`.MODE read-only zero (always Bare), attempts to execute an SFENCE.VMA instruction might raise an illegal-instruction exception.\",\n \"line_number\": 1169,\n \"parameter_name\": \"TRAP_ON_SFENCE_VMA_WHEN_SATP_MODE_IS_READ_ONLY\",\n \"existing_udb_name\": \"TRAP_ON_SFENCE_VMA_WHEN_SATP_MODE_IS_READ_ONLY\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"Implementation choice of whether to trap on SFENCE.VMA when satp.MODE is read-only zero. The word 'might' indicates this is optional behavior.\"\n },\n {\n \"excerpt\": \"The 20-bit VPN is translated into a 22-bit physical page number (PPN)\",\n \"line_number\": 1207,\n \"parameter_name\": \"SATP_PPN_SV32_SIZE\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"The PPN size for Sv32 is specified as 22 bits. This is a fixed architectural parameter for Sv32 implementations.\"\n },\n {\n \"excerpt\": \"The 27-bit VPN is translated into a 44-bit PPN via a three-level page table\",\n \"line_number\": 1598,\n \"parameter_name\": \"SATP_PPN_SV39_SV48_SV57_SIZE\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"The PPN size for Sv39, Sv48, and Sv57 is specified as 44 bits. This is a fixed architectural parameter for these implementations.\"\n },\n {\n \"excerpt\": \"Both `RCID` and `MCID` are WARL fields.\",\n \"line_number\": 2583,\n \"parameter_name\": \"SRMCFG_RCID_MCID_LEGAL_VALUES\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"Both RCID and MCID fields in srmcfg are explicitly described as WARL, meaning implementations can restrict which values are legal for each field.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"Supervisor mode is deliberately restricted in terms of interactions with underlying physical hardware, such as physical memory and device interrupts, to support clean virtualization.\",\n \"line_number\": 8,\n \"reason\": \"This is in a [NOTE] block, which is non-normative. Parameters are never extracted from NOTE blocks.\"\n },\n {\n \"excerpt\": \"When a trap is taken, SPP is set to 0 if the trap originated from user mode, or 1 otherwise.\",\n \"line_number\": 77,\n \"reason\": \"This describes fixed behavior that occurs when a trap is taken. It is not an implementation choice but a required specification.\"\n },\n {\n \"excerpt\": \"When MODE=Direct, all traps into supervisor mode cause the `pc` to be set to the address in the BASE field.\",\n \"line_number\": 293,\n \"reason\": \"This describes what happens when stvec.MODE has a specific value. The behavior is determined by the CSR field value at runtime, not by an implementation choice.\"\n },\n {\n \"excerpt\": \"Software may determine the PMP granularity by writing zero to `pmp0cfg`, then writing all ones to `pmpaddr0`, then reading back `pmpaddr0`.\",\n \"line_number\": 831,\n \"reason\": \"Here 'may' means 'is allowed to' (permission), not 'might or might not' (optionality). This describes a software technique, not an implementation-defined parameter.\"\n }\n ]\n}\n```", + "input_tokens": 37814, + "output_tokens": 4322, + "latency_ms": 152841, + "timestamp": "2026-04-15T14:48:26.174107+00:00", + "error": null, + "retry_count": 1 + }, + { + "chunk_id": "chunk_056", + "source_file": "unpriv-cfi.adoc", + "start_line": 1, + "end_line": 894, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "The Zicfilp extension, when enabled, determines if an indirect call or an indirect jump must land on a landing pad, as specified in <>. If `is_lp_expected` is 1, then the hart updates the `ELP` to `LP_EXPECTED`.", + "line_number": 158, + "parameter_name": "ZICFILP_ENABLED", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether to enable the Zicfilp extension. This is a direct implementation choice that affects whether landing pad enforcement is active." + }, + { + "excerpt": "The `LPAD` instruction (See <>) is encoded using the `AUIPC` major opcode with _rd_=`x0`.", + "line_number": 73, + "parameter_name": "LPAD_ENCODING", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "This defines the specific encoding choice for the LPAD instruction using AUIPC with rd=x0. This is a normative encoding decision." + }, + { + "excerpt": "To support labeled landing pads, the indirect call/jump sites establish an expected landing pad label (e.g., using the `LUI` instruction) in the bits 31:12 of the `x7` register.", + "line_number": 200, + "parameter_name": "LPAD_LABEL_SUPPORT", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "The implementation may choose whether to support labeled landing pads. The text describes the mechanism but doesn't explicitly state it's optional, though the context suggests it's an implementation choice." + }, + { + "excerpt": "The `LPAD` instruction is encoded with a 20-bit immediate value called the landing-pad-label (`LPL`) that is matched to the expected landing pad label. When `LPL` is encoded as zero, the `LPAD` instruction does not perform the label check and in programs built with this single label mode of operation the indirect call/jump sites do not need to establish an expected landing pad label value in `x7`.", + "line_number": 202, + "parameter_name": "LPAD_LPL_ENCODING", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "This defines how the 20-bit landing pad label is encoded in the LPAD instruction. The encoding format is a normative implementation detail." + }, + { + "excerpt": "When Zicfilp is enabled, `LPAD` is the only instruction allowed to execute when the `ELP` state is `LP_EXPECTED`. If Zicfilp is not enabled then the instruction is a no-op.", + "line_number": 235, + "parameter_name": "LPAD_EXECUTION_CONTROL", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "This defines the normative behavior of LPAD instruction execution based on whether Zicfilp is enabled. The implementation controls this behavior." + }, + { + "excerpt": "The Zicfiss instructions, except `SSAMOSWAP.W/D`, are encoded using a subset of May-Be-Operation instructions defined by the Zimop and Zcmop extensions.", + "line_number": 334, + "parameter_name": "ZICFISS_ENCODING_SCHEME", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "high", + "reasoning": "This defines the encoding scheme choice for Zicfiss instructions, using Zimop/Zcmop encodings. This is a normative encoding decision." + }, + { + "excerpt": "The `ssp` CSR is an unprivileged read-write (URW) CSR that reads and writes `XLEN` low order bits of the shadow stack pointer (`ssp`).", + "line_number": 378, + "parameter_name": "SSP_CSR_ACCESS", + "existing_udb_name": null, + "class": "NORM_CSR_RW", + "value_type": "binary", + "confidence": "high", + "reasoning": "This defines that the ssp CSR is read-write. The implementation could potentially make it read-only, making this a CSR access control parameter." + }, + { + "excerpt": "The CSR address is 0x011.", + "line_number": 379, + "parameter_name": "SSP_CSR_ADDRESS", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "This defines the specific CSR address for the ssp register. This is a normative addressing choice." + }, + { + "excerpt": "There is no high CSR defined as the `ssp` is always as wide as the `XLEN` of the current privilege mode.", + "line_number": 380, + "parameter_name": "SSP_CSR_WIDTH", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "This defines that ssp width matches XLEN with no high CSR. This is a normative width decision." + }, + { + "excerpt": "The bits 1:0 of `ssp` are read-only zero. If the UXLEN or SXLEN may never be 32, then the bit 2 is also read-only zero.", + "line_number": 381, + "parameter_name": "SSP_LOW_BITS_RO", + "existing_udb_name": null, + "class": "NORM_CSR_RW", + "value_type": "bitmask", + "confidence": "high", + "reasoning": "This defines which low-order bits of ssp are read-only zero, with bit 2 being conditionally read-only based on XLEN support. This is a CSR field access control parameter." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "Control-flow Integrity (CFI) capabilities help defend against Return-Oriented Programming (ROP) and Call/Jump-Oriented Programming (COP/JOP) style control-flow subversion attacks.", + "line_number": 3, + "reason": "This is descriptive text explaining what CFI does, not an implementation choice or parameter." + }, + { + "excerpt": "The term _call_ is used to refer to a `JAL` or `JALR` instruction with a link register as destination, i.e., _rd_\u2260`x0`.", + "line_number": 37, + "reason": "This is a definition of terminology, not an implementation parameter. It defines what the spec means by 'call'." + }, + { + "excerpt": "When `ELP` is set to `LP_EXPECTED`, if the next instruction in the instruction stream is not 4-byte aligned, or is not `LPAD`, or if the landing pad label encoded in `LPAD` is not zero and does not match the expected landing pad label in bits 31:12 of the `x7` register, then a software-check exception (cause=18) with `__x__tval` set to \"landing pad fault (code=2)\" is raised else the `ELP` is updated to `NO_LP_EXPECTED`.", + "line_number": 207, + "reason": "This describes the behavioral consequences when ELP is LP_EXPECTED. It's describing what happens given a state, not defining an implementation choice." + }, + { + "excerpt": "When Zicfiss is enabled, each function that needs to spill the link register, typically non-leaf functions, store the link register value to the regular stack and a shadow copy of the link register value to the shadow stack when the function is entered (the prologue).", + "line_number": 310, + "reason": "This describes software behavior and programming conventions when using Zicfiss, not an architectural implementation parameter." + }, + { + "excerpt": "The `ssp` is decremented by `SSPUSH` and `C.SSPUSH` only if the store to the shadow stack completes successfully.", + "line_number": 456, + "reason": "This describes the operational behavior of the SSPUSH instruction - what happens during execution, not an implementation choice." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"The Zicfilp extension, when enabled, determines if an indirect call or an indirect jump must land on a landing pad, as specified in <>. If `is_lp_expected` is 1, then the hart updates the `ELP` to `LP_EXPECTED`.\",\n \"line_number\": 158,\n \"parameter_name\": \"ZICFILP_ENABLED\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether to enable the Zicfilp extension. This is a direct implementation choice that affects whether landing pad enforcement is active.\"\n },\n {\n \"excerpt\": \"The `LPAD` instruction (See <>) is encoded using the `AUIPC` major opcode with _rd_=`x0`.\",\n \"line_number\": 73,\n \"parameter_name\": \"LPAD_ENCODING\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"This defines the specific encoding choice for the LPAD instruction using AUIPC with rd=x0. This is a normative encoding decision.\"\n },\n {\n \"excerpt\": \"To support labeled landing pads, the indirect call/jump sites establish an expected landing pad label (e.g., using the `LUI` instruction) in the bits 31:12 of the `x7` register.\",\n \"line_number\": 200,\n \"parameter_name\": \"LPAD_LABEL_SUPPORT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The implementation may choose whether to support labeled landing pads. The text describes the mechanism but doesn't explicitly state it's optional, though the context suggests it's an implementation choice.\"\n },\n {\n \"excerpt\": \"The `LPAD` instruction is encoded with a 20-bit immediate value called the landing-pad-label (`LPL`) that is matched to the expected landing pad label. When `LPL` is encoded as zero, the `LPAD` instruction does not perform the label check and in programs built with this single label mode of operation the indirect call/jump sites do not need to establish an expected landing pad label value in `x7`.\",\n \"line_number\": 202,\n \"parameter_name\": \"LPAD_LPL_ENCODING\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"This defines how the 20-bit landing pad label is encoded in the LPAD instruction. The encoding format is a normative implementation detail.\"\n },\n {\n \"excerpt\": \"When Zicfilp is enabled, `LPAD` is the only instruction allowed to execute when the `ELP` state is `LP_EXPECTED`. If Zicfilp is not enabled then the instruction is a no-op.\",\n \"line_number\": 235,\n \"parameter_name\": \"LPAD_EXECUTION_CONTROL\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"This defines the normative behavior of LPAD instruction execution based on whether Zicfilp is enabled. The implementation controls this behavior.\"\n },\n {\n \"excerpt\": \"The Zicfiss instructions, except `SSAMOSWAP.W/D`, are encoded using a subset of May-Be-Operation instructions defined by the Zimop and Zcmop extensions.\",\n \"line_number\": 334,\n \"parameter_name\": \"ZICFISS_ENCODING_SCHEME\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"This defines the encoding scheme choice for Zicfiss instructions, using Zimop/Zcmop encodings. This is a normative encoding decision.\"\n },\n {\n \"excerpt\": \"The `ssp` CSR is an unprivileged read-write (URW) CSR that reads and writes `XLEN` low order bits of the shadow stack pointer (`ssp`).\",\n \"line_number\": 378,\n \"parameter_name\": \"SSP_CSR_ACCESS\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"This defines that the ssp CSR is read-write. The implementation could potentially make it read-only, making this a CSR access control parameter.\"\n },\n {\n \"excerpt\": \"The CSR address is 0x011.\",\n \"line_number\": 379,\n \"parameter_name\": \"SSP_CSR_ADDRESS\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"This defines the specific CSR address for the ssp register. This is a normative addressing choice.\"\n },\n {\n \"excerpt\": \"There is no high CSR defined as the `ssp` is always as wide as the `XLEN` of the current privilege mode.\",\n \"line_number\": 380,\n \"parameter_name\": \"SSP_CSR_WIDTH\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"This defines that ssp width matches XLEN with no high CSR. This is a normative width decision.\"\n },\n {\n \"excerpt\": \"The bits 1:0 of `ssp` are read-only zero. If the UXLEN or SXLEN may never be 32, then the bit 2 is also read-only zero.\",\n \"line_number\": 381,\n \"parameter_name\": \"SSP_LOW_BITS_RO\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"bitmask\",\n \"confidence\": \"high\",\n \"reasoning\": \"This defines which low-order bits of ssp are read-only zero, with bit 2 being conditionally read-only based on XLEN support. This is a CSR field access control parameter.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"Control-flow Integrity (CFI) capabilities help defend against Return-Oriented Programming (ROP) and Call/Jump-Oriented Programming (COP/JOP) style control-flow subversion attacks.\",\n \"line_number\": 3,\n \"reason\": \"This is descriptive text explaining what CFI does, not an implementation choice or parameter.\"\n },\n {\n \"excerpt\": \"The term _call_ is used to refer to a `JAL` or `JALR` instruction with a link register as destination, i.e., _rd_\u2260`x0`.\",\n \"line_number\": 37,\n \"reason\": \"This is a definition of terminology, not an implementation parameter. It defines what the spec means by 'call'.\"\n },\n {\n \"excerpt\": \"When `ELP` is set to `LP_EXPECTED`, if the next instruction in the instruction stream is not 4-byte aligned, or is not `LPAD`, or if the landing pad label encoded in `LPAD` is not zero and does not match the expected landing pad label in bits 31:12 of the `x7` register, then a software-check exception (cause=18) with `__x__tval` set to \\\"landing pad fault (code=2)\\\" is raised else the `ELP` is updated to `NO_LP_EXPECTED`.\",\n \"line_number\": 207,\n \"reason\": \"This describes the behavioral consequences when ELP is LP_EXPECTED. It's describing what happens given a state, not defining an implementation choice.\"\n },\n {\n \"excerpt\": \"When Zicfiss is enabled, each function that needs to spill the link register, typically non-leaf functions, store the link register value to the regular stack and a shadow copy of the link register value to the shadow stack when the function is entered (the prologue).\",\n \"line_number\": 310,\n \"reason\": \"This describes software behavior and programming conventions when using Zicfiss, not an architectural implementation parameter.\"\n },\n {\n \"excerpt\": \"The `ssp` is decremented by `SSPUSH` and `C.SSPUSH` only if the store to the shadow stack completes successfully.\",\n \"line_number\": 456,\n \"reason\": \"This describes the operational behavior of the SSPUSH instruction - what happens during execution, not an implementation choice.\"\n }\n ]\n}\n```", + "input_tokens": 17556, + "output_tokens": 2282, + "latency_ms": 47620, + "timestamp": "2026-04-15T14:47:20.681307+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_057", + "source_file": "v-st-ext.adoc", + "start_line": 1, + "end_line": 3393, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "The maximum size in bits of a vector element that any operation can produce or consume, _ELEN_ >= 8, which must be a power of 2.", + "line_number": 22, + "parameter_name": "ELEN", + "existing_udb_name": "ELEN", + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "ELEN is a direct implementation parameter defining the maximum element size. It has constraints (>= 8, power of 2) but the specific value is chosen by the implementer." + }, + { + "excerpt": "The number of bits in a single vector register, _VLEN_ >= ELEN, which must be a power of 2, and must be no greater than 2^16.", + "line_number": 23, + "parameter_name": "VLEN", + "existing_udb_name": "VLEN", + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "VLEN is a direct implementation parameter defining the vector register size. It has constraints (>= ELEN, power of 2, <= 2^16) but the specific value is chosen by the implementer." + }, + { + "excerpt": "Implementations may have a writable `misa.V` field.", + "line_number": 108, + "parameter_name": "MUTABLE_MISA_V", + "existing_udb_name": "MUTABLE_MISA_V", + "class": "NORM_CSR_RW", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether misa.V is read-only or read-write. This is a binary choice about the mutability of the field." + }, + { + "excerpt": "Analogous to the way in which the floating-point unit is handled, the `mstatus.VS` field may exist even if `misa.V` is clear.", + "line_number": 108, + "parameter_name": "MSTATUS_VS_EXISTS", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether mstatus.VS field exists when misa.V is clear. This is a direct architectural choice." + }, + { + "excerpt": "Implementations may also change `mstatus.VS` or `vsstatus.VS` from Initial or Clean to Dirty at any time, even when there is no change in vector state.", + "line_number": 127, + "parameter_name": "HW_MSTATUS_VS_DIRTY_UPDATE", + "existing_udb_name": "HW_MSTATUS_VS_DIRTY_UPDATE", + "class": "SW_RULE", + "value_type": "enum", + "confidence": "medium", + "reasoning": "Whether hardware updates mstatus.VS to Dirty is implementation-defined, but software can handle this deterministically by checking and managing VS state with proper fencing." + }, + { + "excerpt": "A small implementation supporting ELEN=32 requires only seven bits of state in `vtype`: two bits for `ma` and `ta`, two bits for `vsew[1:0]` and three bits for `vlmul[2:0]`. The illegal value represented by `vill` can be internally encoded using the illegal 64-bit combination in `vsew[1:0]` without requiring an additional storage bit to hold `vill`.", + "line_number": 175, + "parameter_name": "VILL_IMPLICIT_ENCODING", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "The implementation can choose to encode vill implicitly using illegal vsew combinations rather than using an explicit bit. This is an internal encoding choice." + }, + { + "excerpt": "Implementations must support LMUL integer values of 1, 2, 4, and 8.", + "line_number": 254, + "parameter_name": "SUPPORTED_LMUL_VALUES", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "set", + "confidence": "high", + "reasoning": "This is a fixed requirement that all implementations must support these LMUL values. It is not a parameter as there is no implementation choice." + }, + { + "excerpt": "Implementations may set `vill` in either case.", + "line_number": 1659, + "parameter_name": "RESERVED_VILL_SET", + "existing_udb_name": "RESERVED_VILL_SET_PARAM", + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "The implementation chooses whether to set vill when reserved vsetvl encodings are used. This is a direct implementation choice for handling reserved cases." + }, + { + "excerpt": "All vector loads and stores may generate and accept a non-zero `vstart` value.", + "line_number": 1774, + "parameter_name": "VECTOR_LS_VSTART_SUPPORT", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "The implementation may choose whether vector load/store instructions support non-zero vstart values. The word 'may' indicates this is optional." + }, + { + "excerpt": "Load instructions may overwrite active destination vector register group elements past the element index at which the trap is reported.", + "line_number": 2095, + "parameter_name": "VECTOR_LS_OVERWRITE_PAST_TRAP", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "The implementation may choose whether to overwrite elements past a trap point. This is an implementation-defined behavior choice." + }, + { + "excerpt": "Similarly, fault-only-first load instructions may update active destination elements past the element that causes trimming of the vector length (but not past the original vector length). The values of these spurious updates do not have to correspond to the values in memory at the addressed memory locations.", + "line_number": 2096, + "parameter_name": "VECTOR_FF_PAST_TRAP", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "The implementation may choose whether fault-only-first loads update elements past the trimming point. This is an implementation-defined behavior choice." + }, + { + "excerpt": "If a trap occurs during access to a segment, it is implementation-defined whether a subset of the faulting segment's accesses are performed before the trap is taken.", + "line_number": 2372, + "parameter_name": "VECTOR_LS_SEG_PARTIAL_ACCESS", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "The implementation chooses whether to perform partial segment accesses before taking a trap. This is explicitly marked as implementation-defined." + }, + { + "excerpt": "In both cases, it is implementation-defined whether a subset of the segment is loaded.", + "line_number": 2434, + "parameter_name": "VECTOR_FF_SEG_PARTIAL_ACCESS", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "The implementation chooses whether to perform partial segment loads in fault-only-first operations. This is explicitly marked as implementation-defined." + }, + { + "excerpt": "These instructions may overwrite destination vector register group elements past the point at which a trap is reported or past the point at which vector length is trimmed.", + "line_number": 2437, + "parameter_name": "VECTOR_LS_SEG_FF_OVERLOAD", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "The implementation may choose whether fault-only-first segment loads overwrite elements past trap/trim points. This is an implementation choice." + }, + { + "excerpt": "Implementations are allowed to raise a misaligned address exception on whole register loads and stores if the base address is not naturally aligned to the larger of the size of the encoded EEW in bytes (EEW/8) or the implementation's smallest supported SEW size in bytes (SEW_MIN/8).", + "line_number": 2598, + "parameter_name": "VECTOR_LS_WHOLEREG_MISALIGNED_EXCEPTION", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "The implementation chooses whether to raise misaligned exceptions for whole register loads/stores. This is an implementation choice about exception behavior." + }, + { + "excerpt": "If an element accessed by a vector memory instruction is not naturally aligned to the size of the element, either the element is transferred successfully or an address-misaligned exception is raised on that element.", + "line_number": 2650, + "parameter_name": "VECTOR_LS_MISALIGNED_EXCEPTION", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "The implementation chooses whether to support misaligned vector memory accesses or raise exceptions. This is an implementation choice about memory access behavior." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "The base vector extension is intended to provide general support for data-parallel execution within the 32-bit instruction encoding space, with later vector extensions supporting richer functionality for certain domains.", + "line_number": 4, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks." + }, + { + "excerpt": "When MODE=Direct, all traps into machine mode cause the `pc` to be set to the address in the BASE field.", + "line_number": 1254, + "reason": "This describes what happens when mtvec.MODE has a specific value. The behavior is determined by the CSR field value at runtime, not by an implementation choice." + }, + { + "excerpt": "The vector extension adds 32 architectural vector registers, `v0`-`v31` to the base scalar RISC-V ISA.", + "line_number": 75, + "reason": "This is a fixed requirement that all implementations must have 32 vector registers. There is no implementation choice here." + }, + { + "excerpt": "All systems must support all four options:", + "line_number": 364, + "reason": "This is a fixed requirement ('must support') that applies to all implementations. There is no implementation choice here." + }, + { + "excerpt": "Software may determine the PMP granularity by writing zero to `pmp0cfg`, then writing all ones to `pmpaddr0`, then reading back `pmpaddr0`.", + "line_number": 3530, + "reason": "Here 'may' means 'is allowed to' (permission), not 'might or might not' (optionality). This describes a software technique, not an implementation-defined parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"The maximum size in bits of a vector element that any operation can produce or consume, _ELEN_ >= 8, which must be a power of 2.\",\n \"line_number\": 22,\n \"parameter_name\": \"ELEN\",\n \"existing_udb_name\": \"ELEN\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"ELEN is a direct implementation parameter defining the maximum element size. It has constraints (>= 8, power of 2) but the specific value is chosen by the implementer.\"\n },\n {\n \"excerpt\": \"The number of bits in a single vector register, _VLEN_ >= ELEN, which must be a power of 2, and must be no greater than 2^16.\",\n \"line_number\": 23,\n \"parameter_name\": \"VLEN\",\n \"existing_udb_name\": \"VLEN\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"VLEN is a direct implementation parameter defining the vector register size. It has constraints (>= ELEN, power of 2, <= 2^16) but the specific value is chosen by the implementer.\"\n },\n {\n \"excerpt\": \"Implementations may have a writable `misa.V` field.\",\n \"line_number\": 108,\n \"parameter_name\": \"MUTABLE_MISA_V\",\n \"existing_udb_name\": \"MUTABLE_MISA_V\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether misa.V is read-only or read-write. This is a binary choice about the mutability of the field.\"\n },\n {\n \"excerpt\": \"Analogous to the way in which the floating-point unit is handled, the `mstatus.VS` field may exist even if `misa.V` is clear.\",\n \"line_number\": 108,\n \"parameter_name\": \"MSTATUS_VS_EXISTS\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether mstatus.VS field exists when misa.V is clear. This is a direct architectural choice.\"\n },\n {\n \"excerpt\": \"Implementations may also change `mstatus.VS` or `vsstatus.VS` from Initial or Clean to Dirty at any time, even when there is no change in vector state.\",\n \"line_number\": 127,\n \"parameter_name\": \"HW_MSTATUS_VS_DIRTY_UPDATE\",\n \"existing_udb_name\": \"HW_MSTATUS_VS_DIRTY_UPDATE\",\n \"class\": \"SW_RULE\",\n \"value_type\": \"enum\",\n \"confidence\": \"medium\",\n \"reasoning\": \"Whether hardware updates mstatus.VS to Dirty is implementation-defined, but software can handle this deterministically by checking and managing VS state with proper fencing.\"\n },\n {\n \"excerpt\": \"A small implementation supporting ELEN=32 requires only seven bits of state in `vtype`: two bits for `ma` and `ta`, two bits for `vsew[1:0]` and three bits for `vlmul[2:0]`. The illegal value represented by `vill` can be internally encoded using the illegal 64-bit combination in `vsew[1:0]` without requiring an additional storage bit to hold `vill`.\",\n \"line_number\": 175,\n \"parameter_name\": \"VILL_IMPLICIT_ENCODING\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The implementation can choose to encode vill implicitly using illegal vsew combinations rather than using an explicit bit. This is an internal encoding choice.\"\n },\n {\n \"excerpt\": \"Implementations must support LMUL integer values of 1, 2, 4, and 8.\",\n \"line_number\": 254,\n \"parameter_name\": \"SUPPORTED_LMUL_VALUES\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"This is a fixed requirement that all implementations must support these LMUL values. It is not a parameter as there is no implementation choice.\"\n },\n {\n \"excerpt\": \"Implementations may set `vill` in either case.\",\n \"line_number\": 1659,\n \"parameter_name\": \"RESERVED_VILL_SET\",\n \"existing_udb_name\": \"RESERVED_VILL_SET_PARAM\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The implementation chooses whether to set vill when reserved vsetvl encodings are used. This is a direct implementation choice for handling reserved cases.\"\n },\n {\n \"excerpt\": \"All vector loads and stores may generate and accept a non-zero `vstart` value.\",\n \"line_number\": 1774,\n \"parameter_name\": \"VECTOR_LS_VSTART_SUPPORT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The implementation may choose whether vector load/store instructions support non-zero vstart values. The word 'may' indicates this is optional.\"\n },\n {\n \"excerpt\": \"Load instructions may overwrite active destination vector register group elements past the element index at which the trap is reported.\",\n \"line_number\": 2095,\n \"parameter_name\": \"VECTOR_LS_OVERWRITE_PAST_TRAP\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The implementation may choose whether to overwrite elements past a trap point. This is an implementation-defined behavior choice.\"\n },\n {\n \"excerpt\": \"Similarly, fault-only-first load instructions may update active destination elements past the element that causes trimming of the vector length (but not past the original vector length). The values of these spurious updates do not have to correspond to the values in memory at the addressed memory locations.\",\n \"line_number\": 2096,\n \"parameter_name\": \"VECTOR_FF_PAST_TRAP\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The implementation may choose whether fault-only-first loads update elements past the trimming point. This is an implementation-defined behavior choice.\"\n },\n {\n \"excerpt\": \"If a trap occurs during access to a segment, it is implementation-defined whether a subset of the faulting segment's accesses are performed before the trap is taken.\",\n \"line_number\": 2372,\n \"parameter_name\": \"VECTOR_LS_SEG_PARTIAL_ACCESS\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The implementation chooses whether to perform partial segment accesses before taking a trap. This is explicitly marked as implementation-defined.\"\n },\n {\n \"excerpt\": \"In both cases, it is implementation-defined whether a subset of the segment is loaded.\",\n \"line_number\": 2434,\n \"parameter_name\": \"VECTOR_FF_SEG_PARTIAL_ACCESS\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The implementation chooses whether to perform partial segment loads in fault-only-first operations. This is explicitly marked as implementation-defined.\"\n },\n {\n \"excerpt\": \"These instructions may overwrite destination vector register group elements past the point at which a trap is reported or past the point at which vector length is trimmed.\",\n \"line_number\": 2437,\n \"parameter_name\": \"VECTOR_LS_SEG_FF_OVERLOAD\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The implementation may choose whether fault-only-first segment loads overwrite elements past trap/trim points. This is an implementation choice.\"\n },\n {\n \"excerpt\": \"Implementations are allowed to raise a misaligned address exception on whole register loads and stores if the base address is not naturally aligned to the larger of the size of the encoded EEW in bytes (EEW/8) or the implementation's smallest supported SEW size in bytes (SEW_MIN/8).\",\n \"line_number\": 2598,\n \"parameter_name\": \"VECTOR_LS_WHOLEREG_MISALIGNED_EXCEPTION\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The implementation chooses whether to raise misaligned exceptions for whole register loads/stores. This is an implementation choice about exception behavior.\"\n },\n {\n \"excerpt\": \"If an element accessed by a vector memory instruction is not naturally aligned to the size of the element, either the element is transferred successfully or an address-misaligned exception is raised on that element.\",\n \"line_number\": 2650,\n \"parameter_name\": \"VECTOR_LS_MISALIGNED_EXCEPTION\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The implementation chooses whether to support misaligned vector memory accesses or raise exceptions. This is an implementation choice about memory access behavior.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"The base vector extension is intended to provide general support for data-parallel execution within the 32-bit instruction encoding space, with later vector extensions supporting richer functionality for certain domains.\",\n \"line_number\": 4,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks.\"\n },\n {\n \"excerpt\": \"When MODE=Direct, all traps into machine mode cause the `pc` to be set to the address in the BASE field.\",\n \"line_number\": 1254,\n \"reason\": \"This describes what happens when mtvec.MODE has a specific value. The behavior is determined by the CSR field value at runtime, not by an implementation choice.\"\n },\n {\n \"excerpt\": \"The vector extension adds 32 architectural vector registers, `v0`-`v31` to the base scalar RISC-V ISA.\",\n \"line_number\": 75,\n \"reason\": \"This is a fixed requirement that all implementations must have 32 vector registers. There is no implementation choice here.\"\n },\n {\n \"excerpt\": \"All systems must support all four options:\",\n \"line_number\": 364,\n \"reason\": \"This is a fixed requirement ('must support') that applies to all implementations. There is no implementation choice here.\"\n },\n {\n \"excerpt\": \"Software may determine the PMP granularity by writing zero to `pmp0cfg`, then writing all ones to `pmpaddr0`, then reading back `pmpaddr0`.\",\n \"line_number\": 3530,\n \"reason\": \"Here 'may' means 'is allowed to' (permission), not 'might or might not' (optionality). This describes a software technique, not an implementation-defined parameter.\"\n }\n ]\n}\n```", + "input_tokens": 53055, + "output_tokens": 3025, + "latency_ms": 54960, + "timestamp": "2026-04-15T15:03:59.732494+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_058", + "source_file": "v-st-ext.adoc", + "start_line": 3386, + "end_line": 5396, + "content_start_line": 3394, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "Vector instructions with EGS > VLMAX are reserved.", + "line_number": 5251, + "parameter_name": "EGS_VLMAX_CONSTRAINT", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "This is a direct implementation constraint on which element group sizes are supported. The implementation chooses whether to support EGS values that exceed VLMAX." + }, + { + "excerpt": "When an operand is a vector of element groups, the `vl` setting must correspond to an integer multiple of the element group size, with other values of `vl` reserved.", + "line_number": 5270, + "parameter_name": "EGS_VL_MULTIPLE_CONSTRAINT", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "This defines a constraint on vl setting for element group instructions. The implementation must enforce this constraint, making it a direct architectural choice." + }, + { + "excerpt": "When AVL > VLMAX, the value of `vl` must be set to either VLMAX or a positive integer multiple of EGSMAX.", + "line_number": 5276, + "parameter_name": "EGSMAX_VL_SETTING", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "high", + "reasoning": "When AVL > VLMAX, the implementation has a choice between setting vl to VLMAX or to a multiple of EGSMAX. This is a direct implementation choice for vl setting behavior." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "NOTE: The 7 bit accuracy was chosen as it requires 0,1,2,3 Newton-Raphson iterations to converge to close to bfloat16, FP16, FP32, FP64 accuracy respectively.", + "line_number": 3580, + "reason": "This is inside a NOTE block, which is non-normative. It explains a design rationale but does not define an implementation parameter." + }, + { + "excerpt": "The `vmfeq` and `vmfne` raise the invalid operation exception only on signaling NaN inputs.", + "line_number": 3750, + "reason": "This describes fixed behavioral requirements that all implementations must follow. It is not an implementation choice." + }, + { + "excerpt": "The instruction copies a single SEW-wide element from index 0 of the source vector register to a destination integer register.", + "line_number": 4450, + "reason": "This describes the fixed behavior of the vmv.x.s instruction. It is not an implementation-defined parameter." + }, + { + "excerpt": "Traps on vector reduction instructions are always reported with a `vstart` of 0.", + "line_number": 4050, + "reason": "This is a fixed requirement ('always reported') that applies to all implementations. It is not a parameter." + }, + { + "excerpt": "All Zve* extensions have precise traps.", + "line_number": 5390, + "reason": "This is a fixed requirement for all Zve* extensions. There is no implementation choice here." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"Vector instructions with EGS > VLMAX are reserved.\",\n \"line_number\": 5251,\n \"parameter_name\": \"EGS_VLMAX_CONSTRAINT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"This is a direct implementation constraint on which element group sizes are supported. The implementation chooses whether to support EGS values that exceed VLMAX.\"\n },\n {\n \"excerpt\": \"When an operand is a vector of element groups, the `vl` setting must correspond to an integer multiple of the element group size, with other values of `vl` reserved.\",\n \"line_number\": 5270,\n \"parameter_name\": \"EGS_VL_MULTIPLE_CONSTRAINT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"This defines a constraint on vl setting for element group instructions. The implementation must enforce this constraint, making it a direct architectural choice.\"\n },\n {\n \"excerpt\": \"When AVL > VLMAX, the value of `vl` must be set to either VLMAX or a positive integer multiple of EGSMAX.\",\n \"line_number\": 5276,\n \"parameter_name\": \"EGSMAX_VL_SETTING\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"When AVL > VLMAX, the implementation has a choice between setting vl to VLMAX or to a multiple of EGSMAX. This is a direct implementation choice for vl setting behavior.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"NOTE: The 7 bit accuracy was chosen as it requires 0,1,2,3 Newton-Raphson iterations to converge to close to bfloat16, FP16, FP32, FP64 accuracy respectively.\",\n \"line_number\": 3580,\n \"reason\": \"This is inside a NOTE block, which is non-normative. It explains a design rationale but does not define an implementation parameter.\"\n },\n {\n \"excerpt\": \"The `vmfeq` and `vmfne` raise the invalid operation exception only on signaling NaN inputs.\",\n \"line_number\": 3750,\n \"reason\": \"This describes fixed behavioral requirements that all implementations must follow. It is not an implementation choice.\"\n },\n {\n \"excerpt\": \"The instruction copies a single SEW-wide element from index 0 of the source vector register to a destination integer register.\",\n \"line_number\": 4450,\n \"reason\": \"This describes the fixed behavior of the vmv.x.s instruction. It is not an implementation-defined parameter.\"\n },\n {\n \"excerpt\": \"Traps on vector reduction instructions are always reported with a `vstart` of 0.\",\n \"line_number\": 4050,\n \"reason\": \"This is a fixed requirement ('always reported') that applies to all implementations. It is not a parameter.\"\n },\n {\n \"excerpt\": \"All Zve* extensions have precise traps.\",\n \"line_number\": 5390,\n \"reason\": \"This is a fixed requirement for all Zve* extensions. There is no implementation choice here.\"\n }\n ]\n}\n```", + "input_tokens": 34287, + "output_tokens": 886, + "latency_ms": 38178, + "timestamp": "2026-04-15T14:48:38.239723+00:00", + "error": null, + "retry_count": 1 + }, + { + "chunk_id": "chunk_059", + "source_file": "vector-crypto.adoc", + "start_line": 1, + "end_line": 3340, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "The Zvknhb and Zvbc Vector Crypto Extensions --and accordingly the composite extensions Zvkn, Zvknc, Zvkng, and Zvksc-- depend on Zve64x.", + "line_number": 372, + "parameter_name": "ZVE64X_DEPENDENCY", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "This is a normative requirement that certain extensions depend on Zve64x. The implementation chooses whether to support these extensions, which inherently requires supporting Zve64x." + }, + { + "excerpt": "All of the other Vector Crypto Extensions depend on `Zve32x`.", + "line_number": 374, + "parameter_name": "ZVE32X_DEPENDENCY", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "This is a normative requirement that other vector crypto extensions depend on Zve32x. The implementation chooses whether to support these extensions." + }, + { + "excerpt": "These instructions are only defined for `SEW`=64.", + "line_number": 421, + "parameter_name": "ZVBC_SEW_CONSTRAINT", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "The Zvbc instructions have a constraint that SEW must be 64. This defines the legal values for SEW when these instructions are executed." + }, + { + "excerpt": "All of these instructions work on 128-bit element groups comprised of four 32-bit elements.", + "line_number": 481, + "parameter_name": "ZVKG_ELEMENT_GROUP_SIZE", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "This defines the fixed element group structure for Zvkg instructions - 128-bit groups with four 32-bit elements. This is an architectural parameter of the instruction format." + }, + { + "excerpt": "All of these instructions work on 128-bit element groups comprised of four 32-bit elements.", + "line_number": 520, + "parameter_name": "ZVKNED_ELEMENT_GROUP_SIZE", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "This defines the fixed element group structure for Zvkned (AES) instructions - 128-bit groups with four 32-bit elements." + }, + { + "excerpt": "SHA-256: these instructions work on 128-bit element groups comprised of four 32-bit elements.", + "line_number": 560, + "parameter_name": "ZVKNHA_ZVKNHB_SHA256_ELEMENT_GROUP_SIZE", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "This defines the element group structure for SHA-256 instructions in Zvknh[ab] extensions." + }, + { + "excerpt": "SHA-512: these instructions work on 256-bit element groups comprised of four 64-bit elements.", + "line_number": 561, + "parameter_name": "ZVKNHB_SHA512_ELEMENT_GROUP_SIZE", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "This defines the element group structure for SHA-512 instructions in Zvknhb extension." + }, + { + "excerpt": "All of these instructions work on 128-bit element groups comprised of four 32-bit elements.", + "line_number": 625, + "parameter_name": "ZVKSED_ELEMENT_GROUP_SIZE", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "This defines the fixed element group structure for Zvksed (SM4) instructions - 128-bit groups with four 32-bit elements." + }, + { + "excerpt": "All of these instructions work on 256-bit element groups comprised of eight 32-bit elements.", + "line_number": 665, + "parameter_name": "ZVKSH_ELEMENT_GROUP_SIZE", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "This defines the fixed element group structure for Zvksh (SM3) instructions - 256-bit groups with eight 32-bit elements." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "Where variables are concatenated, the order shown is how they would appear in a vector register from left to right.", + "line_number": 85, + "reason": "This is inside a [NOTE] block, which is non-normative informational content." + }, + { + "excerpt": "For all of the vector crypto instructions in this specification, `EEW`=`SEW`.", + "line_number": 179, + "reason": "This is a fixed requirement that applies to ALL implementations - not a parameter choice." + }, + { + "excerpt": "Instructions that violate the `vl` or `vstart` requirements are _reserved_.", + "line_number": 201, + "reason": "This describes what happens when constraints are violated - it's a behavioral rule, not an implementation choice." + }, + { + "excerpt": "To help avoid side-channel timing attacks, these instructions shall be implemented with data-independent timing.", + "line_number": 489, + "reason": "This is a fixed security requirement that all implementations must satisfy - not a parameter." + }, + { + "excerpt": "The number of element groups to be processed is `vl`/`EGS`.", + "line_number": 491, + "reason": "This describes runtime behavior controlled by the vl CSR value, not an implementation-defined parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"The Zvknhb and Zvbc Vector Crypto Extensions --and accordingly the composite extensions Zvkn, Zvknc, Zvkng, and Zvksc-- depend on Zve64x.\",\n \"line_number\": 372,\n \"parameter_name\": \"ZVE64X_DEPENDENCY\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"This is a normative requirement that certain extensions depend on Zve64x. The implementation chooses whether to support these extensions, which inherently requires supporting Zve64x.\"\n },\n {\n \"excerpt\": \"All of the other Vector Crypto Extensions depend on `Zve32x`.\",\n \"line_number\": 374,\n \"parameter_name\": \"ZVE32X_DEPENDENCY\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"This is a normative requirement that other vector crypto extensions depend on Zve32x. The implementation chooses whether to support these extensions.\"\n },\n {\n \"excerpt\": \"These instructions are only defined for `SEW`=64.\",\n \"line_number\": 421,\n \"parameter_name\": \"ZVBC_SEW_CONSTRAINT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"The Zvbc instructions have a constraint that SEW must be 64. This defines the legal values for SEW when these instructions are executed.\"\n },\n {\n \"excerpt\": \"All of these instructions work on 128-bit element groups comprised of four 32-bit elements.\",\n \"line_number\": 481,\n \"parameter_name\": \"ZVKG_ELEMENT_GROUP_SIZE\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"This defines the fixed element group structure for Zvkg instructions - 128-bit groups with four 32-bit elements. This is an architectural parameter of the instruction format.\"\n },\n {\n \"excerpt\": \"All of these instructions work on 128-bit element groups comprised of four 32-bit elements.\",\n \"line_number\": 520,\n \"parameter_name\": \"ZVKNED_ELEMENT_GROUP_SIZE\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"This defines the fixed element group structure for Zvkned (AES) instructions - 128-bit groups with four 32-bit elements.\"\n },\n {\n \"excerpt\": \"SHA-256: these instructions work on 128-bit element groups comprised of four 32-bit elements.\",\n \"line_number\": 560,\n \"parameter_name\": \"ZVKNHA_ZVKNHB_SHA256_ELEMENT_GROUP_SIZE\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"This defines the element group structure for SHA-256 instructions in Zvknh[ab] extensions.\"\n },\n {\n \"excerpt\": \"SHA-512: these instructions work on 256-bit element groups comprised of four 64-bit elements.\",\n \"line_number\": 561,\n \"parameter_name\": \"ZVKNHB_SHA512_ELEMENT_GROUP_SIZE\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"This defines the element group structure for SHA-512 instructions in Zvknhb extension.\"\n },\n {\n \"excerpt\": \"All of these instructions work on 128-bit element groups comprised of four 32-bit elements.\",\n \"line_number\": 625,\n \"parameter_name\": \"ZVKSED_ELEMENT_GROUP_SIZE\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"This defines the fixed element group structure for Zvksed (SM4) instructions - 128-bit groups with four 32-bit elements.\"\n },\n {\n \"excerpt\": \"All of these instructions work on 256-bit element groups comprised of eight 32-bit elements.\",\n \"line_number\": 665,\n \"parameter_name\": \"ZVKSH_ELEMENT_GROUP_SIZE\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"This defines the fixed element group structure for Zvksh (SM3) instructions - 256-bit groups with eight 32-bit elements.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"Where variables are concatenated, the order shown is how they would appear in a vector register from left to right.\",\n \"line_number\": 85,\n \"reason\": \"This is inside a [NOTE] block, which is non-normative informational content.\"\n },\n {\n \"excerpt\": \"For all of the vector crypto instructions in this specification, `EEW`=`SEW`.\",\n \"line_number\": 179,\n \"reason\": \"This is a fixed requirement that applies to ALL implementations - not a parameter choice.\"\n },\n {\n \"excerpt\": \"Instructions that violate the `vl` or `vstart` requirements are _reserved_.\",\n \"line_number\": 201,\n \"reason\": \"This describes what happens when constraints are violated - it's a behavioral rule, not an implementation choice.\"\n },\n {\n \"excerpt\": \"To help avoid side-channel timing attacks, these instructions shall be implemented with data-independent timing.\",\n \"line_number\": 489,\n \"reason\": \"This is a fixed security requirement that all implementations must satisfy - not a parameter.\"\n },\n {\n \"excerpt\": \"The number of element groups to be processed is `vl`/`EGS`.\",\n \"line_number\": 491,\n \"reason\": \"This describes runtime behavior controlled by the vl CSR value, not an implementation-defined parameter.\"\n }\n ]\n}\n```", + "input_tokens": 39472, + "output_tokens": 1666, + "latency_ms": 106872, + "timestamp": "2026-04-15T14:50:28.153385+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_060", + "source_file": "vector-crypto.adoc", + "start_line": 3311, + "end_line": 4966, + "content_start_line": 3341, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "`zvknha`: `SEW` is any value other than 32", + "line_number": 3348, + "parameter_name": "ZVKNHA_SEW_SUPPORT", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "high", + "reasoning": "The zvknha extension only supports SEW=32 for vsha2ms.vv, making this a direct implementation choice about which SEW values are supported." + }, + { + "excerpt": "`zvknhb`: `SEW` is any value other than 32 or 64", + "line_number": 3349, + "parameter_name": "ZVKNHB_SEW_SUPPORT", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "high", + "reasoning": "The zvknhb extension supports SEW=32 and SEW=64 for vsha2ms.vv, making this a direct implementation choice about which SEW values are supported." + }, + { + "excerpt": "`SEW` is any value other than 32", + "line_number": 3421, + "parameter_name": "VSM3C_SEW_SUPPORT", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "high", + "reasoning": "The vsm3c.vi instruction only supports SEW=32, making this a direct implementation choice about which SEW values are supported." + }, + { + "excerpt": "`SEW` is any value other than 32", + "line_number": 3540, + "parameter_name": "VSM3ME_SEW_SUPPORT", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "high", + "reasoning": "The vsm3me.vv instruction only supports SEW=32, making this a direct implementation choice about which SEW values are supported." + }, + { + "excerpt": "`SEW` is any value other than 32", + "line_number": 3680, + "parameter_name": "VSM4K_SEW_SUPPORT", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "high", + "reasoning": "The vsm4k.vi instruction only supports SEW=32, making this a direct implementation choice about which SEW values are supported." + }, + { + "excerpt": "`SEW` is any value other than 32", + "line_number": 3825, + "parameter_name": "VSM4R_SEW_SUPPORT", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "high", + "reasoning": "The vsm4r instructions only support SEW=32, making this a direct implementation choice about which SEW values are supported." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "Four rounds of SHA-256 message schedule expansion are performed (`zvknha` and `zvknhb`)", + "line_number": 3365, + "reason": "This describes the behavior when SEW=32, not an implementation choice. The parameter is which SEW values are supported, not what happens when a specific SEW is used." + }, + { + "excerpt": "Four rounds of SHA-512 message schedule expansion are performed (`zvkhnb`)", + "line_number": 3366, + "reason": "This describes the behavior when SEW=64, not an implementation choice. The parameter is which SEW values are supported, not what happens when a specific SEW is used." + }, + { + "excerpt": "The round number is provided by the 5-bit `rnds` unsigned immediate. Legal values are 0 - 31", + "line_number": 3456, + "reason": "This is a fixed requirement that all implementations must support - the legal range of the immediate field is not implementation-defined." + }, + { + "excerpt": "The Round group number (`rnd`) comes from `uimm[2:0]`; the bits in `uimm[4:3]` are ignored.", + "line_number": 3698, + "reason": "This describes the fixed encoding format, not an implementation choice. All implementations must decode the immediate field the same way." + }, + { + "excerpt": "Only the low log2(2*`SEW`) bits of the shift-amount value are used, all other bits are ignored.", + "line_number": 3970, + "reason": "This is a fixed requirement for how shift amounts are processed, not an implementation choice. All implementations must behave this way." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"`zvknha`: `SEW` is any value other than 32\",\n \"line_number\": 3348,\n \"parameter_name\": \"ZVKNHA_SEW_SUPPORT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"The zvknha extension only supports SEW=32 for vsha2ms.vv, making this a direct implementation choice about which SEW values are supported.\"\n },\n {\n \"excerpt\": \"`zvknhb`: `SEW` is any value other than 32 or 64\",\n \"line_number\": 3349,\n \"parameter_name\": \"ZVKNHB_SEW_SUPPORT\", \n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"The zvknhb extension supports SEW=32 and SEW=64 for vsha2ms.vv, making this a direct implementation choice about which SEW values are supported.\"\n },\n {\n \"excerpt\": \"`SEW` is any value other than 32\",\n \"line_number\": 3421,\n \"parameter_name\": \"VSM3C_SEW_SUPPORT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\", \n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"The vsm3c.vi instruction only supports SEW=32, making this a direct implementation choice about which SEW values are supported.\"\n },\n {\n \"excerpt\": \"`SEW` is any value other than 32\",\n \"line_number\": 3540,\n \"parameter_name\": \"VSM3ME_SEW_SUPPORT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\", \n \"confidence\": \"high\",\n \"reasoning\": \"The vsm3me.vv instruction only supports SEW=32, making this a direct implementation choice about which SEW values are supported.\"\n },\n {\n \"excerpt\": \"`SEW` is any value other than 32\",\n \"line_number\": 3680,\n \"parameter_name\": \"VSM4K_SEW_SUPPORT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\", \n \"reasoning\": \"The vsm4k.vi instruction only supports SEW=32, making this a direct implementation choice about which SEW values are supported.\"\n },\n {\n \"excerpt\": \"`SEW` is any value other than 32\",\n \"line_number\": 3825,\n \"parameter_name\": \"VSM4R_SEW_SUPPORT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"The vsm4r instructions only support SEW=32, making this a direct implementation choice about which SEW values are supported.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"Four rounds of SHA-256 message schedule expansion are performed (`zvknha` and `zvknhb`)\",\n \"line_number\": 3365,\n \"reason\": \"This describes the behavior when SEW=32, not an implementation choice. The parameter is which SEW values are supported, not what happens when a specific SEW is used.\"\n },\n {\n \"excerpt\": \"Four rounds of SHA-512 message schedule expansion are performed (`zvkhnb`)\",\n \"line_number\": 3366,\n \"reason\": \"This describes the behavior when SEW=64, not an implementation choice. The parameter is which SEW values are supported, not what happens when a specific SEW is used.\"\n },\n {\n \"excerpt\": \"The round number is provided by the 5-bit `rnds` unsigned immediate. Legal values are 0 - 31\",\n \"line_number\": 3456,\n \"reason\": \"This is a fixed requirement that all implementations must support - the legal range of the immediate field is not implementation-defined.\"\n },\n {\n \"excerpt\": \"The Round group number (`rnd`) comes from `uimm[2:0]`; the bits in `uimm[4:3]` are ignored.\",\n \"line_number\": 3698,\n \"reason\": \"This describes the fixed encoding format, not an implementation choice. All implementations must decode the immediate field the same way.\"\n },\n {\n \"excerpt\": \"Only the low log2(2*`SEW`) bits of the shift-amount value are used, all other bits are ignored.\",\n \"line_number\": 3970,\n \"reason\": \"This is a fixed requirement for how shift amounts are processed, not an implementation choice. All implementations must behave this way.\"\n }\n ]\n}\n```", + "input_tokens": 32351, + "output_tokens": 1284, + "latency_ms": 101320, + "timestamp": "2026-04-15T14:53:05.872947+00:00", + "error": null, + "retry_count": 1 + }, + { + "chunk_id": "chunk_062", + "source_file": "zabha.adoc", + "start_line": 1, + "end_line": 68, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [], + "skipped_non_parameters": [ + { + "excerpt": "Zabha omits _byte_ and _halfword_ support for `LR` and `SC` due to low utility.", + "line_number": 62, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. It explains a design decision but does not define an implementation parameter." + }, + { + "excerpt": "The same exception options as specified in the A extension are applicable in cases where the address is not naturally aligned.", + "line_number": 50, + "reason": "This refers to exception options defined elsewhere (A extension) rather than defining new implementation choices. It's a reference to existing behavior, not a new parameter." + }, + { + "excerpt": "Byte and halfword AMOs always sign-extend the value placed in `rd`, and ignore the stem:[XLEN-1:2^{(width + 3)}] bits of the original value in `rs2`.", + "line_number": 42, + "reason": "This describes fixed behavioral requirements ('always sign-extend', 'ignore') that all implementations must follow. There is no implementation choice here." + }, + { + "excerpt": "The Zabha extension depends upon the Zaamo standard extension.", + "line_number": 25, + "reason": "This is a fixed dependency requirement, not an implementation choice. All Zabha implementations must include Zaamo." + }, + { + "excerpt": "If Zacas extension is also implemented, Zabha further provides the `AMOCAS.[B|H]` instructions.", + "line_number": 30, + "reason": "This describes conditional instruction availability based on extension presence, but the choice of whether to implement Zacas is a separate parameter outside this extension's scope." + } + ], + "raw_response": "```json\n{\n \"parameters\": [],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"Zabha omits _byte_ and _halfword_ support for `LR` and `SC` due to low utility.\",\n \"line_number\": 62,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. It explains a design decision but does not define an implementation parameter.\"\n },\n {\n \"excerpt\": \"The same exception options as specified in the A extension are applicable in cases where the address is not naturally aligned.\",\n \"line_number\": 50,\n \"reason\": \"This refers to exception options defined elsewhere (A extension) rather than defining new implementation choices. It's a reference to existing behavior, not a new parameter.\"\n },\n {\n \"excerpt\": \"Byte and halfword AMOs always sign-extend the value placed in `rd`, and ignore the stem:[XLEN-1:2^{(width + 3)}] bits of the original value in `rs2`.\",\n \"line_number\": 42,\n \"reason\": \"This describes fixed behavioral requirements ('always sign-extend', 'ignore') that all implementations must follow. There is no implementation choice here.\"\n },\n {\n \"excerpt\": \"The Zabha extension depends upon the Zaamo standard extension.\",\n \"line_number\": 25,\n \"reason\": \"This is a fixed dependency requirement, not an implementation choice. All Zabha implementations must include Zaamo.\"\n },\n {\n \"excerpt\": \"If Zacas extension is also implemented, Zabha further provides the `AMOCAS.[B|H]` instructions.\",\n \"line_number\": 30,\n \"reason\": \"This describes conditional instruction availability based on extension presence, but the choice of whether to implement Zacas is a separate parameter outside this extension's scope.\"\n }\n ]\n}\n```", + "input_tokens": 6694, + "output_tokens": 457, + "latency_ms": 35380, + "timestamp": "2026-04-15T14:52:07.491013+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_063", + "source_file": "zacas.adoc", + "start_line": 1, + "end_line": 225, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [], + "skipped_non_parameters": [ + { + "excerpt": "Some algorithms may load the previous data value of a memory location into the register used as the compare data value source by a Zacas instruction.", + "line_number": 108, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. It provides informative guidance about algorithm implementation, not architectural requirements." + }, + { + "excerpt": "Just as for AMOs in the A extension, `AMOCAS.W/D/Q` requires that the address held in `rs1` be naturally aligned to the size of the operand", + "line_number": 135, + "reason": "This is a fixed requirement ('requires') that all implementations must satisfy. There is no implementation choice - all implementations must enforce natural alignment." + }, + { + "excerpt": "An unsuccessful `AMOCAS.W/D/Q` may either not perform a memory write or may write back the old value loaded from memory.", + "line_number": 150, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. It describes possible behaviors but does not define a normative implementation choice." + }, + { + "excerpt": "An `AMOCAS.W/D/Q` instruction always requires write permissions.", + "line_number": 156, + "reason": "This is a fixed requirement ('always requires') that applies to all implementations. There is no implementation choice here." + }, + { + "excerpt": "The following example code sequence illustrates the use of `AMOCAS.Q` to implement the _enqueue_ operation", + "line_number": 160, + "reason": "This text is inside a [NOTE] block and provides an example code sequence. It is non-normative and does not define any architectural parameters." + } + ], + "raw_response": "```json\n{\n \"parameters\": [],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"Some algorithms may load the previous data value of a memory location into the register used as the compare data value source by a Zacas instruction.\",\n \"line_number\": 108,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. It provides informative guidance about algorithm implementation, not architectural requirements.\"\n },\n {\n \"excerpt\": \"Just as for AMOs in the A extension, `AMOCAS.W/D/Q` requires that the address held in `rs1` be naturally aligned to the size of the operand\",\n \"line_number\": 135,\n \"reason\": \"This is a fixed requirement ('requires') that all implementations must satisfy. There is no implementation choice - all implementations must enforce natural alignment.\"\n },\n {\n \"excerpt\": \"An unsuccessful `AMOCAS.W/D/Q` may either not perform a memory write or may write back the old value loaded from memory.\",\n \"line_number\": 150,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. It describes possible behaviors but does not define a normative implementation choice.\"\n },\n {\n \"excerpt\": \"An `AMOCAS.W/D/Q` instruction always requires write permissions.\",\n \"line_number\": 156,\n \"reason\": \"This is a fixed requirement ('always requires') that applies to all implementations. There is no implementation choice here.\"\n },\n {\n \"excerpt\": \"The following example code sequence illustrates the use of `AMOCAS.Q` to implement the _enqueue_ operation\",\n \"line_number\": 160,\n \"reason\": \"This text is inside a [NOTE] block and provides an example code sequence. It is non-normative and does not define any architectural parameters.\"\n }\n ]\n}\n```", + "input_tokens": 8913, + "output_tokens": 462, + "latency_ms": 8881, + "timestamp": "2026-04-15T14:52:19.393450+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_064", + "source_file": "zalasr.adoc", + "start_line": 1, + "end_line": 135, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "If the address is not naturally aligned, an address-misaligned exception or an access-fault exception will be generated. The access-fault exception can be generated for a memory access that would otherwise be able to complete except for the misalignment, if the misaligned access should not be emulated.", + "line_number": 22, + "parameter_name": "ZALASR_MISALIGNED_BEHAVIOR", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "medium", + "reasoning": "The implementation chooses whether to generate an address-misaligned exception or an access-fault exception for misaligned Zalasr instructions. This is a direct implementation choice between two exception types." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "The Zalasr instructions always sign-extend the value placed in _rd_ and ignore the upper bits of the value of _rs2_.", + "line_number": 19, + "reason": "This is a fixed behavioral requirement that all implementations must follow - not a parameter." + }, + { + "excerpt": "The instructions in the Zalasr extension require that the address held in _rs1_ be naturally aligned to the size in bytes (2^width^) of the operand.", + "line_number": 20, + "reason": "This is a fixed requirement ('require') that applies to all implementations - not an implementation choice." + }, + { + "excerpt": "The _aq_ bit is mandatory because the two encodings that would be produced are not seen as useful at this time.", + "line_number": 71, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. It explains design rationale but does not define implementation parameters." + }, + { + "excerpt": "This instruction loads 2^width^ bytes of memory from rs1 atomically and writes the result into rd.", + "line_number": 62, + "reason": "This describes the fixed behavior of the instruction that all implementations must follow - not a parameter." + }, + { + "excerpt": "The misaligned atomicity granule PMA, defined in Volume II of this manual, optionally relaxes this alignment requirement.", + "line_number": 25, + "reason": "This refers to a PMA (Physical Memory Attribute) which is a platform-level choice outside the ISA scope, not an architectural parameter of the Zalasr extension itself." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"If the address is not naturally aligned, an address-misaligned exception or an access-fault exception will be generated. The access-fault exception can be generated for a memory access that would otherwise be able to complete except for the misalignment, if the misaligned access should not be emulated.\",\n \"line_number\": 22,\n \"parameter_name\": \"ZALASR_MISALIGNED_BEHAVIOR\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The implementation chooses whether to generate an address-misaligned exception or an access-fault exception for misaligned Zalasr instructions. This is a direct implementation choice between two exception types.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"The Zalasr instructions always sign-extend the value placed in _rd_ and ignore the upper bits of the value of _rs2_.\",\n \"line_number\": 19,\n \"reason\": \"This is a fixed behavioral requirement that all implementations must follow - not a parameter.\"\n },\n {\n \"excerpt\": \"The instructions in the Zalasr extension require that the address held in _rs1_ be naturally aligned to the size in bytes (2^width^) of the operand.\",\n \"line_number\": 20,\n \"reason\": \"This is a fixed requirement ('require') that applies to all implementations - not an implementation choice.\"\n },\n {\n \"excerpt\": \"The _aq_ bit is mandatory because the two encodings that would be produced are not seen as useful at this time.\",\n \"line_number\": 71,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. It explains design rationale but does not define implementation parameters.\"\n },\n {\n \"excerpt\": \"This instruction loads 2^width^ bytes of memory from rs1 atomically and writes the result into rd.\",\n \"line_number\": 62,\n \"reason\": \"This describes the fixed behavior of the instruction that all implementations must follow - not a parameter.\"\n },\n {\n \"excerpt\": \"The misaligned atomicity granule PMA, defined in Volume II of this manual, optionally relaxes this alignment requirement.\",\n \"line_number\": 25,\n \"reason\": \"This refers to a PMA (Physical Memory Attribute) which is a platform-level choice outside the ISA scope, not an architectural parameter of the Zalasr extension itself.\"\n }\n ]\n}\n```", + "input_tokens": 7673, + "output_tokens": 635, + "latency_ms": 19241, + "timestamp": "2026-04-15T14:52:41.669860+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_065", + "source_file": "zawrs.adoc", + "start_line": 1, + "end_line": 103, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "bounds the stall duration to an implementation-define short timeout", + "line_number": 30, + "parameter_name": "WRS_STO_TIMEOUT_DURATION", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "The timeout duration for WRS.STO is explicitly implementation-defined. This is a direct architectural parameter that implementers must choose." + }, + { + "excerpt": "it does not complete within an implementation-specific bounded time limit", + "line_number": 73, + "parameter_name": "WRS_NTO_TW_TIMEOUT", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "When TW bit is set, WRS.NTO has an implementation-specific time limit before causing an illegal-instruction exception. This is a direct architectural parameter." + }, + { + "excerpt": "the `WRS.NTO` does not complete within an implementation-specific bounded time limit", + "line_number": 79, + "parameter_name": "WRS_NTO_VTW_TIMEOUT", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "When VTW bit is set in VS/VU mode, WRS.NTO has an implementation-specific time limit before causing a virtual-instruction exception. This is a separate architectural parameter from the TW timeout." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "The instructions in the Zawrs extension are only useful in conjunction with the LR instruction, which is provided by the Zalrsc component of the A extension.", + "line_number": 37, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks." + }, + { + "excerpt": "Hart execution may be stalled while the following conditions are all satisfied", + "line_number": 58, + "reason": "This describes the behavioral conditions for stalling, not an implementation choice. The behavior is deterministic given the conditions." + }, + { + "excerpt": "While stalled, an implementation is permitted to occasionally terminate the stall and complete execution for any reason.", + "line_number": 64, + "reason": "This grants permission for early termination but doesn't define a specific parameter that implementers must choose. It's a behavioral allowance rather than a configurable parameter." + }, + { + "excerpt": "The duration of a `WRS.STO` instruction's timeout may vary significantly within and among implementations.", + "line_number": 87, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. It provides guidance about typical timeout ranges but is not a normative requirement." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"bounds the stall duration to an implementation-define short timeout\",\n \"line_number\": 30,\n \"parameter_name\": \"WRS_STO_TIMEOUT_DURATION\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"The timeout duration for WRS.STO is explicitly implementation-defined. This is a direct architectural parameter that implementers must choose.\"\n },\n {\n \"excerpt\": \"it does not complete within an implementation-specific bounded time limit\",\n \"line_number\": 73,\n \"parameter_name\": \"WRS_NTO_TW_TIMEOUT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"When TW bit is set, WRS.NTO has an implementation-specific time limit before causing an illegal-instruction exception. This is a direct architectural parameter.\"\n },\n {\n \"excerpt\": \"the `WRS.NTO` does not complete within an implementation-specific bounded time limit\",\n \"line_number\": 79,\n \"parameter_name\": \"WRS_NTO_VTW_TIMEOUT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"When VTW bit is set in VS/VU mode, WRS.NTO has an implementation-specific time limit before causing a virtual-instruction exception. This is a separate architectural parameter from the TW timeout.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"The instructions in the Zawrs extension are only useful in conjunction with the LR instruction, which is provided by the Zalrsc component of the A extension.\",\n \"line_number\": 37,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks.\"\n },\n {\n \"excerpt\": \"Hart execution may be stalled while the following conditions are all satisfied\",\n \"line_number\": 58,\n \"reason\": \"This describes the behavioral conditions for stalling, not an implementation choice. The behavior is deterministic given the conditions.\"\n },\n {\n \"excerpt\": \"While stalled, an implementation is permitted to occasionally terminate the stall and complete execution for any reason.\",\n \"line_number\": 64,\n \"reason\": \"This grants permission for early termination but doesn't define a specific parameter that implementers must choose. It's a behavioral allowance rather than a configurable parameter.\"\n },\n {\n \"excerpt\": \"The duration of a `WRS.STO` instruction's timeout may vary significantly within and among implementations.\",\n \"line_number\": 87,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. It provides guidance about typical timeout ranges but is not a normative requirement.\"\n }\n ]\n}\n```", + "input_tokens": 6901, + "output_tokens": 774, + "latency_ms": 12396, + "timestamp": "2026-04-15T14:52:57.096204+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_066", + "source_file": "zc.adoc", + "start_line": 1, + "end_line": 2587, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "It is implementation defined whether interrupts can also be taken during the sequence execution.", + "line_number": 1421, + "parameter_name": "INTERRUPTS_ALLOWED_IN_PUSHPOP", + "existing_udb_name": null, + "class": "SW_RULE", + "value_type": "binary", + "confidence": "high", + "reasoning": "Whether interrupts are allowed during PUSH/POP sequence execution is implementation-defined. This affects the observable behavior but software can handle this deterministically by proper interrupt management and understanding the re-execution semantics." + }, + { + "excerpt": "It is platform defined whether the core implementation waits for the bus responses before continuing to the final stage of the sequence, or handles errors responses after completing the PUSH instruction.", + "line_number": 1439, + "parameter_name": "PUSHPOP_BUS_FAULT_HANDLING", + "existing_udb_name": null, + "class": "SW_RULE", + "value_type": "binary", + "confidence": "high", + "reasoning": "The timing of bus fault handling (wait for responses vs. handle after completion) is platform-defined. Software can handle this deterministically by understanding the fault model and using appropriate error handling." + }, + { + "excerpt": "The jvt register is an XLEN-bit WARL read/write register that holds the jump table configuration, consisting of the jump table base address (BASE) and the jump table mode (MODE).", + "line_number": 2398, + "parameter_name": "JVT_BASE_MASK", + "existing_udb_name": "JVT_BASE_MASK", + "class": "NORM_CSR_WARL", + "value_type": "bitmask", + "confidence": "high", + "reasoning": "The jvt CSR is WARL, and the set of legal values for the BASE field (bits XLEN-1:6) varies by implementation. The parameter is the mask of supported base address bits." + }, + { + "excerpt": "If jvt is writable, the set of values the register may hold can vary by implementation.", + "line_number": 2404, + "parameter_name": "JVT_READ_ONLY", + "existing_udb_name": "JVT_READ_ONLY", + "class": "NORM_CSR_RW", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether the jvt CSR is read-only or read-write. This is a binary choice about the mutability of the register." + }, + { + "excerpt": "jvt.mode is a WARL field, so can only be programmed to modes which are implemented.", + "line_number": 2424, + "parameter_name": "JVT_BASE_TYPE", + "existing_udb_name": "JVT_BASE_TYPE", + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "medium", + "reasoning": "The jvt.mode field is WARL, and implementations choose which mode values are supported. Currently only mode 000000 (Jump table mode) is defined and must be implemented, but the parameter represents the set of legal mode values." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "NOTE: Zcb can be implemented on any CPU as the instructions are 16-bit versions of existing 32-bit instructions from the application class profile.", + "line_number": 130, + "reason": "This is inside a NOTE block and is therefore non-normative. It provides implementation guidance but does not define an architectural parameter." + }, + { + "excerpt": "This instruction loads a byte from the memory address formed by adding rs1' to the zero extended immediate uimm. The resulting byte is zero extended to XLEN bits and is written to rd'.", + "line_number": 306, + "reason": "This describes the operational behavior of the c.lbu instruction, not an implementation choice. The behavior is fixed for all implementations." + }, + { + "excerpt": "All encodings are currently reserved for all architectures, and have no conflicts with any existing extensions.", + "line_number": 126, + "reason": "This is a statement about encoding space allocation, not an implementation-defined parameter. It describes a fixed property of the specification." + }, + { + "excerpt": "For this encoding to decode as cm.jt, index<32, otherwise it decodes as cm.jalt", + "line_number": 2476, + "reason": "This describes the fixed decoding rule that applies to all implementations. It is not an implementation choice but a specification requirement." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"It is implementation defined whether interrupts can also be taken during the sequence execution.\",\n \"line_number\": 1421,\n \"parameter_name\": \"INTERRUPTS_ALLOWED_IN_PUSHPOP\",\n \"existing_udb_name\": null,\n \"class\": \"SW_RULE\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"Whether interrupts are allowed during PUSH/POP sequence execution is implementation-defined. This affects the observable behavior but software can handle this deterministically by proper interrupt management and understanding the re-execution semantics.\"\n },\n {\n \"excerpt\": \"It is platform defined whether the core implementation waits for the bus responses before continuing to the final stage of the sequence, or handles errors responses after completing the PUSH instruction.\",\n \"line_number\": 1439,\n \"parameter_name\": \"PUSHPOP_BUS_FAULT_HANDLING\",\n \"existing_udb_name\": null,\n \"class\": \"SW_RULE\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The timing of bus fault handling (wait for responses vs. handle after completion) is platform-defined. Software can handle this deterministically by understanding the fault model and using appropriate error handling.\"\n },\n {\n \"excerpt\": \"The jvt register is an XLEN-bit WARL read/write register that holds the jump table configuration, consisting of the jump table base address (BASE) and the jump table mode (MODE).\",\n \"line_number\": 2398,\n \"parameter_name\": \"JVT_BASE_MASK\",\n \"existing_udb_name\": \"JVT_BASE_MASK\",\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"bitmask\",\n \"confidence\": \"high\",\n \"reasoning\": \"The jvt CSR is WARL, and the set of legal values for the BASE field (bits XLEN-1:6) varies by implementation. The parameter is the mask of supported base address bits.\"\n },\n {\n \"excerpt\": \"If jvt is writable, the set of values the register may hold can vary by implementation.\",\n \"line_number\": 2404,\n \"parameter_name\": \"JVT_READ_ONLY\",\n \"existing_udb_name\": \"JVT_READ_ONLY\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether the jvt CSR is read-only or read-write. This is a binary choice about the mutability of the register.\"\n },\n {\n \"excerpt\": \"jvt.mode is a WARL field, so can only be programmed to modes which are implemented.\",\n \"line_number\": 2424,\n \"parameter_name\": \"JVT_BASE_TYPE\",\n \"existing_udb_name\": \"JVT_BASE_TYPE\",\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The jvt.mode field is WARL, and implementations choose which mode values are supported. Currently only mode 000000 (Jump table mode) is defined and must be implemented, but the parameter represents the set of legal mode values.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"NOTE: Zcb can be implemented on any CPU as the instructions are 16-bit versions of existing 32-bit instructions from the application class profile.\",\n \"line_number\": 130,\n \"reason\": \"This is inside a NOTE block and is therefore non-normative. It provides implementation guidance but does not define an architectural parameter.\"\n },\n {\n \"excerpt\": \"This instruction loads a byte from the memory address formed by adding rs1' to the zero extended immediate uimm. The resulting byte is zero extended to XLEN bits and is written to rd'.\",\n \"line_number\": 306,\n \"reason\": \"This describes the operational behavior of the c.lbu instruction, not an implementation choice. The behavior is fixed for all implementations.\"\n },\n {\n \"excerpt\": \"All encodings are currently reserved for all architectures, and have no conflicts with any existing extensions.\",\n \"line_number\": 126,\n \"reason\": \"This is a statement about encoding space allocation, not an implementation-defined parameter. It describes a fixed property of the specification.\"\n },\n {\n \"excerpt\": \"For this encoding to decode as cm.jt, index<32, otherwise it decodes as cm.jalt\",\n \"line_number\": 2476,\n \"reason\": \"This describes the fixed decoding rule that applies to all implementations. It is not an implementation choice but a specification requirement.\"\n }\n ]\n}\n```", + "input_tokens": 31540, + "output_tokens": 1204, + "latency_ms": 23698, + "timestamp": "2026-04-15T15:05:24.460336+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_067", + "source_file": "zfa.adoc", + "start_line": 1, + "end_line": 261, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "Other _rm_ values are _reserved_.", + "line_number": 179, + "parameter_name": "FCVTMOD_RM_RESERVED_BEHAVIOR", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "medium", + "reasoning": "The behavior when reserved rm values are used in FCVTMOD.W.D is implementation-defined. The spec states they are reserved but doesn't specify what happens when they are used." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "The set of 32 constants was chosen by examining floating-point libraries, including the C standard math library, and to optimize fixed-point to floating-point conversion.", + "line_number": 60, + "reason": "This is inside a [NOTE] block, which is non-normative. It explains the rationale for the constant selection but doesn't define an implementation parameter." + }, + { + "excerpt": "The FLI._fmt_ instructions never set any floating-point exception flags.", + "line_number": 95, + "reason": "This is a fixed requirement that applies to all implementations. There is no implementation choice - all implementations must behave this way." + }, + { + "excerpt": "Zero and infinite inputs are copied to _rd_ unmodified.", + "line_number": 118, + "reason": "This describes the required behavior for specific input values. It's a fixed specification requirement, not an implementation choice." + }, + { + "excerpt": "For RV32 only, if the D extension is implemented, the FMVH.X.D instruction moves bits 63:32 of floating-point register _rs1_ into integer register _rd_.", + "line_number": 186, + "reason": "This describes the fixed operation of an instruction. The behavior is completely specified and not implementation-defined." + }, + { + "excerpt": "These instructions are encoded like their FLE and FLT counterparts, but with instruction bit 14 set to 1.", + "line_number": 245, + "reason": "This specifies the fixed encoding format for instructions. All implementations must use this encoding - there is no choice involved." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"Other _rm_ values are _reserved_.\",\n \"line_number\": 179,\n \"parameter_name\": \"FCVTMOD_RM_RESERVED_BEHAVIOR\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The behavior when reserved rm values are used in FCVTMOD.W.D is implementation-defined. The spec states they are reserved but doesn't specify what happens when they are used.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"The set of 32 constants was chosen by examining floating-point libraries, including the C standard math library, and to optimize fixed-point to floating-point conversion.\",\n \"line_number\": 60,\n \"reason\": \"This is inside a [NOTE] block, which is non-normative. It explains the rationale for the constant selection but doesn't define an implementation parameter.\"\n },\n {\n \"excerpt\": \"The FLI._fmt_ instructions never set any floating-point exception flags.\",\n \"line_number\": 95,\n \"reason\": \"This is a fixed requirement that applies to all implementations. There is no implementation choice - all implementations must behave this way.\"\n },\n {\n \"excerpt\": \"Zero and infinite inputs are copied to _rd_ unmodified.\",\n \"line_number\": 118,\n \"reason\": \"This describes the required behavior for specific input values. It's a fixed specification requirement, not an implementation choice.\"\n },\n {\n \"excerpt\": \"For RV32 only, if the D extension is implemented, the FMVH.X.D instruction moves bits 63:32 of floating-point register _rs1_ into integer register _rd_.\",\n \"line_number\": 186,\n \"reason\": \"This describes the fixed operation of an instruction. The behavior is completely specified and not implementation-defined.\"\n },\n {\n \"excerpt\": \"These instructions are encoded like their FLE and FLT counterparts, but with instruction bit 14 set to 1.\",\n \"line_number\": 245,\n \"reason\": \"This specifies the fixed encoding format for instructions. All implementations must use this encoding - there is no choice involved.\"\n }\n ]\n}\n```", + "input_tokens": 9480, + "output_tokens": 581, + "latency_ms": 11620, + "timestamp": "2026-04-15T15:06:37.114752+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_068", + "source_file": "zfh.adoc", + "start_line": 1, + "end_line": 186, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [], + "skipped_non_parameters": [ + { + "excerpt": "This extension primarily provides instructions that consume half-precision operands and produce half-precision results. However, it is also common to compute on half-precision data using higher intermediate precision.", + "line_number": 13, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks." + }, + { + "excerpt": "FLH and FSH are only guaranteed to execute atomically if the effective address is naturally aligned.", + "line_number": 32, + "reason": "This is a fixed requirement that applies to all implementations - there is no implementation choice here." + }, + { + "excerpt": "FCVT.L[U].H and FCVT.H.L[U] are RV64-only instructions.", + "line_number": 73, + "reason": "This is a fixed requirement based on the base ISA (RV64), not an implementation-defined parameter." + }, + { + "excerpt": "The Zfhmin extension includes the following instructions from the Zfh extension: FLH, FSH, FMV.X.H, FMV.H.X, FCVT.S.H, and FCVT.H.S.", + "line_number": 147, + "reason": "This defines the fixed contents of the Zfhmin extension - it is a specification requirement, not an implementation choice." + }, + { + "excerpt": "Zfhmin does not include the FSGNJ.H instruction, because it suffices to instead use the FSGNJ.S instruction to move half-precision values between floating-point registers.", + "line_number": 153, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. Additionally, it describes what is not included in Zfhmin, which is a fixed specification requirement." + } + ], + "raw_response": "```json\n{\n \"parameters\": [],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"This extension primarily provides instructions that consume half-precision operands and produce half-precision results. However, it is also common to compute on half-precision data using higher intermediate precision.\",\n \"line_number\": 13,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks.\"\n },\n {\n \"excerpt\": \"FLH and FSH are only guaranteed to execute atomically if the effective address is naturally aligned.\",\n \"line_number\": 32,\n \"reason\": \"This is a fixed requirement that applies to all implementations - there is no implementation choice here.\"\n },\n {\n \"excerpt\": \"FCVT.L[U].H and FCVT.H.L[U] are RV64-only instructions.\",\n \"line_number\": 73,\n \"reason\": \"This is a fixed requirement based on the base ISA (RV64), not an implementation-defined parameter.\"\n },\n {\n \"excerpt\": \"The Zfhmin extension includes the following instructions from the Zfh extension: FLH, FSH, FMV.X.H, FMV.H.X, FCVT.S.H, and FCVT.H.S.\",\n \"line_number\": 147,\n \"reason\": \"This defines the fixed contents of the Zfhmin extension - it is a specification requirement, not an implementation choice.\"\n },\n {\n \"excerpt\": \"Zfhmin does not include the FSGNJ.H instruction, because it suffices to instead use the FSGNJ.S instruction to move half-precision values between floating-point registers.\",\n \"line_number\": 153,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. Additionally, it describes what is not included in Zfhmin, which is a fixed specification requirement.\"\n }\n ]\n}\n```", + "input_tokens": 8158, + "output_tokens": 494, + "latency_ms": 7879, + "timestamp": "2026-04-15T14:54:31.147794+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_069", + "source_file": "zfinx.adoc", + "start_line": 1, + "end_line": 162, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "In the standard privileged architecture defined in Volume II, the `mstatus` field FS is hardwired to 0 if the Zfinx extension is implemented, and FS no longer affects the trapping behavior of floating-point instructions or `fcsr` accesses.", + "line_number": 143, + "parameter_name": "MSTATUS_FS_LEGAL_VALUES", + "existing_udb_name": "MSTATUS_FS_LEGAL_VALUES", + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "When Zfinx is implemented, mstatus.FS is hardwired to 0, meaning the only legal value is 0. This constrains the WARL field's legal values based on the extension implementation." + }, + { + "excerpt": "The `misa` bits F, D, and Q are hardwired to 0 when the Zfinx extension is implemented.", + "line_number": 147, + "parameter_name": "MUTABLE_MISA_F", + "existing_udb_name": "MUTABLE_MISA_F", + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "When Zfinx is implemented, misa.F is hardwired to 0, constraining its legal values. This affects the WARL behavior of the misa.F field." + }, + { + "excerpt": "The `misa` bits F, D, and Q are hardwired to 0 when the Zfinx extension is implemented.", + "line_number": 147, + "parameter_name": "MUTABLE_MISA_D", + "existing_udb_name": "MUTABLE_MISA_D", + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "When Zfinx is implemented, misa.D is hardwired to 0, constraining its legal values. This affects the WARL behavior of the misa.D field." + }, + { + "excerpt": "The `misa` bits F, D, and Q are hardwired to 0 when the Zfinx extension is implemented.", + "line_number": 147, + "parameter_name": "MUTABLE_MISA_Q", + "existing_udb_name": "MUTABLE_MISA_Q", + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "When Zfinx is implemented, misa.Q is hardwired to 0, constraining its legal values. This affects the WARL behavior of the misa.Q field." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "The F extension uses separate `f` registers for floating-point computation, to reduce register pressure and simplify the provision of register-file ports for wide superscalars.", + "line_number": 13, + "reason": "This is inside a [NOTE] block, which is non-normative informational text. Parameters are never extracted from NOTE blocks." + }, + { + "excerpt": "The Zfinx extension adds all of the instructions that the F extension adds, _except_ for the transfer instructions FLW, FSW, FMV.W.X, FMV.X.W, C.FLW[SP], and C.FSW[SP].", + "line_number": 25, + "reason": "This is a fixed requirement defining what instructions are included in the extension. It's not an implementation choice - all Zfinx implementations must include these specific instructions." + }, + { + "excerpt": "Floating-point operands of width _w_ < XLEN bits occupy bits _w_-1:0 of an `x` register.", + "line_number": 40, + "reason": "This describes the fixed format for how narrow operands are stored in registers. It's a requirement that all implementations must follow, not a choice." + }, + { + "excerpt": "Double-precision operands in RV32Zdinx are held in aligned `x`-register pairs, i.e., register numbers must be even.", + "line_number": 75, + "reason": "This is a fixed requirement for how double-precision operands must be stored in RV32Zdinx. All implementations must follow this rule - it's not an implementation choice." + }, + { + "excerpt": "A future discoverability mechanism might be used to probe the existence of the Zfinx, Zhinx, and Zdinx extensions.", + "line_number": 149, + "reason": "This is inside a [NOTE] block discussing future possibilities, making it non-normative. It doesn't define any current implementation parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"In the standard privileged architecture defined in Volume II, the `mstatus` field FS is hardwired to 0 if the Zfinx extension is implemented, and FS no longer affects the trapping behavior of floating-point instructions or `fcsr` accesses.\",\n \"line_number\": 143,\n \"parameter_name\": \"MSTATUS_FS_LEGAL_VALUES\",\n \"existing_udb_name\": \"MSTATUS_FS_LEGAL_VALUES\",\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"When Zfinx is implemented, mstatus.FS is hardwired to 0, meaning the only legal value is 0. This constrains the WARL field's legal values based on the extension implementation.\"\n },\n {\n \"excerpt\": \"The `misa` bits F, D, and Q are hardwired to 0 when the Zfinx extension is implemented.\",\n \"line_number\": 147,\n \"parameter_name\": \"MUTABLE_MISA_F\",\n \"existing_udb_name\": \"MUTABLE_MISA_F\",\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"When Zfinx is implemented, misa.F is hardwired to 0, constraining its legal values. This affects the WARL behavior of the misa.F field.\"\n },\n {\n \"excerpt\": \"The `misa` bits F, D, and Q are hardwired to 0 when the Zfinx extension is implemented.\",\n \"line_number\": 147,\n \"parameter_name\": \"MUTABLE_MISA_D\",\n \"existing_udb_name\": \"MUTABLE_MISA_D\",\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"When Zfinx is implemented, misa.D is hardwired to 0, constraining its legal values. This affects the WARL behavior of the misa.D field.\"\n },\n {\n \"excerpt\": \"The `misa` bits F, D, and Q are hardwired to 0 when the Zfinx extension is implemented.\",\n \"line_number\": 147,\n \"parameter_name\": \"MUTABLE_MISA_Q\",\n \"existing_udb_name\": \"MUTABLE_MISA_Q\",\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"When Zfinx is implemented, misa.Q is hardwired to 0, constraining its legal values. This affects the WARL behavior of the misa.Q field.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"The F extension uses separate `f` registers for floating-point computation, to reduce register pressure and simplify the provision of register-file ports for wide superscalars.\",\n \"line_number\": 13,\n \"reason\": \"This is inside a [NOTE] block, which is non-normative informational text. Parameters are never extracted from NOTE blocks.\"\n },\n {\n \"excerpt\": \"The Zfinx extension adds all of the instructions that the F extension adds, _except_ for the transfer instructions FLW, FSW, FMV.W.X, FMV.X.W, C.FLW[SP], and C.FSW[SP].\",\n \"line_number\": 25,\n \"reason\": \"This is a fixed requirement defining what instructions are included in the extension. It's not an implementation choice - all Zfinx implementations must include these specific instructions.\"\n },\n {\n \"excerpt\": \"Floating-point operands of width _w_ < XLEN bits occupy bits _w_-1:0 of an `x` register.\",\n \"line_number\": 40,\n \"reason\": \"This describes the fixed format for how narrow operands are stored in registers. It's a requirement that all implementations must follow, not a choice.\"\n },\n {\n \"excerpt\": \"Double-precision operands in RV32Zdinx are held in aligned `x`-register pairs, i.e., register numbers must be even.\",\n \"line_number\": 75,\n \"reason\": \"This is a fixed requirement for how double-precision operands must be stored in RV32Zdinx. All implementations must follow this rule - it's not an implementation choice.\"\n },\n {\n \"excerpt\": \"A future discoverability mechanism might be used to probe the existence of the Zfinx, Zhinx, and Zdinx extensions.\",\n \"line_number\": 149,\n \"reason\": \"This is inside a [NOTE] block discussing future possibilities, making it non-normative. It doesn't define any current implementation parameter.\"\n }\n ]\n}\n```", + "input_tokens": 7572, + "output_tokens": 1260, + "latency_ms": 16318, + "timestamp": "2026-04-15T14:54:50.508537+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_070", + "source_file": "zicond.adoc", + "start_line": 1, + "end_line": 187, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [], + "skipped_non_parameters": [ + { + "excerpt": "If _rs2_ contains the value zero, this instruction writes the value zero to _rd_. Otherwise, this instruction copies the contents of _rs1_ to _rd_.", + "line_number": 44, + "reason": "This describes the fixed behavior of the czero.eqz instruction. All implementations must behave this way - it is not an implementation choice." + }, + { + "excerpt": "Furthermore, if the Zkt extension is implemented, this instruction's timing is independent of the data values in _rs1_ and _rs2_.", + "line_number": 47, + "reason": "This describes required behavior when Zkt is implemented. The timing independence is a fixed requirement, not an implementation parameter." + }, + { + "excerpt": "If _rs2_ contains a nonzero value, this instruction writes the value zero to _rd_. Otherwise, this instruction copies the contents of _rs1_ to _rd_.", + "line_number": 78, + "reason": "This describes the fixed behavior of the czero.nez instruction. All implementations must behave this way - it is not an implementation choice." + }, + { + "excerpt": "This instruction carries a syntactic dependency from both _rs1_ and _rs2_ to _rd_.", + "line_number": 46, + "reason": "This describes a fixed requirement about instruction dependencies that all implementations must follow. It is not a parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"If _rs2_ contains the value zero, this instruction writes the value zero to _rd_. Otherwise, this instruction copies the contents of _rs1_ to _rd_.\",\n \"line_number\": 44,\n \"reason\": \"This describes the fixed behavior of the czero.eqz instruction. All implementations must behave this way - it is not an implementation choice.\"\n },\n {\n \"excerpt\": \"Furthermore, if the Zkt extension is implemented, this instruction's timing is independent of the data values in _rs1_ and _rs2_.\",\n \"line_number\": 47,\n \"reason\": \"This describes required behavior when Zkt is implemented. The timing independence is a fixed requirement, not an implementation parameter.\"\n },\n {\n \"excerpt\": \"If _rs2_ contains a nonzero value, this instruction writes the value zero to _rd_. Otherwise, this instruction copies the contents of _rs1_ to _rd_.\",\n \"line_number\": 78,\n \"reason\": \"This describes the fixed behavior of the czero.nez instruction. All implementations must behave this way - it is not an implementation choice.\"\n },\n {\n \"excerpt\": \"This instruction carries a syntactic dependency from both _rs1_ and _rs2_ to _rd_.\",\n \"line_number\": 46,\n \"reason\": \"This describes a fixed requirement about instruction dependencies that all implementations must follow. It is not a parameter.\"\n }\n ]\n}\n```", + "input_tokens": 7492, + "output_tokens": 379, + "latency_ms": 6838, + "timestamp": "2026-04-15T14:55:00.379136+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_071", + "source_file": "zicsr.adoc", + "start_line": 1, + "end_line": 254, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "The hardware platform may define that accesses to certain CSRs are strongly ordered, as defined by the Memory-Ordering PMAs section in Volume II of this manual.", + "line_number": 244, + "parameter_name": "CSR_STRONG_ORDERING", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "set", + "confidence": "high", + "reasoning": "The platform/implementation chooses which CSRs have strongly ordered access semantics versus the default weakly ordered behavior. This is a direct implementation choice about memory ordering properties." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "While CSRs are primarily used by the privileged architecture, there are several uses in unprivileged code including for counters and timers, and for floating-point status.", + "line_number": 9, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks." + }, + { + "excerpt": "The CSRRW (Atomic Read/Write CSR) instruction atomically swaps values in the CSRs and integer registers.", + "line_number": 26, + "reason": "This describes the fixed behavior of the CSRRW instruction that all implementations must follow. It is not an implementation choice." + }, + { + "excerpt": "If rd=x0, then the instruction shall not read the CSR and shall not cause any of the side effects that might occur on a CSR read.", + "line_number": 30, + "reason": "This describes deterministic behavior based on register encoding. The behavior is fixed by the ISA specification, not chosen by the implementer." + }, + { + "excerpt": "In particular, unless specified otherwise, a CSR access is performed after the execution of any prior instructions in program order whose behavior modifies or is modified by the CSR state", + "line_number": 186, + "reason": "This describes the required ordering behavior that all implementations must follow. It is a fixed requirement, not an implementation choice." + }, + { + "excerpt": "For the RVWMO memory consistency model, CSR accesses are weakly ordered by default", + "line_number": 202, + "reason": "This states the default ordering behavior that applies to all implementations under RVWMO. It is not an implementation choice but a specification requirement." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"The hardware platform may define that accesses to certain CSRs are strongly ordered, as defined by the Memory-Ordering PMAs section in Volume II of this manual.\",\n \"line_number\": 244,\n \"parameter_name\": \"CSR_STRONG_ORDERING\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"The platform/implementation chooses which CSRs have strongly ordered access semantics versus the default weakly ordered behavior. This is a direct implementation choice about memory ordering properties.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"While CSRs are primarily used by the privileged architecture, there are several uses in unprivileged code including for counters and timers, and for floating-point status.\",\n \"line_number\": 9,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks.\"\n },\n {\n \"excerpt\": \"The CSRRW (Atomic Read/Write CSR) instruction atomically swaps values in the CSRs and integer registers.\",\n \"line_number\": 26,\n \"reason\": \"This describes the fixed behavior of the CSRRW instruction that all implementations must follow. It is not an implementation choice.\"\n },\n {\n \"excerpt\": \"If rd=x0, then the instruction shall not read the CSR and shall not cause any of the side effects that might occur on a CSR read.\",\n \"line_number\": 30,\n \"reason\": \"This describes deterministic behavior based on register encoding. The behavior is fixed by the ISA specification, not chosen by the implementer.\"\n },\n {\n \"excerpt\": \"In particular, unless specified otherwise, a CSR access is performed after the execution of any prior instructions in program order whose behavior modifies or is modified by the CSR state\",\n \"line_number\": 186,\n \"reason\": \"This describes the required ordering behavior that all implementations must follow. It is a fixed requirement, not an implementation choice.\"\n },\n {\n \"excerpt\": \"For the RVWMO memory consistency model, CSR accesses are weakly ordered by default\",\n \"line_number\": 202,\n \"reason\": \"This states the default ordering behavior that applies to all implementations under RVWMO. It is not an implementation choice but a specification requirement.\"\n }\n ]\n}\n```", + "input_tokens": 9068, + "output_tokens": 618, + "latency_ms": 11529, + "timestamp": "2026-04-15T14:55:14.952840+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_072", + "source_file": "zifencei.adoc", + "start_line": 1, + "end_line": 129, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "For forward compatibility, base implementations shall ignore these fields, and standard software shall zero these fields.", + "line_number": 108, + "parameter_name": "FENCE_I_RESERVED_FIELD_BEHAVIOR", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation must choose how to handle reserved fields in FENCE.I (funct12, rs1, rd). The spec requires they be ignored, but this is still an implementation choice about how to handle reserved encodings." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "We considered but did not include a \"store instruction word\" instruction as in cite:[majc]. JIT compilers may generate a large trace of instructions before a single FENCE.I, and amortize any instruction cache snooping/invalidation overhead by writing translated instructions to memory regions that are known not to reside in the I-cache.", + "line_number": 11, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. It describes design rationale, not an architectural requirement." + }, + { + "excerpt": "The FENCE.I instruction was designed to support a wide variety of implementations. A simple implementation can flush the local instruction cache and the instruction pipeline when the FENCE.I is executed.", + "line_number": 19, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. It describes possible implementation strategies but does not define required parameters." + }, + { + "excerpt": "RISC-V does not guarantee that stores to instruction memory will be made visible to instruction fetches on a RISC-V hart until that hart executes a FENCE.I instruction.", + "line_number": 66, + "reason": "This describes the required behavior of FENCE.I that all implementations must follow. It is a fixed requirement, not an implementation choice." + }, + { + "excerpt": "A FENCE.I instruction orders all explicit memory accesses that precede the FENCE.I in program order before all instruction fetches that follow the FENCE.I in program order.", + "line_number": 74, + "reason": "This defines the mandatory ordering semantics of FENCE.I that all implementations must provide. It is a fixed requirement, not a parameter." + }, + { + "excerpt": "Because FENCE.I only orders stores with a hart's own instruction fetches, application code should only rely upon FENCE.I if the application thread will not be migrated to a different hart.", + "line_number": 113, + "reason": "This text is inside a [NOTE] block and describes software usage guidance, not an architectural parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"For forward compatibility, base implementations shall ignore these fields, and standard software shall zero these fields.\",\n \"line_number\": 108,\n \"parameter_name\": \"FENCE_I_RESERVED_FIELD_BEHAVIOR\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation must choose how to handle reserved fields in FENCE.I (funct12, rs1, rd). The spec requires they be ignored, but this is still an implementation choice about how to handle reserved encodings.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"We considered but did not include a \\\"store instruction word\\\" instruction as in cite:[majc]. JIT compilers may generate a large trace of instructions before a single FENCE.I, and amortize any instruction cache snooping/invalidation overhead by writing translated instructions to memory regions that are known not to reside in the I-cache.\",\n \"line_number\": 11,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. It describes design rationale, not an architectural requirement.\"\n },\n {\n \"excerpt\": \"The FENCE.I instruction was designed to support a wide variety of implementations. A simple implementation can flush the local instruction cache and the instruction pipeline when the FENCE.I is executed.\",\n \"line_number\": 19,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. It describes possible implementation strategies but does not define required parameters.\"\n },\n {\n \"excerpt\": \"RISC-V does not guarantee that stores to instruction memory will be made visible to instruction fetches on a RISC-V hart until that hart executes a FENCE.I instruction.\",\n \"line_number\": 66,\n \"reason\": \"This describes the required behavior of FENCE.I that all implementations must follow. It is a fixed requirement, not an implementation choice.\"\n },\n {\n \"excerpt\": \"A FENCE.I instruction orders all explicit memory accesses that precede the FENCE.I in program order before all instruction fetches that follow the FENCE.I in program order.\",\n \"line_number\": 74,\n \"reason\": \"This defines the mandatory ordering semantics of FENCE.I that all implementations must provide. It is a fixed requirement, not a parameter.\"\n },\n {\n \"excerpt\": \"Because FENCE.I only orders stores with a hart's own instruction fetches, application code should only rely upon FENCE.I if the application thread will not be migrated to a different hart.\",\n \"line_number\": 113,\n \"reason\": \"This text is inside a [NOTE] block and describes software usage guidance, not an architectural parameter.\"\n }\n ]\n}\n```", + "input_tokens": 7041, + "output_tokens": 695, + "latency_ms": 24548, + "timestamp": "2026-04-15T14:55:40.628399+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_073", + "source_file": "zihintntl.adoc", + "start_line": 1, + "end_line": 189, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [], + "skipped_non_parameters": [ + { + "excerpt": "The NTL instructions do not change architectural state, nor do they alter the architecturally visible effects of the target instruction.", + "line_number": 7, + "reason": "This is a fixed requirement that applies to all implementations - NTL instructions must not change architectural state. No implementation choice is involved." + }, + { + "excerpt": "NTL.P1 is encoded as ADD _x0, x0, x2_.", + "line_number": 14, + "reason": "This specifies a fixed encoding that all implementations must use. There is no implementation choice in the encoding." + }, + { + "excerpt": "The NTL instructions affect all memory-access instructions except the cache-management instructions in the Zicbom extension.", + "line_number": 82, + "reason": "This defines the fixed scope of NTL instructions - which instruction types they affect is not implementation-defined." + }, + { + "excerpt": "In the event that a trap is taken on the target instruction, implementations are discouraged from applying the NTL to the first instruction in the trap handler.", + "line_number": 149, + "reason": "This is a recommendation ('discouraged', 'recommended') about implementation behavior, but it's in a non-normative context and doesn't define a required architectural parameter." + }, + { + "excerpt": "A microarchitecture might use the NTL instructions to inform the cache replacement policy, or to decide which cache to allocate into, or to avoid cache allocation altogether.", + "line_number": 25, + "reason": "This text is inside a [NOTE] block, making it non-normative. Even though it describes implementation choices, parameters should not be extracted from NOTE blocks." + } + ], + "raw_response": "```json\n{\n \"parameters\": [],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"The NTL instructions do not change architectural state, nor do they alter the architecturally visible effects of the target instruction.\",\n \"line_number\": 7,\n \"reason\": \"This is a fixed requirement that applies to all implementations - NTL instructions must not change architectural state. No implementation choice is involved.\"\n },\n {\n \"excerpt\": \"NTL.P1 is encoded as ADD _x0, x0, x2_.\",\n \"line_number\": 14,\n \"reason\": \"This specifies a fixed encoding that all implementations must use. There is no implementation choice in the encoding.\"\n },\n {\n \"excerpt\": \"The NTL instructions affect all memory-access instructions except the cache-management instructions in the Zicbom extension.\",\n \"line_number\": 82,\n \"reason\": \"This defines the fixed scope of NTL instructions - which instruction types they affect is not implementation-defined.\"\n },\n {\n \"excerpt\": \"In the event that a trap is taken on the target instruction, implementations are discouraged from applying the NTL to the first instruction in the trap handler.\",\n \"line_number\": 149,\n \"reason\": \"This is a recommendation ('discouraged', 'recommended') about implementation behavior, but it's in a non-normative context and doesn't define a required architectural parameter.\"\n },\n {\n \"excerpt\": \"A microarchitecture might use the NTL instructions to inform the cache replacement policy, or to decide which cache to allocate into, or to avoid cache allocation altogether.\",\n \"line_number\": 25,\n \"reason\": \"This text is inside a [NOTE] block, making it non-normative. Even though it describes implementation choices, parameters should not be extracted from NOTE blocks.\"\n }\n ]\n}\n```", + "input_tokens": 8272, + "output_tokens": 451, + "latency_ms": 23915, + "timestamp": "2026-04-15T14:56:06.551379+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_074", + "source_file": "zihintpause.adoc", + "start_line": 1, + "end_line": 56, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "The duration of its effect must be bounded and may be zero.", + "line_number": 5, + "parameter_name": "PAUSE_DURATION", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "range", + "confidence": "high", + "reasoning": "The implementation chooses the duration of the PAUSE effect, with the constraint that it must be bounded and may be zero. This is a direct implementation choice about timing behavior." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "Software can use the PAUSE instruction to reduce energy consumption while executing spin-wait code sequences.", + "line_number": 10, + "reason": "This is inside a [NOTE] block, which is non-normative. It describes software usage, not an implementation parameter." + }, + { + "excerpt": "The duration of a PAUSE instruction's effect may vary significantly within and among implementations.", + "line_number": 16, + "reason": "This is inside a [NOTE] block, which is non-normative. While it mentions implementation variation, it's informative guidance, not a normative parameter definition." + }, + { + "excerpt": "PAUSE is encoded as a FENCE instruction with _pred_=`W`, _succ_=`0`, _fm_=`0`, _rd_=`x0`, and _rs1_=`x0`.", + "line_number": 31, + "reason": "This is a fixed encoding requirement that all implementations must follow. There is no implementation choice here." + }, + { + "excerpt": "PAUSE does not _mandate_ any particular memory ordering\u2014hence, it truly is a HINT.", + "line_number": 40, + "reason": "This describes what PAUSE does not require, which is a fixed behavioral specification, not an implementation parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"The duration of its effect must be bounded and may be zero.\",\n \"line_number\": 5,\n \"parameter_name\": \"PAUSE_DURATION\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"range\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses the duration of the PAUSE effect, with the constraint that it must be bounded and may be zero. This is a direct implementation choice about timing behavior.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"Software can use the PAUSE instruction to reduce energy consumption while executing spin-wait code sequences.\",\n \"line_number\": 10,\n \"reason\": \"This is inside a [NOTE] block, which is non-normative. It describes software usage, not an implementation parameter.\"\n },\n {\n \"excerpt\": \"The duration of a PAUSE instruction's effect may vary significantly within and among implementations.\",\n \"line_number\": 16,\n \"reason\": \"This is inside a [NOTE] block, which is non-normative. While it mentions implementation variation, it's informative guidance, not a normative parameter definition.\"\n },\n {\n \"excerpt\": \"PAUSE is encoded as a FENCE instruction with _pred_=`W`, _succ_=`0`, _fm_=`0`, _rd_=`x0`, and _rs1_=`x0`.\",\n \"line_number\": 31,\n \"reason\": \"This is a fixed encoding requirement that all implementations must follow. There is no implementation choice here.\"\n },\n {\n \"excerpt\": \"PAUSE does not _mandate_ any particular memory ordering\u2014hence, it truly is a HINT.\",\n \"line_number\": 40,\n \"reason\": \"This describes what PAUSE does not require, which is a fixed behavioral specification, not an implementation parameter.\"\n }\n ]\n}\n```", + "input_tokens": 6174, + "output_tokens": 487, + "latency_ms": 27410, + "timestamp": "2026-04-15T14:56:37.005424+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_075", + "source_file": "zilsd.adoc", + "start_line": 1, + "end_line": 315, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "Even if naturally aligned, the memory access might not be performed atomically.", + "line_number": 33, + "parameter_name": "ZILSD_8BYTE_ATOMIC", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether 8-byte aligned accesses are performed atomically or not. This is a direct implementation choice not controlled by any CSR field." + }, + { + "excerpt": "If the effective address is a multiple of 4, then each word access is required to be performed atomically.", + "line_number": 34, + "parameter_name": "ZILSD_4BYTE_WORD_ATOMIC", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "While stated as 'required', this appears to be describing an implementation constraint that can be satisfied in different ways (single atomic access vs two atomic word accesses), making it an implementation choice." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "Operands containing `src` for store instructions and `dest` for load instructions are held in aligned `x`-register pairs, i.e., register numbers must be even.", + "line_number": 6, + "reason": "This is a fixed architectural requirement that all implementations must follow - register pairs must be even-numbered. No implementation choice." + }, + { + "excerpt": "As the access size is 64-bit, accesses are only considered naturally aligned for effective addresses that are a multiple of 8. In this case, these instructions are guaranteed to not raise an address-misaligned exception.", + "line_number": 31, + "reason": "This defines what constitutes natural alignment and the guaranteed behavior - it's a fixed rule, not an implementation choice." + }, + { + "excerpt": "To ensure resumable trap handling is possible for the load instructions, the base register must have its original value if a trap is taken.", + "line_number": 45, + "reason": "This is a fixed requirement for trap handling that all implementations must satisfy, not an optional behavior." + }, + { + "excerpt": "For the purposes of RVWMO and exception handling, LD and SD instructions are considered to be misaligned loads and stores", + "line_number": 89, + "reason": "This defines how these instructions are categorized for memory model purposes - it's a fixed classification, not an implementation choice." + }, + { + "excerpt": "If an implementation performs a doubleword load access atomically and the register file implements write-back for even/odd register pairs, the mentioned atomicity requirements are inherently fulfilled.", + "line_number": 48, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. It provides implementation guidance but is not a requirement." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"Even if naturally aligned, the memory access might not be performed atomically.\",\n \"line_number\": 33,\n \"parameter_name\": \"ZILSD_8BYTE_ATOMIC\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether 8-byte aligned accesses are performed atomically or not. This is a direct implementation choice not controlled by any CSR field.\"\n },\n {\n \"excerpt\": \"If the effective address is a multiple of 4, then each word access is required to be performed atomically.\",\n \"line_number\": 34,\n \"parameter_name\": \"ZILSD_4BYTE_WORD_ATOMIC\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"While stated as 'required', this appears to be describing an implementation constraint that can be satisfied in different ways (single atomic access vs two atomic word accesses), making it an implementation choice.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"Operands containing `src` for store instructions and `dest` for load instructions are held in aligned `x`-register pairs, i.e., register numbers must be even.\",\n \"line_number\": 6,\n \"reason\": \"This is a fixed architectural requirement that all implementations must follow - register pairs must be even-numbered. No implementation choice.\"\n },\n {\n \"excerpt\": \"As the access size is 64-bit, accesses are only considered naturally aligned for effective addresses that are a multiple of 8. In this case, these instructions are guaranteed to not raise an address-misaligned exception.\",\n \"line_number\": 31,\n \"reason\": \"This defines what constitutes natural alignment and the guaranteed behavior - it's a fixed rule, not an implementation choice.\"\n },\n {\n \"excerpt\": \"To ensure resumable trap handling is possible for the load instructions, the base register must have its original value if a trap is taken.\",\n \"line_number\": 45,\n \"reason\": \"This is a fixed requirement for trap handling that all implementations must satisfy, not an optional behavior.\"\n },\n {\n \"excerpt\": \"For the purposes of RVWMO and exception handling, LD and SD instructions are considered to be misaligned loads and stores\",\n \"line_number\": 89,\n \"reason\": \"This defines how these instructions are categorized for memory model purposes - it's a fixed classification, not an implementation choice.\"\n },\n {\n \"excerpt\": \"If an implementation performs a doubleword load access atomically and the register file implements write-back for even/odd register pairs, the mentioned atomicity requirements are inherently fulfilled.\",\n \"line_number\": 48,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. It provides implementation guidance but is not a requirement.\"\n }\n ]\n}\n```", + "input_tokens": 9178, + "output_tokens": 760, + "latency_ms": 29101, + "timestamp": "2026-04-15T14:57:09.122498+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_076", + "source_file": "zimop.adoc", + "start_line": 1, + "end_line": 113, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [], + "skipped_non_parameters": [ + { + "excerpt": "It is sometimes desirable to define instruction-set extensions whose instructions, rather than raising illegal-instruction exceptions when the extension is not implemented, take no useful action (beyond writing `x[rd]`).", + "line_number": 12, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks." + }, + { + "excerpt": "The Zimop extension defines 32 MOP instructions named MOP.R.__n__, where __n__ is an integer between 0 and 31, inclusive.", + "line_number": 29, + "reason": "This defines a fixed requirement - the extension defines exactly 32 instructions with specific names. This is not an implementation choice but a specification of what the extension provides." + }, + { + "excerpt": "Unless redefined by another extension, these instructions simply write 0 to `x[rd]`.", + "line_number": 31, + "reason": "This describes the default behavior of MOP instructions. The behavior is fixed by the specification - they write 0 to x[rd] unless redefined by another extension. This is not an implementation parameter." + }, + { + "excerpt": "The Zimop extension additionally defines 8 MOP instructions named MOP.RR.__n__, where __n__ is an integer between 0 and 7, inclusive.", + "line_number": 38, + "reason": "Similar to the MOP.R case, this defines a fixed requirement - exactly 8 instructions with specific names. This is specification content, not an implementation choice." + }, + { + "excerpt": "This section defines the \"Zcmop\" extension, which defines eight 16-bit MOP instructions named C.MOP.__n__, where __n__ is an odd integer between 1 and 15, inclusive.", + "line_number": 62, + "reason": "This defines the fixed content of the Zcmop extension - exactly 8 instructions with specific names and encodings. This is not an implementation parameter but a specification requirement." + } + ], + "raw_response": "```json\n{\n \"parameters\": [],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"It is sometimes desirable to define instruction-set extensions whose instructions, rather than raising illegal-instruction exceptions when the extension is not implemented, take no useful action (beyond writing `x[rd]`).\",\n \"line_number\": 12,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks.\"\n },\n {\n \"excerpt\": \"The Zimop extension defines 32 MOP instructions named MOP.R.__n__, where __n__ is an integer between 0 and 31, inclusive.\",\n \"line_number\": 29,\n \"reason\": \"This defines a fixed requirement - the extension defines exactly 32 instructions with specific names. This is not an implementation choice but a specification of what the extension provides.\"\n },\n {\n \"excerpt\": \"Unless redefined by another extension, these instructions simply write 0 to `x[rd]`.\",\n \"line_number\": 31,\n \"reason\": \"This describes the default behavior of MOP instructions. The behavior is fixed by the specification - they write 0 to x[rd] unless redefined by another extension. This is not an implementation parameter.\"\n },\n {\n \"excerpt\": \"The Zimop extension additionally defines 8 MOP instructions named MOP.RR.__n__, where __n__ is an integer between 0 and 7, inclusive.\",\n \"line_number\": 38,\n \"reason\": \"Similar to the MOP.R case, this defines a fixed requirement - exactly 8 instructions with specific names. This is specification content, not an implementation choice.\"\n },\n {\n \"excerpt\": \"This section defines the \\\"Zcmop\\\" extension, which defines eight 16-bit MOP instructions named C.MOP.__n__, where __n__ is an odd integer between 1 and 15, inclusive.\",\n \"line_number\": 62,\n \"reason\": \"This defines the fixed content of the Zcmop extension - exactly 8 instructions with specific names and encodings. This is not an implementation parameter but a specification requirement.\"\n }\n ]\n}\n```", + "input_tokens": 7113, + "output_tokens": 531, + "latency_ms": 27168, + "timestamp": "2026-04-15T14:57:39.316143+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_077", + "source_file": "zpm.adoc", + "start_line": 1, + "end_line": 223, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "The current standard only supports PMLEN=XLEN-48 (i.e., PMLEN=16 in RV64) and PMLEN=XLEN-57 (i.e., PMLEN=7 in RV64). A setting has been reserved to potentially support other values of PMLEN in future standards.", + "line_number": 108, + "parameter_name": "PMLEN", + "existing_udb_name": "PMLEN", + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "high", + "reasoning": "PMLEN is a direct implementation parameter that determines how many upper bits are masked. The spec defines specific supported values (16 or 7 for RV64) that implementations must choose from." + }, + { + "excerpt": "Pointer masking only applies to RV64. In RV32, trying to enable pointer masking will result in an illegal WARL write and not update the pointer masking configuration bits", + "line_number": 189, + "parameter_name": "POINTER_MASKING_RV32_SUPPORT", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "This is a direct implementation choice about whether pointer masking is supported in RV32. The spec states it only applies to RV64, making this a binary architectural parameter." + }, + { + "excerpt": "Profiles and implementations may choose to support an arbitrary subset of these extensions and must define valid ranges for their corresponding values of PMLEN.", + "line_number": 167, + "parameter_name": "SUPPORTED_PM_EXTENSIONS", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "set", + "confidence": "high", + "reasoning": "Implementations can choose which subset of pointer masking extensions (Ssnpm, Smnpm, Smmpm, etc.) to support. This is a direct implementation choice of selecting from a defined set." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "RISC-V Pointer Masking (PM) is a feature that, when enabled, causes the CPU to ignore the upper bits of the effective address", + "line_number": 7, + "reason": "This describes what pointer masking does when enabled, not an implementation choice about whether to support it or how to configure it." + }, + { + "excerpt": "When MODE=Direct, all traps into machine mode cause the `pc` to be set to the address in the BASE field.", + "line_number": 45, + "reason": "This describes behavior when a specific mode is active, not an implementation parameter. The behavior is determined by runtime CSR values." + }, + { + "excerpt": "Future versions of the pointer masking extension may introduce the ability to freely configure the value of PMLEN.", + "line_number": 113, + "reason": "This is inside a NOTE block discussing future possibilities, not a current architectural parameter that implementations can choose." + }, + { + "excerpt": "Pointer masking applies to all explicit memory accesses generated by instructions on the CPU", + "line_number": 142, + "reason": "This is a fixed requirement about which accesses are subject to pointer masking, not an implementation choice." + }, + { + "excerpt": "The behavior is identical to applying the pointer masking transformation to every constituent aligned memory access.", + "line_number": 155, + "reason": "This describes required behavior for misaligned accesses, not an implementation parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"The current standard only supports PMLEN=XLEN-48 (i.e., PMLEN=16 in RV64) and PMLEN=XLEN-57 (i.e., PMLEN=7 in RV64). A setting has been reserved to potentially support other values of PMLEN in future standards.\",\n \"line_number\": 108,\n \"parameter_name\": \"PMLEN\",\n \"existing_udb_name\": \"PMLEN\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"PMLEN is a direct implementation parameter that determines how many upper bits are masked. The spec defines specific supported values (16 or 7 for RV64) that implementations must choose from.\"\n },\n {\n \"excerpt\": \"Pointer masking only applies to RV64. In RV32, trying to enable pointer masking will result in an illegal WARL write and not update the pointer masking configuration bits\",\n \"line_number\": 189,\n \"parameter_name\": \"POINTER_MASKING_RV32_SUPPORT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"This is a direct implementation choice about whether pointer masking is supported in RV32. The spec states it only applies to RV64, making this a binary architectural parameter.\"\n },\n {\n \"excerpt\": \"Profiles and implementations may choose to support an arbitrary subset of these extensions and must define valid ranges for their corresponding values of PMLEN.\",\n \"line_number\": 167,\n \"parameter_name\": \"SUPPORTED_PM_EXTENSIONS\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"Implementations can choose which subset of pointer masking extensions (Ssnpm, Smnpm, Smmpm, etc.) to support. This is a direct implementation choice of selecting from a defined set.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"RISC-V Pointer Masking (PM) is a feature that, when enabled, causes the CPU to ignore the upper bits of the effective address\",\n \"line_number\": 7,\n \"reason\": \"This describes what pointer masking does when enabled, not an implementation choice about whether to support it or how to configure it.\"\n },\n {\n \"excerpt\": \"When MODE=Direct, all traps into machine mode cause the `pc` to be set to the address in the BASE field.\",\n \"line_number\": 45,\n \"reason\": \"This describes behavior when a specific mode is active, not an implementation parameter. The behavior is determined by runtime CSR values.\"\n },\n {\n \"excerpt\": \"Future versions of the pointer masking extension may introduce the ability to freely configure the value of PMLEN.\",\n \"line_number\": 113,\n \"reason\": \"This is inside a NOTE block discussing future possibilities, not a current architectural parameter that implementations can choose.\"\n },\n {\n \"excerpt\": \"Pointer masking applies to all explicit memory accesses generated by instructions on the CPU\",\n \"line_number\": 142,\n \"reason\": \"This is a fixed requirement about which accesses are subject to pointer masking, not an implementation choice.\"\n },\n {\n \"excerpt\": \"The behavior is identical to applying the pointer masking transformation to every constituent aligned memory access.\",\n \"line_number\": 155,\n \"reason\": \"This describes required behavior for misaligned accesses, not an implementation parameter.\"\n }\n ]\n}\n```", + "input_tokens": 11094, + "output_tokens": 930, + "latency_ms": 38551, + "timestamp": "2026-04-15T14:58:20.892855+00:00", + "error": null, + "retry_count": 0 + }, + { + "chunk_id": "chunk_078", + "source_file": "ztso-st-ext.adoc", + "start_line": 1, + "end_line": 49, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [], + "skipped_non_parameters": [ + { + "excerpt": "_The Ztso extension is meant to facilitate the porting of code originally written for the x86 or SPARC architectures, both of which use TSO by default. It also supports implementations which inherently provide RVTSO behavior and want to expose that fact to software._", + "line_number": 8, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks." + }, + { + "excerpt": "All load operations behave as if they have an acquire-RCpc annotation", + "line_number": 17, + "reason": "This is a fixed requirement that all implementations supporting Ztso must satisfy. There is no implementation choice - it defines mandatory behavior." + }, + { + "excerpt": "All store operations behave as if they have a release-RCpc annotation.", + "line_number": 18, + "reason": "This is a fixed requirement that all implementations supporting Ztso must satisfy. There is no implementation choice - it defines mandatory behavior." + }, + { + "excerpt": "Additionally, if the Ztso extension is implemented, then vector memory instructions in the V extension and Zve family of extensions follow RVTSO at the instruction level.", + "line_number": 34, + "reason": "This is a conditional requirement ('if Ztso is implemented, then...') but not a parameter. It defines mandatory behavior when the extension is present." + }, + { + "excerpt": "Binaries compiled to run only under Ztso should indicate as such via a flag in the binary, so that platforms which do not implement Ztso can simply refuse to run them.", + "line_number": 42, + "reason": "This describes a software/toolchain requirement about binary flags, not an architectural implementation parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"_The Ztso extension is meant to facilitate the porting of code originally written for the x86 or SPARC architectures, both of which use TSO by default. It also supports implementations which inherently provide RVTSO behavior and want to expose that fact to software._\",\n \"line_number\": 8,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks.\"\n },\n {\n \"excerpt\": \"All load operations behave as if they have an acquire-RCpc annotation\",\n \"line_number\": 17,\n \"reason\": \"This is a fixed requirement that all implementations supporting Ztso must satisfy. There is no implementation choice - it defines mandatory behavior.\"\n },\n {\n \"excerpt\": \"All store operations behave as if they have a release-RCpc annotation.\",\n \"line_number\": 18,\n \"reason\": \"This is a fixed requirement that all implementations supporting Ztso must satisfy. There is no implementation choice - it defines mandatory behavior.\"\n },\n {\n \"excerpt\": \"Additionally, if the Ztso extension is implemented, then vector memory instructions in the V extension and Zve family of extensions follow RVTSO at the instruction level.\",\n \"line_number\": 34,\n \"reason\": \"This is a conditional requirement ('if Ztso is implemented, then...') but not a parameter. It defines mandatory behavior when the extension is present.\"\n },\n {\n \"excerpt\": \"Binaries compiled to run only under Ztso should indicate as such via a flag in the binary, so that platforms which do not implement Ztso can simply refuse to run them.\",\n \"line_number\": 42,\n \"reason\": \"This describes a software/toolchain requirement about binary flags, not an architectural implementation parameter.\"\n }\n ]\n}\n```", + "input_tokens": 6229, + "output_tokens": 475, + "latency_ms": 29803, + "timestamp": "2026-04-15T14:58:51.099637+00:00", + "error": null, + "retry_count": 0 + } + ] +} diff --git a/param_extraction/results/all_results_claude-sonnet-4.json.license b/param_extraction/results/all_results_claude-sonnet-4.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/all_results_claude-sonnet-4.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_001.json b/param_extraction/results/claude-sonnet-4/chunk_001.json new file mode 100644 index 0000000000..441335bfd2 --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_001.json @@ -0,0 +1,64 @@ +{ + "chunk_id": "chunk_001", + "source_file": "a-st-ext.adoc", + "start_line": 1, + "end_line": 484, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "An implementation can register an arbitrarily large reservation set on each LR, provided the reservation set includes all bytes of the addressed data word or doubleword.", + "line_number": 139, + "parameter_name": "LRSC_RESERVATION_STRATEGY", + "existing_udb_name": "LRSC_RESERVATION_STRATEGY", + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "high", + "reasoning": "The implementation chooses the size and strategy for the reservation set. This is a direct architectural choice about how LR/SC reservations are tracked." + }, + { + "excerpt": "The misaligned atomicity granule PMA, defined in Volume II of this manual, optionally relaxes this alignment requirement. If present, the misaligned atomicity granule PMA specifies the size of a misaligned atomicity granule, a power-of-two number of bytes.", + "line_number": 378, + "parameter_name": "MISALIGNED_MAX_ATOMICITY_GRANULE_SIZE", + "existing_udb_name": "MISALIGNED_MAX_ATOMICITY_GRANULE_SIZE", + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "The implementation may optionally define a misaligned atomicity granule size (power of 2). This is a direct implementation choice about memory alignment requirements for atomic operations." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "After much debate, the language community and architecture community appear to have finally settled on release consistency as the standard memory consistency model and so the RISC-V atomic support is built around this model.", + "line_number": 13, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. It provides background information but does not define any implementation choices." + }, + { + "excerpt": "If both bits are clear, no additional ordering constraints are imposed on the atomic memory operation.", + "line_number": 35, + "reason": "This describes the behavior when aq and rl bits have specific values. It is behavioral description based on CSR field values, not a parameter definition." + }, + { + "excerpt": "LR.W loads a word from the address in rs1, places the sign-extended value in rd, and registers a reservation set\u2014a set of bytes that subsumes the bytes in the addressed word.", + "line_number": 56, + "reason": "This describes the fixed behavior of the LR.W instruction. It is a requirement that all implementations must follow, not an implementation choice." + }, + { + "excerpt": "The failure code with value 1 encodes an unspecified failure. Other failure codes are reserved at this time.", + "line_number": 108, + "reason": "This defines a fixed encoding (failure code 1 = unspecified). It is not an implementation choice but a specification requirement." + }, + { + "excerpt": "For LR and SC, the Zalrsc extension requires that the address held in rs1 be naturally aligned to the size of the operand", + "line_number": 119, + "reason": "This is a fixed requirement ('requires') that all implementations must satisfy. There is no implementation choice here." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"An implementation can register an arbitrarily large reservation set on each LR, provided the reservation set includes all bytes of the addressed data word or doubleword.\",\n \"line_number\": 139,\n \"parameter_name\": \"LRSC_RESERVATION_STRATEGY\",\n \"existing_udb_name\": \"LRSC_RESERVATION_STRATEGY\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses the size and strategy for the reservation set. This is a direct architectural choice about how LR/SC reservations are tracked.\"\n },\n {\n \"excerpt\": \"The misaligned atomicity granule PMA, defined in Volume II of this manual, optionally relaxes this alignment requirement. If present, the misaligned atomicity granule PMA specifies the size of a misaligned atomicity granule, a power-of-two number of bytes.\",\n \"line_number\": 378,\n \"parameter_name\": \"MISALIGNED_MAX_ATOMICITY_GRANULE_SIZE\",\n \"existing_udb_name\": \"MISALIGNED_MAX_ATOMICITY_GRANULE_SIZE\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation may optionally define a misaligned atomicity granule size (power of 2). This is a direct implementation choice about memory alignment requirements for atomic operations.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"After much debate, the language community and architecture community appear to have finally settled on release consistency as the standard memory consistency model and so the RISC-V atomic support is built around this model.\",\n \"line_number\": 13,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. It provides background information but does not define any implementation choices.\"\n },\n {\n \"excerpt\": \"If both bits are clear, no additional ordering constraints are imposed on the atomic memory operation.\",\n \"line_number\": 35,\n \"reason\": \"This describes the behavior when aq and rl bits have specific values. It is behavioral description based on CSR field values, not a parameter definition.\"\n },\n {\n \"excerpt\": \"LR.W loads a word from the address in rs1, places the sign-extended value in rd, and registers a reservation set\u2014a set of bytes that subsumes the bytes in the addressed word.\",\n \"line_number\": 56,\n \"reason\": \"This describes the fixed behavior of the LR.W instruction. It is a requirement that all implementations must follow, not an implementation choice.\"\n },\n {\n \"excerpt\": \"The failure code with value 1 encodes an unspecified failure. Other failure codes are reserved at this time.\",\n \"line_number\": 108,\n \"reason\": \"This defines a fixed encoding (failure code 1 = unspecified). It is not an implementation choice but a specification requirement.\"\n },\n {\n \"excerpt\": \"For LR and SC, the Zalrsc extension requires that the address held in rs1 be naturally aligned to the size of the operand\",\n \"line_number\": 119,\n \"reason\": \"This is a fixed requirement ('requires') that all implementations must satisfy. There is no implementation choice here.\"\n }\n ]\n}\n```", + "input_tokens": 11425, + "output_tokens": 840, + "latency_ms": 18157, + "timestamp": "2026-04-15T14:21:52.209347+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_001.json.license b/param_extraction/results/claude-sonnet-4/chunk_001.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_001.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_002.json b/param_extraction/results/claude-sonnet-4/chunk_002.json new file mode 100644 index 0000000000..7c4995c5c8 --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_002.json @@ -0,0 +1,43 @@ +{ + "chunk_id": "chunk_002", + "source_file": "b-st-ext.adoc", + "start_line": 1, + "end_line": 3375, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [], + "skipped_non_parameters": [ + { + "excerpt": "The bit-manipulation (bitmanip) extension collection is comprised of several component extensions to the base RISC-V architecture that are intended to provide some combination of code-size reduction, performance improvement, and energy reduction.", + "line_number": 4, + "reason": "This is descriptive text about the purpose of the extensions, not an implementation choice." + }, + { + "excerpt": "The bitmanip extensions are defined for RV32 and RV64.", + "line_number": 13, + "reason": "This states which base architectures support the extensions, but is not an implementation parameter - it's a fixed requirement." + }, + { + "excerpt": "For RV32, the encodings corresponding to shamt[5]=1 are reserved.", + "line_number": 1050, + "reason": "This describes encoding constraints for RV32, which is a fixed requirement, not an implementation choice." + }, + { + "excerpt": "The Logical with Negate instructions can be implemented by inverting the _rs2_ inputs to the base-required AND, OR, and XOR logic instructions.", + "line_number": 175, + "reason": "This is inside an Implementation Hint [NOTE] block, which is non-normative and should not be extracted." + }, + { + "excerpt": "This instruction is available only on RV32.", + "line_number": 3264, + "reason": "This states availability constraints for specific instructions, which is a fixed requirement rather than an implementation parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"The bit-manipulation (bitmanip) extension collection is comprised of several component extensions to the base RISC-V architecture that are intended to provide some combination of code-size reduction, performance improvement, and energy reduction.\",\n \"line_number\": 4,\n \"reason\": \"This is descriptive text about the purpose of the extensions, not an implementation choice.\"\n },\n {\n \"excerpt\": \"The bitmanip extensions are defined for RV32 and RV64.\",\n \"line_number\": 13,\n \"reason\": \"This states which base architectures support the extensions, but is not an implementation parameter - it's a fixed requirement.\"\n },\n {\n \"excerpt\": \"For RV32, the encodings corresponding to shamt[5]=1 are reserved.\",\n \"line_number\": 1050,\n \"reason\": \"This describes encoding constraints for RV32, which is a fixed requirement, not an implementation choice.\"\n },\n {\n \"excerpt\": \"The Logical with Negate instructions can be implemented by inverting the _rs2_ inputs to the base-required AND, OR, and XOR logic instructions.\",\n \"line_number\": 175,\n \"reason\": \"This is inside an Implementation Hint [NOTE] block, which is non-normative and should not be extracted.\"\n },\n {\n \"excerpt\": \"This instruction is available only on RV32.\",\n \"line_number\": 3264,\n \"reason\": \"This states availability constraints for specific instructions, which is a fixed requirement rather than an implementation parameter.\"\n }\n ]\n}\n```", + "input_tokens": 34261, + "output_tokens": 404, + "latency_ms": 11327, + "timestamp": "2026-04-15T14:22:06.310479+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_002.json.license b/param_extraction/results/claude-sonnet-4/chunk_002.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_002.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_003.json b/param_extraction/results/claude-sonnet-4/chunk_003.json new file mode 100644 index 0000000000..8330695c7b --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_003.json @@ -0,0 +1,54 @@ +{ + "chunk_id": "chunk_003", + "source_file": "bfloat16.adoc", + "start_line": 1, + "end_line": 790, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "All of the BF16 instructions in the extensions defined in this specification (i.e., Zfbfmin, Zvfbfmin, and Zvfbfwma) fully support subnormal numbers. That is, instructions are able to accept subnormal values as inputs and they can produce subnormal results.", + "line_number": 149, + "parameter_name": "BF16_SUBNORMAL_SUPPORT", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "The specification explicitly states that BF16 instructions fully support subnormal numbers, but the NOTE indicates future extensions may choose not to support them, making this an implementation choice." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "Future floating-point extensions, including those that operate on BF16 values, may chose not to support subnormal numbers.", + "line_number": 154, + "reason": "This is inside a [NOTE] block, which is non-normative. NOTE blocks are informative only and do not define architectural parameters." + }, + { + "excerpt": "For BF16, the RISC-V canonical NaN corresponds to the pattern of _0x7fc0_ which is the most significant 16 bits of the RISC-V single-precision canonical NaN.", + "line_number": 185, + "reason": "This defines a fixed constant value (0x7fc0) that all implementations must use for the canonical NaN. It is not a parameter but a fixed requirement." + }, + { + "excerpt": "In RISC-V, tininess is detected after rounding.", + "line_number": 244, + "reason": "This is a fixed requirement that applies to all RISC-V implementations. There is no implementation choice here - all must detect tininess after rounding." + }, + { + "excerpt": "This extension depends upon the single-precision floating-point extension `F`.", + "line_number": 284, + "reason": "This describes a dependency requirement, not an implementation choice. All implementations of this extension must include the F extension." + }, + { + "excerpt": "SEW is any value other than 16", + "line_number": 520, + "reason": "This describes a reserved encoding constraint, not an implementation parameter. It specifies what values are illegal, not what choices implementers have." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"All of the BF16 instructions in the extensions defined in this specification (i.e., Zfbfmin, Zvfbfmin, and Zvfbfwma) fully support subnormal numbers. That is, instructions are able to accept subnormal values as inputs and they can produce subnormal results.\",\n \"line_number\": 149,\n \"parameter_name\": \"BF16_SUBNORMAL_SUPPORT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The specification explicitly states that BF16 instructions fully support subnormal numbers, but the NOTE indicates future extensions may choose not to support them, making this an implementation choice.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"Future floating-point extensions, including those that operate on BF16 values, may chose not to support subnormal numbers.\",\n \"line_number\": 154,\n \"reason\": \"This is inside a [NOTE] block, which is non-normative. NOTE blocks are informative only and do not define architectural parameters.\"\n },\n {\n \"excerpt\": \"For BF16, the RISC-V canonical NaN corresponds to the pattern of _0x7fc0_ which is the most significant 16 bits of the RISC-V single-precision canonical NaN.\",\n \"line_number\": 185,\n \"reason\": \"This defines a fixed constant value (0x7fc0) that all implementations must use for the canonical NaN. It is not a parameter but a fixed requirement.\"\n },\n {\n \"excerpt\": \"In RISC-V, tininess is detected after rounding.\",\n \"line_number\": 244,\n \"reason\": \"This is a fixed requirement that applies to all RISC-V implementations. There is no implementation choice here - all must detect tininess after rounding.\"\n },\n {\n \"excerpt\": \"This extension depends upon the single-precision floating-point extension `F`.\",\n \"line_number\": 284,\n \"reason\": \"This describes a dependency requirement, not an implementation choice. All implementations of this extension must include the F extension.\"\n },\n {\n \"excerpt\": \"SEW is any value other than 16\",\n \"line_number\": 520,\n \"reason\": \"This describes a reserved encoding constraint, not an implementation parameter. It specifies what values are illegal, not what choices implementers have.\"\n }\n ]\n}\n```", + "input_tokens": 13920, + "output_tokens": 634, + "latency_ms": 15362, + "timestamp": "2026-04-15T14:25:36.457672+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_003.json.license b/param_extraction/results/claude-sonnet-4/chunk_003.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_003.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_006.json b/param_extraction/results/claude-sonnet-4/chunk_006.json new file mode 100644 index 0000000000..3474a7ff81 --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_006.json @@ -0,0 +1,94 @@ +{ + "chunk_id": "chunk_006", + "source_file": "c-st-ext.adoc", + "start_line": 1, + "end_line": 931, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "The C extension allows 16-bit instructions to be freely intermixed with 32-bit instructions, with the latter now able to start on any 16-bit boundary, i.e., IALIGN=16.", + "line_number": 25, + "parameter_name": "IALIGN", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "IALIGN is a direct architectural parameter that defines instruction alignment. With the C extension, it becomes 16 bits instead of the base 32 bits." + }, + { + "excerpt": "CIW, CL, CS, CA, and CB are limited to just 8 of them.", + "line_number": 174, + "parameter_name": "RVC_REGISTER_SUBSET", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "set", + "confidence": "high", + "reasoning": "The C extension limits certain instruction formats to only 8 registers (x8-x15) instead of all 32. This is a direct architectural choice in the instruction encoding." + }, + { + "excerpt": "Compressed register-based floating-point loads and stores also use the CL and CS formats respectively, with the eight registers mapping to `f8` to `f15`.", + "line_number": 186, + "parameter_name": "RVC_FP_REGISTER_SUBSET", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "set", + "confidence": "high", + "reasoning": "Similar to integer registers, compressed floating-point instructions are limited to f8-f15. This is a direct architectural encoding choice." + }, + { + "excerpt": "As with base RVI instructions, the offsets of all RVC control transfer instructions are in multiples of 2 bytes.", + "line_number": 456, + "parameter_name": "RVC_OFFSET_ALIGNMENT", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "RVC control transfer instructions have offsets that are multiples of 2 bytes, which is a direct architectural constraint." + }, + { + "excerpt": "A 16-bit instruction with all bits zero is permanently reserved as an illegal instruction.", + "line_number": 774, + "parameter_name": "RVC_ILLEGAL_ZERO", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "The all-zero 16-bit pattern is permanently reserved as illegal. This is a direct architectural choice about instruction encoding." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "Typically, 50%-60% of the RISC-V instructions in a program can be replaced with RVC instructions, resulting in a 25%-30% code-size reduction.", + "line_number": 9, + "reason": "This describes typical compression ratios, which are empirical observations, not implementation-defined parameters." + }, + { + "excerpt": "C.LWSP loads a 32-bit value from memory into register _rd_. It computes an effective address by adding the _zero_-extended offset, scaled by 4, to the stack pointer, `x2`. It expands to `lw rd, offset(x2)`.", + "line_number": 295, + "reason": "This describes the behavior of a specific instruction, not an implementation choice. The instruction semantics are fixed." + }, + { + "excerpt": "C.LWSP is valid only when _rd_\u2260`x0`; the code points with _rd_=`x0` are reserved.", + "line_number": 298, + "reason": "This describes encoding constraints for a specific instruction, not an implementation parameter. The constraint is fixed by the specification." + }, + { + "excerpt": "Register save/restore code at function entry/exit represents a significant portion of static code size.", + "line_number": 370, + "reason": "This text is inside a NOTE block and describes rationale, not normative requirements." + }, + { + "excerpt": "The immediate fields are scrambled in the instruction formats instead of in sequential order so that as many bits as possible are in the same position in every instruction, thereby simplifying implementations.", + "line_number": 210, + "reason": "This text is inside a NOTE block explaining design rationale, not defining implementation parameters." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"The C extension allows 16-bit instructions to be freely intermixed with 32-bit instructions, with the latter now able to start on any 16-bit boundary, i.e., IALIGN=16.\",\n \"line_number\": 25,\n \"parameter_name\": \"IALIGN\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"IALIGN is a direct architectural parameter that defines instruction alignment. With the C extension, it becomes 16 bits instead of the base 32 bits.\"\n },\n {\n \"excerpt\": \"CIW, CL, CS, CA, and CB are limited to just 8 of them.\",\n \"line_number\": 174,\n \"parameter_name\": \"RVC_REGISTER_SUBSET\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"The C extension limits certain instruction formats to only 8 registers (x8-x15) instead of all 32. This is a direct architectural choice in the instruction encoding.\"\n },\n {\n \"excerpt\": \"Compressed register-based floating-point loads and stores also use the CL and CS formats respectively, with the eight registers mapping to `f8` to `f15`.\",\n \"line_number\": 186,\n \"parameter_name\": \"RVC_FP_REGISTER_SUBSET\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"Similar to integer registers, compressed floating-point instructions are limited to f8-f15. This is a direct architectural encoding choice.\"\n },\n {\n \"excerpt\": \"As with base RVI instructions, the offsets of all RVC control transfer instructions are in multiples of 2 bytes.\",\n \"line_number\": 456,\n \"parameter_name\": \"RVC_OFFSET_ALIGNMENT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"RVC control transfer instructions have offsets that are multiples of 2 bytes, which is a direct architectural constraint.\"\n },\n {\n \"excerpt\": \"A 16-bit instruction with all bits zero is permanently reserved as an illegal instruction.\",\n \"line_number\": 774,\n \"parameter_name\": \"RVC_ILLEGAL_ZERO\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The all-zero 16-bit pattern is permanently reserved as illegal. This is a direct architectural choice about instruction encoding.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"Typically, 50%-60% of the RISC-V instructions in a program can be replaced with RVC instructions, resulting in a 25%-30% code-size reduction.\",\n \"line_number\": 9,\n \"reason\": \"This describes typical compression ratios, which are empirical observations, not implementation-defined parameters.\"\n },\n {\n \"excerpt\": \"C.LWSP loads a 32-bit value from memory into register _rd_. It computes an effective address by adding the _zero_-extended offset, scaled by 4, to the stack pointer, `x2`. It expands to `lw rd, offset(x2)`.\",\n \"line_number\": 295,\n \"reason\": \"This describes the behavior of a specific instruction, not an implementation choice. The instruction semantics are fixed.\"\n },\n {\n \"excerpt\": \"C.LWSP is valid only when _rd_\u2260`x0`; the code points with _rd_=`x0` are reserved.\",\n \"line_number\": 298,\n \"reason\": \"This describes encoding constraints for a specific instruction, not an implementation parameter. The constraint is fixed by the specification.\"\n },\n {\n \"excerpt\": \"Register save/restore code at function entry/exit represents a significant portion of static code size.\",\n \"line_number\": 370,\n \"reason\": \"This text is inside a NOTE block and describes rationale, not normative requirements.\"\n },\n {\n \"excerpt\": \"The immediate fields are scrambled in the instruction formats instead of in sequential order so that as many bits as possible are in the same position in every instruction, thereby simplifying implementations.\",\n \"line_number\": 210,\n \"reason\": \"This text is inside a NOTE block explaining design rationale, not defining implementation parameters.\"\n }\n ]\n}\n```", + "input_tokens": 18031, + "output_tokens": 1198, + "latency_ms": 25143, + "timestamp": "2026-04-15T14:26:34.068428+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_006.json.license b/param_extraction/results/claude-sonnet-4/chunk_006.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_006.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_008.json b/param_extraction/results/claude-sonnet-4/chunk_008.json new file mode 100644 index 0000000000..b4d80b91d7 --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_008.json @@ -0,0 +1,104 @@ +{ + "chunk_id": "chunk_008", + "source_file": "cmo.adoc", + "start_line": 1, + "end_line": 1094, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "If the above constraints are not met, the behavior of a CBO instruction is UNSPECIFIED.", + "line_number": 334, + "parameter_name": "CBO_UNSPECIFIED_BEHAVIOR", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "medium", + "reasoning": "When PMP/PMA constraints are not met for a cache block, the implementation can choose any behavior since it's UNSPECIFIED. This is a direct implementation choice." + }, + { + "excerpt": "If neither a load instruction nor store instruction is permitted to access the physical addresses, but an instruction fetch is permitted to access the physical addresses, whether a cache-block management instruction is permitted to access the cache block is UNSPECIFIED.", + "line_number": 361, + "parameter_name": "CBM_IFETCH_ONLY_ACCESS", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "When only instruction fetch is permitted but not load/store, the implementation chooses whether cache-block management instructions can access the block. This is explicitly UNSPECIFIED, making it a binary implementation choice." + }, + { + "excerpt": "Each `x{csrname}` register is WARL; however, software should determine the legal values from the execution environment discovery mechanism.", + "line_number": 598, + "parameter_name": "XENVCFG_LEGAL_VALUES", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "The xenvcfg registers are WARL, meaning implementations can choose which values are legal for the CBIE/CBCFE/CBZE fields. The parameter is the set of legal values for these CSR fields." + }, + { + "excerpt": "Unless otherwise defined by the debug architecture specification, the behavior of trigger modules with respect to CMO instructions is UNSPECIFIED.", + "line_number": 421, + "parameter_name": "CMO_TRIGGER_BEHAVIOR", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "medium", + "reasoning": "The behavior of trigger modules with CMO instructions is UNSPECIFIED, allowing implementations to choose how triggers interact with these instructions." + }, + { + "excerpt": "An implementation may or may not update the entire set of bytes atomically with a single store operation.", + "line_number": 149, + "parameter_name": "CBO_ZERO_ATOMICITY", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "For cache-block zero instructions, implementations can choose whether to update all bytes atomically or not. This is a direct binary implementation choice." + }, + { + "excerpt": "An implementation may or may not update the entire set of bytes atomically.", + "line_number": 1050, + "parameter_name": "CBO_ZERO_ATOMIC_UPDATE", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "This reiterates the atomicity choice for cbo.zero instruction - whether the implementation updates the cache block bytes atomically or not." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "The term CMO encompasses all operations on caches or resources related to caches. The term CBO represents a subset of CMOs that operate only on cache blocks. The first CMO extensions only define CBOs.", + "line_number": 44, + "reason": "This is inside a [NOTE] block, which is non-normative informational text." + }, + { + "excerpt": "In the initial set of CMO extensions, the size of a cache block shall be uniform throughout the system.", + "line_number": 95, + "reason": "This is a fixed requirement ('shall be uniform') that all implementations must satisfy, not an implementation choice." + }, + { + "excerpt": "When MODE=Direct, all traps into machine mode cause the `pc` to be set to the address in the BASE field.", + "line_number": 254, + "reason": "This describes behavior when a CSR field has a specific value, not an implementation parameter. The behavior is determined by runtime CSR state." + }, + { + "excerpt": "CMO instructions do _not_ generate address-misaligned exceptions.", + "line_number": 417, + "reason": "This is a fixed requirement that applies to ALL implementations - CMO instructions must not generate address-misaligned exceptions." + }, + { + "excerpt": "Software may determine the PMP granularity by writing zero to `pmp0cfg`, then writing all ones to `pmpaddr0`, then reading back `pmpaddr0`.", + "line_number": 330, + "reason": "Here 'may' means permission (software is allowed to do this), not optionality. This describes a software technique, not an implementation parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"If the above constraints are not met, the behavior of a CBO instruction is UNSPECIFIED.\",\n \"line_number\": 334,\n \"parameter_name\": \"CBO_UNSPECIFIED_BEHAVIOR\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"medium\",\n \"reasoning\": \"When PMP/PMA constraints are not met for a cache block, the implementation can choose any behavior since it's UNSPECIFIED. This is a direct implementation choice.\"\n },\n {\n \"excerpt\": \"If neither a load instruction nor store instruction is permitted to access the physical addresses, but an instruction fetch is permitted to access the physical addresses, whether a cache-block management instruction is permitted to access the cache block is UNSPECIFIED.\",\n \"line_number\": 361,\n \"parameter_name\": \"CBM_IFETCH_ONLY_ACCESS\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"When only instruction fetch is permitted but not load/store, the implementation chooses whether cache-block management instructions can access the block. This is explicitly UNSPECIFIED, making it a binary implementation choice.\"\n },\n {\n \"excerpt\": \"Each `x{csrname}` register is WARL; however, software should determine the legal values from the execution environment discovery mechanism.\",\n \"line_number\": 598,\n \"parameter_name\": \"XENVCFG_LEGAL_VALUES\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"The xenvcfg registers are WARL, meaning implementations can choose which values are legal for the CBIE/CBCFE/CBZE fields. The parameter is the set of legal values for these CSR fields.\"\n },\n {\n \"excerpt\": \"Unless otherwise defined by the debug architecture specification, the behavior of trigger modules with respect to CMO instructions is UNSPECIFIED.\",\n \"line_number\": 421,\n \"parameter_name\": \"CMO_TRIGGER_BEHAVIOR\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The behavior of trigger modules with CMO instructions is UNSPECIFIED, allowing implementations to choose how triggers interact with these instructions.\"\n },\n {\n \"excerpt\": \"An implementation may or may not update the entire set of bytes atomically with a single store operation.\",\n \"line_number\": 149,\n \"parameter_name\": \"CBO_ZERO_ATOMICITY\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"For cache-block zero instructions, implementations can choose whether to update all bytes atomically or not. This is a direct binary implementation choice.\"\n },\n {\n \"excerpt\": \"An implementation may or may not update the entire set of bytes atomically.\",\n \"line_number\": 1050,\n \"parameter_name\": \"CBO_ZERO_ATOMIC_UPDATE\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"This reiterates the atomicity choice for cbo.zero instruction - whether the implementation updates the cache block bytes atomically or not.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"The term CMO encompasses all operations on caches or resources related to caches. The term CBO represents a subset of CMOs that operate only on cache blocks. The first CMO extensions only define CBOs.\",\n \"line_number\": 44,\n \"reason\": \"This is inside a [NOTE] block, which is non-normative informational text.\"\n },\n {\n \"excerpt\": \"In the initial set of CMO extensions, the size of a cache block shall be uniform throughout the system.\",\n \"line_number\": 95,\n \"reason\": \"This is a fixed requirement ('shall be uniform') that all implementations must satisfy, not an implementation choice.\"\n },\n {\n \"excerpt\": \"When MODE=Direct, all traps into machine mode cause the `pc` to be set to the address in the BASE field.\",\n \"line_number\": 254,\n \"reason\": \"This describes behavior when a CSR field has a specific value, not an implementation parameter. The behavior is determined by runtime CSR state.\"\n },\n {\n \"excerpt\": \"CMO instructions do _not_ generate address-misaligned exceptions.\",\n \"line_number\": 417,\n \"reason\": \"This is a fixed requirement that applies to ALL implementations - CMO instructions must not generate address-misaligned exceptions.\"\n },\n {\n \"excerpt\": \"Software may determine the PMP granularity by writing zero to `pmp0cfg`, then writing all ones to `pmpaddr0`, then reading back `pmpaddr0`.\",\n \"line_number\": 330,\n \"reason\": \"Here 'may' means permission (software is allowed to do this), not optionality. This describes a software technique, not an implementation parameter.\"\n }\n ]\n}\n```", + "input_tokens": 17042, + "output_tokens": 1351, + "latency_ms": 111723, + "timestamp": "2026-04-15T14:24:56.995242+00:00", + "error": null, + "retry_count": 1 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_008.json.license b/param_extraction/results/claude-sonnet-4/chunk_008.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_008.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_010.json b/param_extraction/results/claude-sonnet-4/chunk_010.json new file mode 100644 index 0000000000..b1c74022b9 --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_010.json @@ -0,0 +1,69 @@ +{ + "chunk_id": "chunk_010", + "source_file": "counters.adoc", + "start_line": 1, + "end_line": 237, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "The implemented number and width of these additional counters, and the set of events they count, are platform-specific.", + "line_number": 201, + "parameter_name": "HPM_COUNTER_EN", + "existing_udb_name": "HPM_COUNTER_EN", + "class": "NORM_DIRECT", + "value_type": "set", + "confidence": "high", + "reasoning": "The number of implemented hardware performance counters (hpmcounter3-31) is a direct implementation choice. Implementations can choose which subset of the 29 possible counters to implement." + }, + { + "excerpt": "The implemented number and width of these additional counters, and the set of events they count, are platform-specific.", + "line_number": 201, + "parameter_name": "HPM_EVENTS", + "existing_udb_name": "HPM_EVENTS", + "class": "NORM_DIRECT", + "value_type": "set", + "confidence": "high", + "reasoning": "The set of events that each hardware performance counter can count is platform-specific. This is a direct implementation choice about which events are supported by each counter." + }, + { + "excerpt": "Accessing an unimplemented counter may cause an illegal-instruction exception or may return a constant value.", + "line_number": 203, + "parameter_name": "TRAP_ON_UNIMPLEMENTED_HPM_COUNTER", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "Implementation can choose whether accessing an unimplemented performance counter causes an illegal instruction exception or returns a constant value. This is a binary choice in behavior." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "We recommend provision of these basic counters in implementations as they are essential for basic performance analysis", + "line_number": 16, + "reason": "This is inside a [NOTE] block, which is non-normative. Recommendations in NOTE blocks are not architectural parameters." + }, + { + "excerpt": "The RDCYCLE pseudoinstruction reads the low XLEN bits of the `cycle` CSR which holds a count of the number of clock cycles executed by the processor core", + "line_number": 53, + "reason": "This describes the fixed behavior of RDCYCLE instruction. All implementations must provide this behavior - it's not a parameter." + }, + { + "excerpt": "The real-time clocks of all harts must be synchronized to within one tick of the real-time clock.", + "line_number": 118, + "reason": "This is a fixed requirement ('must be synchronized') that applies to all implementations. There is no implementation choice here." + }, + { + "excerpt": "Instructions that cause synchronous exceptions, including ECALL and EBREAK, are not considered to retire", + "line_number": 142, + "reason": "This is inside a [NOTE] block and describes fixed behavior for instruction retirement counting. It's not an implementation choice." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"The implemented number and width of these additional counters, and the set of events they count, are platform-specific.\",\n \"line_number\": 201,\n \"parameter_name\": \"HPM_COUNTER_EN\",\n \"existing_udb_name\": \"HPM_COUNTER_EN\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"The number of implemented hardware performance counters (hpmcounter3-31) is a direct implementation choice. Implementations can choose which subset of the 29 possible counters to implement.\"\n },\n {\n \"excerpt\": \"The implemented number and width of these additional counters, and the set of events they count, are platform-specific.\",\n \"line_number\": 201,\n \"parameter_name\": \"HPM_EVENTS\",\n \"existing_udb_name\": \"HPM_EVENTS\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"The set of events that each hardware performance counter can count is platform-specific. This is a direct implementation choice about which events are supported by each counter.\"\n },\n {\n \"excerpt\": \"Accessing an unimplemented counter may cause an illegal-instruction exception or may return a constant value.\",\n \"line_number\": 203,\n \"parameter_name\": \"TRAP_ON_UNIMPLEMENTED_HPM_COUNTER\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"Implementation can choose whether accessing an unimplemented performance counter causes an illegal instruction exception or returns a constant value. This is a binary choice in behavior.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"We recommend provision of these basic counters in implementations as they are essential for basic performance analysis\",\n \"line_number\": 16,\n \"reason\": \"This is inside a [NOTE] block, which is non-normative. Recommendations in NOTE blocks are not architectural parameters.\"\n },\n {\n \"excerpt\": \"The RDCYCLE pseudoinstruction reads the low XLEN bits of the `cycle` CSR which holds a count of the number of clock cycles executed by the processor core\",\n \"line_number\": 53,\n \"reason\": \"This describes the fixed behavior of RDCYCLE instruction. All implementations must provide this behavior - it's not a parameter.\"\n },\n {\n \"excerpt\": \"The real-time clocks of all harts must be synchronized to within one tick of the real-time clock.\",\n \"line_number\": 118,\n \"reason\": \"This is a fixed requirement ('must be synchronized') that applies to all implementations. There is no implementation choice here.\"\n },\n {\n \"excerpt\": \"Instructions that cause synchronous exceptions, including ECALL and EBREAK, are not considered to retire\",\n \"line_number\": 142,\n \"reason\": \"This is inside a [NOTE] block and describes fixed behavior for instruction retirement counting. It's not an implementation choice.\"\n }\n ]\n}\n```", + "input_tokens": 8549, + "output_tokens": 797, + "latency_ms": 13427, + "timestamp": "2026-04-15T14:24:41.343859+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_010.json.license b/param_extraction/results/claude-sonnet-4/chunk_010.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_010.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_011.json b/param_extraction/results/claude-sonnet-4/chunk_011.json new file mode 100644 index 0000000000..15ceb60484 --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_011.json @@ -0,0 +1,54 @@ +{ + "chunk_id": "chunk_011", + "source_file": "d-st-ext.adoc", + "start_line": 1, + "end_line": 239, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "The D extension widens the 32 floating-point registers, `f0-f31`, to 64 bits (FLEN=64 in <>", + "line_number": 11, + "parameter_name": "FLEN", + "existing_udb_name": "FLEN", + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "FLEN is set to 64 when the D extension is implemented. This is a direct architectural parameter that determines the width of floating-point registers." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "FLEN can be 32, 64, or 128 depending on which of the F, D, and Q extensions are supported. There can be up to four different floating-point precisions supported, including H, F, D, and Q.", + "line_number": 17, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. It provides informative context about FLEN values but does not define an implementation choice." + }, + { + "excerpt": "The FLD instruction loads a double-precision floating-point value from memory into floating-point register _rd_", + "line_number": 95, + "reason": "This describes the fixed behavior of the FLD instruction. All implementations must support this behavior - it is not an implementation choice." + }, + { + "excerpt": "FLD and FSD are only guaranteed to execute atomically if the effective address is naturally aligned and XLEN\u226564.", + "line_number": 105, + "reason": "This describes a fixed requirement about when atomicity is guaranteed. It is not an implementation choice but a specification of when certain guarantees apply." + }, + { + "excerpt": "FCVT.L[U].D and FCVT.D.L[U] are RV64-only instructions.", + "line_number": 130, + "reason": "This is a fixed requirement that these instructions are only available on RV64. It is not an implementation choice but a specification constraint." + }, + { + "excerpt": "The double-precision floating-point compare instructions are defined analogously to their single-precision counterparts, but operate on double-precision operands.", + "line_number": 218, + "reason": "This describes the fixed behavior of compare instructions. All implementations must follow this specification - it is not a parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"The D extension widens the 32 floating-point registers, `f0-f31`, to 64 bits (FLEN=64 in <>\",\n \"line_number\": 11,\n \"parameter_name\": \"FLEN\",\n \"existing_udb_name\": \"FLEN\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"FLEN is set to 64 when the D extension is implemented. This is a direct architectural parameter that determines the width of floating-point registers.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"FLEN can be 32, 64, or 128 depending on which of the F, D, and Q extensions are supported. There can be up to four different floating-point precisions supported, including H, F, D, and Q.\",\n \"line_number\": 17,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. It provides informative context about FLEN values but does not define an implementation choice.\"\n },\n {\n \"excerpt\": \"The FLD instruction loads a double-precision floating-point value from memory into floating-point register _rd_\",\n \"line_number\": 95,\n \"reason\": \"This describes the fixed behavior of the FLD instruction. All implementations must support this behavior - it is not an implementation choice.\"\n },\n {\n \"excerpt\": \"FLD and FSD are only guaranteed to execute atomically if the effective address is naturally aligned and XLEN\u226564.\",\n \"line_number\": 105,\n \"reason\": \"This describes a fixed requirement about when atomicity is guaranteed. It is not an implementation choice but a specification of when certain guarantees apply.\"\n },\n {\n \"excerpt\": \"FCVT.L[U].D and FCVT.D.L[U] are RV64-only instructions.\",\n \"line_number\": 130,\n \"reason\": \"This is a fixed requirement that these instructions are only available on RV64. It is not an implementation choice but a specification constraint.\"\n },\n {\n \"excerpt\": \"The double-precision floating-point compare instructions are defined analogously to their single-precision counterparts, but operate on double-precision operands.\",\n \"line_number\": 218,\n \"reason\": \"This describes the fixed behavior of compare instructions. All implementations must follow this specification - it is not a parameter.\"\n }\n ]\n}\n```", + "input_tokens": 8888, + "output_tokens": 632, + "latency_ms": 28422, + "timestamp": "2026-04-15T14:26:09.828408+00:00", + "error": null, + "retry_count": 1 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_011.json.license b/param_extraction/results/claude-sonnet-4/chunk_011.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_011.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_012.json b/param_extraction/results/claude-sonnet-4/chunk_012.json new file mode 100644 index 0000000000..ed1ac83a93 --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_012.json @@ -0,0 +1,54 @@ +{ + "chunk_id": "chunk_012", + "source_file": "f-st-ext.adoc", + "start_line": 1, + "end_line": 524, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "The behavior of floating-point instructions that depend on rounding mode when executed with a reserved rounding mode is _reserved_, including both static reserved rounding modes (101-110) and dynamic reserved rounding modes (101-111).", + "line_number": 130, + "parameter_name": "TRAP_ON_RESERVED_ROUNDING_MODE", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "The behavior when encountering reserved rounding modes is implementation-defined ('reserved'). Implementations may trap or handle it differently, making this a direct implementation choice." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "We considered a unified register file for both integer and floating-point values as this simplifies software register allocation and calling conventions, and reduces total user state.", + "line_number": 24, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. It describes design considerations, not architectural requirements." + }, + { + "excerpt": "The F extension adds 32 floating-point registers, `f0-f31`, each 32 bits wide", + "line_number": 11, + "reason": "This is a fixed requirement of the F extension - all implementations must provide exactly 32 floating-point registers of 32 bits each. There is no implementation choice here." + }, + { + "excerpt": "FADD.S and FMUL.S perform single-precision floating-point addition and multiplication respectively, between _rs1_ and _rs2_", + "line_number": 244, + "reason": "This describes the fixed behavior of specific instructions. The operation performed is defined by the instruction encoding, not by implementation choice." + }, + { + "excerpt": "FLW and FSW are only guaranteed to execute atomically if the effective address is naturally aligned.", + "line_number": 218, + "reason": "This is a fixed requirement about when atomicity is guaranteed. All implementations must follow this rule - there is no implementation choice." + }, + { + "excerpt": "As described in <>, the execution environment defines whether misaligned floating-point loads and stores are handled invisibly or raise a contained or fatal trap.", + "line_number": 224, + "reason": "This refers to execution environment behavior, which is outside the ISA scope. The ISA itself doesn't define this choice - it's a platform-level decision." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"The behavior of floating-point instructions that depend on rounding mode when executed with a reserved rounding mode is _reserved_, including both static reserved rounding modes (101-110) and dynamic reserved rounding modes (101-111).\",\n \"line_number\": 130,\n \"parameter_name\": \"TRAP_ON_RESERVED_ROUNDING_MODE\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The behavior when encountering reserved rounding modes is implementation-defined ('reserved'). Implementations may trap or handle it differently, making this a direct implementation choice.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"We considered a unified register file for both integer and floating-point values as this simplifies software register allocation and calling conventions, and reduces total user state.\",\n \"line_number\": 24,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. It describes design considerations, not architectural requirements.\"\n },\n {\n \"excerpt\": \"The F extension adds 32 floating-point registers, `f0-f31`, each 32 bits wide\",\n \"line_number\": 11,\n \"reason\": \"This is a fixed requirement of the F extension - all implementations must provide exactly 32 floating-point registers of 32 bits each. There is no implementation choice here.\"\n },\n {\n \"excerpt\": \"FADD.S and FMUL.S perform single-precision floating-point addition and multiplication respectively, between _rs1_ and _rs2_\",\n \"line_number\": 244,\n \"reason\": \"This describes the fixed behavior of specific instructions. The operation performed is defined by the instruction encoding, not by implementation choice.\"\n },\n {\n \"excerpt\": \"FLW and FSW are only guaranteed to execute atomically if the effective address is naturally aligned.\",\n \"line_number\": 218,\n \"reason\": \"This is a fixed requirement about when atomicity is guaranteed. All implementations must follow this rule - there is no implementation choice.\"\n },\n {\n \"excerpt\": \"As described in <>, the execution environment defines whether misaligned floating-point loads and stores are handled invisibly or raise a contained or fatal trap.\",\n \"line_number\": 224,\n \"reason\": \"This refers to execution environment behavior, which is outside the ISA scope. The ISA itself doesn't define this choice - it's a platform-level decision.\"\n }\n ]\n}\n```", + "input_tokens": 13070, + "output_tokens": 639, + "latency_ms": 15811, + "timestamp": "2026-04-15T14:27:24.342301+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_012.json.license b/param_extraction/results/claude-sonnet-4/chunk_012.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_012.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_013.json b/param_extraction/results/claude-sonnet-4/chunk_013.json new file mode 100644 index 0000000000..b5f2da8832 --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_013.json @@ -0,0 +1,38 @@ +{ + "chunk_id": "chunk_013", + "source_file": "fraclmul.adoc", + "start_line": 1, + "end_line": 175, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [], + "skipped_non_parameters": [ + { + "excerpt": "This appendix presents a non-normative example to help explain where compilers can make good use of the fractional LMUL feature.", + "line_number": 3, + "reason": "This is a non-normative example section that explains compiler usage patterns, not an architectural parameter definition." + }, + { + "excerpt": "Without fractional LMUL, the compiler would be forced to use LMUL=1 for the 8-bit computation and LMUL=8 for the 64-bit computation(s)", + "line_number": 26, + "reason": "This describes compiler behavior and usage patterns, not an implementation-defined architectural parameter." + }, + { + "excerpt": "If instead of using LMUL=1 for the 8-bit computation, the compiler is allowed to use a fractional LMUL=1/2", + "line_number": 103, + "reason": "This describes a compiler optimization strategy using existing architectural features, not a parameter that implementations choose." + }, + { + "excerpt": "vsetvli s1, zero, e8,mf2,ta,mu // LMUL=1/2 !", + "line_number": 110, + "reason": "This is assembly code showing usage of fractional LMUL values, which are runtime software choices, not implementation-defined parameters." + } + ], + "raw_response": "```json\n{\n \"parameters\": [],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"This appendix presents a non-normative example to help explain where compilers can make good use of the fractional LMUL feature.\",\n \"line_number\": 3,\n \"reason\": \"This is a non-normative example section that explains compiler usage patterns, not an architectural parameter definition.\"\n },\n {\n \"excerpt\": \"Without fractional LMUL, the compiler would be forced to use LMUL=1 for the 8-bit computation and LMUL=8 for the 64-bit computation(s)\",\n \"line_number\": 26,\n \"reason\": \"This describes compiler behavior and usage patterns, not an implementation-defined architectural parameter.\"\n },\n {\n \"excerpt\": \"If instead of using LMUL=1 for the 8-bit computation, the compiler is allowed to use a fractional LMUL=1/2\",\n \"line_number\": 103,\n \"reason\": \"This describes a compiler optimization strategy using existing architectural features, not a parameter that implementations choose.\"\n },\n {\n \"excerpt\": \"vsetvli s1, zero, e8,mf2,ta,mu // LMUL=1/2 !\",\n \"line_number\": 110,\n \"reason\": \"This is assembly code showing usage of fractional LMUL values, which are runtime software choices, not implementation-defined parameters.\"\n }\n ]\n}\n```", + "input_tokens": 8146, + "output_tokens": 370, + "latency_ms": 7094, + "timestamp": "2026-04-15T14:30:26.354359+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_013.json.license b/param_extraction/results/claude-sonnet-4/chunk_013.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_013.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_014.json b/param_extraction/results/claude-sonnet-4/chunk_014.json new file mode 100644 index 0000000000..168602e43c --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_014.json @@ -0,0 +1,159 @@ +{ + "chunk_id": "chunk_014", + "source_file": "hypervisor.adoc", + "start_line": 1, + "end_line": 2932, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "CSR `mtval` must not be read-only zero", + "line_number": 24, + "parameter_name": "MTVAL_IMPLEMENTED", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation must choose whether mtval is implemented (not read-only zero) or not. This is a direct architectural choice." + }, + { + "excerpt": "standard page-based address translation must be supported, either Sv32 for RV32, or a minimum of Sv39 for RV64", + "line_number": 25, + "parameter_name": "H_VM_SUPPORTED", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "high", + "reasoning": "The implementation must choose which page-based translation modes to support when the H extension is enabled. This is a direct architectural requirement." + }, + { + "excerpt": "we use the term _HSXLEN_ to refer to the effective XLEN when executing in HS-mode", + "line_number": 139, + "parameter_name": "HSXLEN", + "existing_udb_name": "HSXLEN", + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "high", + "reasoning": "HSXLEN is an architectural parameter that determines the effective XLEN in HS-mode, similar to MXLEN." + }, + { + "excerpt": "_VSXLEN_ to refer to the effective XLEN when executing in VS-mode", + "line_number": 140, + "parameter_name": "VSXLEN", + "existing_udb_name": "VSXLEN", + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "high", + "reasoning": "VSXLEN is an architectural parameter that determines the effective XLEN in VS-mode." + }, + { + "excerpt": "an implementation may make VSXL be a read-only field whose value always ensures that VSXLEN=HSXLEN", + "line_number": 165, + "parameter_name": "VSXL_READ_ONLY", + "existing_udb_name": null, + "class": "NORM_CSR_RW", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether the VSXL field is read-only or writable, controlling whether VSXLEN can differ from HSXLEN." + }, + { + "excerpt": "An implementation may have WFI always raise a virtual-instruction exception in VS-mode when VTW=1 (and `mstatus`.TW=0), even if there are pending globally-disabled interrupts when the instruction is executed", + "line_number": 181, + "parameter_name": "VTW_VIRTINSTR_BEHAVIOR", + "existing_udb_name": "VTW_VIRTINSTR_PARAM", + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether WFI always raises a virtual-instruction exception when VTW=1, or only when it doesn't complete within a bounded time." + }, + { + "excerpt": "GEILEN may be zero, in which case VGEIN may be read-only zero", + "line_number": 192, + "parameter_name": "GEILEN", + "existing_udb_name": "GEILEN", + "class": "NORM_DIRECT", + "value_type": "range", + "confidence": "high", + "reasoning": "GEILEN is the maximum guest external interrupt number, which is an implementation-defined parameter that may be zero." + }, + { + "excerpt": "An implementation may make field UBE be a read-only copy of `hstatus`.VSBE", + "line_number": 1050, + "parameter_name": "VSSTATUS_UBE_READONLY", + "existing_udb_name": "VSSTATUS_UBE_PARAM", + "class": "NORM_CSR_RW", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether vsstatus.UBE is read-only (copying hstatus.VSBE) or independently writable." + }, + { + "excerpt": "The number of VMID bits is UNSPECIFIED and may be zero", + "line_number": 1421, + "parameter_name": "VMID_WIDTH", + "existing_udb_name": "VMID_WIDTH", + "class": "NORM_DIRECT", + "value_type": "range", + "confidence": "high", + "reasoning": "VMIDLEN is the number of implemented VMID bits, which is an implementation-defined parameter that may be zero." + }, + { + "excerpt": "The least-significant bits of VMID are implemented first: that is, if VMIDLEN > 0, VMID[VMIDLEN-1:0] is writable. The maximal value of VMIDLEN, termed VMIDMAX, is 7 for Sv32x4 or 14 for Sv39x4, Sv48x4, and Sv57x4", + "line_number": 1425, + "parameter_name": "VMIDLEN", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "range", + "confidence": "high", + "reasoning": "VMIDLEN is the actual number of implemented VMID bits, constrained by VMIDMAX but chosen by the implementation." + }, + { + "excerpt": "When a guest-page-fault trap is taken into HS-mode, `htval` is written with either zero or the guest physical address that faulted, shifted right by 2 bits", + "line_number": 1568, + "parameter_name": "HTVAL_TRAPVAL_PARAM", + "existing_udb_name": "HTVAL_TRAPVAL_PARAM", + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether to write the faulting guest physical address to htval or just write zero on guest-page faults." + }, + { + "excerpt": "When a guest-page-fault trap is taken into M-mode, `mtval2` is written with either zero or the guest physical address that faulted, shifted right by 2 bits", + "line_number": 2644, + "parameter_name": "MTVAL2_TRAPVAL_PARAM", + "existing_udb_name": "MTVAL2_TRAPVAL_PARAM", + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether to write the faulting guest physical address to mtval2 or just write zero on guest-page faults." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "The hypervisor extension is enabled by setting bit 7 in the `misa` CSR", + "line_number": 29, + "reason": "This describes how to enable the extension, not an implementation choice. All implementations must use bit 7 for the H extension." + }, + { + "excerpt": "When V=1, the VS CSRs substitute for the corresponding supervisor CSRs, taking over all functions of the usual supervisor CSRs except as specified otherwise", + "line_number": 95, + "reason": "This describes the behavioral effect of V=1, not an implementation parameter. The behavior is fixed by the specification." + }, + { + "excerpt": "When MODE=Direct, all traps into machine mode cause the `pc` to be set to the address in the BASE field", + "line_number": 1254, + "reason": "This describes what happens when mtvec.MODE has a specific value. The behavior is determined by the CSR field value at runtime, not by an implementation choice." + }, + { + "excerpt": "Software may determine the PMP granularity by writing zero to `pmp0cfg`, then writing all ones to `pmpaddr0`, then reading back `pmpaddr0`", + "line_number": 3530, + "reason": "Here 'may' means 'is allowed to' (permission), not 'might or might not' (optionality). This describes a software technique, not an implementation-defined parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"CSR `mtval` must not be read-only zero\",\n \"line_number\": 24,\n \"parameter_name\": \"MTVAL_IMPLEMENTED\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation must choose whether mtval is implemented (not read-only zero) or not. This is a direct architectural choice.\"\n },\n {\n \"excerpt\": \"standard page-based address translation must be supported, either Sv32 for RV32, or a minimum of Sv39 for RV64\",\n \"line_number\": 25,\n \"parameter_name\": \"H_VM_SUPPORTED\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation must choose which page-based translation modes to support when the H extension is enabled. This is a direct architectural requirement.\"\n },\n {\n \"excerpt\": \"we use the term _HSXLEN_ to refer to the effective XLEN when executing in HS-mode\",\n \"line_number\": 139,\n \"parameter_name\": \"HSXLEN\",\n \"existing_udb_name\": \"HSXLEN\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"HSXLEN is an architectural parameter that determines the effective XLEN in HS-mode, similar to MXLEN.\"\n },\n {\n \"excerpt\": \"_VSXLEN_ to refer to the effective XLEN when executing in VS-mode\",\n \"line_number\": 140,\n \"parameter_name\": \"VSXLEN\",\n \"existing_udb_name\": \"VSXLEN\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"VSXLEN is an architectural parameter that determines the effective XLEN in VS-mode.\"\n },\n {\n \"excerpt\": \"an implementation may make VSXL be a read-only field whose value always ensures that VSXLEN=HSXLEN\",\n \"line_number\": 165,\n \"parameter_name\": \"VSXL_READ_ONLY\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether the VSXL field is read-only or writable, controlling whether VSXLEN can differ from HSXLEN.\"\n },\n {\n \"excerpt\": \"An implementation may have WFI always raise a virtual-instruction exception in VS-mode when VTW=1 (and `mstatus`.TW=0), even if there are pending globally-disabled interrupts when the instruction is executed\",\n \"line_number\": 181,\n \"parameter_name\": \"VTW_VIRTINSTR_BEHAVIOR\",\n \"existing_udb_name\": \"VTW_VIRTINSTR_PARAM\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether WFI always raises a virtual-instruction exception when VTW=1, or only when it doesn't complete within a bounded time.\"\n },\n {\n \"excerpt\": \"GEILEN may be zero, in which case VGEIN may be read-only zero\",\n \"line_number\": 192,\n \"parameter_name\": \"GEILEN\",\n \"existing_udb_name\": \"GEILEN\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"range\",\n \"confidence\": \"high\",\n \"reasoning\": \"GEILEN is the maximum guest external interrupt number, which is an implementation-defined parameter that may be zero.\"\n },\n {\n \"excerpt\": \"An implementation may make field UBE be a read-only copy of `hstatus`.VSBE\",\n \"line_number\": 1050,\n \"parameter_name\": \"VSSTATUS_UBE_READONLY\",\n \"existing_udb_name\": \"VSSTATUS_UBE_PARAM\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether vsstatus.UBE is read-only (copying hstatus.VSBE) or independently writable.\"\n },\n {\n \"excerpt\": \"The number of VMID bits is UNSPECIFIED and may be zero\",\n \"line_number\": 1421,\n \"parameter_name\": \"VMID_WIDTH\",\n \"existing_udb_name\": \"VMID_WIDTH\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"range\",\n \"confidence\": \"high\",\n \"reasoning\": \"VMIDLEN is the number of implemented VMID bits, which is an implementation-defined parameter that may be zero.\"\n },\n {\n \"excerpt\": \"The least-significant bits of VMID are implemented first: that is, if VMIDLEN > 0, VMID[VMIDLEN-1:0] is writable. The maximal value of VMIDLEN, termed VMIDMAX, is 7 for Sv32x4 or 14 for Sv39x4, Sv48x4, and Sv57x4\",\n \"line_number\": 1425,\n \"parameter_name\": \"VMIDLEN\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"range\",\n \"confidence\": \"high\",\n \"reasoning\": \"VMIDLEN is the actual number of implemented VMID bits, constrained by VMIDMAX but chosen by the implementation.\"\n },\n {\n \"excerpt\": \"When a guest-page-fault trap is taken into HS-mode, `htval` is written with either zero or the guest physical address that faulted, shifted right by 2 bits\",\n \"line_number\": 1568,\n \"parameter_name\": \"HTVAL_TRAPVAL_PARAM\",\n \"existing_udb_name\": \"HTVAL_TRAPVAL_PARAM\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether to write the faulting guest physical address to htval or just write zero on guest-page faults.\"\n },\n {\n \"excerpt\": \"When a guest-page-fault trap is taken into M-mode, `mtval2` is written with either zero or the guest physical address that faulted, shifted right by 2 bits\",\n \"line_number\": 2644,\n \"parameter_name\": \"MTVAL2_TRAPVAL_PARAM\",\n \"existing_udb_name\": \"MTVAL2_TRAPVAL_PARAM\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether to write the faulting guest physical address to mtval2 or just write zero on guest-page faults.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"The hypervisor extension is enabled by setting bit 7 in the `misa` CSR\",\n \"line_number\": 29,\n \"reason\": \"This describes how to enable the extension, not an implementation choice. All implementations must use bit 7 for the H extension.\"\n },\n {\n \"excerpt\": \"When V=1, the VS CSRs substitute for the corresponding supervisor CSRs, taking over all functions of the usual supervisor CSRs except as specified otherwise\",\n \"line_number\": 95,\n \"reason\": \"This describes the behavioral effect of V=1, not an implementation parameter. The behavior is fixed by the specification.\"\n },\n {\n \"excerpt\": \"When MODE=Direct, all traps into machine mode cause the `pc` to be set to the address in the BASE field\",\n \"line_number\": 1254,\n \"reason\": \"This describes what happens when mtvec.MODE has a specific value. The behavior is determined by the CSR field value at runtime, not by an implementation choice.\"\n },\n {\n \"excerpt\": \"Software may determine the PMP granularity by writing zero to `pmp0cfg`, then writing all ones to `pmpaddr0`, then reading back `pmpaddr0`\",\n \"line_number\": 3530,\n \"reason\": \"Here 'may' means 'is allowed to' (permission), not 'might or might not' (optionality). This describes a software technique, not an implementation-defined parameter.\"\n }\n ]\n}\n```", + "input_tokens": 43015, + "output_tokens": 2247, + "latency_ms": 39566, + "timestamp": "2026-04-15T14:28:47.169712+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_014.json.license b/param_extraction/results/claude-sonnet-4/chunk_014.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_014.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_016.json b/param_extraction/results/claude-sonnet-4/chunk_016.json new file mode 100644 index 0000000000..1e151ad392 --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_016.json @@ -0,0 +1,114 @@ +{ + "chunk_id": "chunk_016", + "source_file": "indirect-csr.adoc", + "start_line": 1, + "end_line": 333, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "`miselect` is a WARL register.", + "line_number": 67, + "parameter_name": "MISELECT_WARL_VALUES", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "miselect is explicitly stated to be WARL, meaning implementations can restrict which values are legal. The parameter is the set of supported miselect values." + }, + { + "excerpt": "The `miselect` register may be read-only zero if there are no extensions implemented that utilize it.", + "line_number": 72, + "parameter_name": "MISELECT_ACCESS", + "existing_udb_name": null, + "class": "NORM_CSR_RW", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether miselect is read-only zero or read-write, depending on whether extensions that use it are implemented." + }, + { + "excerpt": "The behavior upon accessing `mireg*` from M-mode, while `miselect` holds a value that is not implemented, is UNSPECIFIED.", + "line_number": 84, + "parameter_name": "MIREG_UNIMPLEMENTED_BEHAVIOR", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "high", + "reasoning": "The behavior when accessing mireg* with unimplemented miselect values is explicitly unspecified, giving implementations freedom to choose (e.g., illegal instruction exception, read-only zero, etc.)." + }, + { + "excerpt": "The `siselect` register will support the value range 0..0xFFF at a minimum. A future extension may define a value range outside of this minimum range. Only if such an extension is implemented will `siselect` be required to support larger values.", + "line_number": 119, + "parameter_name": "SISELECT_RANGE", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "range", + "confidence": "high", + "reasoning": "The siselect register must support at least 0..0xFFF, but implementations may support larger ranges if they implement extensions that require them. The actual supported range is an implementation choice." + }, + { + "excerpt": "The behavior upon accessing `sireg*` from M-mode or S-mode, while `siselect` holds a value that is not implemented at supervisor level, is UNSPECIFIED.", + "line_number": 137, + "parameter_name": "SIREG_UNIMPLEMENTED_BEHAVIOR", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "high", + "reasoning": "The behavior when accessing sireg* with unimplemented siselect values is explicitly unspecified, giving implementations freedom to choose the response." + }, + { + "excerpt": "The `vsiselect` register will support the value range 0..0xFFF at a minimum. A future extension may define a value range outside of this minimum range. Only if such an extension is implemented will `vsiselect` be required to support larger values.", + "line_number": 177, + "parameter_name": "VSISELECT_RANGE", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "range", + "confidence": "high", + "reasoning": "Similar to siselect, vsiselect must support at least 0..0xFFF, but implementations may support larger ranges based on implemented extensions." + }, + { + "excerpt": "The behavior upon accessing `vsireg*` from M-mode or HS-mode, or accessing `sireg*` (really `vsireg*`) from VS-mode, while `vsiselect` holds a value that is not implemented at HS level, is UNSPECIFIED.", + "line_number": 205, + "parameter_name": "VSIREG_UNIMPLEMENTED_BEHAVIOR", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "high", + "reasoning": "The behavior when accessing vsireg* with unimplemented vsiselect values is explicitly unspecified, allowing implementation-defined responses." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "CSRs are accessed indirectly via this extension using select values, in contrast to being accessed directly using standard CSR numbers.", + "line_number": 18, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks." + }, + { + "excerpt": "The `mireg*` CSR numbers are not consecutive because miph is CSR number 0x354.", + "line_number": 54, + "reason": "This text is inside a [NOTE] block explaining CSR numbering, which is informative rather than defining an implementation parameter." + }, + { + "excerpt": "When `mstateen0`[60]=0, an attempt to access one of these CSRs from a privilege mode less privileged than M-mode results in an illegal-instruction exception.", + "line_number": 237, + "reason": "This describes what happens when a CSR field has a specific value (mstateen0[60]=0). The behavior is determined by the field value at runtime, not by an implementation choice." + }, + { + "excerpt": "The CSRs in the table above are required if S-mode is implemented.", + "line_number": 117, + "reason": "This is a fixed requirement ('required if S-mode is implemented') that applies to all implementations with S-mode. There is no implementation choice here." + }, + { + "excerpt": "It is expected that implementations will typically raise an illegal-instruction exception for such accesses", + "line_number": 87, + "reason": "This text is inside a [NOTE] block describing expected behavior, which is informative guidance rather than a normative parameter definition." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"`miselect` is a WARL register.\",\n \"line_number\": 67,\n \"parameter_name\": \"MISELECT_WARL_VALUES\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"miselect is explicitly stated to be WARL, meaning implementations can restrict which values are legal. The parameter is the set of supported miselect values.\"\n },\n {\n \"excerpt\": \"The `miselect` register may be read-only zero if there are no extensions implemented that utilize it.\",\n \"line_number\": 72,\n \"parameter_name\": \"MISELECT_ACCESS\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether miselect is read-only zero or read-write, depending on whether extensions that use it are implemented.\"\n },\n {\n \"excerpt\": \"The behavior upon accessing `mireg*` from M-mode, while `miselect` holds a value that is not implemented, is UNSPECIFIED.\",\n \"line_number\": 84,\n \"parameter_name\": \"MIREG_UNIMPLEMENTED_BEHAVIOR\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"The behavior when accessing mireg* with unimplemented miselect values is explicitly unspecified, giving implementations freedom to choose (e.g., illegal instruction exception, read-only zero, etc.).\"\n },\n {\n \"excerpt\": \"The `siselect` register will support the value range 0..0xFFF at a minimum. A future extension may define a value range outside of this minimum range. Only if such an extension is implemented will `siselect` be required to support larger values.\",\n \"line_number\": 119,\n \"parameter_name\": \"SISELECT_RANGE\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"range\",\n \"confidence\": \"high\",\n \"reasoning\": \"The siselect register must support at least 0..0xFFF, but implementations may support larger ranges if they implement extensions that require them. The actual supported range is an implementation choice.\"\n },\n {\n \"excerpt\": \"The behavior upon accessing `sireg*` from M-mode or S-mode, while `siselect` holds a value that is not implemented at supervisor level, is UNSPECIFIED.\",\n \"line_number\": 137,\n \"parameter_name\": \"SIREG_UNIMPLEMENTED_BEHAVIOR\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"The behavior when accessing sireg* with unimplemented siselect values is explicitly unspecified, giving implementations freedom to choose the response.\"\n },\n {\n \"excerpt\": \"The `vsiselect` register will support the value range 0..0xFFF at a minimum. A future extension may define a value range outside of this minimum range. Only if such an extension is implemented will `vsiselect` be required to support larger values.\",\n \"line_number\": 177,\n \"parameter_name\": \"VSISELECT_RANGE\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"range\",\n \"confidence\": \"high\",\n \"reasoning\": \"Similar to siselect, vsiselect must support at least 0..0xFFF, but implementations may support larger ranges based on implemented extensions.\"\n },\n {\n \"excerpt\": \"The behavior upon accessing `vsireg*` from M-mode or HS-mode, or accessing `sireg*` (really `vsireg*`) from VS-mode, while `vsiselect` holds a value that is not implemented at HS level, is UNSPECIFIED.\",\n \"line_number\": 205,\n \"parameter_name\": \"VSIREG_UNIMPLEMENTED_BEHAVIOR\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"The behavior when accessing vsireg* with unimplemented vsiselect values is explicitly unspecified, allowing implementation-defined responses.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"CSRs are accessed indirectly via this extension using select values, in contrast to being accessed directly using standard CSR numbers.\",\n \"line_number\": 18,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks.\"\n },\n {\n \"excerpt\": \"The `mireg*` CSR numbers are not consecutive because miph is CSR number 0x354.\",\n \"line_number\": 54,\n \"reason\": \"This text is inside a [NOTE] block explaining CSR numbering, which is informative rather than defining an implementation parameter.\"\n },\n {\n \"excerpt\": \"When `mstateen0`[60]=0, an attempt to access one of these CSRs from a privilege mode less privileged than M-mode results in an illegal-instruction exception.\",\n \"line_number\": 237,\n \"reason\": \"This describes what happens when a CSR field has a specific value (mstateen0[60]=0). The behavior is determined by the field value at runtime, not by an implementation choice.\"\n },\n {\n \"excerpt\": \"The CSRs in the table above are required if S-mode is implemented.\",\n \"line_number\": 117,\n \"reason\": \"This is a fixed requirement ('required if S-mode is implemented') that applies to all implementations with S-mode. There is no implementation choice here.\"\n },\n {\n \"excerpt\": \"It is expected that implementations will typically raise an illegal-instruction exception for such accesses\",\n \"line_number\": 87,\n \"reason\": \"This text is inside a [NOTE] block describing expected behavior, which is informative guidance rather than a normative parameter definition.\"\n }\n ]\n}\n```", + "input_tokens": 10071, + "output_tokens": 1606, + "latency_ms": 72872, + "timestamp": "2026-04-15T14:30:07.069009+00:00", + "error": null, + "retry_count": 1 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_016.json.license b/param_extraction/results/claude-sonnet-4/chunk_016.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_016.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_017.json b/param_extraction/results/claude-sonnet-4/chunk_017.json new file mode 100644 index 0000000000..045055c5bf --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_017.json @@ -0,0 +1,84 @@ +{ + "chunk_id": "chunk_017", + "source_file": "intro.adoc", + "start_line": 1, + "end_line": 696, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "We use the term XLEN to refer to the width of an integer register in bits (either 32 or 64).", + "line_number": 217, + "parameter_name": "XLEN", + "existing_udb_name": "MXLEN", + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "high", + "reasoning": "XLEN is a fundamental architectural parameter that determines the width of integer registers and address space. The implementation chooses either 32 or 64 bits." + }, + { + "excerpt": "We use the term IALIGN (measured in bits) to refer to the instruction-address alignment constraint the implementation enforces. IALIGN is 32 bits in the base ISA, but some ISA extensions, including the compressed ISA extension, relax IALIGN to 16 bits. IALIGN may not take on any value other than 16 or 32.", + "line_number": 481, + "parameter_name": "IALIGN", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "high", + "reasoning": "IALIGN is an implementation choice for instruction alignment constraints. The spec explicitly states it may only be 16 or 32 bits, making this a direct architectural parameter." + }, + { + "excerpt": "We use the term ILEN (measured in bits) to refer to the maximum instruction length supported by an implementation, and which is always a multiple of IALIGN.", + "line_number": 487, + "parameter_name": "ILEN", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "ILEN is the maximum instruction length supported by an implementation. While constrained to be a multiple of IALIGN, the specific value is chosen by the implementer." + }, + { + "excerpt": "RISC-V base ISAs have either little-endian or big-endian memory systems, with the privileged architecture further defining bi-endian operation.", + "line_number": 548, + "parameter_name": "MEMORY_ENDIANNESS", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "high", + "reasoning": "The memory system endianness is an implementation choice between little-endian, big-endian, or bi-endian operation. This is a direct architectural parameter." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "Commentary on our design decisions is formatted as in this paragraph. This non-normative text can be skipped if the reader is only interested in the specification itself.", + "line_number": 35, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. Parameters should not be extracted from NOTE blocks." + }, + { + "excerpt": "The RISC-V ISA is defined avoiding implementation details as much as possible", + "line_number": 49, + "reason": "This describes the design philosophy of the specification itself, not an implementation choice or parameter." + }, + { + "excerpt": "A word of memory is defined as 32 bits (4 bytes). Correspondingly, a halfword is 16 bits (2 bytes), a doubleword is 64 bits (8 bytes), and a quadword is 128 bits (16 bytes).", + "line_number": 374, + "reason": "These are fixed definitions that apply to all implementations, not implementation choices. All RISC-V implementations must use these same definitions." + }, + { + "excerpt": "All the 32-bit instructions in the base ISA have their lowest two bits set to `11`.", + "line_number": 494, + "reason": "This is a fixed requirement that all implementations must follow, not an implementation choice." + }, + { + "excerpt": "The term UNSPECIFIED refers to a behavior or value that is intentionally unconstrained.", + "line_number": 686, + "reason": "This defines terminology used in the specification rather than describing an implementation parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"We use the term XLEN to refer to the width of an integer register in bits (either 32 or 64).\",\n \"line_number\": 217,\n \"parameter_name\": \"XLEN\",\n \"existing_udb_name\": \"MXLEN\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"XLEN is a fundamental architectural parameter that determines the width of integer registers and address space. The implementation chooses either 32 or 64 bits.\"\n },\n {\n \"excerpt\": \"We use the term IALIGN (measured in bits) to refer to the instruction-address alignment constraint the implementation enforces. IALIGN is 32 bits in the base ISA, but some ISA extensions, including the compressed ISA extension, relax IALIGN to 16 bits. IALIGN may not take on any value other than 16 or 32.\",\n \"line_number\": 481,\n \"parameter_name\": \"IALIGN\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"IALIGN is an implementation choice for instruction alignment constraints. The spec explicitly states it may only be 16 or 32 bits, making this a direct architectural parameter.\"\n },\n {\n \"excerpt\": \"We use the term ILEN (measured in bits) to refer to the maximum instruction length supported by an implementation, and which is always a multiple of IALIGN.\",\n \"line_number\": 487,\n \"parameter_name\": \"ILEN\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"ILEN is the maximum instruction length supported by an implementation. While constrained to be a multiple of IALIGN, the specific value is chosen by the implementer.\"\n },\n {\n \"excerpt\": \"RISC-V base ISAs have either little-endian or big-endian memory systems, with the privileged architecture further defining bi-endian operation.\",\n \"line_number\": 548,\n \"parameter_name\": \"MEMORY_ENDIANNESS\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"The memory system endianness is an implementation choice between little-endian, big-endian, or bi-endian operation. This is a direct architectural parameter.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"Commentary on our design decisions is formatted as in this paragraph. This non-normative text can be skipped if the reader is only interested in the specification itself.\",\n \"line_number\": 35,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. Parameters should not be extracted from NOTE blocks.\"\n },\n {\n \"excerpt\": \"The RISC-V ISA is defined avoiding implementation details as much as possible\",\n \"line_number\": 49,\n \"reason\": \"This describes the design philosophy of the specification itself, not an implementation choice or parameter.\"\n },\n {\n \"excerpt\": \"A word of memory is defined as 32 bits (4 bytes). Correspondingly, a halfword is 16 bits (2 bytes), a doubleword is 64 bits (8 bytes), and a quadword is 128 bits (16 bytes).\",\n \"line_number\": 374,\n \"reason\": \"These are fixed definitions that apply to all implementations, not implementation choices. All RISC-V implementations must use these same definitions.\"\n },\n {\n \"excerpt\": \"All the 32-bit instructions in the base ISA have their lowest two bits set to `11`.\",\n \"line_number\": 494,\n \"reason\": \"This is a fixed requirement that all implementations must follow, not an implementation choice.\"\n },\n {\n \"excerpt\": \"The term UNSPECIFIED refers to a behavior or value that is intentionally unconstrained.\",\n \"line_number\": 686,\n \"reason\": \"This defines terminology used in the specification rather than describing an implementation parameter.\"\n }\n ]\n}\n```", + "input_tokens": 14175, + "output_tokens": 1093, + "latency_ms": 46897, + "timestamp": "2026-04-15T14:32:01.646723+00:00", + "error": null, + "retry_count": 1 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_017.json.license b/param_extraction/results/claude-sonnet-4/chunk_017.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_017.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_018.json b/param_extraction/results/claude-sonnet-4/chunk_018.json new file mode 100644 index 0000000000..f7ed586af2 --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_018.json @@ -0,0 +1,43 @@ +{ + "chunk_id": "chunk_018", + "source_file": "m-st-ext.adoc", + "start_line": 1, + "end_line": 157, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [], + "skipped_non_parameters": [ + { + "excerpt": "We separate integer multiply and divide out from the base to simplify low-end implementations, or for applications where integer multiply and divide operations are either infrequent or better handled in attached accelerators.", + "line_number": 9, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. It explains design rationale but does not define any implementation choices." + }, + { + "excerpt": "MUL performs an XLEN-bit\u00d7XLEN-bit multiplication of `rs1` by `rs2` and places the lower XLEN bits in the destination register.", + "line_number": 23, + "reason": "This describes the fixed behavior of the MUL instruction that all implementations must follow. There is no implementation choice here." + }, + { + "excerpt": "The quotient of division by zero has all bits set, and the remainder of division by zero equals the dividend.", + "line_number": 85, + "reason": "This specifies the required behavior for division by zero that all implementations must follow. It is a fixed requirement, not a parameter." + }, + { + "excerpt": "Signed division overflow occurs only when the most-negative integer is divided by \u22121. The quotient of a signed division with overflow is equal to the dividend, and the remainder is zero.", + "line_number": 86, + "reason": "This defines the mandatory behavior for signed division overflow. All implementations must behave this way - there is no choice involved." + }, + { + "excerpt": "The `Zmmul` extension enables low-cost implementations that require multiplication operations but not division.", + "line_number": 135, + "reason": "This text is inside a [NOTE] block and is non-normative. It explains the motivation for the Zmmul extension but does not define any implementation parameters." + } + ], + "raw_response": "```json\n{\n \"parameters\": [],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"We separate integer multiply and divide out from the base to simplify low-end implementations, or for applications where integer multiply and divide operations are either infrequent or better handled in attached accelerators.\",\n \"line_number\": 9,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. It explains design rationale but does not define any implementation choices.\"\n },\n {\n \"excerpt\": \"MUL performs an XLEN-bit\u00d7XLEN-bit multiplication of `rs1` by `rs2` and places the lower XLEN bits in the destination register.\",\n \"line_number\": 23,\n \"reason\": \"This describes the fixed behavior of the MUL instruction that all implementations must follow. There is no implementation choice here.\"\n },\n {\n \"excerpt\": \"The quotient of division by zero has all bits set, and the remainder of division by zero equals the dividend.\",\n \"line_number\": 85,\n \"reason\": \"This specifies the required behavior for division by zero that all implementations must follow. It is a fixed requirement, not a parameter.\"\n },\n {\n \"excerpt\": \"Signed division overflow occurs only when the most-negative integer is divided by \u22121. The quotient of a signed division with overflow is equal to the dividend, and the remainder is zero.\",\n \"line_number\": 86,\n \"reason\": \"This defines the mandatory behavior for signed division overflow. All implementations must behave this way - there is no choice involved.\"\n },\n {\n \"excerpt\": \"The `Zmmul` extension enables low-cost implementations that require multiplication operations but not division.\",\n \"line_number\": 135,\n \"reason\": \"This text is inside a [NOTE] block and is non-normative. It explains the motivation for the Zmmul extension but does not define any implementation parameters.\"\n }\n ]\n}\n```", + "input_tokens": 7576, + "output_tokens": 474, + "latency_ms": 62507, + "timestamp": "2026-04-15T14:32:50.005533+00:00", + "error": null, + "retry_count": 1 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_018.json.license b/param_extraction/results/claude-sonnet-4/chunk_018.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_018.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_019.json b/param_extraction/results/claude-sonnet-4/chunk_019.json new file mode 100644 index 0000000000..b47b1b4265 --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_019.json @@ -0,0 +1,224 @@ +{ + "chunk_id": "chunk_019", + "source_file": "machine.adoc", + "start_line": 1, + "end_line": 3334, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "a value of zero can be returned to indicate the `misa` register has not been implemented", + "line_number": 23, + "parameter_name": "MISA_CSR_IMPLEMENTED", + "existing_udb_name": "MISA_CSR_IMPLEMENTED", + "class": "NORM_CSR_RW", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether the misa register is implemented (returns actual values) or not implemented (returns zero). This is a binary choice about the register's functionality." + }, + { + "excerpt": "The Extensions field is a *WARL* field that can contain writable bits where the implementation allows the supported ISA to be modified.", + "line_number": 60, + "parameter_name": "MUTABLE_MISA_EXTENSIONS", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "bitmask", + "confidence": "high", + "reasoning": "The Extensions field in misa is WARL, and implementations choose which extension bits are writable vs read-only. This defines the set of legal values for the Extensions field." + }, + { + "excerpt": "The `marchid` CSR is an MXLEN-bit read-only register encoding the base microarchitecture of the hart.", + "line_number": 217, + "parameter_name": "MARCHID_IMPLEMENTED", + "existing_udb_name": "MARCHID_IMPLEMENTED", + "class": "NORM_CSR_RW", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether marchid returns an actual architecture ID or zero to indicate it's not implemented. This is a binary choice about the register's functionality." + }, + { + "excerpt": "The `mimpid` CSR provides a unique encoding of the version of the processor implementation.", + "line_number": 248, + "parameter_name": "MIMPID_IMPLEMENTED", + "existing_udb_name": "MIMPID_IMPLEMENTED", + "class": "NORM_CSR_RW", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether mimpid returns an actual implementation ID or zero to indicate it's not implemented. This is a binary choice about the register's functionality." + }, + { + "excerpt": "The M-mode-disable-trap (`MDT`) bit is a WARL field introduced by the Smdbltrp extension.", + "line_number": 398, + "parameter_name": "SMDBLTRP_IMPLEMENTED", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "The implementation chooses whether to implement the Smdbltrp extension, which introduces the MDT bit. This is a direct implementation choice about extension support." + }, + { + "excerpt": "For RV64 harts, the SXL and UXL fields are *WARL* fields that control the value of XLEN for S-mode and U-mode, respectively.", + "line_number": 481, + "parameter_name": "SXLEN_UXLEN_CONTROL", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "enum", + "confidence": "high", + "reasoning": "The SXL and UXL fields are WARL, and implementations choose which XLEN values are supported for S-mode and U-mode. This defines the set of legal values for these fields." + }, + { + "excerpt": "The MBE, SBE, and UBE bits in `mstatus` and `mstatush` are *WARL* fields that control the endianness of memory accesses other than instruction fetches.", + "line_number": 679, + "parameter_name": "M_MODE_ENDIANNESS", + "existing_udb_name": "M_MODE_ENDIANNESS", + "class": "NORM_CSR_WARL", + "value_type": "enum", + "confidence": "high", + "reasoning": "The MBE field is WARL, and implementations choose which endianness values are supported (little-endian only, big-endian only, or both). This defines the set of legal values for the endianness control." + }, + { + "excerpt": "an implementation may make SBE be a read-only copy of MBE", + "line_number": 734, + "parameter_name": "S_MODE_ENDIANNESS", + "existing_udb_name": "S_MODE_ENDIANNESS", + "class": "NORM_CSR_RW", + "value_type": "enum", + "confidence": "high", + "reasoning": "The implementation chooses whether SBE is independently writable or a read-only copy of MBE. This controls the mutability and independence of the S-mode endianness control." + }, + { + "excerpt": "an implementation may make UBE be a read-only copy of either MBE or SBE", + "line_number": 735, + "parameter_name": "U_MODE_ENDIANNESS", + "existing_udb_name": "U_MODE_ENDIANNESS", + "class": "NORM_CSR_RW", + "value_type": "enum", + "confidence": "high", + "reasoning": "The implementation chooses whether UBE is independently writable or a read-only copy of MBE or SBE. This controls the mutability and independence of the U-mode endianness control." + }, + { + "excerpt": "The TVM (Trap Virtual Memory) bit is a *WARL* field that supports intercepting supervisor virtual-memory management operations.", + "line_number": 747, + "parameter_name": "MSTATUS_TVM_IMPLEMENTED", + "existing_udb_name": "MSTATUS_TVM_IMPLEMENTED", + "class": "NORM_CSR_WARL", + "value_type": "binary", + "confidence": "high", + "reasoning": "The TVM bit is WARL, and implementations choose whether to support trapping virtual memory operations. This defines whether TVM functionality is available." + }, + { + "excerpt": "The TW (Timeout Wait) bit is a *WARL* field that supports intercepting the WFI instruction", + "line_number": 760, + "parameter_name": "MSTATUS_TW_IMPLEMENTED", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "binary", + "confidence": "high", + "reasoning": "The TW bit is WARL, and implementations choose whether to support trapping WFI instructions. This defines whether TW functionality is available." + }, + { + "excerpt": "The TSR (Trap SRET) bit is a *WARL* field that supports intercepting the supervisor exception return instruction, SRET.", + "line_number": 779, + "parameter_name": "MSTATUS_TSR_IMPLEMENTED", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "binary", + "confidence": "high", + "reasoning": "The TSR bit is WARL, and implementations choose whether to support trapping SRET instructions. This defines whether TSR functionality is available." + }, + { + "excerpt": "The FS[1:0] and VS[1:0] *WARL* fields", + "line_number": 793, + "parameter_name": "MSTATUS_FS_LEGAL_VALUES", + "existing_udb_name": "MSTATUS_FS_LEGAL_VALUES", + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "The FS field is WARL, and implementations choose which status values are supported (Off, Initial, Clean, Dirty). This defines the set of legal values for floating-point state tracking." + }, + { + "excerpt": "The FS[1:0] and VS[1:0] *WARL* fields", + "line_number": 793, + "parameter_name": "MSTATUS_VS_LEGAL_VALUES", + "existing_udb_name": "MSTATUS_VS_LEGAL_VALUES", + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "The VS field is WARL, and implementations choose which status values are supported (Off, Initial, Clean, Dirty). This defines the set of legal values for vector state tracking." + }, + { + "excerpt": "it is implementation-defined whether FS transitions to Dirty", + "line_number": 1012, + "parameter_name": "HW_MSTATUS_FS_DIRTY_UPDATE", + "existing_udb_name": "HW_MSTATUS_FS_DIRTY_UPDATE", + "class": "SW_RULE", + "value_type": "enum", + "confidence": "high", + "reasoning": "Whether hardware updates mstatus.FS to Dirty is implementation-defined, but software can handle this deterministically by checking and managing FS state with proper fencing. The outcome is predictable if software follows the rules." + }, + { + "excerpt": "it is implementation-defined whether an instruction that writes a vector register or vector CSR but does not alter its contents causes VS to transition to Dirty", + "line_number": 1020, + "parameter_name": "HW_MSTATUS_VS_DIRTY_UPDATE", + "existing_udb_name": "HW_MSTATUS_VS_DIRTY_UPDATE", + "class": "SW_RULE", + "value_type": "enum", + "confidence": "high", + "reasoning": "Whether hardware updates mstatus.VS to Dirty is implementation-defined, but software can handle this deterministically by checking and managing VS state with proper fencing. The outcome is predictable if software follows the rules." + }, + { + "excerpt": "The `mtvec` register must always be implemented, but can contain a read-only value.", + "line_number": 1217, + "parameter_name": "MTVEC_ACCESS", + "existing_udb_name": "MTVEC_ACCESS", + "class": "NORM_CSR_RW", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether mtvec is read-only or read-write. This is a binary choice about the mutability of the register." + }, + { + "excerpt": "If `mtvec` is writable, the set of values the register may hold can vary by implementation.", + "line_number": 1219, + "parameter_name": "MTVEC_MODES", + "existing_udb_name": "MTVEC_MODES", + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "The mtvec MODE field is WARL, and the set of supported mode values (Direct=0, Vectored=1) varies by implementation. The parameter is the set of legal MODE values." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "This register must be readable in any implementation", + "line_number": 22, + "reason": "This is a fixed requirement ('must be readable') that all implementations must satisfy. There is no implementation choice here." + }, + { + "excerpt": "When MODE=Direct, all traps into machine mode cause the `pc` to be set to the address in the BASE field.", + "line_number": 1254, + "reason": "This describes what happens when mtvec.MODE has a specific value. The behavior is determined by the CSR field value at runtime, not by an implementation choice." + }, + { + "excerpt": "Software may determine the PMP granularity by writing zero to `pmp0cfg`, then writing all ones to `pmpaddr0`, then reading back `pmpaddr0`.", + "line_number": 3530, + "reason": "Here 'may' means 'is allowed to' (permission), not 'might or might not' (optionality). This describes a software technique, not an implementation-defined parameter." + }, + { + "excerpt": "The `misa` CSR is MXLEN bits wide.", + "line_number": 42, + "reason": "This is a fixed architectural requirement that the misa register width equals MXLEN. There is no implementation choice." + }, + { + "excerpt": "The MXL field is read-only.", + "line_number": 30, + "reason": "This is a fixed requirement that the MXL field is always read-only. There is no implementation choice about its mutability." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"a value of zero can be returned to indicate the `misa` register has not been implemented\",\n \"line_number\": 23,\n \"parameter_name\": \"MISA_CSR_IMPLEMENTED\",\n \"existing_udb_name\": \"MISA_CSR_IMPLEMENTED\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether the misa register is implemented (returns actual values) or not implemented (returns zero). This is a binary choice about the register's functionality.\"\n },\n {\n \"excerpt\": \"The Extensions field is a *WARL* field that can contain writable bits where the implementation allows the supported ISA to be modified.\",\n \"line_number\": 60,\n \"parameter_name\": \"MUTABLE_MISA_EXTENSIONS\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"bitmask\",\n \"confidence\": \"high\",\n \"reasoning\": \"The Extensions field in misa is WARL, and implementations choose which extension bits are writable vs read-only. This defines the set of legal values for the Extensions field.\"\n },\n {\n \"excerpt\": \"The `marchid` CSR is an MXLEN-bit read-only register encoding the base microarchitecture of the hart.\",\n \"line_number\": 217,\n \"parameter_name\": \"MARCHID_IMPLEMENTED\",\n \"existing_udb_name\": \"MARCHID_IMPLEMENTED\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether marchid returns an actual architecture ID or zero to indicate it's not implemented. This is a binary choice about the register's functionality.\"\n },\n {\n \"excerpt\": \"The `mimpid` CSR provides a unique encoding of the version of the processor implementation.\",\n \"line_number\": 248,\n \"parameter_name\": \"MIMPID_IMPLEMENTED\",\n \"existing_udb_name\": \"MIMPID_IMPLEMENTED\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether mimpid returns an actual implementation ID or zero to indicate it's not implemented. This is a binary choice about the register's functionality.\"\n },\n {\n \"excerpt\": \"The M-mode-disable-trap (`MDT`) bit is a WARL field introduced by the Smdbltrp extension.\",\n \"line_number\": 398,\n \"parameter_name\": \"SMDBLTRP_IMPLEMENTED\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The implementation chooses whether to implement the Smdbltrp extension, which introduces the MDT bit. This is a direct implementation choice about extension support.\"\n },\n {\n \"excerpt\": \"For RV64 harts, the SXL and UXL fields are *WARL* fields that control the value of XLEN for S-mode and U-mode, respectively.\",\n \"line_number\": 481,\n \"parameter_name\": \"SXLEN_UXLEN_CONTROL\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"The SXL and UXL fields are WARL, and implementations choose which XLEN values are supported for S-mode and U-mode. This defines the set of legal values for these fields.\"\n },\n {\n \"excerpt\": \"The MBE, SBE, and UBE bits in `mstatus` and `mstatush` are *WARL* fields that control the endianness of memory accesses other than instruction fetches.\",\n \"line_number\": 679,\n \"parameter_name\": \"M_MODE_ENDIANNESS\",\n \"existing_udb_name\": \"M_MODE_ENDIANNESS\",\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"The MBE field is WARL, and implementations choose which endianness values are supported (little-endian only, big-endian only, or both). This defines the set of legal values for the endianness control.\"\n },\n {\n \"excerpt\": \"an implementation may make SBE be a read-only copy of MBE\",\n \"line_number\": 734,\n \"parameter_name\": \"S_MODE_ENDIANNESS\",\n \"existing_udb_name\": \"S_MODE_ENDIANNESS\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether SBE is independently writable or a read-only copy of MBE. This controls the mutability and independence of the S-mode endianness control.\"\n },\n {\n \"excerpt\": \"an implementation may make UBE be a read-only copy of either MBE or SBE\",\n \"line_number\": 735,\n \"parameter_name\": \"U_MODE_ENDIANNESS\",\n \"existing_udb_name\": \"U_MODE_ENDIANNESS\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether UBE is independently writable or a read-only copy of MBE or SBE. This controls the mutability and independence of the U-mode endianness control.\"\n },\n {\n \"excerpt\": \"The TVM (Trap Virtual Memory) bit is a *WARL* field that supports intercepting supervisor virtual-memory management operations.\",\n \"line_number\": 747,\n \"parameter_name\": \"MSTATUS_TVM_IMPLEMENTED\",\n \"existing_udb_name\": \"MSTATUS_TVM_IMPLEMENTED\",\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The TVM bit is WARL, and implementations choose whether to support trapping virtual memory operations. This defines whether TVM functionality is available.\"\n },\n {\n \"excerpt\": \"The TW (Timeout Wait) bit is a *WARL* field that supports intercepting the WFI instruction\",\n \"line_number\": 760,\n \"parameter_name\": \"MSTATUS_TW_IMPLEMENTED\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The TW bit is WARL, and implementations choose whether to support trapping WFI instructions. This defines whether TW functionality is available.\"\n },\n {\n \"excerpt\": \"The TSR (Trap SRET) bit is a *WARL* field that supports intercepting the supervisor exception return instruction, SRET.\",\n \"line_number\": 779,\n \"parameter_name\": \"MSTATUS_TSR_IMPLEMENTED\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The TSR bit is WARL, and implementations choose whether to support trapping SRET instructions. This defines whether TSR functionality is available.\"\n },\n {\n \"excerpt\": \"The FS[1:0] and VS[1:0] *WARL* fields\",\n \"line_number\": 793,\n \"parameter_name\": \"MSTATUS_FS_LEGAL_VALUES\",\n \"existing_udb_name\": \"MSTATUS_FS_LEGAL_VALUES\",\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"The FS field is WARL, and implementations choose which status values are supported (Off, Initial, Clean, Dirty). This defines the set of legal values for floating-point state tracking.\"\n },\n {\n \"excerpt\": \"The FS[1:0] and VS[1:0] *WARL* fields\",\n \"line_number\": 793,\n \"parameter_name\": \"MSTATUS_VS_LEGAL_VALUES\",\n \"existing_udb_name\": \"MSTATUS_VS_LEGAL_VALUES\",\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"The VS field is WARL, and implementations choose which status values are supported (Off, Initial, Clean, Dirty). This defines the set of legal values for vector state tracking.\"\n },\n {\n \"excerpt\": \"it is implementation-defined whether FS transitions to Dirty\",\n \"line_number\": 1012,\n \"parameter_name\": \"HW_MSTATUS_FS_DIRTY_UPDATE\",\n \"existing_udb_name\": \"HW_MSTATUS_FS_DIRTY_UPDATE\",\n \"class\": \"SW_RULE\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"Whether hardware updates mstatus.FS to Dirty is implementation-defined, but software can handle this deterministically by checking and managing FS state with proper fencing. The outcome is predictable if software follows the rules.\"\n },\n {\n \"excerpt\": \"it is implementation-defined whether an instruction that writes a vector register or vector CSR but does not alter its contents causes VS to transition to Dirty\",\n \"line_number\": 1020,\n \"parameter_name\": \"HW_MSTATUS_VS_DIRTY_UPDATE\",\n \"existing_udb_name\": \"HW_MSTATUS_VS_DIRTY_UPDATE\",\n \"class\": \"SW_RULE\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"Whether hardware updates mstatus.VS to Dirty is implementation-defined, but software can handle this deterministically by checking and managing VS state with proper fencing. The outcome is predictable if software follows the rules.\"\n },\n {\n \"excerpt\": \"The `mtvec` register must always be implemented, but can contain a read-only value.\",\n \"line_number\": 1217,\n \"parameter_name\": \"MTVEC_ACCESS\",\n \"existing_udb_name\": \"MTVEC_ACCESS\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether mtvec is read-only or read-write. This is a binary choice about the mutability of the register.\"\n },\n {\n \"excerpt\": \"If `mtvec` is writable, the set of values the register may hold can vary by implementation.\",\n \"line_number\": 1219,\n \"parameter_name\": \"MTVEC_MODES\",\n \"existing_udb_name\": \"MTVEC_MODES\",\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"The mtvec MODE field is WARL, and the set of supported mode values (Direct=0, Vectored=1) varies by implementation. The parameter is the set of legal MODE values.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"This register must be readable in any implementation\",\n \"line_number\": 22,\n \"reason\": \"This is a fixed requirement ('must be readable') that all implementations must satisfy. There is no implementation choice here.\"\n },\n {\n \"excerpt\": \"When MODE=Direct, all traps into machine mode cause the `pc` to be set to the address in the BASE field.\",\n \"line_number\": 1254,\n \"reason\": \"This describes what happens when mtvec.MODE has a specific value. The behavior is determined by the CSR field value at runtime, not by an implementation choice.\"\n },\n {\n \"excerpt\": \"Software may determine the PMP granularity by writing zero to `pmp0cfg`, then writing all ones to `pmpaddr0`, then reading back `pmpaddr0`.\",\n \"line_number\": 3530,\n \"reason\": \"Here 'may' means 'is allowed to' (permission), not 'might or might not' (optionality). This describes a software technique, not an implementation-defined parameter.\"\n },\n {\n \"excerpt\": \"The `misa` CSR is MXLEN bits wide.\",\n \"line_number\": 42,\n \"reason\": \"This is a fixed architectural requirement that the misa register width equals MXLEN. There is no implementation choice.\"\n },\n {\n \"excerpt\": \"The MXL field is read-only.\",\n \"line_number\": 30,\n \"reason\": \"This is a fixed requirement that the MXL field is always read-only. There is no implementation choice about its mutability.\"\n }\n ]\n}\n```", + "input_tokens": 48136, + "output_tokens": 3365, + "latency_ms": 49161, + "timestamp": "2026-04-15T14:18:19.533071+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_019.json.license b/param_extraction/results/claude-sonnet-4/chunk_019.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_019.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_020.json b/param_extraction/results/claude-sonnet-4/chunk_020.json new file mode 100644 index 0000000000..87bbd8403a --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_020.json @@ -0,0 +1,104 @@ +{ + "chunk_id": "chunk_020", + "source_file": "machine.adoc", + "start_line": 3305, + "end_line": 3629, + "content_start_line": 3335, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "Implementations may implement zero, 16, or 64 PMP entries; the lowest-numbered PMP entries must be implemented first.", + "line_number": 3340, + "parameter_name": "NUM_PMP_ENTRIES", + "existing_udb_name": "NUM_PMP_ENTRIES", + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "high", + "reasoning": "The number of PMP entries is a direct implementation choice with exactly three allowed values: 0, 16, or 64. This is not controlled by any CSR field." + }, + { + "excerpt": "All PMP CSR fields are WARL and may be read-only zero.", + "line_number": 3341, + "parameter_name": "PMP_CSR_WARL_VALUES", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "PMP CSR fields are WARL, meaning implementations can restrict which values are legal. The phrase 'may be read-only zero' indicates the set of legal values is implementation-defined." + }, + { + "excerpt": "The granularity of PMP access control settings are platform-specific, but the standard PMP encoding supports regions as small as four bytes.", + "line_number": 3308, + "parameter_name": "PMP_GRANULARITY", + "existing_udb_name": "PMP_GRANULARITY", + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "PMP granularity is explicitly stated as platform-specific, meaning it's an implementation choice. The granularity determines the minimum region size that can be protected." + }, + { + "excerpt": "Optionally, PMP checks may additionally apply to M-mode accesses, in which case the PMP registers themselves are locked, so that even M-mode software cannot change them until the hart is reset.", + "line_number": 3325, + "parameter_name": "PMP_CHECKS_ON_M_MODE", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "The word 'Optionally' indicates this is an implementation choice - whether PMP checks apply to M-mode accesses or not. This is a binary decision." + }, + { + "excerpt": "Not all physical address bits may be implemented, and so the `pmpaddr` registers are WARL.", + "line_number": 3370, + "parameter_name": "PMPADDR_WARL_VALUES", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "The pmpaddr registers are WARL because not all physical address bits may be implemented. This means the set of legal address values is implementation-defined." + }, + { + "excerpt": "The R, W, and X fields form a collective WARL field for which the combinations with R=0 and W=1 are reserved.", + "line_number": 3383, + "parameter_name": "PMP_RWX_WARL_VALUES", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "The R/W/X fields form a collective WARL field, meaning implementations can restrict which combinations are legal beyond just the reserved R=0,W=1 combination." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "Platforms vary widely in demands for physical memory protection, and some platforms may provide other PMP structures in addition to or instead of the scheme described in this section.", + "line_number": 3314, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks." + }, + { + "excerpt": "When MODE=Direct, all traps into machine mode cause the `pc` to be set to the address in the BASE field.", + "line_number": 3254, + "reason": "This describes behavior when a CSR field has a specific value, not an implementation choice. The parameter would be which MODE values are supported, not this behavioral description." + }, + { + "excerpt": "PMP violations are always trapped precisely at the processor.", + "line_number": 3330, + "reason": "This is a fixed requirement ('always trapped precisely') that all implementations must satisfy. There is no implementation choice here." + }, + { + "excerpt": "Software may determine the PMP granularity by writing zero to `pmp0cfg`, then writing all ones to `pmpaddr0`, then reading back `pmpaddr0`.", + "line_number": 3470, + "reason": "Here 'may' means 'is allowed to' (permission), not 'might or might not' (optionality). This describes a software technique for discovery, not an implementation-defined parameter." + }, + { + "excerpt": "When A=0, this PMP entry is disabled and matches no addresses.", + "line_number": 3400, + "reason": "This describes what happens when the A field has a specific value (0). This is behavioral description based on CSR field values, not an implementation choice." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"Implementations may implement zero, 16, or 64 PMP entries; the lowest-numbered PMP entries must be implemented first.\",\n \"line_number\": 3340,\n \"parameter_name\": \"NUM_PMP_ENTRIES\",\n \"existing_udb_name\": \"NUM_PMP_ENTRIES\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"The number of PMP entries is a direct implementation choice with exactly three allowed values: 0, 16, or 64. This is not controlled by any CSR field.\"\n },\n {\n \"excerpt\": \"All PMP CSR fields are WARL and may be read-only zero.\",\n \"line_number\": 3341,\n \"parameter_name\": \"PMP_CSR_WARL_VALUES\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"PMP CSR fields are WARL, meaning implementations can restrict which values are legal. The phrase 'may be read-only zero' indicates the set of legal values is implementation-defined.\"\n },\n {\n \"excerpt\": \"The granularity of PMP access control settings are platform-specific, but the standard PMP encoding supports regions as small as four bytes.\",\n \"line_number\": 3308,\n \"parameter_name\": \"PMP_GRANULARITY\",\n \"existing_udb_name\": \"PMP_GRANULARITY\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"PMP granularity is explicitly stated as platform-specific, meaning it's an implementation choice. The granularity determines the minimum region size that can be protected.\"\n },\n {\n \"excerpt\": \"Optionally, PMP checks may additionally apply to M-mode accesses, in which case the PMP registers themselves are locked, so that even M-mode software cannot change them until the hart is reset.\",\n \"line_number\": 3325,\n \"parameter_name\": \"PMP_CHECKS_ON_M_MODE\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The word 'Optionally' indicates this is an implementation choice - whether PMP checks apply to M-mode accesses or not. This is a binary decision.\"\n },\n {\n \"excerpt\": \"Not all physical address bits may be implemented, and so the `pmpaddr` registers are WARL.\",\n \"line_number\": 3370,\n \"parameter_name\": \"PMPADDR_WARL_VALUES\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"The pmpaddr registers are WARL because not all physical address bits may be implemented. This means the set of legal address values is implementation-defined.\"\n },\n {\n \"excerpt\": \"The R, W, and X fields form a collective WARL field for which the combinations with R=0 and W=1 are reserved.\",\n \"line_number\": 3383,\n \"parameter_name\": \"PMP_RWX_WARL_VALUES\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"The R/W/X fields form a collective WARL field, meaning implementations can restrict which combinations are legal beyond just the reserved R=0,W=1 combination.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"Platforms vary widely in demands for physical memory protection, and some platforms may provide other PMP structures in addition to or instead of the scheme described in this section.\",\n \"line_number\": 3314,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks.\"\n },\n {\n \"excerpt\": \"When MODE=Direct, all traps into machine mode cause the `pc` to be set to the address in the BASE field.\",\n \"line_number\": 3254,\n \"reason\": \"This describes behavior when a CSR field has a specific value, not an implementation choice. The parameter would be which MODE values are supported, not this behavioral description.\"\n },\n {\n \"excerpt\": \"PMP violations are always trapped precisely at the processor.\",\n \"line_number\": 3330,\n \"reason\": \"This is a fixed requirement ('always trapped precisely') that all implementations must satisfy. There is no implementation choice here.\"\n },\n {\n \"excerpt\": \"Software may determine the PMP granularity by writing zero to `pmp0cfg`, then writing all ones to `pmpaddr0`, then reading back `pmpaddr0`.\",\n \"line_number\": 3470,\n \"reason\": \"Here 'may' means 'is allowed to' (permission), not 'might or might not' (optionality). This describes a software technique for discovery, not an implementation-defined parameter.\"\n },\n {\n \"excerpt\": \"When A=0, this PMP entry is disabled and matches no addresses.\",\n \"line_number\": 3400,\n \"reason\": \"This describes what happens when the A field has a specific value (0). This is behavioral description based on CSR field values, not an implementation choice.\"\n }\n ]\n}\n```", + "input_tokens": 9523, + "output_tokens": 1416, + "latency_ms": 22837, + "timestamp": "2026-04-15T14:18:44.406115+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_020.json.license b/param_extraction/results/claude-sonnet-4/chunk_020.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_020.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_025.json b/param_extraction/results/claude-sonnet-4/chunk_025.json new file mode 100644 index 0000000000..0cde6b6ae9 --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_025.json @@ -0,0 +1,43 @@ +{ + "chunk_id": "chunk_025", + "source_file": "naming.adoc", + "start_line": 1, + "end_line": 222, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [], + "skipped_non_parameters": [ + { + "excerpt": "The RISC-V ISA is designed to support a wide variety of implementations with various experimental instruction-set extensions. We have found that an organized naming scheme simplifies software tools and documentation.", + "line_number": 9, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. It provides background information but does not define any architectural parameters." + }, + { + "excerpt": "The ISA naming strings are case insensitive.", + "line_number": 16, + "reason": "This is a fixed requirement that applies to all implementations - there is no implementation choice about case sensitivity." + }, + { + "excerpt": "RISC-V ISA strings begin with either RV32I, RV32E, RV64I, or RV64E, indicating the supported address space size in bits for the base integer ISA.", + "line_number": 20, + "reason": "This describes the naming convention format, not an implementation parameter. The choice of which base ISA to implement is covered by other parameters like MXLEN." + }, + { + "excerpt": "Standard ISA extensions are given a name consisting of a single letter.", + "line_number": 25, + "reason": "This is a documentation rule about how extensions are named, not an architectural implementation choice." + }, + { + "excerpt": "Many augmentations to the hypervisor-level architecture are more naturally defined as supervisor-level extensions, following the scheme described in the previous section.", + "line_number": 89, + "reason": "This text is inside a NOTE block and is therefore non-normative. It provides guidance but does not define any architectural parameters." + } + ], + "raw_response": "```json\n{\n \"parameters\": [],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"The RISC-V ISA is designed to support a wide variety of implementations with various experimental instruction-set extensions. We have found that an organized naming scheme simplifies software tools and documentation.\",\n \"line_number\": 9,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. It provides background information but does not define any architectural parameters.\"\n },\n {\n \"excerpt\": \"The ISA naming strings are case insensitive.\",\n \"line_number\": 16,\n \"reason\": \"This is a fixed requirement that applies to all implementations - there is no implementation choice about case sensitivity.\"\n },\n {\n \"excerpt\": \"RISC-V ISA strings begin with either RV32I, RV32E, RV64I, or RV64E, indicating the supported address space size in bits for the base integer ISA.\",\n \"line_number\": 20,\n \"reason\": \"This describes the naming convention format, not an implementation parameter. The choice of which base ISA to implement is covered by other parameters like MXLEN.\"\n },\n {\n \"excerpt\": \"Standard ISA extensions are given a name consisting of a single letter.\",\n \"line_number\": 25,\n \"reason\": \"This is a documentation rule about how extensions are named, not an architectural implementation choice.\"\n },\n {\n \"excerpt\": \"Many augmentations to the hypervisor-level architecture are more naturally defined as supervisor-level extensions, following the scheme described in the previous section.\",\n \"line_number\": 89,\n \"reason\": \"This text is inside a NOTE block and is therefore non-normative. It provides guidance but does not define any architectural parameters.\"\n }\n ]\n}\n```", + "input_tokens": 7850, + "output_tokens": 438, + "latency_ms": 8751, + "timestamp": "2026-04-15T14:32:26.654987+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_025.json.license b/param_extraction/results/claude-sonnet-4/chunk_025.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_025.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_026.json b/param_extraction/results/claude-sonnet-4/chunk_026.json new file mode 100644 index 0000000000..d820063679 --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_026.json @@ -0,0 +1,104 @@ +{ + "chunk_id": "chunk_026", + "source_file": "priv-cfi.adoc", + "start_line": 1, + "end_line": 373, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "it is implementation-defined whether FS transitions to Dirty.", + "line_number": 1014, + "parameter_name": "REPORT_CAUSE_IN_MTVAL_ON_LANDING_PAD_SOFTWARE_CHECK", + "existing_udb_name": "REPORT_CAUSE_IN_MTVAL_ON_LANDING_PAD_SOFTWARE_CHECK", + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "The specification mentions software-check exceptions with mtval set to 'landing pad fault (code=2)' but doesn't explicitly state this is implementation-defined. However, based on the UDB parameter name pattern, this appears to be about whether the cause is reported in mtval for landing pad software checks." + }, + { + "excerpt": "The software-check exception due to the instruction not being an `LPAD` instruction when `ELP` is `LP_EXPECTED` or a software-check exception caused by the `LPAD` instruction itself leads to a trap being delivered to the same or to a higher privilege mode.", + "line_number": 78, + "parameter_name": "REPORT_CAUSE_IN_STVAL_ON_LANDING_PAD_SOFTWARE_CHECK", + "existing_udb_name": "REPORT_CAUSE_IN_STVAL_ON_LANDING_PAD_SOFTWARE_CHECK", + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "Similar to mtval case, this relates to reporting cause information in stval for landing pad software check exceptions, though not explicitly stated as implementation-defined in this text." + }, + { + "excerpt": "The software-check exception due to the instruction not being an `LPAD` instruction when `ELP` is `LP_EXPECTED` or a software-check exception caused by the `LPAD` instruction itself leads to a trap being delivered to the same or to a higher privilege mode.", + "line_number": 78, + "parameter_name": "REPORT_CAUSE_IN_VSTVAL_ON_LANDING_PAD_SOFTWARE_CHECK", + "existing_udb_name": "REPORT_CAUSE_IN_VSTVAL_ON_LANDING_PAD_SOFTWARE_CHECK", + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "Similar pattern for vstval reporting of landing pad software check exception causes." + }, + { + "excerpt": "If a shadow stack (SS) instruction raises an access-fault, page-fault, or guest-page-fault exception that is supposed to indicate the original instruction type (load or store/AMO), then the reported exception cause is respectively a store/AMO access fault (code 7), a store/AMO page fault (code 15), or a store/AMO guest-page fault (code 23).", + "line_number": 280, + "parameter_name": "REPORT_CAUSE_IN_MTVAL_ON_SHADOW_STACK_SOFTWARE_CHECK", + "existing_udb_name": "REPORT_CAUSE_IN_MTVAL_ON_SHADOW_STACK_SOFTWARE_CHECK", + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "This describes how shadow stack instruction exceptions are reported, which relates to cause reporting in mtval for shadow stack software checks." + }, + { + "excerpt": "If a shadow stack (SS) instruction raises an access-fault, page-fault, or guest-page-fault exception that is supposed to indicate the original instruction type (load or store/AMO), then the reported exception cause is respectively a store/AMO access fault (code 7), a store/AMO page fault (code 15), or a store/AMO guest-page fault (code 23).", + "line_number": 280, + "parameter_name": "REPORT_CAUSE_IN_STVAL_ON_SHADOW_STACK_SOFTWARE_CHECK", + "existing_udb_name": "REPORT_CAUSE_IN_STVAL_ON_SHADOW_STACK_SOFTWARE_CHECK", + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "Similar pattern for stval reporting of shadow stack software check exception causes." + }, + { + "excerpt": "If a shadow stack (SS) instruction raises an access-fault, page-fault, or guest-page-fault exception that is supposed to indicate the original instruction type (load or store/AMO), then the reported exception cause is respectively a store/AMO access fault (code 7), a store/AMO page fault (code 15), or a store/AMO guest-page fault (code 23).", + "line_number": 280, + "parameter_name": "REPORT_CAUSE_IN_VSTVAL_ON_SHADOW_STACK_SOFTWARE_CHECK", + "existing_udb_name": "REPORT_CAUSE_IN_VSTVAL_ON_SHADOW_STACK_SOFTWARE_CHECK", + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "Similar pattern for vstval reporting of shadow stack software check exception causes." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "The Zicfilp must be explicitly enabled for use at each privilege mode.", + "line_number": 44, + "reason": "This is inside a [NOTE] block, which is non-normative. Parameters should not be extracted from NOTE blocks." + }, + { + "excerpt": "When a trap is taken into privilege mode `x`, the `__x__PELP` is set to `ELP` and `ELP` is set to `NO_LP_EXPECTED`.", + "line_number": 89, + "reason": "This describes the required behavior when a trap occurs, not an implementation choice. All implementations must follow this behavior." + }, + { + "excerpt": "The encoding `R=0`, `W=1`, and `X=0`, is defined to represent an SS page.", + "line_number": 189, + "reason": "This defines a fixed encoding that all implementations must use, not an implementation choice." + }, + { + "excerpt": "Memory mapped as an SS page cannot be written to by instructions other than `SSAMOSWAP.W/D`, `SSPUSH`, and `C.SSPUSH`.", + "line_number": 198, + "reason": "This describes required behavior for SS pages, not an implementation choice. All implementations must enforce this restriction." + }, + { + "excerpt": "When S-mode is not implemented, then `xSSE` is 0 at both M and U privilege modes.", + "line_number": 165, + "reason": "This is a fixed requirement based on the presence/absence of S-mode, not an implementation choice." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"it is implementation-defined whether FS transitions to Dirty.\",\n \"line_number\": 1014,\n \"parameter_name\": \"REPORT_CAUSE_IN_MTVAL_ON_LANDING_PAD_SOFTWARE_CHECK\",\n \"existing_udb_name\": \"REPORT_CAUSE_IN_MTVAL_ON_LANDING_PAD_SOFTWARE_CHECK\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The specification mentions software-check exceptions with mtval set to 'landing pad fault (code=2)' but doesn't explicitly state this is implementation-defined. However, based on the UDB parameter name pattern, this appears to be about whether the cause is reported in mtval for landing pad software checks.\"\n },\n {\n \"excerpt\": \"The software-check exception due to the instruction not being an `LPAD` instruction when `ELP` is `LP_EXPECTED` or a software-check exception caused by the `LPAD` instruction itself leads to a trap being delivered to the same or to a higher privilege mode.\",\n \"line_number\": 78,\n \"parameter_name\": \"REPORT_CAUSE_IN_STVAL_ON_LANDING_PAD_SOFTWARE_CHECK\",\n \"existing_udb_name\": \"REPORT_CAUSE_IN_STVAL_ON_LANDING_PAD_SOFTWARE_CHECK\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"Similar to mtval case, this relates to reporting cause information in stval for landing pad software check exceptions, though not explicitly stated as implementation-defined in this text.\"\n },\n {\n \"excerpt\": \"The software-check exception due to the instruction not being an `LPAD` instruction when `ELP` is `LP_EXPECTED` or a software-check exception caused by the `LPAD` instruction itself leads to a trap being delivered to the same or to a higher privilege mode.\",\n \"line_number\": 78,\n \"parameter_name\": \"REPORT_CAUSE_IN_VSTVAL_ON_LANDING_PAD_SOFTWARE_CHECK\",\n \"existing_udb_name\": \"REPORT_CAUSE_IN_VSTVAL_ON_LANDING_PAD_SOFTWARE_CHECK\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"Similar pattern for vstval reporting of landing pad software check exception causes.\"\n },\n {\n \"excerpt\": \"If a shadow stack (SS) instruction raises an access-fault, page-fault, or guest-page-fault exception that is supposed to indicate the original instruction type (load or store/AMO), then the reported exception cause is respectively a store/AMO access fault (code 7), a store/AMO page fault (code 15), or a store/AMO guest-page fault (code 23).\",\n \"line_number\": 280,\n \"parameter_name\": \"REPORT_CAUSE_IN_MTVAL_ON_SHADOW_STACK_SOFTWARE_CHECK\",\n \"existing_udb_name\": \"REPORT_CAUSE_IN_MTVAL_ON_SHADOW_STACK_SOFTWARE_CHECK\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"This describes how shadow stack instruction exceptions are reported, which relates to cause reporting in mtval for shadow stack software checks.\"\n },\n {\n \"excerpt\": \"If a shadow stack (SS) instruction raises an access-fault, page-fault, or guest-page-fault exception that is supposed to indicate the original instruction type (load or store/AMO), then the reported exception cause is respectively a store/AMO access fault (code 7), a store/AMO page fault (code 15), or a store/AMO guest-page fault (code 23).\",\n \"line_number\": 280,\n \"parameter_name\": \"REPORT_CAUSE_IN_STVAL_ON_SHADOW_STACK_SOFTWARE_CHECK\",\n \"existing_udb_name\": \"REPORT_CAUSE_IN_STVAL_ON_SHADOW_STACK_SOFTWARE_CHECK\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"Similar pattern for stval reporting of shadow stack software check exception causes.\"\n },\n {\n \"excerpt\": \"If a shadow stack (SS) instruction raises an access-fault, page-fault, or guest-page-fault exception that is supposed to indicate the original instruction type (load or store/AMO), then the reported exception cause is respectively a store/AMO access fault (code 7), a store/AMO page fault (code 15), or a store/AMO guest-page fault (code 23).\",\n \"line_number\": 280,\n \"parameter_name\": \"REPORT_CAUSE_IN_VSTVAL_ON_SHADOW_STACK_SOFTWARE_CHECK\",\n \"existing_udb_name\": \"REPORT_CAUSE_IN_VSTVAL_ON_SHADOW_STACK_SOFTWARE_CHECK\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"Similar pattern for vstval reporting of shadow stack software check exception causes.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"The Zicfilp must be explicitly enabled for use at each privilege mode.\",\n \"line_number\": 44,\n \"reason\": \"This is inside a [NOTE] block, which is non-normative. Parameters should not be extracted from NOTE blocks.\"\n },\n {\n \"excerpt\": \"When a trap is taken into privilege mode `x`, the `__x__PELP` is set to `ELP` and `ELP` is set to `NO_LP_EXPECTED`.\",\n \"line_number\": 89,\n \"reason\": \"This describes the required behavior when a trap occurs, not an implementation choice. All implementations must follow this behavior.\"\n },\n {\n \"excerpt\": \"The encoding `R=0`, `W=1`, and `X=0`, is defined to represent an SS page.\",\n \"line_number\": 189,\n \"reason\": \"This defines a fixed encoding that all implementations must use, not an implementation choice.\"\n },\n {\n \"excerpt\": \"Memory mapped as an SS page cannot be written to by instructions other than `SSAMOSWAP.W/D`, `SSPUSH`, and `C.SSPUSH`.\",\n \"line_number\": 198,\n \"reason\": \"This describes required behavior for SS pages, not an implementation choice. All implementations must enforce this restriction.\"\n },\n {\n \"excerpt\": \"When S-mode is not implemented, then `xSSE` is 0 at both M and U privilege modes.\",\n \"line_number\": 165,\n \"reason\": \"This is a fixed requirement based on the presence/absence of S-mode, not an implementation choice.\"\n }\n ]\n}\n```", + "input_tokens": 10841, + "output_tokens": 1752, + "latency_ms": 55058, + "timestamp": "2026-04-15T14:34:15.692408+00:00", + "error": null, + "retry_count": 1 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_026.json.license b/param_extraction/results/claude-sonnet-4/chunk_026.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_026.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_027.json b/param_extraction/results/claude-sonnet-4/chunk_027.json new file mode 100644 index 0000000000..a54d11b1ce --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_027.json @@ -0,0 +1,54 @@ +{ + "chunk_id": "chunk_027", + "source_file": "priv-csrs.adoc", + "start_line": 1, + "end_line": 1272, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "Implementations are permitted but not required to raise an illegal-instruction exception if an instruction attempts to write a non-supported value to a *WLRL* field.", + "line_number": 1157, + "parameter_name": "TRAP_ON_ILLEGAL_WLRL", + "existing_udb_name": "TRAP_ON_ILLEGAL_WLRL", + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether to trap on illegal WLRL writes. This is a direct binary choice (trap or don't trap) not controlled by any CSR field." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "The CSR address convention uses the upper bits of the CSR address to encode default access privileges. This simplifies error checking in the hardware and provides a larger CSR space, but does constrain the mapping of CSRs into the address space.", + "line_number": 35, + "reason": "This is inside a [NOTE] block, which is non-normative informative text." + }, + { + "excerpt": "The top two bits (csr[11:10]) indicate whether the register is read/write (`00`,`01`, or `10`) or read-only (`11`).", + "line_number": 29, + "reason": "This describes a fixed encoding convention that all implementations must follow, not an implementation choice." + }, + { + "excerpt": "Instructions that access a non-existent CSR are reserved.", + "line_number": 46, + "reason": "This is a fixed requirement ('are reserved') that applies to all implementations, not a parameter." + }, + { + "excerpt": "For forward compatibility, implementations that do not furnish these fields must make them read-only zero.", + "line_number": 1120, + "reason": "This is a fixed requirement ('must make them read-only zero') for implementations that don't implement WPRI fields, not a choice." + }, + { + "excerpt": "Software should not write anything other than legal values to such a field, and should not assume a read will return a legal value unless the last write was of a legal value", + "line_number": 1140, + "reason": "This describes software behavior requirements, not implementation choices. The 'should' applies to software, not hardware implementation options." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"Implementations are permitted but not required to raise an illegal-instruction exception if an instruction attempts to write a non-supported value to a *WLRL* field.\",\n \"line_number\": 1157,\n \"parameter_name\": \"TRAP_ON_ILLEGAL_WLRL\",\n \"existing_udb_name\": \"TRAP_ON_ILLEGAL_WLRL\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether to trap on illegal WLRL writes. This is a direct binary choice (trap or don't trap) not controlled by any CSR field.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"The CSR address convention uses the upper bits of the CSR address to encode default access privileges. This simplifies error checking in the hardware and provides a larger CSR space, but does constrain the mapping of CSRs into the address space.\",\n \"line_number\": 35,\n \"reason\": \"This is inside a [NOTE] block, which is non-normative informative text.\"\n },\n {\n \"excerpt\": \"The top two bits (csr[11:10]) indicate whether the register is read/write (`00`,`01`, or `10`) or read-only (`11`).\",\n \"line_number\": 29,\n \"reason\": \"This describes a fixed encoding convention that all implementations must follow, not an implementation choice.\"\n },\n {\n \"excerpt\": \"Instructions that access a non-existent CSR are reserved.\",\n \"line_number\": 46,\n \"reason\": \"This is a fixed requirement ('are reserved') that applies to all implementations, not a parameter.\"\n },\n {\n \"excerpt\": \"For forward compatibility, implementations that do not furnish these fields must make them read-only zero.\",\n \"line_number\": 1120,\n \"reason\": \"This is a fixed requirement ('must make them read-only zero') for implementations that don't implement WPRI fields, not a choice.\"\n },\n {\n \"excerpt\": \"Software should not write anything other than legal values to such a field, and should not assume a read will return a legal value unless the last write was of a legal value\",\n \"line_number\": 1140,\n \"reason\": \"This describes software behavior requirements, not implementation choices. The 'should' applies to software, not hardware implementation options.\"\n }\n ]\n}\n```", + "input_tokens": 18597, + "output_tokens": 616, + "latency_ms": 13566, + "timestamp": "2026-04-15T14:36:17.903304+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_027.json.license b/param_extraction/results/claude-sonnet-4/chunk_027.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_027.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_030.json b/param_extraction/results/claude-sonnet-4/chunk_030.json new file mode 100644 index 0000000000..8f70f0dc3a --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_030.json @@ -0,0 +1,64 @@ +{ + "chunk_id": "chunk_030", + "source_file": "priv-intro.adoc", + "start_line": 1, + "end_line": 217, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "Implementations might provide anywhere from 1 to 3 privilege modes", + "line_number": 135, + "parameter_name": "NUM_PRIVILEGE_MODES", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "range", + "confidence": "high", + "reasoning": "The number of privilege modes (1, 2, or 3) is a direct implementation choice that determines the protection model. This is not controlled by any CSR field." + }, + { + "excerpt": "Implementations may also include a debug mode to support off-chip debugging and/or manufacturing test.", + "line_number": 179, + "parameter_name": "DEBUG_MODE_IMPLEMENTED", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "Whether debug mode is implemented is an optional implementation choice. The use of 'may' indicates this is not mandatory for all implementations." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "Commentary on our design decisions is formatted as in this paragraph, and can be skipped if the reader is only interested in the specification itself.", + "line_number": 11, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks." + }, + { + "excerpt": "At any time, a RISC-V hardware thread (_hart_) is running at some privilege level encoded as a mode in one or more CSRs", + "line_number": 85, + "reason": "This describes a fixed requirement that applies to all implementations - every hart must be running at some privilege level. This is not an implementation choice." + }, + { + "excerpt": "Three RISC-V privilege levels are currently defined", + "line_number": 88, + "reason": "This states a fixed fact about the specification - there are exactly three defined privilege levels. This is not an implementation parameter." + }, + { + "excerpt": "All hardware implementations must provide M-mode", + "line_number": 145, + "reason": "This is a fixed requirement ('must provide') that applies to all implementations. M-mode is mandatory, not optional." + }, + { + "excerpt": "attempts to perform operations not permitted by the current privilege mode will cause an exception to be raised", + "line_number": 100, + "reason": "This describes required behavior that all implementations must follow when privilege violations occur. It is not an implementation choice." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"Implementations might provide anywhere from 1 to 3 privilege modes\",\n \"line_number\": 135,\n \"parameter_name\": \"NUM_PRIVILEGE_MODES\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"range\",\n \"confidence\": \"high\",\n \"reasoning\": \"The number of privilege modes (1, 2, or 3) is a direct implementation choice that determines the protection model. This is not controlled by any CSR field.\"\n },\n {\n \"excerpt\": \"Implementations may also include a debug mode to support off-chip debugging and/or manufacturing test.\",\n \"line_number\": 179,\n \"parameter_name\": \"DEBUG_MODE_IMPLEMENTED\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"Whether debug mode is implemented is an optional implementation choice. The use of 'may' indicates this is not mandatory for all implementations.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"Commentary on our design decisions is formatted as in this paragraph, and can be skipped if the reader is only interested in the specification itself.\",\n \"line_number\": 11,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks.\"\n },\n {\n \"excerpt\": \"At any time, a RISC-V hardware thread (_hart_) is running at some privilege level encoded as a mode in one or more CSRs\",\n \"line_number\": 85,\n \"reason\": \"This describes a fixed requirement that applies to all implementations - every hart must be running at some privilege level. This is not an implementation choice.\"\n },\n {\n \"excerpt\": \"Three RISC-V privilege levels are currently defined\",\n \"line_number\": 88,\n \"reason\": \"This states a fixed fact about the specification - there are exactly three defined privilege levels. This is not an implementation parameter.\"\n },\n {\n \"excerpt\": \"All hardware implementations must provide M-mode\",\n \"line_number\": 145,\n \"reason\": \"This is a fixed requirement ('must provide') that applies to all implementations. M-mode is mandatory, not optional.\"\n },\n {\n \"excerpt\": \"attempts to perform operations not permitted by the current privilege mode will cause an exception to be raised\",\n \"line_number\": 100,\n \"reason\": \"This describes required behavior that all implementations must follow when privilege violations occur. It is not an implementation choice.\"\n }\n ]\n}\n```", + "input_tokens": 7802, + "output_tokens": 668, + "latency_ms": 25216, + "timestamp": "2026-04-15T14:34:58.897142+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_030.json.license b/param_extraction/results/claude-sonnet-4/chunk_030.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_030.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_033.json b/param_extraction/results/claude-sonnet-4/chunk_033.json new file mode 100644 index 0000000000..1e610cffcc --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_033.json @@ -0,0 +1,49 @@ +{ + "chunk_id": "chunk_033", + "source_file": "q-st-ext.adoc", + "start_line": 1, + "end_line": 120, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "The floating-point registers are now extended to hold either a single, double, or quad-precision floating-point value (FLEN=128).", + "line_number": 7, + "parameter_name": "FLEN", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "FLEN=128 is a direct architectural parameter that defines the width of floating-point registers when the Q extension is implemented. This is a design-time choice that affects register width." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "FLQ and FSQ are only guaranteed to execute atomically if the effective address is naturally aligned and XLEN=128.", + "line_number": 23, + "reason": "This describes a conditional guarantee about atomic execution based on alignment and XLEN value, not an implementation choice. The atomicity behavior is deterministic given the conditions." + }, + { + "excerpt": "FLQ and FSQ do not modify the bits being transferred; in particular, the payloads of non-canonical NaNs are preserved.", + "line_number": 26, + "reason": "This is a fixed requirement that all implementations must satisfy - bits must not be modified during transfer. There is no implementation choice here." + }, + { + "excerpt": "FCVT.L[U].Q and FCVT.Q.L[U] are RV64-only instructions.", + "line_number": 58, + "reason": "This states a fixed requirement about which instructions are available in RV64 vs RV32. It's not an implementation choice but a specification rule." + }, + { + "excerpt": "FMV.X.Q and FMV.Q.X instructions are not provided in RV32 or RV64, so quad-precision bit patterns must be moved to the integer registers via memory.", + "line_number": 82, + "reason": "This states that certain instructions are not provided in any base ISA width, which is a fixed specification rule, not an implementation parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"The floating-point registers are now extended to hold either a single, double, or quad-precision floating-point value (FLEN=128).\",\n \"line_number\": 7,\n \"parameter_name\": \"FLEN\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"FLEN=128 is a direct architectural parameter that defines the width of floating-point registers when the Q extension is implemented. This is a design-time choice that affects register width.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"FLQ and FSQ are only guaranteed to execute atomically if the effective address is naturally aligned and XLEN=128.\",\n \"line_number\": 23,\n \"reason\": \"This describes a conditional guarantee about atomic execution based on alignment and XLEN value, not an implementation choice. The atomicity behavior is deterministic given the conditions.\"\n },\n {\n \"excerpt\": \"FLQ and FSQ do not modify the bits being transferred; in particular, the payloads of non-canonical NaNs are preserved.\",\n \"line_number\": 26,\n \"reason\": \"This is a fixed requirement that all implementations must satisfy - bits must not be modified during transfer. There is no implementation choice here.\"\n },\n {\n \"excerpt\": \"FCVT.L[U].Q and FCVT.Q.L[U] are RV64-only instructions.\",\n \"line_number\": 58,\n \"reason\": \"This states a fixed requirement about which instructions are available in RV64 vs RV32. It's not an implementation choice but a specification rule.\"\n },\n {\n \"excerpt\": \"FMV.X.Q and FMV.Q.X instructions are not provided in RV32 or RV64, so quad-precision bit patterns must be moved to the integer registers via memory.\",\n \"line_number\": 82,\n \"reason\": \"This states that certain instructions are not provided in any base ISA width, which is a fixed specification rule, not an implementation parameter.\"\n }\n ]\n}\n```", + "input_tokens": 7196, + "output_tokens": 549, + "latency_ms": 48766, + "timestamp": "2026-04-15T14:35:50.697927+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_033.json.license b/param_extraction/results/claude-sonnet-4/chunk_033.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_033.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_037.json b/param_extraction/results/claude-sonnet-4/chunk_037.json new file mode 100644 index 0000000000..8b886128e2 --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_037.json @@ -0,0 +1,74 @@ +{ + "chunk_id": "chunk_037", + "source_file": "rnmi.adoc", + "start_line": 1, + "end_line": 166, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "The RNMI interrupt trap handler address is implementation-defined.", + "line_number": 23, + "parameter_name": "RNMI_INTERRUPT_HANDLER_ADDRESS", + "existing_udb_name": null, + "class": "NON_ISA", + "value_type": "value", + "confidence": "high", + "reasoning": "This is a platform-level address choice outside the ISA scope, similar to reset vector or NMI addresses in the NON_ISA class." + }, + { + "excerpt": "RNMI also has an associated exception trap handler address, which is implementation defined.", + "line_number": 25, + "parameter_name": "RNMI_EXCEPTION_HANDLER_ADDRESS", + "existing_udb_name": null, + "class": "NON_ISA", + "value_type": "value", + "confidence": "high", + "reasoning": "This is another platform-level address choice outside the ISA scope, similar to the interrupt handler address." + }, + { + "excerpt": "`mnepc` is a *WARL* register that must be able to hold all valid virtual addresses. It need not be capable of holding all possible invalid addresses. Prior to writing `mnepc`, implementations may convert an invalid address into some other invalid address that `mnepc` is capable of holding.", + "line_number": 58, + "parameter_name": "MNEPC_WARL_VALUES", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "This defines the WARL behavior of mnepc - the set of legal values it can hold varies by implementation. The parameter is which invalid addresses can be held." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "For example, some implementations might use the address specified in `mtvec` as the RNMI exception trap handler.", + "line_number": 27, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. It's an example suggestion, not an architectural requirement." + }, + { + "excerpt": "RNMIs are masked out of reset to give software the opportunity to initialize data structures and devices for subsequent RNMI handling.", + "line_number": 95, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. It explains rationale but doesn't define a parameter." + }, + { + "excerpt": "Upon reset, NMIE contains the value 0.", + "line_number": 93, + "reason": "This is a fixed requirement that applies to all implementations - the reset value is always 0, not implementation-defined." + }, + { + "excerpt": "When an RNMI interrupt is detected, the interrupted PC is written to the `mnepc` CSR", + "line_number": 135, + "reason": "This describes the required behavior when an RNMI occurs. It's a fixed specification requirement, not an implementation choice." + }, + { + "excerpt": "Software can set NMIE to 1, but attempts to clear NMIE have no effect.", + "line_number": 97, + "reason": "This describes the required behavior of the NMIE bit - it's a fixed specification requirement that applies to all implementations, not a parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"The RNMI interrupt trap handler address is implementation-defined.\",\n \"line_number\": 23,\n \"parameter_name\": \"RNMI_INTERRUPT_HANDLER_ADDRESS\",\n \"existing_udb_name\": null,\n \"class\": \"NON_ISA\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"This is a platform-level address choice outside the ISA scope, similar to reset vector or NMI addresses in the NON_ISA class.\"\n },\n {\n \"excerpt\": \"RNMI also has an associated exception trap handler address, which is implementation defined.\",\n \"line_number\": 25,\n \"parameter_name\": \"RNMI_EXCEPTION_HANDLER_ADDRESS\", \n \"existing_udb_name\": null,\n \"class\": \"NON_ISA\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"This is another platform-level address choice outside the ISA scope, similar to the interrupt handler address.\"\n },\n {\n \"excerpt\": \"`mnepc` is a *WARL* register that must be able to hold all valid virtual addresses. It need not be capable of holding all possible invalid addresses. Prior to writing `mnepc`, implementations may convert an invalid address into some other invalid address that `mnepc` is capable of holding.\",\n \"line_number\": 58,\n \"parameter_name\": \"MNEPC_WARL_VALUES\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"This defines the WARL behavior of mnepc - the set of legal values it can hold varies by implementation. The parameter is which invalid addresses can be held.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"For example, some implementations might use the address specified in `mtvec` as the RNMI exception trap handler.\",\n \"line_number\": 27,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. It's an example suggestion, not an architectural requirement.\"\n },\n {\n \"excerpt\": \"RNMIs are masked out of reset to give software the opportunity to initialize data structures and devices for subsequent RNMI handling.\",\n \"line_number\": 95,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. It explains rationale but doesn't define a parameter.\"\n },\n {\n \"excerpt\": \"Upon reset, NMIE contains the value 0.\",\n \"line_number\": 93,\n \"reason\": \"This is a fixed requirement that applies to all implementations - the reset value is always 0, not implementation-defined.\"\n },\n {\n \"excerpt\": \"When an RNMI interrupt is detected, the interrupted PC is written to the `mnepc` CSR\",\n \"line_number\": 135,\n \"reason\": \"This describes the required behavior when an RNMI occurs. It's a fixed specification requirement, not an implementation choice.\"\n },\n {\n \"excerpt\": \"Software can set NMIE to 1, but attempts to clear NMIE have no effect.\",\n \"line_number\": 97,\n \"reason\": \"This describes the required behavior of the NMIE bit - it's a fixed specification requirement that applies to all implementations, not a parameter.\"\n }\n ]\n}\n```", + "input_tokens": 7656, + "output_tokens": 880, + "latency_ms": 14351, + "timestamp": "2026-04-15T14:37:33.299230+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_037.json.license b/param_extraction/results/claude-sonnet-4/chunk_037.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_037.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_039.json b/param_extraction/results/claude-sonnet-4/chunk_039.json new file mode 100644 index 0000000000..cd1bb4a068 --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_039.json @@ -0,0 +1,114 @@ +{ + "chunk_id": "chunk_039", + "source_file": "rv32.adoc", + "start_line": 1, + "end_line": 1105, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "The EEI will define whether the memory system is little-endian or big-endian.", + "line_number": 651, + "parameter_name": "ENDIANNESS_LITTLE_OR_BIG", + "existing_udb_name": "ENDIANNESS_LITTLE_OR_BIG", + "class": "NON_ISA", + "value_type": "binary", + "confidence": "high", + "reasoning": "This is a platform-level choice about memory system endianness, which is outside the ISA scope and defined by the execution environment interface (EEI)." + }, + { + "excerpt": "Loads and stores whose effective address is not naturally aligned to the referenced datatype (i.e., the effective address is not divisible by the size of the access in bytes) have behavior dependent on the EEI.", + "line_number": 672, + "parameter_name": "MISALIGNED_LDST_EEI_DEPENDENT_BEHAVIOR", + "existing_udb_name": "MISALIGNED_LDST_EEI_DEPENDENT_BEHAVIOR", + "class": "NON_ISA", + "value_type": "enum", + "confidence": "high", + "reasoning": "The behavior of misaligned loads and stores is explicitly defined as EEI-dependent, making it a platform-level choice outside the ISA scope." + }, + { + "excerpt": "misaligned loads and stores can be handled in hardware", + "line_number": 678, + "parameter_name": "MISALIGNED_LDST_FULLY_HW_SUPPORTED", + "existing_udb_name": "MISALIGNED_LDST_FULLY_HW_SUPPORTED", + "class": "NON_ISA", + "value_type": "binary", + "confidence": "medium", + "reasoning": "This describes one possible EEI choice for handling misaligned accesses - whether they are supported in hardware or not." + }, + { + "excerpt": "via an invisible trap into the execution environment implementation", + "line_number": 679, + "parameter_name": "MISALIGNED_LDST_INVISIBLE_TRAP", + "existing_udb_name": "MISALIGNED_LDST_INVISIBLE_TRAP", + "class": "NON_ISA", + "value_type": "binary", + "confidence": "medium", + "reasoning": "This describes another EEI choice for handling misaligned accesses through invisible traps." + }, + { + "excerpt": "combination of hardware and invisible trap depending on address", + "line_number": 680, + "parameter_name": "MISALIGNED_LDST_HW_OR_INVISIBLE_TRAP_FUNC_OF_ADDR", + "existing_udb_name": "MISALIGNED_LDST_HW_OR_INVISIBLE_TRAP_FUNC_OF_ADDR", + "class": "NON_ISA", + "value_type": "binary", + "confidence": "medium", + "reasoning": "This describes a third EEI choice where misaligned access handling varies by address." + }, + { + "excerpt": "loads and stores that are not naturally aligned may either complete execution successfully or raise an exception", + "line_number": 683, + "parameter_name": "MISALIGNED_LDST_FULLY_HW_SUPPORTED_OR_VISIBLE_TRAP", + "existing_udb_name": "MISALIGNED_LDST_FULLY_HW_SUPPORTED_OR_VISIBLE_TRAP", + "class": "NON_ISA", + "value_type": "binary", + "confidence": "medium", + "reasoning": "This describes the EEI choice of whether misaligned accesses complete or trap when not guaranteed to be handled invisibly." + }, + { + "excerpt": "When an EEI does not guarantee misaligned loads and stores are handled invisibly, the EEI must define if exceptions caused by address misalignment result in a contained trap (allowing software running inside the execution environment to handle the trap) or a fatal trap (terminating execution).", + "line_number": 691, + "parameter_name": "MISALIGNED_LDST_CONTAINED_OR_FATAL_TRAP", + "existing_udb_name": "MISALIGNED_LDST_CONTAINED_OR_FATAL_TRAP", + "class": "NON_ISA", + "value_type": "binary", + "confidence": "high", + "reasoning": "This is an EEI-defined choice about whether misalignment exceptions are contained or fatal, which is a platform-level decision." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "For RV32I, the 32 `x` registers are each 32 bits wide, i.e., `XLEN=32`.", + "line_number": 39, + "reason": "This is a fixed requirement for RV32I - XLEN is always 32 for this ISA variant, not an implementation choice." + }, + { + "excerpt": "Register `x0` is hardwired with all bits equal to 0.", + "line_number": 40, + "reason": "This is a fixed architectural requirement that all implementations must satisfy - x0 must always be zero." + }, + { + "excerpt": "An instruction-address-misaligned exception is generated on a taken branch or unconditional jump if the target address is not `IALIGN-bit` aligned.", + "line_number": 149, + "reason": "This describes required behavior when a condition is met, not an implementation choice. The behavior is deterministic." + }, + { + "excerpt": "ADDI adds the sign-extended 12-bit immediate to register _rs1_.", + "line_number": 264, + "reason": "This describes the fixed operation of the ADDI instruction, which is the same across all implementations." + }, + { + "excerpt": "HINTs do not change any architecturally visible state, except for advancing the `pc` and any applicable performance counters.", + "line_number": 1026, + "reason": "This describes the required behavior of HINT instructions - they must not change architectural state. This is a fixed requirement, not a parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"The EEI will define whether the memory system is little-endian or big-endian.\",\n \"line_number\": 651,\n \"parameter_name\": \"ENDIANNESS_LITTLE_OR_BIG\",\n \"existing_udb_name\": \"ENDIANNESS_LITTLE_OR_BIG\",\n \"class\": \"NON_ISA\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"This is a platform-level choice about memory system endianness, which is outside the ISA scope and defined by the execution environment interface (EEI).\"\n },\n {\n \"excerpt\": \"Loads and stores whose effective address is not naturally aligned to the referenced datatype (i.e., the effective address is not divisible by the size of the access in bytes) have behavior dependent on the EEI.\",\n \"line_number\": 672,\n \"parameter_name\": \"MISALIGNED_LDST_EEI_DEPENDENT_BEHAVIOR\",\n \"existing_udb_name\": \"MISALIGNED_LDST_EEI_DEPENDENT_BEHAVIOR\",\n \"class\": \"NON_ISA\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"The behavior of misaligned loads and stores is explicitly defined as EEI-dependent, making it a platform-level choice outside the ISA scope.\"\n },\n {\n \"excerpt\": \"misaligned loads and stores can be handled in hardware\",\n \"line_number\": 678,\n \"parameter_name\": \"MISALIGNED_LDST_FULLY_HW_SUPPORTED\",\n \"existing_udb_name\": \"MISALIGNED_LDST_FULLY_HW_SUPPORTED\",\n \"class\": \"NON_ISA\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"This describes one possible EEI choice for handling misaligned accesses - whether they are supported in hardware or not.\"\n },\n {\n \"excerpt\": \"via an invisible trap into the execution environment implementation\",\n \"line_number\": 679,\n \"parameter_name\": \"MISALIGNED_LDST_INVISIBLE_TRAP\",\n \"existing_udb_name\": \"MISALIGNED_LDST_INVISIBLE_TRAP\",\n \"class\": \"NON_ISA\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"This describes another EEI choice for handling misaligned accesses through invisible traps.\"\n },\n {\n \"excerpt\": \"combination of hardware and invisible trap depending on address\",\n \"line_number\": 680,\n \"parameter_name\": \"MISALIGNED_LDST_HW_OR_INVISIBLE_TRAP_FUNC_OF_ADDR\",\n \"existing_udb_name\": \"MISALIGNED_LDST_HW_OR_INVISIBLE_TRAP_FUNC_OF_ADDR\",\n \"class\": \"NON_ISA\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"This describes a third EEI choice where misaligned access handling varies by address.\"\n },\n {\n \"excerpt\": \"loads and stores that are not naturally aligned may either complete execution successfully or raise an exception\",\n \"line_number\": 683,\n \"parameter_name\": \"MISALIGNED_LDST_FULLY_HW_SUPPORTED_OR_VISIBLE_TRAP\",\n \"existing_udb_name\": \"MISALIGNED_LDST_FULLY_HW_SUPPORTED_OR_VISIBLE_TRAP\",\n \"class\": \"NON_ISA\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"This describes the EEI choice of whether misaligned accesses complete or trap when not guaranteed to be handled invisibly.\"\n },\n {\n \"excerpt\": \"When an EEI does not guarantee misaligned loads and stores are handled invisibly, the EEI must define if exceptions caused by address misalignment result in a contained trap (allowing software running inside the execution environment to handle the trap) or a fatal trap (terminating execution).\",\n \"line_number\": 691,\n \"parameter_name\": \"MISALIGNED_LDST_CONTAINED_OR_FATAL_TRAP\",\n \"existing_udb_name\": \"MISALIGNED_LDST_CONTAINED_OR_FATAL_TRAP\",\n \"class\": \"NON_ISA\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"This is an EEI-defined choice about whether misalignment exceptions are contained or fatal, which is a platform-level decision.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"For RV32I, the 32 `x` registers are each 32 bits wide, i.e., `XLEN=32`.\",\n \"line_number\": 39,\n \"reason\": \"This is a fixed requirement for RV32I - XLEN is always 32 for this ISA variant, not an implementation choice.\"\n },\n {\n \"excerpt\": \"Register `x0` is hardwired with all bits equal to 0.\",\n \"line_number\": 40,\n \"reason\": \"This is a fixed architectural requirement that all implementations must satisfy - x0 must always be zero.\"\n },\n {\n \"excerpt\": \"An instruction-address-misaligned exception is generated on a taken branch or unconditional jump if the target address is not `IALIGN-bit` aligned.\",\n \"line_number\": 149,\n \"reason\": \"This describes required behavior when a condition is met, not an implementation choice. The behavior is deterministic.\"\n },\n {\n \"excerpt\": \"ADDI adds the sign-extended 12-bit immediate to register _rs1_.\",\n \"line_number\": 264,\n \"reason\": \"This describes the fixed operation of the ADDI instruction, which is the same across all implementations.\"\n },\n {\n \"excerpt\": \"HINTs do not change any architecturally visible state, except for advancing the `pc` and any applicable performance counters.\",\n \"line_number\": 1026,\n \"reason\": \"This describes the required behavior of HINT instructions - they must not change architectural state. This is a fixed requirement, not a parameter.\"\n }\n ]\n}\n```", + "input_tokens": 19338, + "output_tokens": 1604, + "latency_ms": 28120, + "timestamp": "2026-04-15T15:07:37.927340+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_039.json.license b/param_extraction/results/claude-sonnet-4/chunk_039.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_039.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_040.json b/param_extraction/results/claude-sonnet-4/chunk_040.json new file mode 100644 index 0000000000..16ada9a395 --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_040.json @@ -0,0 +1,43 @@ +{ + "chunk_id": "chunk_040", + "source_file": "rv32e.adoc", + "start_line": 1, + "end_line": 47, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [], + "skipped_non_parameters": [ + { + "excerpt": "RV32E and RV64E reduce the integer register count to 16 general-purpose registers, (`x0-x15`), where `x0` is a dedicated zero register.", + "line_number": 21, + "reason": "This is a fixed requirement of the RV32E/RV64E specification, not an implementation choice. All RV32E/RV64E implementations must have exactly 16 registers." + }, + { + "excerpt": "RV32E and RV64E use the same instruction-set encoding as RV32I and RV64I respectively, except that only registers `x0-x15` are provided.", + "line_number": 33, + "reason": "This describes the fixed encoding rules for RV32E/RV64E, not an implementation parameter. The encoding is mandated by the specification." + }, + { + "excerpt": "All encodings specifying the other registers `x16-x31` are reserved.", + "line_number": 35, + "reason": "This is a fixed requirement that all implementations must follow - reserved encodings are not implementation-defined choices." + }, + { + "excerpt": "We have found that in the small RV32I core implementations, the upper 16 registers consume around one quarter of the total area of the core excluding memories, thus their removal saves around 25% core area with a corresponding core power reduction.", + "line_number": 25, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. It provides background information but does not define any architectural parameters." + }, + { + "excerpt": "The previous draft of this chapter made all encodings using the `x16-x31` registers available as custom. This version takes a more conservative approach, making these reserved so that they can be allocated between custom space or new standard encodings at a later date.", + "line_number": 38, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. It explains the rationale for the current approach but does not define implementation choices." + } + ], + "raw_response": "```json\n{\n \"parameters\": [],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"RV32E and RV64E reduce the integer register count to 16 general-purpose registers, (`x0-x15`), where `x0` is a dedicated zero register.\",\n \"line_number\": 21,\n \"reason\": \"This is a fixed requirement of the RV32E/RV64E specification, not an implementation choice. All RV32E/RV64E implementations must have exactly 16 registers.\"\n },\n {\n \"excerpt\": \"RV32E and RV64E use the same instruction-set encoding as RV32I and RV64I respectively, except that only registers `x0-x15` are provided.\",\n \"line_number\": 33,\n \"reason\": \"This describes the fixed encoding rules for RV32E/RV64E, not an implementation parameter. The encoding is mandated by the specification.\"\n },\n {\n \"excerpt\": \"All encodings specifying the other registers `x16-x31` are reserved.\",\n \"line_number\": 35,\n \"reason\": \"This is a fixed requirement that all implementations must follow - reserved encodings are not implementation-defined choices.\"\n },\n {\n \"excerpt\": \"We have found that in the small RV32I core implementations, the upper 16 registers consume around one quarter of the total area of the core excluding memories, thus their removal saves around 25% core area with a corresponding core power reduction.\",\n \"line_number\": 25,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. It provides background information but does not define any architectural parameters.\"\n },\n {\n \"excerpt\": \"The previous draft of this chapter made all encodings using the `x16-x31` registers available as custom. This version takes a more conservative approach, making these reserved so that they can be allocated between custom space or new standard encodings at a later date.\",\n \"line_number\": 38,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. It explains the rationale for the current approach but does not define implementation choices.\"\n }\n ]\n}\n```", + "input_tokens": 6125, + "output_tokens": 534, + "latency_ms": 16633, + "timestamp": "2026-04-15T14:38:15.761897+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_040.json.license b/param_extraction/results/claude-sonnet-4/chunk_040.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_040.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_041.json b/param_extraction/results/claude-sonnet-4/chunk_041.json new file mode 100644 index 0000000000..fe989f7ae7 --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_041.json @@ -0,0 +1,54 @@ +{ + "chunk_id": "chunk_041", + "source_file": "rv64.adoc", + "start_line": 1, + "end_line": 260, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "RV64I widens the integer registers and supported user address space to 64 bits (XLEN=64 in <>).", + "line_number": 10, + "parameter_name": "XLEN", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "XLEN is a fundamental architectural parameter that defines the width of integer registers. In RV64I, it is fixed at 64 bits, but this represents an implementation choice between different ISA variants (RV32I vs RV64I)." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "These \"*W\" instructions ignore the upper 32 bits of their inputs and always produce 32-bit signed values, sign-extending them to 64 bits, i.e. bits XLEN-1 through 31 are equal.", + "line_number": 16, + "reason": "This describes the fixed behavior of W-suffix instructions in RV64I. It is a normative requirement that applies to all RV64I implementations, not an implementation choice." + }, + { + "excerpt": "ADDIW is an RV64I instruction that adds the sign-extended 12-bit immediate to register _rs1_ and produces the proper sign extension of a 32-bit result in _rd_.", + "line_number": 42, + "reason": "This describes the fixed operation of the ADDIW instruction. The behavior is defined by the ISA specification, not left to implementation choice." + }, + { + "excerpt": "SLLIW, SRLIW, and SRAIW encodings with _imm[5] {ne} 0_ are reserved.", + "line_number": 66, + "reason": "This states that certain encodings are reserved, which is a fixed specification requirement. Reserved encodings are not implementation-defined parameters." + }, + { + "excerpt": "The execution environment will define what portions of the address space are legal to access.", + "line_number": 130, + "reason": "This refers to execution environment choices, which are platform-level decisions outside the ISA scope. The ISA itself does not define which address ranges are legal." + }, + { + "excerpt": "91% of the HINT space is reserved for standard HINTs. The remainder of the HINT space is designated for custom HINTs; no standard HINTs will ever be defined in this subspace.", + "line_number": 150, + "reason": "This describes the allocation of HINT encoding space, which is a fixed specification decision. The percentages and designations are not implementation choices but specification design decisions." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"RV64I widens the integer registers and supported user address space to 64 bits (XLEN=64 in <>).\",\n \"line_number\": 10,\n \"parameter_name\": \"XLEN\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"XLEN is a fundamental architectural parameter that defines the width of integer registers. In RV64I, it is fixed at 64 bits, but this represents an implementation choice between different ISA variants (RV32I vs RV64I).\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"These \\\"*W\\\" instructions ignore the upper 32 bits of their inputs and always produce 32-bit signed values, sign-extending them to 64 bits, i.e. bits XLEN-1 through 31 are equal.\",\n \"line_number\": 16,\n \"reason\": \"This describes the fixed behavior of W-suffix instructions in RV64I. It is a normative requirement that applies to all RV64I implementations, not an implementation choice.\"\n },\n {\n \"excerpt\": \"ADDIW is an RV64I instruction that adds the sign-extended 12-bit immediate to register _rs1_ and produces the proper sign extension of a 32-bit result in _rd_.\",\n \"line_number\": 42,\n \"reason\": \"This describes the fixed operation of the ADDIW instruction. The behavior is defined by the ISA specification, not left to implementation choice.\"\n },\n {\n \"excerpt\": \"SLLIW, SRLIW, and SRAIW encodings with _imm[5] {ne} 0_ are reserved.\",\n \"line_number\": 66,\n \"reason\": \"This states that certain encodings are reserved, which is a fixed specification requirement. Reserved encodings are not implementation-defined parameters.\"\n },\n {\n \"excerpt\": \"The execution environment will define what portions of the address space are legal to access.\",\n \"line_number\": 130,\n \"reason\": \"This refers to execution environment choices, which are platform-level decisions outside the ISA scope. The ISA itself does not define which address ranges are legal.\"\n },\n {\n \"excerpt\": \"91% of the HINT space is reserved for standard HINTs. The remainder of the HINT space is designated for custom HINTs; no standard HINTs will ever be defined in this subspace.\",\n \"line_number\": 150,\n \"reason\": \"This describes the allocation of HINT encoding space, which is a fixed specification decision. The percentages and designations are not implementation choices but specification design decisions.\"\n }\n ]\n}\n```", + "input_tokens": 9275, + "output_tokens": 692, + "latency_ms": 12580, + "timestamp": "2026-04-15T14:38:31.362837+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_041.json.license b/param_extraction/results/claude-sonnet-4/chunk_041.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_041.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_042.json b/param_extraction/results/claude-sonnet-4/chunk_042.json new file mode 100644 index 0000000000..90d7f185ed --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_042.json @@ -0,0 +1,64 @@ +{ + "chunk_id": "chunk_042", + "source_file": "rvwmo.adoc", + "start_line": 1, + "end_line": 817, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "A misaligned load or store instruction may be decomposed into a set of component memory operations of any granularity.", + "line_number": 95, + "parameter_name": "MISALIGNED_DECOMPOSITION_GRANULARITY", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "medium", + "reasoning": "The granularity of decomposition for misaligned memory operations is implementation-defined. The spec says 'any granularity', leaving the specific choice to the implementer." + }, + { + "excerpt": "A floating-point load or store of more than XLEN bits may also be decomposed into a set of component memory operations of any granularity.", + "line_number": 96, + "parameter_name": "FP_WIDE_DECOMPOSITION_GRANULARITY", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "medium", + "reasoning": "Similar to misaligned operations, the granularity for decomposing wide floating-point operations is implementation-defined ('any granularity')." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "This chapter defines the memory model for regular main memory operations. The interaction of the memory model with I/O memory, instruction fetches, FENCE.I, page-table walks, and SFENCE.VMA is not (yet) formalized.", + "line_number": 29, + "reason": "This text is inside a [NOTE] block, which is non-normative. Parameters should not be extracted from NOTE blocks." + }, + { + "excerpt": "Each aligned memory instruction that accesses XLEN or fewer bits gives rise to exactly one memory operation, unless specified otherwise.", + "line_number": 68, + "reason": "This is a fixed requirement that applies to all implementations - it defines what 'must' happen, not an implementation choice." + }, + { + "excerpt": "All memory operations are single-copy atomic: they can never be observed in a partially complete state.", + "line_number": 66, + "reason": "This is a fixed architectural requirement ('can never be observed') that all implementations must satisfy, not a parameter." + }, + { + "excerpt": "The global memory order is defined over the primitive load and store operations generated by memory instructions.", + "line_number": 52, + "reason": "This is a definitional statement about how the memory model works, not an implementation choice or parameter." + }, + { + "excerpt": "An execution of a RISC-V program obeys the RVWMO memory consistency model only if there exists a global memory order conforming to preserved program order", + "line_number": 295, + "reason": "This describes a requirement that all implementations must satisfy ('only if'), not an implementation-defined parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"A misaligned load or store instruction may be decomposed into a set of component memory operations of any granularity.\",\n \"line_number\": 95,\n \"parameter_name\": \"MISALIGNED_DECOMPOSITION_GRANULARITY\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The granularity of decomposition for misaligned memory operations is implementation-defined. The spec says 'any granularity', leaving the specific choice to the implementer.\"\n },\n {\n \"excerpt\": \"A floating-point load or store of more than XLEN bits may also be decomposed into a set of component memory operations of any granularity.\",\n \"line_number\": 96,\n \"parameter_name\": \"FP_WIDE_DECOMPOSITION_GRANULARITY\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"medium\",\n \"reasoning\": \"Similar to misaligned operations, the granularity for decomposing wide floating-point operations is implementation-defined ('any granularity').\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"This chapter defines the memory model for regular main memory operations. The interaction of the memory model with I/O memory, instruction fetches, FENCE.I, page-table walks, and SFENCE.VMA is not (yet) formalized.\",\n \"line_number\": 29,\n \"reason\": \"This text is inside a [NOTE] block, which is non-normative. Parameters should not be extracted from NOTE blocks.\"\n },\n {\n \"excerpt\": \"Each aligned memory instruction that accesses XLEN or fewer bits gives rise to exactly one memory operation, unless specified otherwise.\",\n \"line_number\": 68,\n \"reason\": \"This is a fixed requirement that applies to all implementations - it defines what 'must' happen, not an implementation choice.\"\n },\n {\n \"excerpt\": \"All memory operations are single-copy atomic: they can never be observed in a partially complete state.\",\n \"line_number\": 66,\n \"reason\": \"This is a fixed architectural requirement ('can never be observed') that all implementations must satisfy, not a parameter.\"\n },\n {\n \"excerpt\": \"The global memory order is defined over the primitive load and store operations generated by memory instructions.\",\n \"line_number\": 52,\n \"reason\": \"This is a definitional statement about how the memory model works, not an implementation choice or parameter.\"\n },\n {\n \"excerpt\": \"An execution of a RISC-V program obeys the RVWMO memory consistency model only if there exists a global memory order conforming to preserved program order\",\n \"line_number\": 295,\n \"reason\": \"This describes a requirement that all implementations must satisfy ('only if'), not an implementation-defined parameter.\"\n }\n ]\n}\n```", + "input_tokens": 14911, + "output_tokens": 749, + "latency_ms": 17038, + "timestamp": "2026-04-15T14:59:32.111622+00:00", + "error": null, + "retry_count": 1 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_042.json.license b/param_extraction/results/claude-sonnet-4/chunk_042.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_042.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_043.json b/param_extraction/results/claude-sonnet-4/chunk_043.json new file mode 100644 index 0000000000..202c3141b3 --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_043.json @@ -0,0 +1,43 @@ +{ + "chunk_id": "chunk_043", + "source_file": "scalar-crypto.adoc", + "start_line": 1, + "end_line": 3448, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [], + "skipped_non_parameters": [ + { + "excerpt": "Detection of individual cryptography extensions uses the unified software-based RISC-V discovery method.", + "line_number": 179, + "reason": "This describes a software detection mechanism, not an architectural parameter that implementers choose." + }, + { + "excerpt": "This instruction must _always_ be implemented such that its execution latency does not depend on the data being operated on.", + "line_number": 1000, + "reason": "This is a fixed requirement ('must always') that applies to all implementations, not an implementation choice." + }, + { + "excerpt": "For RV32, the encodings corresponding to shamt[5]=1 are reserved.", + "line_number": 2800, + "reason": "This describes reserved encodings, which are fixed constraints rather than implementation parameters." + }, + { + "excerpt": "A core which implements `Zkn` must implement all of the above extensions.", + "line_number": 400, + "reason": "This is a fixed requirement for extension compliance, not an implementation choice." + }, + { + "excerpt": "Note that `rnum` must be in the range `0x0..0xA`. The values `0xB..0xF` are reserved.", + "line_number": 1500, + "reason": "This describes fixed constraints on instruction operands, not implementation parameters." + } + ], + "raw_response": "```json\n{\n \"parameters\": [],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"Detection of individual cryptography extensions uses the unified software-based RISC-V discovery method.\",\n \"line_number\": 179,\n \"reason\": \"This describes a software detection mechanism, not an architectural parameter that implementers choose.\"\n },\n {\n \"excerpt\": \"This instruction must _always_ be implemented such that its execution latency does not depend on the data being operated on.\",\n \"line_number\": 1000,\n \"reason\": \"This is a fixed requirement ('must always') that applies to all implementations, not an implementation choice.\"\n },\n {\n \"excerpt\": \"For RV32, the encodings corresponding to shamt[5]=1 are reserved.\",\n \"line_number\": 2800,\n \"reason\": \"This describes reserved encodings, which are fixed constraints rather than implementation parameters.\"\n },\n {\n \"excerpt\": \"A core which implements `Zkn` must implement all of the above extensions.\",\n \"line_number\": 400,\n \"reason\": \"This is a fixed requirement for extension compliance, not an implementation choice.\"\n },\n {\n \"excerpt\": \"Note that `rnum` must be in the range `0x0..0xA`. The values `0xB..0xF` are reserved.\",\n \"line_number\": 1500,\n \"reason\": \"This describes fixed constraints on instruction operands, not implementation parameters.\"\n }\n ]\n}\n```", + "input_tokens": 35038, + "output_tokens": 367, + "latency_ms": 9507, + "timestamp": "2026-04-15T14:39:54.247258+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_043.json.license b/param_extraction/results/claude-sonnet-4/chunk_043.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_043.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_044.json b/param_extraction/results/claude-sonnet-4/chunk_044.json new file mode 100644 index 0000000000..8ea35d4b33 --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_044.json @@ -0,0 +1,74 @@ +{ + "chunk_id": "chunk_044", + "source_file": "scalar-crypto.adoc", + "start_line": 3419, + "end_line": 5590, + "content_start_line": 3449, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "The `seed` CSR is also access controlled by execution mode, and attempted read or write access will raise an illegal-instruction exception outside M mode unless access is explicitly granted.", + "line_number": 3549, + "parameter_name": "SEED_CSR_ACCESS_CONTROL", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether to grant access to the seed CSR from lower privilege modes or restrict it to M-mode only. This is a direct implementation choice about access control policy." + }, + { + "excerpt": "Implementations may implement `mseccfg` such that `[s,u]seed` is a read-only constant value `0`.", + "line_number": 3916, + "parameter_name": "MSECCFG_SEED_FIELDS_IMPLEMENTED", + "existing_udb_name": null, + "class": "NORM_CSR_RW", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether the mseccfg.[s,u]seed fields are read-only zero (not implemented) or read-write (implemented). This controls the mutability of these CSR fields." + }, + { + "excerpt": "An implementation of the entropy source should meet at least one of the following requirements sets in order to be considered a secure and safe design", + "line_number": 3635, + "parameter_name": "ENTROPY_SOURCE_STANDARD", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "medium", + "reasoning": "The implementation chooses which entropy source standard to follow (NIST SP 800-90B, AIS-31 PTG.2, or virtual source). This is a design-time choice that affects the entropy source behavior and requirements." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "This instruction is useful for implementing the SHA3 cryptographic hash function on a 32-bit architecture, as it implements the bit-interleaving operation used to speed up the 64-bit rotations directly.", + "line_number": 3475, + "reason": "This is inside a [NOTE] block, which is non-normative informational content, not an architectural requirement." + }, + { + "excerpt": "The 32-bit contents of `seed` are as follows:", + "line_number": 3497, + "reason": "This describes the fixed format of the seed CSR, which is a specification requirement that all implementations must follow, not a parameter." + }, + { + "excerpt": "Software normally uses the instruction `csrrw rd, seed, x0` to read the `seed` CSR.", + "line_number": 3527, + "reason": "This describes software usage patterns, not an implementation-defined architectural parameter." + }, + { + "excerpt": "Each returned `seed[15:0]` = `entropy` value represents unique randomness when `OPST`=`ES16`", + "line_number": 3565, + "reason": "This describes the required behavior when the CSR is in ES16 state, which is a fixed specification requirement, not an implementation choice." + }, + { + "excerpt": "When `OPST` is not `ES16`, `entropy` must be set to 0.", + "line_number": 3571, + "reason": "This is a fixed requirement ('must be set to 0') that all implementations must follow, not a parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"The `seed` CSR is also access controlled by execution mode, and attempted read or write access will raise an illegal-instruction exception outside M mode unless access is explicitly granted.\",\n \"line_number\": 3549,\n \"parameter_name\": \"SEED_CSR_ACCESS_CONTROL\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether to grant access to the seed CSR from lower privilege modes or restrict it to M-mode only. This is a direct implementation choice about access control policy.\"\n },\n {\n \"excerpt\": \"Implementations may implement `mseccfg` such that `[s,u]seed` is a read-only constant value `0`.\",\n \"line_number\": 3916,\n \"parameter_name\": \"MSECCFG_SEED_FIELDS_IMPLEMENTED\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether the mseccfg.[s,u]seed fields are read-only zero (not implemented) or read-write (implemented). This controls the mutability of these CSR fields.\"\n },\n {\n \"excerpt\": \"An implementation of the entropy source should meet at least one of the following requirements sets in order to be considered a secure and safe design\",\n \"line_number\": 3635,\n \"parameter_name\": \"ENTROPY_SOURCE_STANDARD\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The implementation chooses which entropy source standard to follow (NIST SP 800-90B, AIS-31 PTG.2, or virtual source). This is a design-time choice that affects the entropy source behavior and requirements.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"This instruction is useful for implementing the SHA3 cryptographic hash function on a 32-bit architecture, as it implements the bit-interleaving operation used to speed up the 64-bit rotations directly.\",\n \"line_number\": 3475,\n \"reason\": \"This is inside a [NOTE] block, which is non-normative informational content, not an architectural requirement.\"\n },\n {\n \"excerpt\": \"The 32-bit contents of `seed` are as follows:\",\n \"line_number\": 3497,\n \"reason\": \"This describes the fixed format of the seed CSR, which is a specification requirement that all implementations must follow, not a parameter.\"\n },\n {\n \"excerpt\": \"Software normally uses the instruction `csrrw rd, seed, x0` to read the `seed` CSR.\",\n \"line_number\": 3527,\n \"reason\": \"This describes software usage patterns, not an implementation-defined architectural parameter.\"\n },\n {\n \"excerpt\": \"Each returned `seed[15:0]` = `entropy` value represents unique randomness when `OPST`=`ES16`\",\n \"line_number\": 3565,\n \"reason\": \"This describes the required behavior when the CSR is in ES16 state, which is a fixed specification requirement, not an implementation choice.\"\n },\n {\n \"excerpt\": \"When `OPST` is not `ES16`, `entropy` must be set to 0.\",\n \"line_number\": 3571,\n \"reason\": \"This is a fixed requirement ('must be set to 0') that all implementations must follow, not a parameter.\"\n }\n ]\n}\n```", + "input_tokens": 36762, + "output_tokens": 931, + "latency_ms": 22565, + "timestamp": "2026-04-15T15:00:55.701126+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_044.json.license b/param_extraction/results/claude-sonnet-4/chunk_044.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_044.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_045.json b/param_extraction/results/claude-sonnet-4/chunk_045.json new file mode 100644 index 0000000000..38f29127d7 --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_045.json @@ -0,0 +1,54 @@ +{ + "chunk_id": "chunk_045", + "source_file": "smcdeleg.adoc", + "start_line": 1, + "end_line": 147, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "It is optional whether the LCOFI bit (bit 13) in each of `mideleg` and `hideleg`, which allows all LCOFIs to be delegated to S-mode and VS-mode, respectively, is implemented and writable.", + "line_number": 145, + "parameter_name": "LCOFI_DELEGATION_SUPPORT", + "existing_udb_name": null, + "class": "NORM_CSR_RW", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether the LCOFI bits in mideleg and hideleg are implemented and writable. This is a binary choice about the mutability of specific CSR fields." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "NOTE: _The memory-mapped `mtime` register is not a performance monitoring counter to be managed by supervisor software, hence the special treatment of `siselect` value 0x41 described above._", + "line_number": 85, + "reason": "This is inside a [NOTE] block and is therefore non-normative explanatory text, not a parameter definition." + }, + { + "excerpt": "When `menvcfg`.CDE=0, attempts to access `scountinhibit` raise an illegal-instruction exception.", + "line_number": 108, + "reason": "This describes behavior when a CSR field has a specific value (CDE=0). The behavior is determined by the field value at runtime, not by an implementation choice." + }, + { + "excerpt": "For a RISC-V hardware platform, Smcdeleg and Ssccfg must always be implemented in tandem.", + "line_number": 28, + "reason": "This is a fixed requirement ('must always') that applies to all implementations supporting these extensions. There is no implementation choice here." + }, + { + "excerpt": "illegal-instruction exceptions are raised for the following cases", + "line_number": 70, + "reason": "This describes mandatory exception behavior that all implementations must follow. The conditions are fixed requirements, not implementation choices." + }, + { + "excerpt": "The `siselect` (and `vsiselect`) index range 0x40-0x5F is reserved for delegated counter access.", + "line_number": 35, + "reason": "This defines a fixed architectural mapping/reservation that all implementations must follow. It is not an implementation choice." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"It is optional whether the LCOFI bit (bit 13) in each of `mideleg` and `hideleg`, which allows all LCOFIs to be delegated to S-mode and VS-mode, respectively, is implemented and writable.\",\n \"line_number\": 145,\n \"parameter_name\": \"LCOFI_DELEGATION_SUPPORT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether the LCOFI bits in mideleg and hideleg are implemented and writable. This is a binary choice about the mutability of specific CSR fields.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"NOTE: _The memory-mapped `mtime` register is not a performance monitoring counter to be managed by supervisor software, hence the special treatment of `siselect` value 0x41 described above._\",\n \"line_number\": 85,\n \"reason\": \"This is inside a [NOTE] block and is therefore non-normative explanatory text, not a parameter definition.\"\n },\n {\n \"excerpt\": \"When `menvcfg`.CDE=0, attempts to access `scountinhibit` raise an illegal-instruction exception.\",\n \"line_number\": 108,\n \"reason\": \"This describes behavior when a CSR field has a specific value (CDE=0). The behavior is determined by the field value at runtime, not by an implementation choice.\"\n },\n {\n \"excerpt\": \"For a RISC-V hardware platform, Smcdeleg and Ssccfg must always be implemented in tandem.\",\n \"line_number\": 28,\n \"reason\": \"This is a fixed requirement ('must always') that applies to all implementations supporting these extensions. There is no implementation choice here.\"\n },\n {\n \"excerpt\": \"illegal-instruction exceptions are raised for the following cases\",\n \"line_number\": 70,\n \"reason\": \"This describes mandatory exception behavior that all implementations must follow. The conditions are fixed requirements, not implementation choices.\"\n },\n {\n \"excerpt\": \"The `siselect` (and `vsiselect`) index range 0x40-0x5F is reserved for delegated counter access.\",\n \"line_number\": 35,\n \"reason\": \"This defines a fixed architectural mapping/reservation that all implementations must follow. It is not an implementation choice.\"\n }\n ]\n}\n```", + "input_tokens": 8004, + "output_tokens": 635, + "latency_ms": 69171, + "timestamp": "2026-04-15T14:41:27.212626+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_045.json.license b/param_extraction/results/claude-sonnet-4/chunk_045.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_045.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_046.json b/param_extraction/results/claude-sonnet-4/chunk_046.json new file mode 100644 index 0000000000..0201ce2442 --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_046.json @@ -0,0 +1,59 @@ +{ + "chunk_id": "chunk_046", + "source_file": "smcntrpmf.adoc", + "start_line": 1, + "end_line": 69, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "For each bit in 61:58, if the associated privilege mode is not implemented, the bit is read-only zero.", + "line_number": 35, + "parameter_name": "MCYCLECFG_PRIVILEGE_MODE_SUPPORT", + "existing_udb_name": null, + "class": "NORM_CSR_RW", + "value_type": "bitmask", + "confidence": "high", + "reasoning": "The implementation chooses which privilege modes are supported, which determines whether the corresponding INH bits in mcyclecfg/minstretcfg are read-only zero or read-write. This is a per-bit RO/RW choice based on privilege mode implementation." + }, + { + "excerpt": "the change of privilege mode may be reported as occurring in any one of those cycles (possibly different for each occurrence of a trap or trap return).", + "line_number": 46, + "parameter_name": "PRIVILEGE_MODE_TRANSITION_CYCLE_TIMING", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "medium", + "reasoning": "The implementation chooses in which cycle during a multi-cycle trap/return operation the privilege mode change is reported to occur. This affects cycle counter behavior and is an implementation-defined timing choice." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "The more natural CSR number for mcyclecfg would be 0x320, but that was allocated to mcountinhibit.", + "line_number": 40, + "reason": "This is inside a [NOTE] block, which is non-normative commentary about CSR numbering decisions, not an architectural parameter." + }, + { + "excerpt": "The RISC-V ISA has no requirement that the number of cycles for a trap or trap return be the same for all occurrences.", + "line_number": 48, + "reason": "This is inside a [NOTE] block describing what the ISA does NOT require, rather than defining an implementation parameter." + }, + { + "excerpt": "When all __x__INH bits are zero, event counting is enabled in all modes.", + "line_number": 33, + "reason": "This describes the behavior when CSR fields have specific values, not an implementation choice. The parameter is which modes are supported (affecting RO/RW nature of bits), not this behavioral description." + }, + { + "excerpt": "instructions that retire in a non-inhibited mode increment instret, and instructions that retire in an inhibited mode do not", + "line_number": 52, + "reason": "This describes the required behavior based on CSR field values at runtime, not an implementation-defined parameter. All implementations must follow this rule." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"For each bit in 61:58, if the associated privilege mode is not implemented, the bit is read-only zero.\",\n \"line_number\": 35,\n \"parameter_name\": \"MCYCLECFG_PRIVILEGE_MODE_SUPPORT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"bitmask\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses which privilege modes are supported, which determines whether the corresponding INH bits in mcyclecfg/minstretcfg are read-only zero or read-write. This is a per-bit RO/RW choice based on privilege mode implementation.\"\n },\n {\n \"excerpt\": \"the change of privilege mode may be reported as occurring in any one of those cycles (possibly different for each occurrence of a trap or trap return).\",\n \"line_number\": 46,\n \"parameter_name\": \"PRIVILEGE_MODE_TRANSITION_CYCLE_TIMING\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The implementation chooses in which cycle during a multi-cycle trap/return operation the privilege mode change is reported to occur. This affects cycle counter behavior and is an implementation-defined timing choice.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"The more natural CSR number for mcyclecfg would be 0x320, but that was allocated to mcountinhibit.\",\n \"line_number\": 40,\n \"reason\": \"This is inside a [NOTE] block, which is non-normative commentary about CSR numbering decisions, not an architectural parameter.\"\n },\n {\n \"excerpt\": \"The RISC-V ISA has no requirement that the number of cycles for a trap or trap return be the same for all occurrences.\",\n \"line_number\": 48,\n \"reason\": \"This is inside a [NOTE] block describing what the ISA does NOT require, rather than defining an implementation parameter.\"\n },\n {\n \"excerpt\": \"When all __x__INH bits are zero, event counting is enabled in all modes.\",\n \"line_number\": 33,\n \"reason\": \"This describes the behavior when CSR fields have specific values, not an implementation choice. The parameter is which modes are supported (affecting RO/RW nature of bits), not this behavioral description.\"\n },\n {\n \"excerpt\": \"instructions that retire in a non-inhibited mode increment instret, and instructions that retire in an inhibited mode do not\",\n \"line_number\": 52,\n \"reason\": \"This describes the required behavior based on CSR field values at runtime, not an implementation-defined parameter. All implementations must follow this rule.\"\n }\n ]\n}\n```", + "input_tokens": 6822, + "output_tokens": 716, + "latency_ms": 13446, + "timestamp": "2026-04-15T14:41:28.185793+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_046.json.license b/param_extraction/results/claude-sonnet-4/chunk_046.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_046.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_047.json b/param_extraction/results/claude-sonnet-4/chunk_047.json new file mode 100644 index 0000000000..fe6361a78e --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_047.json @@ -0,0 +1,144 @@ +{ + "chunk_id": "chunk_047", + "source_file": "smctr.adoc", + "start_line": 1, + "end_line": 763, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "The number of records that can be held in the buffer depends upon both the implementation (the maximum supported depth) and the CTR configuration (the software selected depth).", + "line_number": 9, + "parameter_name": "CTR_MAX_DEPTH", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "The implementation chooses the maximum supported depth of the CTR buffer. This is a direct architectural parameter not controlled by any CSR field." + }, + { + "excerpt": "All fields are optional except for M, S, U, and BPFRZ. All unimplemented fields are read-only 0, while all implemented fields are writable. If the Sscofpmf extension is implemented, LCOFIFRZ must be writable.", + "line_number": 108, + "parameter_name": "MCTRCTL_FIELD_SUPPORT", + "existing_udb_name": null, + "class": "NORM_CSR_RW", + "value_type": "set", + "confidence": "high", + "reasoning": "The implementation chooses which mctrctl fields to implement as writable vs read-only-0. This controls the RW nature of CSR fields." + }, + { + "excerpt": "It is implementation-specific which DEPTH value(s) are supported.", + "line_number": 179, + "parameter_name": "SCTRDEPTH_SUPPORTED_VALUES", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "The DEPTH field is WARL and the implementation defines which depth values (16, 32, 64, 128, 256) are legal. This is the set of legal values for a WARL CSR field." + }, + { + "excerpt": "The optional MISP bit is set by the hardware when the recorded transfer is an instruction whose target or taken/not-taken direction was mispredicted by the branch predictor. MISP is read-only 0 when not implemented.", + "line_number": 244, + "parameter_name": "CTRTARGET_MISP_SUPPORT", + "existing_udb_name": null, + "class": "NORM_CSR_RW", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether to implement the MISP bit as functional or read-only-0. This is a binary choice about field implementation." + }, + { + "excerpt": "This register must be implemented, though all fields within it are optional. Unimplemented fields are read-only 0.", + "line_number": 260, + "parameter_name": "CTRDATA_FIELD_SUPPORT", + "existing_udb_name": null, + "class": "NORM_CSR_RW", + "value_type": "set", + "confidence": "high", + "reasoning": "The implementation chooses which ctrdata fields (TYPE, CCV, CC) to implement as functional vs read-only-0. This controls the RW nature of CSR fields." + }, + { + "excerpt": "The `ctrdata` register may optionally include a count of CPU cycles elapsed since the prior CTR record.", + "line_number": 456, + "parameter_name": "CTR_CYCLE_COUNTING_SUPPORT", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether to support cycle counting functionality in the ctrdata register. This is a direct implementation choice." + }, + { + "excerpt": "An implementation that supports cycle counting must implement CCV and all CCM bits, but may implement 0..4 exponent bits in CCE. Unimplemented CCE bits are read-only 0.", + "line_number": 472, + "parameter_name": "CTR_CCE_WIDTH", + "existing_udb_name": null, + "class": "NORM_CSR_RW", + "value_type": "range", + "confidence": "high", + "reasoning": "The implementation chooses how many CCE exponent bits (0-4) to implement, with unimplemented bits being read-only-0. This controls the width of a CSR field." + }, + { + "excerpt": "When the optional `__x__ctrctl`.RASEMU bit is implemented and set to 1, transfer recording behavior is altered to emulate the behavior of a return-address stack (RAS).", + "line_number": 507, + "parameter_name": "CTR_RASEMU_SUPPORT", + "existing_udb_name": null, + "class": "NORM_CSR_RW", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether to implement the RASEMU bit as functional or read-only-0. This is a binary choice about field implementation." + }, + { + "excerpt": "If external trap recording is implemented, `mctrctl`.MTE and `sctrctl`.STE must be implemented, while `vsctrctl`.STE must be implemented if the H extension is implemented.", + "line_number": 427, + "parameter_name": "CTR_EXTERNAL_TRAP_SUPPORT", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether to support external trap recording functionality. This is a direct implementation choice that affects which CSR fields must be implemented." + }, + { + "excerpt": "All transfer type filter bits are optional.", + "line_number": 432, + "parameter_name": "CTR_TRANSFER_TYPE_FILTER_SUPPORT", + "existing_udb_name": null, + "class": "NORM_CSR_RW", + "value_type": "set", + "confidence": "high", + "reasoning": "The implementation chooses which transfer type filter bits to implement as functional vs read-only-0. This controls which CSR fields are writable." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "Only qualified transfers are recorded. Qualified transfers are those that meet the filtering criteria, which include the privilege mode and the transfer type.", + "line_number": 11, + "reason": "This describes the behavior of qualified transfers, which is determined by CSR field values at runtime, not an implementation choice." + }, + { + "excerpt": "The machine-level extension, *Smctr*, encompasses all newly added Control Status Registers (CSRs), instructions, and behavior modifications for a hart across all privilege levels.", + "line_number": 17, + "reason": "This is a definition of what the Smctr extension includes, not an implementation-defined parameter." + }, + { + "excerpt": "Enable transfer recording in the selected privileged mode(s).", + "line_number": 60, + "reason": "This describes the behavior when M/S/U bits are set, which is runtime behavior controlled by CSR field values, not an implementation choice." + }, + { + "excerpt": "CTR records qualified control transfers. Control transfers are qualified if they meet the following criteria:", + "line_number": 598, + "reason": "This describes the behavioral criteria for recording transfers, which is determined by CSR configurations at runtime, not an implementation parameter." + }, + { + "excerpt": "Recording in Debug Mode is always inhibited. Transfers into and out of Debug Mode are never recorded.", + "line_number": 635, + "reason": "This is a fixed requirement ('always inhibited', 'never recorded') that applies to all implementations, not a parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"The number of records that can be held in the buffer depends upon both the implementation (the maximum supported depth) and the CTR configuration (the software selected depth).\",\n \"line_number\": 9,\n \"parameter_name\": \"CTR_MAX_DEPTH\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses the maximum supported depth of the CTR buffer. This is a direct architectural parameter not controlled by any CSR field.\"\n },\n {\n \"excerpt\": \"All fields are optional except for M, S, U, and BPFRZ. All unimplemented fields are read-only 0, while all implemented fields are writable. If the Sscofpmf extension is implemented, LCOFIFRZ must be writable.\",\n \"line_number\": 108,\n \"parameter_name\": \"MCTRCTL_FIELD_SUPPORT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses which mctrctl fields to implement as writable vs read-only-0. This controls the RW nature of CSR fields.\"\n },\n {\n \"excerpt\": \"It is implementation-specific which DEPTH value(s) are supported.\",\n \"line_number\": 179,\n \"parameter_name\": \"SCTRDEPTH_SUPPORTED_VALUES\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"The DEPTH field is WARL and the implementation defines which depth values (16, 32, 64, 128, 256) are legal. This is the set of legal values for a WARL CSR field.\"\n },\n {\n \"excerpt\": \"The optional MISP bit is set by the hardware when the recorded transfer is an instruction whose target or taken/not-taken direction was mispredicted by the branch predictor. MISP is read-only 0 when not implemented.\",\n \"line_number\": 244,\n \"parameter_name\": \"CTRTARGET_MISP_SUPPORT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether to implement the MISP bit as functional or read-only-0. This is a binary choice about field implementation.\"\n },\n {\n \"excerpt\": \"This register must be implemented, though all fields within it are optional. Unimplemented fields are read-only 0.\",\n \"line_number\": 260,\n \"parameter_name\": \"CTRDATA_FIELD_SUPPORT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses which ctrdata fields (TYPE, CCV, CC) to implement as functional vs read-only-0. This controls the RW nature of CSR fields.\"\n },\n {\n \"excerpt\": \"The `ctrdata` register may optionally include a count of CPU cycles elapsed since the prior CTR record.\",\n \"line_number\": 456,\n \"parameter_name\": \"CTR_CYCLE_COUNTING_SUPPORT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether to support cycle counting functionality in the ctrdata register. This is a direct implementation choice.\"\n },\n {\n \"excerpt\": \"An implementation that supports cycle counting must implement CCV and all CCM bits, but may implement 0..4 exponent bits in CCE. Unimplemented CCE bits are read-only 0.\",\n \"line_number\": 472,\n \"parameter_name\": \"CTR_CCE_WIDTH\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"range\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses how many CCE exponent bits (0-4) to implement, with unimplemented bits being read-only-0. This controls the width of a CSR field.\"\n },\n {\n \"excerpt\": \"When the optional `__x__ctrctl`.RASEMU bit is implemented and set to 1, transfer recording behavior is altered to emulate the behavior of a return-address stack (RAS).\",\n \"line_number\": 507,\n \"parameter_name\": \"CTR_RASEMU_SUPPORT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether to implement the RASEMU bit as functional or read-only-0. This is a binary choice about field implementation.\"\n },\n {\n \"excerpt\": \"If external trap recording is implemented, `mctrctl`.MTE and `sctrctl`.STE must be implemented, while `vsctrctl`.STE must be implemented if the H extension is implemented.\",\n \"line_number\": 427,\n \"parameter_name\": \"CTR_EXTERNAL_TRAP_SUPPORT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether to support external trap recording functionality. This is a direct implementation choice that affects which CSR fields must be implemented.\"\n },\n {\n \"excerpt\": \"All transfer type filter bits are optional.\",\n \"line_number\": 432,\n \"parameter_name\": \"CTR_TRANSFER_TYPE_FILTER_SUPPORT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses which transfer type filter bits to implement as functional vs read-only-0. This controls which CSR fields are writable.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"Only qualified transfers are recorded. Qualified transfers are those that meet the filtering criteria, which include the privilege mode and the transfer type.\",\n \"line_number\": 11,\n \"reason\": \"This describes the behavior of qualified transfers, which is determined by CSR field values at runtime, not an implementation choice.\"\n },\n {\n \"excerpt\": \"The machine-level extension, *Smctr*, encompasses all newly added Control Status Registers (CSRs), instructions, and behavior modifications for a hart across all privilege levels.\",\n \"line_number\": 17,\n \"reason\": \"This is a definition of what the Smctr extension includes, not an implementation-defined parameter.\"\n },\n {\n \"excerpt\": \"Enable transfer recording in the selected privileged mode(s).\",\n \"line_number\": 60,\n \"reason\": \"This describes the behavior when M/S/U bits are set, which is runtime behavior controlled by CSR field values, not an implementation choice.\"\n },\n {\n \"excerpt\": \"CTR records qualified control transfers. Control transfers are qualified if they meet the following criteria:\",\n \"line_number\": 598,\n \"reason\": \"This describes the behavioral criteria for recording transfers, which is determined by CSR configurations at runtime, not an implementation parameter.\"\n },\n {\n \"excerpt\": \"Recording in Debug Mode is always inhibited. Transfers into and out of Debug Mode are never recorded.\",\n \"line_number\": 635,\n \"reason\": \"This is a fixed requirement ('always inhibited', 'never recorded') that applies to all implementations, not a parameter.\"\n }\n ]\n}\n```", + "input_tokens": 20546, + "output_tokens": 2018, + "latency_ms": 60793, + "timestamp": "2026-04-15T14:42:31.996318+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_047.json.license b/param_extraction/results/claude-sonnet-4/chunk_047.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_047.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_048.json b/param_extraction/results/claude-sonnet-4/chunk_048.json new file mode 100644 index 0000000000..bd0017cb6d --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_048.json @@ -0,0 +1,44 @@ +{ + "chunk_id": "chunk_048", + "source_file": "smdbltrp.adoc", + "start_line": 1, + "end_line": 17, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "The extension introduces a mechanism to enter Debug Mode instead of asserting a critical-error signal to the platform when the hart is in a critical error state.", + "line_number": 13, + "parameter_name": "SMDBLTRP_DEBUG_MODE_ON_CRITICAL_ERROR", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "The extension 'introduces a mechanism' which implies an implementation choice between entering Debug Mode vs asserting a critical-error signal when in a critical error state. This is a binary choice for how to handle critical errors." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "The Smdbltrp extension addresses a double trap (See <>) in M-mode.", + "line_number": 4, + "reason": "This describes what the extension does, not an implementation choice. It's a fixed functional requirement." + }, + { + "excerpt": "When the Smrnmi extension (<>) is implemented, it enables invocation of the RNMI handler on a double trap in M-mode to handle the critical error.", + "line_number": 5, + "reason": "This describes conditional behavior based on whether another extension is present, but doesn't define an implementation parameter within Smdbltrp itself." + }, + { + "excerpt": "If the Smrnmi extension is not implemented or if a double trap occurs during the RNMI handler's execution, this extension helps transition the hart to a critical error state", + "line_number": 7, + "reason": "This describes what happens in specific conditions, but is a fixed behavioral requirement rather than an implementation choice." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"The extension introduces a mechanism to enter Debug Mode instead of asserting a critical-error signal to the platform when the hart is in a critical error state.\",\n \"line_number\": 13,\n \"parameter_name\": \"SMDBLTRP_DEBUG_MODE_ON_CRITICAL_ERROR\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The extension 'introduces a mechanism' which implies an implementation choice between entering Debug Mode vs asserting a critical-error signal when in a critical error state. This is a binary choice for how to handle critical errors.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"The Smdbltrp extension addresses a double trap (See <>) in M-mode.\",\n \"line_number\": 4,\n \"reason\": \"This describes what the extension does, not an implementation choice. It's a fixed functional requirement.\"\n },\n {\n \"excerpt\": \"When the Smrnmi extension (<>) is implemented, it enables invocation of the RNMI handler on a double trap in M-mode to handle the critical error.\",\n \"line_number\": 5,\n \"reason\": \"This describes conditional behavior based on whether another extension is present, but doesn't define an implementation parameter within Smdbltrp itself.\"\n },\n {\n \"excerpt\": \"If the Smrnmi extension is not implemented or if a double trap occurs during the RNMI handler's execution, this extension helps transition the hart to a critical error state\",\n \"line_number\": 7,\n \"reason\": \"This describes what happens in specific conditions, but is a fixed behavioral requirement rather than an implementation choice.\"\n }\n ]\n}\n```", + "input_tokens": 5822, + "output_tokens": 463, + "latency_ms": 8725, + "timestamp": "2026-04-15T14:43:37.228381+00:00", + "error": null, + "retry_count": 1 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_048.json.license b/param_extraction/results/claude-sonnet-4/chunk_048.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_048.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_049.json b/param_extraction/results/claude-sonnet-4/chunk_049.json new file mode 100644 index 0000000000..c6569b5577 --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_049.json @@ -0,0 +1,43 @@ +{ + "chunk_id": "chunk_049", + "source_file": "smepmp.adoc", + "start_line": 1, + "end_line": 77, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [], + "skipped_non_parameters": [ + { + "excerpt": "Terms: * *PMP Entry*: A pair of ``pmpcfg[i]`` / ``pmpaddr[i]`` registers. * *PMP Rule*: The contents of a pmpcfg register and its associated pmpaddr register(s), that encode a valid protected physical memory region...", + "line_number": 14, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. It provides definitions and explanations but does not define architectural parameters." + }, + { + "excerpt": "Without the Smepmp extension, it is not possible for a PMP rule to be *enforced* only on non-Machine modes and *denied* on Machine mode", + "line_number": 30, + "reason": "This describes the behavior without the extension, explaining the motivation for the extension rather than defining implementation choices." + }, + { + "excerpt": "The physical memory protection rules when `mseccfg.MML` is set to 1 are summarized in the truth table below.", + "line_number": 42, + "reason": "This describes the behavior when a CSR field has a specific value (MML=1). The behavior is determined by the CSR field value at runtime, not by an implementation choice." + }, + { + "excerpt": "Since all fields defined in ``mseccfg`` as part of this extension are locked when set (``MMWP``/``MML``) or locked when cleared (``RLB``), software can't poll them for determining the presence of Smepmp.", + "line_number": 69, + "reason": "This describes the behavior of the CSR fields and software discovery mechanisms, but does not define any implementation-defined choices or parameters." + }, + { + "excerpt": "It is expected that BootROM will set ``mseccfg.MMWP`` and/or ``mseccfg.MML`` during early boot, before jumping to the firmware", + "line_number": 69, + "reason": "This describes expected software behavior and boot sequence, not an architectural parameter that implementers choose." + } + ], + "raw_response": "```json\n{\n \"parameters\": [],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"Terms: * *PMP Entry*: A pair of ``pmpcfg[i]`` / ``pmpaddr[i]`` registers. * *PMP Rule*: The contents of a pmpcfg register and its associated pmpaddr register(s), that encode a valid protected physical memory region...\",\n \"line_number\": 14,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. It provides definitions and explanations but does not define architectural parameters.\"\n },\n {\n \"excerpt\": \"Without the Smepmp extension, it is not possible for a PMP rule to be *enforced* only on non-Machine modes and *denied* on Machine mode\",\n \"line_number\": 30,\n \"reason\": \"This describes the behavior without the extension, explaining the motivation for the extension rather than defining implementation choices.\"\n },\n {\n \"excerpt\": \"The physical memory protection rules when `mseccfg.MML` is set to 1 are summarized in the truth table below.\",\n \"line_number\": 42,\n \"reason\": \"This describes the behavior when a CSR field has a specific value (MML=1). The behavior is determined by the CSR field value at runtime, not by an implementation choice.\"\n },\n {\n \"excerpt\": \"Since all fields defined in ``mseccfg`` as part of this extension are locked when set (``MMWP``/``MML``) or locked when cleared (``RLB``), software can't poll them for determining the presence of Smepmp.\",\n \"line_number\": 69,\n \"reason\": \"This describes the behavior of the CSR fields and software discovery mechanisms, but does not define any implementation-defined choices or parameters.\"\n },\n {\n \"excerpt\": \"It is expected that BootROM will set ``mseccfg.MMWP`` and/or ``mseccfg.MML`` during early boot, before jumping to the firmware\",\n \"line_number\": 69,\n \"reason\": \"This describes expected software behavior and boot sequence, not an architectural parameter that implementers choose.\"\n }\n ]\n}\n```", + "input_tokens": 7291, + "output_tokens": 540, + "latency_ms": 9735, + "timestamp": "2026-04-15T14:43:25.400747+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_049.json.license b/param_extraction/results/claude-sonnet-4/chunk_049.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_049.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_050.json b/param_extraction/results/claude-sonnet-4/chunk_050.json new file mode 100644 index 0000000000..1c60bef84b --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_050.json @@ -0,0 +1,174 @@ +{ + "chunk_id": "chunk_050", + "source_file": "smstateen.adoc", + "start_line": 1, + "end_line": 373, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.", + "line_number": 127, + "parameter_name": "MSTATEEN_AIA_TYPE", + "existing_udb_name": "MSTATEEN_AIA_TYPE", + "class": "NORM_CSR_RW", + "value_type": "enum", + "confidence": "high", + "reasoning": "Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal." + }, + { + "excerpt": "Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.", + "line_number": 127, + "parameter_name": "MSTATEEN_CONTEXT_TYPE", + "existing_udb_name": "MSTATEEN_CONTEXT_TYPE", + "class": "NORM_CSR_RW", + "value_type": "enum", + "confidence": "high", + "reasoning": "Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal." + }, + { + "excerpt": "Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.", + "line_number": 127, + "parameter_name": "MSTATEEN_CSRIND_TYPE", + "existing_udb_name": "MSTATEEN_CSRIND_TYPE", + "class": "NORM_CSR_RW", + "value_type": "enum", + "confidence": "high", + "reasoning": "Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal." + }, + { + "excerpt": "Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.", + "line_number": 127, + "parameter_name": "MSTATEEN_ENVCFG_TYPE", + "existing_udb_name": "MSTATEEN_ENVCFG_TYPE", + "class": "NORM_CSR_RW", + "value_type": "enum", + "confidence": "high", + "reasoning": "Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal." + }, + { + "excerpt": "Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.", + "line_number": 127, + "parameter_name": "MSTATEEN_IMSIC_TYPE", + "existing_udb_name": "MSTATEEN_IMSIC_TYPE", + "class": "NORM_CSR_RW", + "value_type": "enum", + "confidence": "high", + "reasoning": "Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal." + }, + { + "excerpt": "Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.", + "line_number": 127, + "parameter_name": "MSTATEEN_JVT_TYPE", + "existing_udb_name": "MSTATEEN_JVT_TYPE", + "class": "NORM_CSR_RW", + "value_type": "enum", + "confidence": "high", + "reasoning": "Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal." + }, + { + "excerpt": "Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.", + "line_number": 127, + "parameter_name": "HSTATEEN_AIA_TYPE", + "existing_udb_name": "HSTATEEN_AIA_TYPE", + "class": "NORM_CSR_RW", + "value_type": "enum", + "confidence": "high", + "reasoning": "Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal." + }, + { + "excerpt": "Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.", + "line_number": 127, + "parameter_name": "HSTATEEN_CONTEXT_TYPE", + "existing_udb_name": "HSTATEEN_CONTEXT_TYPE", + "class": "NORM_CSR_RW", + "value_type": "enum", + "confidence": "high", + "reasoning": "Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal." + }, + { + "excerpt": "Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.", + "line_number": 127, + "parameter_name": "HSTATEEN_CSRIND_TYPE", + "existing_udb_name": "HSTATEEN_CSRIND_TYPE", + "class": "NORM_CSR_RW", + "value_type": "enum", + "confidence": "high", + "reasoning": "Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal." + }, + { + "excerpt": "Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.", + "line_number": 127, + "parameter_name": "HSTATEEN_ENVCFG_TYPE", + "existing_udb_name": "HSTATEEN_ENVCFG_TYPE", + "class": "NORM_CSR_RW", + "value_type": "enum", + "confidence": "high", + "reasoning": "Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal." + }, + { + "excerpt": "Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.", + "line_number": 127, + "parameter_name": "HSTATEEN_IMSIC_TYPE", + "existing_udb_name": "HSTATEEN_IMSIC_TYPE", + "class": "NORM_CSR_RW", + "value_type": "enum", + "confidence": "high", + "reasoning": "Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal." + }, + { + "excerpt": "Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.", + "line_number": 127, + "parameter_name": "SSTATEEN_JVT_TYPE", + "existing_udb_name": "SSTATEEN_JVT_TYPE", + "class": "NORM_CSR_RW", + "value_type": "enum", + "confidence": "high", + "reasoning": "Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal." + }, + { + "excerpt": "When a `stateen` CSR prevents access to state for a privilege mode, attempting to execute in that privilege mode an instruction that _implicitly_ updates the state without reading it may or may not raise an illegal-instruction or virtual-instruction exception.", + "line_number": 95, + "parameter_name": "STATEEN_IMPLICIT_UPDATE_EXCEPTION", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "The implementation chooses whether implicit state updates raise exceptions when stateen bits block access. This is a direct implementation choice about exception behavior." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "The requirements that non-standard extensions must meet to be conforming are not relaxed due solely to changes in the value of this bit.", + "line_number": 201, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks." + }, + { + "excerpt": "Setting the IMSIC bit in `hstateen0` to zero prevents a virtual machine from accessing the hart's IMSIC the same as setting `hstatus`.VGEIN = 0.", + "line_number": 244, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks." + }, + { + "excerpt": "When this extension is not implemented, all state added by an extension is accessible as defined by that extension.", + "line_number": 89, + "reason": "This describes what happens when the extension is not implemented - it's a fixed requirement, not an implementation choice." + }, + { + "excerpt": "The C bit controls access to any and all custom state.", + "line_number": 195, + "reason": "This describes the behavior controlled by a CSR bit value, not an implementation parameter. The parameter would be whether the C bit is read-only or read-write." + }, + { + "excerpt": "On reset, all writable `mstateen` bits are initialized by the hardware to zeros.", + "line_number": 142, + "reason": "This is a fixed requirement ('are initialized') that all implementations must satisfy. There is no implementation choice here." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.\",\n \"line_number\": 127,\n \"parameter_name\": \"MSTATEEN_AIA_TYPE\",\n \"existing_udb_name\": \"MSTATEEN_AIA_TYPE\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal.\"\n },\n {\n \"excerpt\": \"Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.\",\n \"line_number\": 127,\n \"parameter_name\": \"MSTATEEN_CONTEXT_TYPE\",\n \"existing_udb_name\": \"MSTATEEN_CONTEXT_TYPE\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal.\"\n },\n {\n \"excerpt\": \"Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.\",\n \"line_number\": 127,\n \"parameter_name\": \"MSTATEEN_CSRIND_TYPE\",\n \"existing_udb_name\": \"MSTATEEN_CSRIND_TYPE\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal.\"\n },\n {\n \"excerpt\": \"Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.\",\n \"line_number\": 127,\n \"parameter_name\": \"MSTATEEN_ENVCFG_TYPE\",\n \"existing_udb_name\": \"MSTATEEN_ENVCFG_TYPE\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal.\"\n },\n {\n \"excerpt\": \"Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.\",\n \"line_number\": 127,\n \"parameter_name\": \"MSTATEEN_IMSIC_TYPE\",\n \"existing_udb_name\": \"MSTATEEN_IMSIC_TYPE\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal.\"\n },\n {\n \"excerpt\": \"Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.\",\n \"line_number\": 127,\n \"parameter_name\": \"MSTATEEN_JVT_TYPE\",\n \"existing_udb_name\": \"MSTATEEN_JVT_TYPE\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal.\"\n },\n {\n \"excerpt\": \"Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.\",\n \"line_number\": 127,\n \"parameter_name\": \"HSTATEEN_AIA_TYPE\",\n \"existing_udb_name\": \"HSTATEEN_AIA_TYPE\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal.\"\n },\n {\n \"excerpt\": \"Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.\",\n \"line_number\": 127,\n \"parameter_name\": \"HSTATEEN_CONTEXT_TYPE\",\n \"existing_udb_name\": \"HSTATEEN_CONTEXT_TYPE\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal.\"\n },\n {\n \"excerpt\": \"Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.\",\n \"line_number\": 127,\n \"parameter_name\": \"HSTATEEN_CSRIND_TYPE\",\n \"existing_udb_name\": \"HSTATEEN_CSRIND_TYPE\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal.\"\n },\n {\n \"excerpt\": \"Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.\",\n \"line_number\": 127,\n \"parameter_name\": \"HSTATEEN_ENVCFG_TYPE\",\n \"existing_udb_name\": \"HSTATEEN_ENVCFG_TYPE\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal.\"\n },\n {\n \"excerpt\": \"Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.\",\n \"line_number\": 127,\n \"parameter_name\": \"HSTATEEN_IMSIC_TYPE\",\n \"existing_udb_name\": \"HSTATEEN_IMSIC_TYPE\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal.\"\n },\n {\n \"excerpt\": \"Each standard-defined bit of a `stateen` CSR is WARL and may be read-only zero or one, subject to the following conditions.\",\n \"line_number\": 127,\n \"parameter_name\": \"SSTATEEN_JVT_TYPE\",\n \"existing_udb_name\": \"SSTATEEN_JVT_TYPE\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"Each bit in stateen CSRs can be read-only zero, read-only one, or read-write. This is a choice about the mutability of CSR fields, not just which values are legal.\"\n },\n {\n \"excerpt\": \"When a `stateen` CSR prevents access to state for a privilege mode, attempting to execute in that privilege mode an instruction that _implicitly_ updates the state without reading it may or may not raise an illegal-instruction or virtual-instruction exception.\",\n \"line_number\": 95,\n \"parameter_name\": \"STATEEN_IMPLICIT_UPDATE_EXCEPTION\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The implementation chooses whether implicit state updates raise exceptions when stateen bits block access. This is a direct implementation choice about exception behavior.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"The requirements that non-standard extensions must meet to be conforming are not relaxed due solely to changes in the value of this bit.\",\n \"line_number\": 201,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks.\"\n },\n {\n \"excerpt\": \"Setting the IMSIC bit in `hstateen0` to zero prevents a virtual machine from accessing the hart's IMSIC the same as setting `hstatus`.VGEIN = 0.\",\n \"line_number\": 244,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks.\"\n },\n {\n \"excerpt\": \"When this extension is not implemented, all state added by an extension is accessible as defined by that extension.\",\n \"line_number\": 89,\n \"reason\": \"This describes what happens when the extension is not implemented - it's a fixed requirement, not an implementation choice.\"\n },\n {\n \"excerpt\": \"The C bit controls access to any and all custom state.\",\n \"line_number\": 195,\n \"reason\": \"This describes the behavior controlled by a CSR bit value, not an implementation parameter. The parameter would be whether the C bit is read-only or read-write.\"\n },\n {\n \"excerpt\": \"On reset, all writable `mstateen` bits are initialized by the hardware to zeros.\",\n \"line_number\": 142,\n \"reason\": \"This is a fixed requirement ('are initialized') that all implementations must satisfy. There is no implementation choice here.\"\n }\n ]\n}\n```", + "input_tokens": 11058, + "output_tokens": 2766, + "latency_ms": 59851, + "timestamp": "2026-04-15T14:44:28.358422+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_050.json.license b/param_extraction/results/claude-sonnet-4/chunk_050.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_050.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_051.json b/param_extraction/results/claude-sonnet-4/chunk_051.json new file mode 100644 index 0000000000..afc7f57c20 --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_051.json @@ -0,0 +1,54 @@ +{ + "chunk_id": "chunk_051", + "source_file": "sscofpmf.adoc", + "start_line": 1, + "end_line": 126, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "For each ``x``INH bit, if the associated privilege mode is not implemented, the bit is read-only zero.", + "line_number": 47, + "parameter_name": "MHPMEVENT_INH_BITS_IMPLEMENTATION", + "existing_udb_name": null, + "class": "NORM_CSR_RW", + "value_type": "bitmask", + "confidence": "high", + "reasoning": "The implementation chooses which privilege modes are supported, which determines whether each INH bit is read-only zero or read-write. This controls the RO/RW nature of specific CSR fields based on architectural choices." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "Note that the new count overflow interrupt will be treated as a standard local interrupt that is assigned to bit 13 in the mip/mie/sip/sie registers.", + "line_number": 24, + "reason": "This is a fixed assignment specification - bit 13 is always used for this interrupt, not an implementation choice." + }, + { + "excerpt": "The OF bit is set when the corresponding hpmcounter overflows, and remains set until written by software.", + "line_number": 53, + "reason": "This describes the required behavior of the OF bit - all implementations must behave this way, not a parameter." + }, + { + "excerpt": "If an hpmcounter overflows while the associated OF bit is zero, then a \"count overflow interrupt request\" is generated.", + "line_number": 60, + "reason": "This describes mandatory behavior when certain conditions are met - not an implementation choice." + }, + { + "excerpt": "There are not separate overflow status and overflow interrupt enable bits.", + "line_number": 82, + "reason": "This text is inside a [NOTE] block and is therefore non-normative informational content." + }, + { + "excerpt": "In M-mode, scountovf bit _X_ is always readable.", + "line_number": 108, + "reason": "This is a fixed requirement that applies to all implementations - M-mode always has read access, not a parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"For each ``x``INH bit, if the associated privilege mode is not implemented, the bit is read-only zero.\",\n \"line_number\": 47,\n \"parameter_name\": \"MHPMEVENT_INH_BITS_IMPLEMENTATION\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"bitmask\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses which privilege modes are supported, which determines whether each INH bit is read-only zero or read-write. This controls the RO/RW nature of specific CSR fields based on architectural choices.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"Note that the new count overflow interrupt will be treated as a standard local interrupt that is assigned to bit 13 in the mip/mie/sip/sie registers.\",\n \"line_number\": 24,\n \"reason\": \"This is a fixed assignment specification - bit 13 is always used for this interrupt, not an implementation choice.\"\n },\n {\n \"excerpt\": \"The OF bit is set when the corresponding hpmcounter overflows, and remains set until written by software.\",\n \"line_number\": 53,\n \"reason\": \"This describes the required behavior of the OF bit - all implementations must behave this way, not a parameter.\"\n },\n {\n \"excerpt\": \"If an hpmcounter overflows while the associated OF bit is zero, then a \\\"count overflow interrupt request\\\" is generated.\",\n \"line_number\": 60,\n \"reason\": \"This describes mandatory behavior when certain conditions are met - not an implementation choice.\"\n },\n {\n \"excerpt\": \"There are not separate overflow status and overflow interrupt enable bits.\",\n \"line_number\": 82,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative informational content.\"\n },\n {\n \"excerpt\": \"In M-mode, scountovf bit _X_ is always readable.\",\n \"line_number\": 108,\n \"reason\": \"This is a fixed requirement that applies to all implementations - M-mode always has read access, not a parameter.\"\n }\n ]\n}\n```", + "input_tokens": 7226, + "output_tokens": 564, + "latency_ms": 22359, + "timestamp": "2026-04-15T14:44:53.758617+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_051.json.license b/param_extraction/results/claude-sonnet-4/chunk_051.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_051.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_052.json b/param_extraction/results/claude-sonnet-4/chunk_052.json new file mode 100644 index 0000000000..c6921cf2c1 --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_052.json @@ -0,0 +1,38 @@ +{ + "chunk_id": "chunk_052", + "source_file": "ssdbltrp.adoc", + "start_line": 1, + "end_line": 15, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [], + "skipped_non_parameters": [ + { + "excerpt": "It enables HS-mode to invoke a critical error handler in a virtual machine on a double trap in VS-mode.", + "line_number": 5, + "reason": "This describes the functionality/purpose of the extension, not an implementation choice. All implementations of Ssdbltrp must provide this capability." + }, + { + "excerpt": "It also allows M-mode to invoke a critical error handler in the OS/Hypervisor on a double trap in S/HS-mode.", + "line_number": 6, + "reason": "This describes required functionality of the extension, not a parameter. The behavior is fixed for all implementations." + }, + { + "excerpt": "The Ssdbltrp extension adds the `menvcfg`.DTE", + "line_number": 10, + "reason": "This states that the extension adds a CSR field, which is a fixed requirement. It doesn't specify any implementation choices about the field's behavior or legal values." + }, + { + "excerpt": "If the hypervisor extension is additionally implemented, then the extension adds the `henvcfg`.DTE", + "line_number": 11, + "reason": "This is a conditional requirement based on hypervisor extension presence, but not an implementation choice. If H-ext is present, these fields must be added." + } + ], + "raw_response": "```json\n{\n \"parameters\": [],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"It enables HS-mode to invoke a critical error handler in a virtual machine on a double trap in VS-mode.\",\n \"line_number\": 5,\n \"reason\": \"This describes the functionality/purpose of the extension, not an implementation choice. All implementations of Ssdbltrp must provide this capability.\"\n },\n {\n \"excerpt\": \"It also allows M-mode to invoke a critical error handler in the OS/Hypervisor on a double trap in S/HS-mode.\",\n \"line_number\": 6,\n \"reason\": \"This describes required functionality of the extension, not a parameter. The behavior is fixed for all implementations.\"\n },\n {\n \"excerpt\": \"The Ssdbltrp extension adds the `menvcfg`.DTE\",\n \"line_number\": 10,\n \"reason\": \"This states that the extension adds a CSR field, which is a fixed requirement. It doesn't specify any implementation choices about the field's behavior or legal values.\"\n },\n {\n \"excerpt\": \"If the hypervisor extension is additionally implemented, then the extension adds the `henvcfg`.DTE\",\n \"line_number\": 11,\n \"reason\": \"This is a conditional requirement based on hypervisor extension presence, but not an implementation choice. If H-ext is present, these fields must be added.\"\n }\n ]\n}\n```", + "input_tokens": 5888, + "output_tokens": 357, + "latency_ms": 7002, + "timestamp": "2026-04-15T15:02:03.742495+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_052.json.license b/param_extraction/results/claude-sonnet-4/chunk_052.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_052.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_053.json b/param_extraction/results/claude-sonnet-4/chunk_053.json new file mode 100644 index 0000000000..d873d324c7 --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_053.json @@ -0,0 +1,38 @@ +{ + "chunk_id": "chunk_053", + "source_file": "sstc.adoc", + "start_line": 1, + "end_line": 24, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [], + "skipped_non_parameters": [ + { + "excerpt": "The current Privileged arch specification only defines a hardware mechanism for generating machine-mode timer interrupts (based on the mtime and mtimecmp registers).", + "line_number": 4, + "reason": "This describes the existing specification requirements, not an implementation choice." + }, + { + "excerpt": "This extension serves to provide supervisor mode with its own CSR-based timer interrupt facility that it can directly manage to provide its own timer service", + "line_number": 13, + "reason": "This describes the purpose and functionality of the extension, not an implementation-defined parameter." + }, + { + "excerpt": "This extension adds the S-level `stimecmp` CSR (<>) and the VS-level `vstimecmp` CSR (<>).", + "line_number": 21, + "reason": "This states what CSRs are added by the extension, which is a fixed requirement, not an implementation choice." + }, + { + "excerpt": "This extension adds the `STCE` bit to the `menvcfg` (<>) and `henvcfg` (<>) CSRs.", + "line_number": 22, + "reason": "This describes what bits are added to existing CSRs, which is a specification requirement, not a parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"The current Privileged arch specification only defines a hardware mechanism for generating machine-mode timer interrupts (based on the mtime and mtimecmp registers).\",\n \"line_number\": 4,\n \"reason\": \"This describes the existing specification requirements, not an implementation choice.\"\n },\n {\n \"excerpt\": \"This extension serves to provide supervisor mode with its own CSR-based timer interrupt facility that it can directly manage to provide its own timer service\",\n \"line_number\": 13,\n \"reason\": \"This describes the purpose and functionality of the extension, not an implementation-defined parameter.\"\n },\n {\n \"excerpt\": \"This extension adds the S-level `stimecmp` CSR (<>) and the VS-level `vstimecmp` CSR (<>).\",\n \"line_number\": 21,\n \"reason\": \"This states what CSRs are added by the extension, which is a fixed requirement, not an implementation choice.\"\n },\n {\n \"excerpt\": \"This extension adds the `STCE` bit to the `menvcfg` (<>) and `henvcfg` (<>) CSRs.\",\n \"line_number\": 22,\n \"reason\": \"This describes what bits are added to existing CSRs, which is a specification requirement, not a parameter.\"\n }\n ]\n}\n```", + "input_tokens": 5983, + "output_tokens": 372, + "latency_ms": 5912, + "timestamp": "2026-04-15T14:45:11.654133+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_053.json.license b/param_extraction/results/claude-sonnet-4/chunk_053.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_053.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_054.json b/param_extraction/results/claude-sonnet-4/chunk_054.json new file mode 100644 index 0000000000..18c91b40bf --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_054.json @@ -0,0 +1,259 @@ +{ + "chunk_id": "chunk_054", + "source_file": "supervisor.adoc", + "start_line": 1, + "end_line": 2630, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "When SXLEN=64, it is a *WARL* field that encodes the current value of UXLEN. In particular, an implementation may make UXL be a read-only field whose value always ensures that UXLEN=SXLEN.", + "line_number": 119, + "parameter_name": "SSTATUS_UXL_LEGAL_VALUES", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "The UXL field is WARL and implementations may make it read-only or allow different values. The parameter is the set of legal UXL values the implementation supports." + }, + { + "excerpt": "When such a HINT is executed with XLEN < SXLEN and bits SXLEN..XLEN of the destination register not all equal to bit XLEN-1, it is implementation-defined whether bits SXLEN..XLEN of the destination register are unchanged or are overwritten with copies of bit XLEN-1.", + "line_number": 133, + "parameter_name": "HINT_SXLEN_PARAM", + "existing_udb_name": "HINT_SXLEN_PARAM", + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "Implementation-defined choice of whether to preserve or sign-extend upper bits in HINT instructions when XLEN < SXLEN. This is a direct architectural choice." + }, + { + "excerpt": "SUM is read-only 0 if `satp`.MODE is read-only 0.", + "line_number": 169, + "parameter_name": "SSTATUS_SUM_ACCESS", + "existing_udb_name": null, + "class": "NORM_CSR_RW", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether SUM is read-only zero or read-write, depending on whether satp.MODE is read-only zero. This controls the mutability of the SUM field." + }, + { + "excerpt": "The UBE bit is a *WARL* field that controls the endianness of explicit memory accesses made from U-mode, which may differ from the endianness of memory accesses in S-mode. An implementation may make UBE be a read-only field that always specifies the same endianness as for S-mode.", + "line_number": 194, + "parameter_name": "U_MODE_ENDIANNESS", + "existing_udb_name": "U_MODE_ENDIANNESS", + "class": "NORM_CSR_RW", + "value_type": "enum", + "confidence": "high", + "reasoning": "The UBE field can be read-only-0 (little-endian), read-only-1 (big-endian), or read-write (dynamic). This controls the RO/RW nature and legal values of the endianness field." + }, + { + "excerpt": "The S-mode-disable-trap (`SDT`) bit is a WARL field introduced by the Ssdbltrp extension", + "line_number": 218, + "parameter_name": "SSTATUS_SDT_LEGAL_VALUES", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "medium", + "reasoning": "SDT is described as a WARL field, meaning implementations can restrict which values are legal. The parameter would be the set of supported values." + }, + { + "excerpt": "When MODE=Vectored, all synchronous exceptions into supervisor mode cause the `pc` to be set to the address in the BASE field, whereas interrupts cause the `pc` to be set to the address in the BASE field plus four times the interrupt cause number.", + "line_number": 295, + "parameter_name": "STVEC_MODE_VECTORED", + "existing_udb_name": "STVEC_MODE_VECTORED", + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "Implementation choice of whether to support Vectored mode in stvec. The text shows this is an optional mode (value 1 in the encoding table)." + }, + { + "excerpt": "Each individual bit in register `sip` may be writable or may be read-only.", + "line_number": 334, + "parameter_name": "SIP_BITS_ACCESS", + "existing_udb_name": null, + "class": "NORM_CSR_RW", + "value_type": "bitmask", + "confidence": "high", + "reasoning": "Each bit in sip can independently be writable or read-only. This is a per-bit RW/RO choice for the register." + }, + { + "excerpt": "A bit in `sie` must be writable if the corresponding interrupt can ever become pending. Bits of `sie` that are not writable are read-only zero.", + "line_number": 341, + "parameter_name": "SIE_BITS_ACCESS", + "existing_udb_name": null, + "class": "NORM_CSR_RW", + "value_type": "bitmask", + "confidence": "high", + "reasoning": "Each bit in sie can be writable or read-only zero, depending on whether the corresponding interrupt can become pending. This is a per-bit RW/RO choice." + }, + { + "excerpt": "Each standard interrupt type (SEI, STI, SSI, or LCOFI) may not be implemented, in which case the corresponding interrupt-pending and interrupt-enable bits are read-only zeros. All bits in `sip` and `sie` are *WARL* fields.", + "line_number": 408, + "parameter_name": "SIP_SIE_INTERRUPT_SUPPORT", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "Implementation chooses which standard interrupt types to implement. The WARL nature means the set of legal values varies by implementation based on which interrupts are supported." + }, + { + "excerpt": "`scounteren` must be implemented. However, any of the bits may be read-only zero, indicating reads to the corresponding counter will cause an exception when executing in U-mode. Hence, they are effectively *WARL* fields.", + "line_number": 448, + "parameter_name": "SCOUNTEREN_BITS_ACCESS", + "existing_udb_name": null, + "class": "NORM_CSR_RW", + "value_type": "bitmask", + "confidence": "high", + "reasoning": "Each bit in scounteren can be writable or read-only zero. This controls whether U-mode can access the corresponding counter, making it a per-bit RW/RO choice." + }, + { + "excerpt": "`sepc` is a *WARL* register that must be able to hold all valid virtual addresses. It need not be capable of holding all possible invalid addresses.", + "line_number": 485, + "parameter_name": "SEPC_WARL_VALUES", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "medium", + "reasoning": "sepc is WARL and need not hold all possible invalid addresses. The parameter is the set of addresses sepc can hold, which may exclude some invalid addresses." + }, + { + "excerpt": "The Exception Code is a *WLRL* field. It is required to hold the values 0\u201331 (i.e., bits 4\u20130 must be implemented), but otherwise it is only guaranteed to hold supported exception codes.", + "line_number": 508, + "parameter_name": "SCAUSE_EXCEPTION_CODE_LEGAL_VALUES", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "The Exception Code field is WLRL and only guaranteed to hold supported exception codes beyond the required 0-31 range. The parameter is the set of legal exception codes." + }, + { + "excerpt": "`stval` is a *WARL* register that must be able to hold all valid virtual addresses and the value 0. It need not be capable of holding all possible invalid addresses.", + "line_number": 618, + "parameter_name": "STVAL_WARL_VALUES", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "medium", + "reasoning": "stval is WARL and need not hold all possible invalid addresses. The parameter is the set of values stval can hold, which may exclude some invalid addresses." + }, + { + "excerpt": "If `satp`.MODE is read-only zero (always Bare), the implementation may make FIOM read-only zero.", + "line_number": 665, + "parameter_name": "SENVCFG_FIOM_ACCESS", + "existing_udb_name": null, + "class": "NORM_CSR_RW", + "value_type": "binary", + "confidence": "high", + "reasoning": "Implementation choice of whether FIOM is read-only zero or read-write, depending on satp.MODE support. This controls the mutability of the FIOM field." + }, + { + "excerpt": "The `CBIE` (Cache Block Invalidate instruction Enable) WARL field to `senvcfg` to control execution of the `CBO.INVAL` instruction in U-mode.", + "line_number": 720, + "parameter_name": "SENVCFG_CBIE_LEGAL_VALUES", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "CBIE is explicitly described as a WARL field, meaning implementations can restrict which values are legal. The parameter is the set of supported CBIE values." + }, + { + "excerpt": "If the Ssnpm extension is implemented, the `PMM` field enables or disables pointer masking (see <>) for the next-lower privilege mode (U/VU), according to the values in <>. If Ssnpm is not implemented, `PMM` is read-only zero.", + "line_number": 738, + "parameter_name": "SENVCFG_PMM_LEGAL_VALUES", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "PMM field has specific legal values defined in a table, and is read-only zero if Ssnpm is not implemented. This is a WARL field with implementation-defined legal values." + }, + { + "excerpt": "Implementations are not required to support all MODE settings, and if `satp` is written with an unsupported MODE, the entire write has no effect; no fields in `satp` are modified.", + "line_number": 825, + "parameter_name": "SATP_MODE_SUPPORT", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "Implementations choose which satp MODE values to support. Unsupported modes cause writes to have no effect, making this a WARL field with implementation-defined legal values." + }, + { + "excerpt": "The number of ASID bits is UNSPECIFIED and may be zero. The number of implemented ASID bits, termed _ASIDLEN_, may be determined by writing one to every bit position in the ASID field, then reading back the value in `satp` to see which bit positions in the ASID field hold a one.", + "line_number": 831, + "parameter_name": "ASID_WIDTH", + "existing_udb_name": "ASID_WIDTH", + "class": "NORM_DIRECT", + "value_type": "range", + "confidence": "high", + "reasoning": "ASIDLEN is implementation-defined and can range from 0 to ASIDMAX (9 for Sv32, 16 for others). This is a direct implementation choice of how many ASID bits to implement." + }, + { + "excerpt": "For implementations that make `satp`.MODE read-only zero (always Bare), attempts to execute an SFENCE.VMA instruction might raise an illegal-instruction exception.", + "line_number": 1169, + "parameter_name": "TRAP_ON_SFENCE_VMA_WHEN_SATP_MODE_IS_READ_ONLY", + "existing_udb_name": "TRAP_ON_SFENCE_VMA_WHEN_SATP_MODE_IS_READ_ONLY", + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "Implementation choice of whether to trap on SFENCE.VMA when satp.MODE is read-only zero. The word 'might' indicates this is optional behavior." + }, + { + "excerpt": "The 20-bit VPN is translated into a 22-bit physical page number (PPN)", + "line_number": 1207, + "parameter_name": "SATP_PPN_SV32_SIZE", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "The PPN size for Sv32 is specified as 22 bits. This is a fixed architectural parameter for Sv32 implementations." + }, + { + "excerpt": "The 27-bit VPN is translated into a 44-bit PPN via a three-level page table", + "line_number": 1598, + "parameter_name": "SATP_PPN_SV39_SV48_SV57_SIZE", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "The PPN size for Sv39, Sv48, and Sv57 is specified as 44 bits. This is a fixed architectural parameter for these implementations." + }, + { + "excerpt": "Both `RCID` and `MCID` are WARL fields.", + "line_number": 2583, + "parameter_name": "SRMCFG_RCID_MCID_LEGAL_VALUES", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "Both RCID and MCID fields in srmcfg are explicitly described as WARL, meaning implementations can restrict which values are legal for each field." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "Supervisor mode is deliberately restricted in terms of interactions with underlying physical hardware, such as physical memory and device interrupts, to support clean virtualization.", + "line_number": 8, + "reason": "This is in a [NOTE] block, which is non-normative. Parameters are never extracted from NOTE blocks." + }, + { + "excerpt": "When a trap is taken, SPP is set to 0 if the trap originated from user mode, or 1 otherwise.", + "line_number": 77, + "reason": "This describes fixed behavior that occurs when a trap is taken. It is not an implementation choice but a required specification." + }, + { + "excerpt": "When MODE=Direct, all traps into supervisor mode cause the `pc` to be set to the address in the BASE field.", + "line_number": 293, + "reason": "This describes what happens when stvec.MODE has a specific value. The behavior is determined by the CSR field value at runtime, not by an implementation choice." + }, + { + "excerpt": "Software may determine the PMP granularity by writing zero to `pmp0cfg`, then writing all ones to `pmpaddr0`, then reading back `pmpaddr0`.", + "line_number": 831, + "reason": "Here 'may' means 'is allowed to' (permission), not 'might or might not' (optionality). This describes a software technique, not an implementation-defined parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"When SXLEN=64, it is a *WARL* field that encodes the current value of UXLEN. In particular, an implementation may make UXL be a read-only field whose value always ensures that UXLEN=SXLEN.\",\n \"line_number\": 119,\n \"parameter_name\": \"SSTATUS_UXL_LEGAL_VALUES\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"The UXL field is WARL and implementations may make it read-only or allow different values. The parameter is the set of legal UXL values the implementation supports.\"\n },\n {\n \"excerpt\": \"When such a HINT is executed with XLEN < SXLEN and bits SXLEN..XLEN of the destination register not all equal to bit XLEN-1, it is implementation-defined whether bits SXLEN..XLEN of the destination register are unchanged or are overwritten with copies of bit XLEN-1.\",\n \"line_number\": 133,\n \"parameter_name\": \"HINT_SXLEN_PARAM\",\n \"existing_udb_name\": \"HINT_SXLEN_PARAM\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"Implementation-defined choice of whether to preserve or sign-extend upper bits in HINT instructions when XLEN < SXLEN. This is a direct architectural choice.\"\n },\n {\n \"excerpt\": \"SUM is read-only 0 if `satp`.MODE is read-only 0.\",\n \"line_number\": 169,\n \"parameter_name\": \"SSTATUS_SUM_ACCESS\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether SUM is read-only zero or read-write, depending on whether satp.MODE is read-only zero. This controls the mutability of the SUM field.\"\n },\n {\n \"excerpt\": \"The UBE bit is a *WARL* field that controls the endianness of explicit memory accesses made from U-mode, which may differ from the endianness of memory accesses in S-mode. An implementation may make UBE be a read-only field that always specifies the same endianness as for S-mode.\",\n \"line_number\": 194,\n \"parameter_name\": \"U_MODE_ENDIANNESS\",\n \"existing_udb_name\": \"U_MODE_ENDIANNESS\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"The UBE field can be read-only-0 (little-endian), read-only-1 (big-endian), or read-write (dynamic). This controls the RO/RW nature and legal values of the endianness field.\"\n },\n {\n \"excerpt\": \"The S-mode-disable-trap (`SDT`) bit is a WARL field introduced by the Ssdbltrp extension\",\n \"line_number\": 218,\n \"parameter_name\": \"SSTATUS_SDT_LEGAL_VALUES\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"medium\",\n \"reasoning\": \"SDT is described as a WARL field, meaning implementations can restrict which values are legal. The parameter would be the set of supported values.\"\n },\n {\n \"excerpt\": \"When MODE=Vectored, all synchronous exceptions into supervisor mode cause the `pc` to be set to the address in the BASE field, whereas interrupts cause the `pc` to be set to the address in the BASE field plus four times the interrupt cause number.\",\n \"line_number\": 295,\n \"parameter_name\": \"STVEC_MODE_VECTORED\",\n \"existing_udb_name\": \"STVEC_MODE_VECTORED\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"Implementation choice of whether to support Vectored mode in stvec. The text shows this is an optional mode (value 1 in the encoding table).\"\n },\n {\n \"excerpt\": \"Each individual bit in register `sip` may be writable or may be read-only.\",\n \"line_number\": 334,\n \"parameter_name\": \"SIP_BITS_ACCESS\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"bitmask\",\n \"confidence\": \"high\",\n \"reasoning\": \"Each bit in sip can independently be writable or read-only. This is a per-bit RW/RO choice for the register.\"\n },\n {\n \"excerpt\": \"A bit in `sie` must be writable if the corresponding interrupt can ever become pending. Bits of `sie` that are not writable are read-only zero.\",\n \"line_number\": 341,\n \"parameter_name\": \"SIE_BITS_ACCESS\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"bitmask\",\n \"confidence\": \"high\",\n \"reasoning\": \"Each bit in sie can be writable or read-only zero, depending on whether the corresponding interrupt can become pending. This is a per-bit RW/RO choice.\"\n },\n {\n \"excerpt\": \"Each standard interrupt type (SEI, STI, SSI, or LCOFI) may not be implemented, in which case the corresponding interrupt-pending and interrupt-enable bits are read-only zeros. All bits in `sip` and `sie` are *WARL* fields.\",\n \"line_number\": 408,\n \"parameter_name\": \"SIP_SIE_INTERRUPT_SUPPORT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"Implementation chooses which standard interrupt types to implement. The WARL nature means the set of legal values varies by implementation based on which interrupts are supported.\"\n },\n {\n \"excerpt\": \"`scounteren` must be implemented. However, any of the bits may be read-only zero, indicating reads to the corresponding counter will cause an exception when executing in U-mode. Hence, they are effectively *WARL* fields.\",\n \"line_number\": 448,\n \"parameter_name\": \"SCOUNTEREN_BITS_ACCESS\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"bitmask\",\n \"confidence\": \"high\",\n \"reasoning\": \"Each bit in scounteren can be writable or read-only zero. This controls whether U-mode can access the corresponding counter, making it a per-bit RW/RO choice.\"\n },\n {\n \"excerpt\": \"`sepc` is a *WARL* register that must be able to hold all valid virtual addresses. It need not be capable of holding all possible invalid addresses.\",\n \"line_number\": 485,\n \"parameter_name\": \"SEPC_WARL_VALUES\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"medium\",\n \"reasoning\": \"sepc is WARL and need not hold all possible invalid addresses. The parameter is the set of addresses sepc can hold, which may exclude some invalid addresses.\"\n },\n {\n \"excerpt\": \"The Exception Code is a *WLRL* field. It is required to hold the values 0\u201331 (i.e., bits 4\u20130 must be implemented), but otherwise it is only guaranteed to hold supported exception codes.\",\n \"line_number\": 508,\n \"parameter_name\": \"SCAUSE_EXCEPTION_CODE_LEGAL_VALUES\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"The Exception Code field is WLRL and only guaranteed to hold supported exception codes beyond the required 0-31 range. The parameter is the set of legal exception codes.\"\n },\n {\n \"excerpt\": \"`stval` is a *WARL* register that must be able to hold all valid virtual addresses and the value 0. It need not be capable of holding all possible invalid addresses.\",\n \"line_number\": 618,\n \"parameter_name\": \"STVAL_WARL_VALUES\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"medium\",\n \"reasoning\": \"stval is WARL and need not hold all possible invalid addresses. The parameter is the set of values stval can hold, which may exclude some invalid addresses.\"\n },\n {\n \"excerpt\": \"If `satp`.MODE is read-only zero (always Bare), the implementation may make FIOM read-only zero.\",\n \"line_number\": 665,\n \"parameter_name\": \"SENVCFG_FIOM_ACCESS\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"Implementation choice of whether FIOM is read-only zero or read-write, depending on satp.MODE support. This controls the mutability of the FIOM field.\"\n },\n {\n \"excerpt\": \"The `CBIE` (Cache Block Invalidate instruction Enable) WARL field to `senvcfg` to control execution of the `CBO.INVAL` instruction in U-mode.\",\n \"line_number\": 720,\n \"parameter_name\": \"SENVCFG_CBIE_LEGAL_VALUES\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"CBIE is explicitly described as a WARL field, meaning implementations can restrict which values are legal. The parameter is the set of supported CBIE values.\"\n },\n {\n \"excerpt\": \"If the Ssnpm extension is implemented, the `PMM` field enables or disables pointer masking (see <>) for the next-lower privilege mode (U/VU), according to the values in <>. If Ssnpm is not implemented, `PMM` is read-only zero.\",\n \"line_number\": 738,\n \"parameter_name\": \"SENVCFG_PMM_LEGAL_VALUES\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"PMM field has specific legal values defined in a table, and is read-only zero if Ssnpm is not implemented. This is a WARL field with implementation-defined legal values.\"\n },\n {\n \"excerpt\": \"Implementations are not required to support all MODE settings, and if `satp` is written with an unsupported MODE, the entire write has no effect; no fields in `satp` are modified.\",\n \"line_number\": 825,\n \"parameter_name\": \"SATP_MODE_SUPPORT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"Implementations choose which satp MODE values to support. Unsupported modes cause writes to have no effect, making this a WARL field with implementation-defined legal values.\"\n },\n {\n \"excerpt\": \"The number of ASID bits is UNSPECIFIED and may be zero. The number of implemented ASID bits, termed _ASIDLEN_, may be determined by writing one to every bit position in the ASID field, then reading back the value in `satp` to see which bit positions in the ASID field hold a one.\",\n \"line_number\": 831,\n \"parameter_name\": \"ASID_WIDTH\",\n \"existing_udb_name\": \"ASID_WIDTH\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"range\",\n \"confidence\": \"high\",\n \"reasoning\": \"ASIDLEN is implementation-defined and can range from 0 to ASIDMAX (9 for Sv32, 16 for others). This is a direct implementation choice of how many ASID bits to implement.\"\n },\n {\n \"excerpt\": \"For implementations that make `satp`.MODE read-only zero (always Bare), attempts to execute an SFENCE.VMA instruction might raise an illegal-instruction exception.\",\n \"line_number\": 1169,\n \"parameter_name\": \"TRAP_ON_SFENCE_VMA_WHEN_SATP_MODE_IS_READ_ONLY\",\n \"existing_udb_name\": \"TRAP_ON_SFENCE_VMA_WHEN_SATP_MODE_IS_READ_ONLY\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"Implementation choice of whether to trap on SFENCE.VMA when satp.MODE is read-only zero. The word 'might' indicates this is optional behavior.\"\n },\n {\n \"excerpt\": \"The 20-bit VPN is translated into a 22-bit physical page number (PPN)\",\n \"line_number\": 1207,\n \"parameter_name\": \"SATP_PPN_SV32_SIZE\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"The PPN size for Sv32 is specified as 22 bits. This is a fixed architectural parameter for Sv32 implementations.\"\n },\n {\n \"excerpt\": \"The 27-bit VPN is translated into a 44-bit PPN via a three-level page table\",\n \"line_number\": 1598,\n \"parameter_name\": \"SATP_PPN_SV39_SV48_SV57_SIZE\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"The PPN size for Sv39, Sv48, and Sv57 is specified as 44 bits. This is a fixed architectural parameter for these implementations.\"\n },\n {\n \"excerpt\": \"Both `RCID` and `MCID` are WARL fields.\",\n \"line_number\": 2583,\n \"parameter_name\": \"SRMCFG_RCID_MCID_LEGAL_VALUES\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"Both RCID and MCID fields in srmcfg are explicitly described as WARL, meaning implementations can restrict which values are legal for each field.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"Supervisor mode is deliberately restricted in terms of interactions with underlying physical hardware, such as physical memory and device interrupts, to support clean virtualization.\",\n \"line_number\": 8,\n \"reason\": \"This is in a [NOTE] block, which is non-normative. Parameters are never extracted from NOTE blocks.\"\n },\n {\n \"excerpt\": \"When a trap is taken, SPP is set to 0 if the trap originated from user mode, or 1 otherwise.\",\n \"line_number\": 77,\n \"reason\": \"This describes fixed behavior that occurs when a trap is taken. It is not an implementation choice but a required specification.\"\n },\n {\n \"excerpt\": \"When MODE=Direct, all traps into supervisor mode cause the `pc` to be set to the address in the BASE field.\",\n \"line_number\": 293,\n \"reason\": \"This describes what happens when stvec.MODE has a specific value. The behavior is determined by the CSR field value at runtime, not by an implementation choice.\"\n },\n {\n \"excerpt\": \"Software may determine the PMP granularity by writing zero to `pmp0cfg`, then writing all ones to `pmpaddr0`, then reading back `pmpaddr0`.\",\n \"line_number\": 831,\n \"reason\": \"Here 'may' means 'is allowed to' (permission), not 'might or might not' (optionality). This describes a software technique, not an implementation-defined parameter.\"\n }\n ]\n}\n```", + "input_tokens": 37814, + "output_tokens": 4322, + "latency_ms": 152841, + "timestamp": "2026-04-15T14:48:26.174107+00:00", + "error": null, + "retry_count": 1 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_054.json.license b/param_extraction/results/claude-sonnet-4/chunk_054.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_054.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_056.json b/param_extraction/results/claude-sonnet-4/chunk_056.json new file mode 100644 index 0000000000..40270fe73b --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_056.json @@ -0,0 +1,144 @@ +{ + "chunk_id": "chunk_056", + "source_file": "unpriv-cfi.adoc", + "start_line": 1, + "end_line": 894, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "The Zicfilp extension, when enabled, determines if an indirect call or an indirect jump must land on a landing pad, as specified in <>. If `is_lp_expected` is 1, then the hart updates the `ELP` to `LP_EXPECTED`.", + "line_number": 158, + "parameter_name": "ZICFILP_ENABLED", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether to enable the Zicfilp extension. This is a direct implementation choice that affects whether landing pad enforcement is active." + }, + { + "excerpt": "The `LPAD` instruction (See <>) is encoded using the `AUIPC` major opcode with _rd_=`x0`.", + "line_number": 73, + "parameter_name": "LPAD_ENCODING", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "This defines the specific encoding choice for the LPAD instruction using AUIPC with rd=x0. This is a normative encoding decision." + }, + { + "excerpt": "To support labeled landing pads, the indirect call/jump sites establish an expected landing pad label (e.g., using the `LUI` instruction) in the bits 31:12 of the `x7` register.", + "line_number": 200, + "parameter_name": "LPAD_LABEL_SUPPORT", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "The implementation may choose whether to support labeled landing pads. The text describes the mechanism but doesn't explicitly state it's optional, though the context suggests it's an implementation choice." + }, + { + "excerpt": "The `LPAD` instruction is encoded with a 20-bit immediate value called the landing-pad-label (`LPL`) that is matched to the expected landing pad label. When `LPL` is encoded as zero, the `LPAD` instruction does not perform the label check and in programs built with this single label mode of operation the indirect call/jump sites do not need to establish an expected landing pad label value in `x7`.", + "line_number": 202, + "parameter_name": "LPAD_LPL_ENCODING", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "This defines how the 20-bit landing pad label is encoded in the LPAD instruction. The encoding format is a normative implementation detail." + }, + { + "excerpt": "When Zicfilp is enabled, `LPAD` is the only instruction allowed to execute when the `ELP` state is `LP_EXPECTED`. If Zicfilp is not enabled then the instruction is a no-op.", + "line_number": 235, + "parameter_name": "LPAD_EXECUTION_CONTROL", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "This defines the normative behavior of LPAD instruction execution based on whether Zicfilp is enabled. The implementation controls this behavior." + }, + { + "excerpt": "The Zicfiss instructions, except `SSAMOSWAP.W/D`, are encoded using a subset of May-Be-Operation instructions defined by the Zimop and Zcmop extensions.", + "line_number": 334, + "parameter_name": "ZICFISS_ENCODING_SCHEME", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "high", + "reasoning": "This defines the encoding scheme choice for Zicfiss instructions, using Zimop/Zcmop encodings. This is a normative encoding decision." + }, + { + "excerpt": "The `ssp` CSR is an unprivileged read-write (URW) CSR that reads and writes `XLEN` low order bits of the shadow stack pointer (`ssp`).", + "line_number": 378, + "parameter_name": "SSP_CSR_ACCESS", + "existing_udb_name": null, + "class": "NORM_CSR_RW", + "value_type": "binary", + "confidence": "high", + "reasoning": "This defines that the ssp CSR is read-write. The implementation could potentially make it read-only, making this a CSR access control parameter." + }, + { + "excerpt": "The CSR address is 0x011.", + "line_number": 379, + "parameter_name": "SSP_CSR_ADDRESS", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "This defines the specific CSR address for the ssp register. This is a normative addressing choice." + }, + { + "excerpt": "There is no high CSR defined as the `ssp` is always as wide as the `XLEN` of the current privilege mode.", + "line_number": 380, + "parameter_name": "SSP_CSR_WIDTH", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "This defines that ssp width matches XLEN with no high CSR. This is a normative width decision." + }, + { + "excerpt": "The bits 1:0 of `ssp` are read-only zero. If the UXLEN or SXLEN may never be 32, then the bit 2 is also read-only zero.", + "line_number": 381, + "parameter_name": "SSP_LOW_BITS_RO", + "existing_udb_name": null, + "class": "NORM_CSR_RW", + "value_type": "bitmask", + "confidence": "high", + "reasoning": "This defines which low-order bits of ssp are read-only zero, with bit 2 being conditionally read-only based on XLEN support. This is a CSR field access control parameter." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "Control-flow Integrity (CFI) capabilities help defend against Return-Oriented Programming (ROP) and Call/Jump-Oriented Programming (COP/JOP) style control-flow subversion attacks.", + "line_number": 3, + "reason": "This is descriptive text explaining what CFI does, not an implementation choice or parameter." + }, + { + "excerpt": "The term _call_ is used to refer to a `JAL` or `JALR` instruction with a link register as destination, i.e., _rd_\u2260`x0`.", + "line_number": 37, + "reason": "This is a definition of terminology, not an implementation parameter. It defines what the spec means by 'call'." + }, + { + "excerpt": "When `ELP` is set to `LP_EXPECTED`, if the next instruction in the instruction stream is not 4-byte aligned, or is not `LPAD`, or if the landing pad label encoded in `LPAD` is not zero and does not match the expected landing pad label in bits 31:12 of the `x7` register, then a software-check exception (cause=18) with `__x__tval` set to \"landing pad fault (code=2)\" is raised else the `ELP` is updated to `NO_LP_EXPECTED`.", + "line_number": 207, + "reason": "This describes the behavioral consequences when ELP is LP_EXPECTED. It's describing what happens given a state, not defining an implementation choice." + }, + { + "excerpt": "When Zicfiss is enabled, each function that needs to spill the link register, typically non-leaf functions, store the link register value to the regular stack and a shadow copy of the link register value to the shadow stack when the function is entered (the prologue).", + "line_number": 310, + "reason": "This describes software behavior and programming conventions when using Zicfiss, not an architectural implementation parameter." + }, + { + "excerpt": "The `ssp` is decremented by `SSPUSH` and `C.SSPUSH` only if the store to the shadow stack completes successfully.", + "line_number": 456, + "reason": "This describes the operational behavior of the SSPUSH instruction - what happens during execution, not an implementation choice." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"The Zicfilp extension, when enabled, determines if an indirect call or an indirect jump must land on a landing pad, as specified in <>. If `is_lp_expected` is 1, then the hart updates the `ELP` to `LP_EXPECTED`.\",\n \"line_number\": 158,\n \"parameter_name\": \"ZICFILP_ENABLED\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether to enable the Zicfilp extension. This is a direct implementation choice that affects whether landing pad enforcement is active.\"\n },\n {\n \"excerpt\": \"The `LPAD` instruction (See <>) is encoded using the `AUIPC` major opcode with _rd_=`x0`.\",\n \"line_number\": 73,\n \"parameter_name\": \"LPAD_ENCODING\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"This defines the specific encoding choice for the LPAD instruction using AUIPC with rd=x0. This is a normative encoding decision.\"\n },\n {\n \"excerpt\": \"To support labeled landing pads, the indirect call/jump sites establish an expected landing pad label (e.g., using the `LUI` instruction) in the bits 31:12 of the `x7` register.\",\n \"line_number\": 200,\n \"parameter_name\": \"LPAD_LABEL_SUPPORT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The implementation may choose whether to support labeled landing pads. The text describes the mechanism but doesn't explicitly state it's optional, though the context suggests it's an implementation choice.\"\n },\n {\n \"excerpt\": \"The `LPAD` instruction is encoded with a 20-bit immediate value called the landing-pad-label (`LPL`) that is matched to the expected landing pad label. When `LPL` is encoded as zero, the `LPAD` instruction does not perform the label check and in programs built with this single label mode of operation the indirect call/jump sites do not need to establish an expected landing pad label value in `x7`.\",\n \"line_number\": 202,\n \"parameter_name\": \"LPAD_LPL_ENCODING\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"This defines how the 20-bit landing pad label is encoded in the LPAD instruction. The encoding format is a normative implementation detail.\"\n },\n {\n \"excerpt\": \"When Zicfilp is enabled, `LPAD` is the only instruction allowed to execute when the `ELP` state is `LP_EXPECTED`. If Zicfilp is not enabled then the instruction is a no-op.\",\n \"line_number\": 235,\n \"parameter_name\": \"LPAD_EXECUTION_CONTROL\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"This defines the normative behavior of LPAD instruction execution based on whether Zicfilp is enabled. The implementation controls this behavior.\"\n },\n {\n \"excerpt\": \"The Zicfiss instructions, except `SSAMOSWAP.W/D`, are encoded using a subset of May-Be-Operation instructions defined by the Zimop and Zcmop extensions.\",\n \"line_number\": 334,\n \"parameter_name\": \"ZICFISS_ENCODING_SCHEME\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"This defines the encoding scheme choice for Zicfiss instructions, using Zimop/Zcmop encodings. This is a normative encoding decision.\"\n },\n {\n \"excerpt\": \"The `ssp` CSR is an unprivileged read-write (URW) CSR that reads and writes `XLEN` low order bits of the shadow stack pointer (`ssp`).\",\n \"line_number\": 378,\n \"parameter_name\": \"SSP_CSR_ACCESS\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"This defines that the ssp CSR is read-write. The implementation could potentially make it read-only, making this a CSR access control parameter.\"\n },\n {\n \"excerpt\": \"The CSR address is 0x011.\",\n \"line_number\": 379,\n \"parameter_name\": \"SSP_CSR_ADDRESS\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"This defines the specific CSR address for the ssp register. This is a normative addressing choice.\"\n },\n {\n \"excerpt\": \"There is no high CSR defined as the `ssp` is always as wide as the `XLEN` of the current privilege mode.\",\n \"line_number\": 380,\n \"parameter_name\": \"SSP_CSR_WIDTH\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"This defines that ssp width matches XLEN with no high CSR. This is a normative width decision.\"\n },\n {\n \"excerpt\": \"The bits 1:0 of `ssp` are read-only zero. If the UXLEN or SXLEN may never be 32, then the bit 2 is also read-only zero.\",\n \"line_number\": 381,\n \"parameter_name\": \"SSP_LOW_BITS_RO\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"bitmask\",\n \"confidence\": \"high\",\n \"reasoning\": \"This defines which low-order bits of ssp are read-only zero, with bit 2 being conditionally read-only based on XLEN support. This is a CSR field access control parameter.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"Control-flow Integrity (CFI) capabilities help defend against Return-Oriented Programming (ROP) and Call/Jump-Oriented Programming (COP/JOP) style control-flow subversion attacks.\",\n \"line_number\": 3,\n \"reason\": \"This is descriptive text explaining what CFI does, not an implementation choice or parameter.\"\n },\n {\n \"excerpt\": \"The term _call_ is used to refer to a `JAL` or `JALR` instruction with a link register as destination, i.e., _rd_\u2260`x0`.\",\n \"line_number\": 37,\n \"reason\": \"This is a definition of terminology, not an implementation parameter. It defines what the spec means by 'call'.\"\n },\n {\n \"excerpt\": \"When `ELP` is set to `LP_EXPECTED`, if the next instruction in the instruction stream is not 4-byte aligned, or is not `LPAD`, or if the landing pad label encoded in `LPAD` is not zero and does not match the expected landing pad label in bits 31:12 of the `x7` register, then a software-check exception (cause=18) with `__x__tval` set to \\\"landing pad fault (code=2)\\\" is raised else the `ELP` is updated to `NO_LP_EXPECTED`.\",\n \"line_number\": 207,\n \"reason\": \"This describes the behavioral consequences when ELP is LP_EXPECTED. It's describing what happens given a state, not defining an implementation choice.\"\n },\n {\n \"excerpt\": \"When Zicfiss is enabled, each function that needs to spill the link register, typically non-leaf functions, store the link register value to the regular stack and a shadow copy of the link register value to the shadow stack when the function is entered (the prologue).\",\n \"line_number\": 310,\n \"reason\": \"This describes software behavior and programming conventions when using Zicfiss, not an architectural implementation parameter.\"\n },\n {\n \"excerpt\": \"The `ssp` is decremented by `SSPUSH` and `C.SSPUSH` only if the store to the shadow stack completes successfully.\",\n \"line_number\": 456,\n \"reason\": \"This describes the operational behavior of the SSPUSH instruction - what happens during execution, not an implementation choice.\"\n }\n ]\n}\n```", + "input_tokens": 17556, + "output_tokens": 2282, + "latency_ms": 47620, + "timestamp": "2026-04-15T14:47:20.681307+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_056.json.license b/param_extraction/results/claude-sonnet-4/chunk_056.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_056.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_057.json b/param_extraction/results/claude-sonnet-4/chunk_057.json new file mode 100644 index 0000000000..f51a773fc5 --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_057.json @@ -0,0 +1,204 @@ +{ + "chunk_id": "chunk_057", + "source_file": "v-st-ext.adoc", + "start_line": 1, + "end_line": 3393, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "The maximum size in bits of a vector element that any operation can produce or consume, _ELEN_ >= 8, which must be a power of 2.", + "line_number": 22, + "parameter_name": "ELEN", + "existing_udb_name": "ELEN", + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "ELEN is a direct implementation parameter defining the maximum element size. It has constraints (>= 8, power of 2) but the specific value is chosen by the implementer." + }, + { + "excerpt": "The number of bits in a single vector register, _VLEN_ >= ELEN, which must be a power of 2, and must be no greater than 2^16.", + "line_number": 23, + "parameter_name": "VLEN", + "existing_udb_name": "VLEN", + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "VLEN is a direct implementation parameter defining the vector register size. It has constraints (>= ELEN, power of 2, <= 2^16) but the specific value is chosen by the implementer." + }, + { + "excerpt": "Implementations may have a writable `misa.V` field.", + "line_number": 108, + "parameter_name": "MUTABLE_MISA_V", + "existing_udb_name": "MUTABLE_MISA_V", + "class": "NORM_CSR_RW", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether misa.V is read-only or read-write. This is a binary choice about the mutability of the field." + }, + { + "excerpt": "Analogous to the way in which the floating-point unit is handled, the `mstatus.VS` field may exist even if `misa.V` is clear.", + "line_number": 108, + "parameter_name": "MSTATUS_VS_EXISTS", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether mstatus.VS field exists when misa.V is clear. This is a direct architectural choice." + }, + { + "excerpt": "Implementations may also change `mstatus.VS` or `vsstatus.VS` from Initial or Clean to Dirty at any time, even when there is no change in vector state.", + "line_number": 127, + "parameter_name": "HW_MSTATUS_VS_DIRTY_UPDATE", + "existing_udb_name": "HW_MSTATUS_VS_DIRTY_UPDATE", + "class": "SW_RULE", + "value_type": "enum", + "confidence": "medium", + "reasoning": "Whether hardware updates mstatus.VS to Dirty is implementation-defined, but software can handle this deterministically by checking and managing VS state with proper fencing." + }, + { + "excerpt": "A small implementation supporting ELEN=32 requires only seven bits of state in `vtype`: two bits for `ma` and `ta`, two bits for `vsew[1:0]` and three bits for `vlmul[2:0]`. The illegal value represented by `vill` can be internally encoded using the illegal 64-bit combination in `vsew[1:0]` without requiring an additional storage bit to hold `vill`.", + "line_number": 175, + "parameter_name": "VILL_IMPLICIT_ENCODING", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "The implementation can choose to encode vill implicitly using illegal vsew combinations rather than using an explicit bit. This is an internal encoding choice." + }, + { + "excerpt": "Implementations must support LMUL integer values of 1, 2, 4, and 8.", + "line_number": 254, + "parameter_name": "SUPPORTED_LMUL_VALUES", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "set", + "confidence": "high", + "reasoning": "This is a fixed requirement that all implementations must support these LMUL values. It is not a parameter as there is no implementation choice." + }, + { + "excerpt": "Implementations may set `vill` in either case.", + "line_number": 1659, + "parameter_name": "RESERVED_VILL_SET", + "existing_udb_name": "RESERVED_VILL_SET_PARAM", + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "The implementation chooses whether to set vill when reserved vsetvl encodings are used. This is a direct implementation choice for handling reserved cases." + }, + { + "excerpt": "All vector loads and stores may generate and accept a non-zero `vstart` value.", + "line_number": 1774, + "parameter_name": "VECTOR_LS_VSTART_SUPPORT", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "The implementation may choose whether vector load/store instructions support non-zero vstart values. The word 'may' indicates this is optional." + }, + { + "excerpt": "Load instructions may overwrite active destination vector register group elements past the element index at which the trap is reported.", + "line_number": 2095, + "parameter_name": "VECTOR_LS_OVERWRITE_PAST_TRAP", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "The implementation may choose whether to overwrite elements past a trap point. This is an implementation-defined behavior choice." + }, + { + "excerpt": "Similarly, fault-only-first load instructions may update active destination elements past the element that causes trimming of the vector length (but not past the original vector length). The values of these spurious updates do not have to correspond to the values in memory at the addressed memory locations.", + "line_number": 2096, + "parameter_name": "VECTOR_FF_PAST_TRAP", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "The implementation may choose whether fault-only-first loads update elements past the trimming point. This is an implementation-defined behavior choice." + }, + { + "excerpt": "If a trap occurs during access to a segment, it is implementation-defined whether a subset of the faulting segment's accesses are performed before the trap is taken.", + "line_number": 2372, + "parameter_name": "VECTOR_LS_SEG_PARTIAL_ACCESS", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "The implementation chooses whether to perform partial segment accesses before taking a trap. This is explicitly marked as implementation-defined." + }, + { + "excerpt": "In both cases, it is implementation-defined whether a subset of the segment is loaded.", + "line_number": 2434, + "parameter_name": "VECTOR_FF_SEG_PARTIAL_ACCESS", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "The implementation chooses whether to perform partial segment loads in fault-only-first operations. This is explicitly marked as implementation-defined." + }, + { + "excerpt": "These instructions may overwrite destination vector register group elements past the point at which a trap is reported or past the point at which vector length is trimmed.", + "line_number": 2437, + "parameter_name": "VECTOR_LS_SEG_FF_OVERLOAD", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "The implementation may choose whether fault-only-first segment loads overwrite elements past trap/trim points. This is an implementation choice." + }, + { + "excerpt": "Implementations are allowed to raise a misaligned address exception on whole register loads and stores if the base address is not naturally aligned to the larger of the size of the encoded EEW in bytes (EEW/8) or the implementation's smallest supported SEW size in bytes (SEW_MIN/8).", + "line_number": 2598, + "parameter_name": "VECTOR_LS_WHOLEREG_MISALIGNED_EXCEPTION", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "The implementation chooses whether to raise misaligned exceptions for whole register loads/stores. This is an implementation choice about exception behavior." + }, + { + "excerpt": "If an element accessed by a vector memory instruction is not naturally aligned to the size of the element, either the element is transferred successfully or an address-misaligned exception is raised on that element.", + "line_number": 2650, + "parameter_name": "VECTOR_LS_MISALIGNED_EXCEPTION", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "The implementation chooses whether to support misaligned vector memory accesses or raise exceptions. This is an implementation choice about memory access behavior." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "The base vector extension is intended to provide general support for data-parallel execution within the 32-bit instruction encoding space, with later vector extensions supporting richer functionality for certain domains.", + "line_number": 4, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks." + }, + { + "excerpt": "When MODE=Direct, all traps into machine mode cause the `pc` to be set to the address in the BASE field.", + "line_number": 1254, + "reason": "This describes what happens when mtvec.MODE has a specific value. The behavior is determined by the CSR field value at runtime, not by an implementation choice." + }, + { + "excerpt": "The vector extension adds 32 architectural vector registers, `v0`-`v31` to the base scalar RISC-V ISA.", + "line_number": 75, + "reason": "This is a fixed requirement that all implementations must have 32 vector registers. There is no implementation choice here." + }, + { + "excerpt": "All systems must support all four options:", + "line_number": 364, + "reason": "This is a fixed requirement ('must support') that applies to all implementations. There is no implementation choice here." + }, + { + "excerpt": "Software may determine the PMP granularity by writing zero to `pmp0cfg`, then writing all ones to `pmpaddr0`, then reading back `pmpaddr0`.", + "line_number": 3530, + "reason": "Here 'may' means 'is allowed to' (permission), not 'might or might not' (optionality). This describes a software technique, not an implementation-defined parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"The maximum size in bits of a vector element that any operation can produce or consume, _ELEN_ >= 8, which must be a power of 2.\",\n \"line_number\": 22,\n \"parameter_name\": \"ELEN\",\n \"existing_udb_name\": \"ELEN\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"ELEN is a direct implementation parameter defining the maximum element size. It has constraints (>= 8, power of 2) but the specific value is chosen by the implementer.\"\n },\n {\n \"excerpt\": \"The number of bits in a single vector register, _VLEN_ >= ELEN, which must be a power of 2, and must be no greater than 2^16.\",\n \"line_number\": 23,\n \"parameter_name\": \"VLEN\",\n \"existing_udb_name\": \"VLEN\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"VLEN is a direct implementation parameter defining the vector register size. It has constraints (>= ELEN, power of 2, <= 2^16) but the specific value is chosen by the implementer.\"\n },\n {\n \"excerpt\": \"Implementations may have a writable `misa.V` field.\",\n \"line_number\": 108,\n \"parameter_name\": \"MUTABLE_MISA_V\",\n \"existing_udb_name\": \"MUTABLE_MISA_V\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether misa.V is read-only or read-write. This is a binary choice about the mutability of the field.\"\n },\n {\n \"excerpt\": \"Analogous to the way in which the floating-point unit is handled, the `mstatus.VS` field may exist even if `misa.V` is clear.\",\n \"line_number\": 108,\n \"parameter_name\": \"MSTATUS_VS_EXISTS\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether mstatus.VS field exists when misa.V is clear. This is a direct architectural choice.\"\n },\n {\n \"excerpt\": \"Implementations may also change `mstatus.VS` or `vsstatus.VS` from Initial or Clean to Dirty at any time, even when there is no change in vector state.\",\n \"line_number\": 127,\n \"parameter_name\": \"HW_MSTATUS_VS_DIRTY_UPDATE\",\n \"existing_udb_name\": \"HW_MSTATUS_VS_DIRTY_UPDATE\",\n \"class\": \"SW_RULE\",\n \"value_type\": \"enum\",\n \"confidence\": \"medium\",\n \"reasoning\": \"Whether hardware updates mstatus.VS to Dirty is implementation-defined, but software can handle this deterministically by checking and managing VS state with proper fencing.\"\n },\n {\n \"excerpt\": \"A small implementation supporting ELEN=32 requires only seven bits of state in `vtype`: two bits for `ma` and `ta`, two bits for `vsew[1:0]` and three bits for `vlmul[2:0]`. The illegal value represented by `vill` can be internally encoded using the illegal 64-bit combination in `vsew[1:0]` without requiring an additional storage bit to hold `vill`.\",\n \"line_number\": 175,\n \"parameter_name\": \"VILL_IMPLICIT_ENCODING\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The implementation can choose to encode vill implicitly using illegal vsew combinations rather than using an explicit bit. This is an internal encoding choice.\"\n },\n {\n \"excerpt\": \"Implementations must support LMUL integer values of 1, 2, 4, and 8.\",\n \"line_number\": 254,\n \"parameter_name\": \"SUPPORTED_LMUL_VALUES\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"This is a fixed requirement that all implementations must support these LMUL values. It is not a parameter as there is no implementation choice.\"\n },\n {\n \"excerpt\": \"Implementations may set `vill` in either case.\",\n \"line_number\": 1659,\n \"parameter_name\": \"RESERVED_VILL_SET\",\n \"existing_udb_name\": \"RESERVED_VILL_SET_PARAM\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The implementation chooses whether to set vill when reserved vsetvl encodings are used. This is a direct implementation choice for handling reserved cases.\"\n },\n {\n \"excerpt\": \"All vector loads and stores may generate and accept a non-zero `vstart` value.\",\n \"line_number\": 1774,\n \"parameter_name\": \"VECTOR_LS_VSTART_SUPPORT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The implementation may choose whether vector load/store instructions support non-zero vstart values. The word 'may' indicates this is optional.\"\n },\n {\n \"excerpt\": \"Load instructions may overwrite active destination vector register group elements past the element index at which the trap is reported.\",\n \"line_number\": 2095,\n \"parameter_name\": \"VECTOR_LS_OVERWRITE_PAST_TRAP\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The implementation may choose whether to overwrite elements past a trap point. This is an implementation-defined behavior choice.\"\n },\n {\n \"excerpt\": \"Similarly, fault-only-first load instructions may update active destination elements past the element that causes trimming of the vector length (but not past the original vector length). The values of these spurious updates do not have to correspond to the values in memory at the addressed memory locations.\",\n \"line_number\": 2096,\n \"parameter_name\": \"VECTOR_FF_PAST_TRAP\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The implementation may choose whether fault-only-first loads update elements past the trimming point. This is an implementation-defined behavior choice.\"\n },\n {\n \"excerpt\": \"If a trap occurs during access to a segment, it is implementation-defined whether a subset of the faulting segment's accesses are performed before the trap is taken.\",\n \"line_number\": 2372,\n \"parameter_name\": \"VECTOR_LS_SEG_PARTIAL_ACCESS\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The implementation chooses whether to perform partial segment accesses before taking a trap. This is explicitly marked as implementation-defined.\"\n },\n {\n \"excerpt\": \"In both cases, it is implementation-defined whether a subset of the segment is loaded.\",\n \"line_number\": 2434,\n \"parameter_name\": \"VECTOR_FF_SEG_PARTIAL_ACCESS\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The implementation chooses whether to perform partial segment loads in fault-only-first operations. This is explicitly marked as implementation-defined.\"\n },\n {\n \"excerpt\": \"These instructions may overwrite destination vector register group elements past the point at which a trap is reported or past the point at which vector length is trimmed.\",\n \"line_number\": 2437,\n \"parameter_name\": \"VECTOR_LS_SEG_FF_OVERLOAD\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The implementation may choose whether fault-only-first segment loads overwrite elements past trap/trim points. This is an implementation choice.\"\n },\n {\n \"excerpt\": \"Implementations are allowed to raise a misaligned address exception on whole register loads and stores if the base address is not naturally aligned to the larger of the size of the encoded EEW in bytes (EEW/8) or the implementation's smallest supported SEW size in bytes (SEW_MIN/8).\",\n \"line_number\": 2598,\n \"parameter_name\": \"VECTOR_LS_WHOLEREG_MISALIGNED_EXCEPTION\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The implementation chooses whether to raise misaligned exceptions for whole register loads/stores. This is an implementation choice about exception behavior.\"\n },\n {\n \"excerpt\": \"If an element accessed by a vector memory instruction is not naturally aligned to the size of the element, either the element is transferred successfully or an address-misaligned exception is raised on that element.\",\n \"line_number\": 2650,\n \"parameter_name\": \"VECTOR_LS_MISALIGNED_EXCEPTION\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The implementation chooses whether to support misaligned vector memory accesses or raise exceptions. This is an implementation choice about memory access behavior.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"The base vector extension is intended to provide general support for data-parallel execution within the 32-bit instruction encoding space, with later vector extensions supporting richer functionality for certain domains.\",\n \"line_number\": 4,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks.\"\n },\n {\n \"excerpt\": \"When MODE=Direct, all traps into machine mode cause the `pc` to be set to the address in the BASE field.\",\n \"line_number\": 1254,\n \"reason\": \"This describes what happens when mtvec.MODE has a specific value. The behavior is determined by the CSR field value at runtime, not by an implementation choice.\"\n },\n {\n \"excerpt\": \"The vector extension adds 32 architectural vector registers, `v0`-`v31` to the base scalar RISC-V ISA.\",\n \"line_number\": 75,\n \"reason\": \"This is a fixed requirement that all implementations must have 32 vector registers. There is no implementation choice here.\"\n },\n {\n \"excerpt\": \"All systems must support all four options:\",\n \"line_number\": 364,\n \"reason\": \"This is a fixed requirement ('must support') that applies to all implementations. There is no implementation choice here.\"\n },\n {\n \"excerpt\": \"Software may determine the PMP granularity by writing zero to `pmp0cfg`, then writing all ones to `pmpaddr0`, then reading back `pmpaddr0`.\",\n \"line_number\": 3530,\n \"reason\": \"Here 'may' means 'is allowed to' (permission), not 'might or might not' (optionality). This describes a software technique, not an implementation-defined parameter.\"\n }\n ]\n}\n```", + "input_tokens": 53055, + "output_tokens": 3025, + "latency_ms": 54960, + "timestamp": "2026-04-15T15:03:59.732494+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_057.json.license b/param_extraction/results/claude-sonnet-4/chunk_057.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_057.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_058.json b/param_extraction/results/claude-sonnet-4/chunk_058.json new file mode 100644 index 0000000000..0d0b1afc12 --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_058.json @@ -0,0 +1,74 @@ +{ + "chunk_id": "chunk_058", + "source_file": "v-st-ext.adoc", + "start_line": 3386, + "end_line": 5396, + "content_start_line": 3394, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "Vector instructions with EGS > VLMAX are reserved.", + "line_number": 5251, + "parameter_name": "EGS_VLMAX_CONSTRAINT", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "This is a direct implementation constraint on which element group sizes are supported. The implementation chooses whether to support EGS values that exceed VLMAX." + }, + { + "excerpt": "When an operand is a vector of element groups, the `vl` setting must correspond to an integer multiple of the element group size, with other values of `vl` reserved.", + "line_number": 5270, + "parameter_name": "EGS_VL_MULTIPLE_CONSTRAINT", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "This defines a constraint on vl setting for element group instructions. The implementation must enforce this constraint, making it a direct architectural choice." + }, + { + "excerpt": "When AVL > VLMAX, the value of `vl` must be set to either VLMAX or a positive integer multiple of EGSMAX.", + "line_number": 5276, + "parameter_name": "EGSMAX_VL_SETTING", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "high", + "reasoning": "When AVL > VLMAX, the implementation has a choice between setting vl to VLMAX or to a multiple of EGSMAX. This is a direct implementation choice for vl setting behavior." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "NOTE: The 7 bit accuracy was chosen as it requires 0,1,2,3 Newton-Raphson iterations to converge to close to bfloat16, FP16, FP32, FP64 accuracy respectively.", + "line_number": 3580, + "reason": "This is inside a NOTE block, which is non-normative. It explains a design rationale but does not define an implementation parameter." + }, + { + "excerpt": "The `vmfeq` and `vmfne` raise the invalid operation exception only on signaling NaN inputs.", + "line_number": 3750, + "reason": "This describes fixed behavioral requirements that all implementations must follow. It is not an implementation choice." + }, + { + "excerpt": "The instruction copies a single SEW-wide element from index 0 of the source vector register to a destination integer register.", + "line_number": 4450, + "reason": "This describes the fixed behavior of the vmv.x.s instruction. It is not an implementation-defined parameter." + }, + { + "excerpt": "Traps on vector reduction instructions are always reported with a `vstart` of 0.", + "line_number": 4050, + "reason": "This is a fixed requirement ('always reported') that applies to all implementations. It is not a parameter." + }, + { + "excerpt": "All Zve* extensions have precise traps.", + "line_number": 5390, + "reason": "This is a fixed requirement for all Zve* extensions. There is no implementation choice here." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"Vector instructions with EGS > VLMAX are reserved.\",\n \"line_number\": 5251,\n \"parameter_name\": \"EGS_VLMAX_CONSTRAINT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"This is a direct implementation constraint on which element group sizes are supported. The implementation chooses whether to support EGS values that exceed VLMAX.\"\n },\n {\n \"excerpt\": \"When an operand is a vector of element groups, the `vl` setting must correspond to an integer multiple of the element group size, with other values of `vl` reserved.\",\n \"line_number\": 5270,\n \"parameter_name\": \"EGS_VL_MULTIPLE_CONSTRAINT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"This defines a constraint on vl setting for element group instructions. The implementation must enforce this constraint, making it a direct architectural choice.\"\n },\n {\n \"excerpt\": \"When AVL > VLMAX, the value of `vl` must be set to either VLMAX or a positive integer multiple of EGSMAX.\",\n \"line_number\": 5276,\n \"parameter_name\": \"EGSMAX_VL_SETTING\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"When AVL > VLMAX, the implementation has a choice between setting vl to VLMAX or to a multiple of EGSMAX. This is a direct implementation choice for vl setting behavior.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"NOTE: The 7 bit accuracy was chosen as it requires 0,1,2,3 Newton-Raphson iterations to converge to close to bfloat16, FP16, FP32, FP64 accuracy respectively.\",\n \"line_number\": 3580,\n \"reason\": \"This is inside a NOTE block, which is non-normative. It explains a design rationale but does not define an implementation parameter.\"\n },\n {\n \"excerpt\": \"The `vmfeq` and `vmfne` raise the invalid operation exception only on signaling NaN inputs.\",\n \"line_number\": 3750,\n \"reason\": \"This describes fixed behavioral requirements that all implementations must follow. It is not an implementation choice.\"\n },\n {\n \"excerpt\": \"The instruction copies a single SEW-wide element from index 0 of the source vector register to a destination integer register.\",\n \"line_number\": 4450,\n \"reason\": \"This describes the fixed behavior of the vmv.x.s instruction. It is not an implementation-defined parameter.\"\n },\n {\n \"excerpt\": \"Traps on vector reduction instructions are always reported with a `vstart` of 0.\",\n \"line_number\": 4050,\n \"reason\": \"This is a fixed requirement ('always reported') that applies to all implementations. It is not a parameter.\"\n },\n {\n \"excerpt\": \"All Zve* extensions have precise traps.\",\n \"line_number\": 5390,\n \"reason\": \"This is a fixed requirement for all Zve* extensions. There is no implementation choice here.\"\n }\n ]\n}\n```", + "input_tokens": 34287, + "output_tokens": 886, + "latency_ms": 38178, + "timestamp": "2026-04-15T14:48:38.239723+00:00", + "error": null, + "retry_count": 1 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_058.json.license b/param_extraction/results/claude-sonnet-4/chunk_058.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_058.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_059.json b/param_extraction/results/claude-sonnet-4/chunk_059.json new file mode 100644 index 0000000000..38e7088e66 --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_059.json @@ -0,0 +1,134 @@ +{ + "chunk_id": "chunk_059", + "source_file": "vector-crypto.adoc", + "start_line": 1, + "end_line": 3340, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "The Zvknhb and Zvbc Vector Crypto Extensions --and accordingly the composite extensions Zvkn, Zvknc, Zvkng, and Zvksc-- depend on Zve64x.", + "line_number": 372, + "parameter_name": "ZVE64X_DEPENDENCY", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "This is a normative requirement that certain extensions depend on Zve64x. The implementation chooses whether to support these extensions, which inherently requires supporting Zve64x." + }, + { + "excerpt": "All of the other Vector Crypto Extensions depend on `Zve32x`.", + "line_number": 374, + "parameter_name": "ZVE32X_DEPENDENCY", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "This is a normative requirement that other vector crypto extensions depend on Zve32x. The implementation chooses whether to support these extensions." + }, + { + "excerpt": "These instructions are only defined for `SEW`=64.", + "line_number": 421, + "parameter_name": "ZVBC_SEW_CONSTRAINT", + "existing_udb_name": null, + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "The Zvbc instructions have a constraint that SEW must be 64. This defines the legal values for SEW when these instructions are executed." + }, + { + "excerpt": "All of these instructions work on 128-bit element groups comprised of four 32-bit elements.", + "line_number": 481, + "parameter_name": "ZVKG_ELEMENT_GROUP_SIZE", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "This defines the fixed element group structure for Zvkg instructions - 128-bit groups with four 32-bit elements. This is an architectural parameter of the instruction format." + }, + { + "excerpt": "All of these instructions work on 128-bit element groups comprised of four 32-bit elements.", + "line_number": 520, + "parameter_name": "ZVKNED_ELEMENT_GROUP_SIZE", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "This defines the fixed element group structure for Zvkned (AES) instructions - 128-bit groups with four 32-bit elements." + }, + { + "excerpt": "SHA-256: these instructions work on 128-bit element groups comprised of four 32-bit elements.", + "line_number": 560, + "parameter_name": "ZVKNHA_ZVKNHB_SHA256_ELEMENT_GROUP_SIZE", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "This defines the element group structure for SHA-256 instructions in Zvknh[ab] extensions." + }, + { + "excerpt": "SHA-512: these instructions work on 256-bit element groups comprised of four 64-bit elements.", + "line_number": 561, + "parameter_name": "ZVKNHB_SHA512_ELEMENT_GROUP_SIZE", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "This defines the element group structure for SHA-512 instructions in Zvknhb extension." + }, + { + "excerpt": "All of these instructions work on 128-bit element groups comprised of four 32-bit elements.", + "line_number": 625, + "parameter_name": "ZVKSED_ELEMENT_GROUP_SIZE", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "This defines the fixed element group structure for Zvksed (SM4) instructions - 128-bit groups with four 32-bit elements." + }, + { + "excerpt": "All of these instructions work on 256-bit element groups comprised of eight 32-bit elements.", + "line_number": 665, + "parameter_name": "ZVKSH_ELEMENT_GROUP_SIZE", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "This defines the fixed element group structure for Zvksh (SM3) instructions - 256-bit groups with eight 32-bit elements." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "Where variables are concatenated, the order shown is how they would appear in a vector register from left to right.", + "line_number": 85, + "reason": "This is inside a [NOTE] block, which is non-normative informational content." + }, + { + "excerpt": "For all of the vector crypto instructions in this specification, `EEW`=`SEW`.", + "line_number": 179, + "reason": "This is a fixed requirement that applies to ALL implementations - not a parameter choice." + }, + { + "excerpt": "Instructions that violate the `vl` or `vstart` requirements are _reserved_.", + "line_number": 201, + "reason": "This describes what happens when constraints are violated - it's a behavioral rule, not an implementation choice." + }, + { + "excerpt": "To help avoid side-channel timing attacks, these instructions shall be implemented with data-independent timing.", + "line_number": 489, + "reason": "This is a fixed security requirement that all implementations must satisfy - not a parameter." + }, + { + "excerpt": "The number of element groups to be processed is `vl`/`EGS`.", + "line_number": 491, + "reason": "This describes runtime behavior controlled by the vl CSR value, not an implementation-defined parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"The Zvknhb and Zvbc Vector Crypto Extensions --and accordingly the composite extensions Zvkn, Zvknc, Zvkng, and Zvksc-- depend on Zve64x.\",\n \"line_number\": 372,\n \"parameter_name\": \"ZVE64X_DEPENDENCY\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"This is a normative requirement that certain extensions depend on Zve64x. The implementation chooses whether to support these extensions, which inherently requires supporting Zve64x.\"\n },\n {\n \"excerpt\": \"All of the other Vector Crypto Extensions depend on `Zve32x`.\",\n \"line_number\": 374,\n \"parameter_name\": \"ZVE32X_DEPENDENCY\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"This is a normative requirement that other vector crypto extensions depend on Zve32x. The implementation chooses whether to support these extensions.\"\n },\n {\n \"excerpt\": \"These instructions are only defined for `SEW`=64.\",\n \"line_number\": 421,\n \"parameter_name\": \"ZVBC_SEW_CONSTRAINT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"The Zvbc instructions have a constraint that SEW must be 64. This defines the legal values for SEW when these instructions are executed.\"\n },\n {\n \"excerpt\": \"All of these instructions work on 128-bit element groups comprised of four 32-bit elements.\",\n \"line_number\": 481,\n \"parameter_name\": \"ZVKG_ELEMENT_GROUP_SIZE\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"This defines the fixed element group structure for Zvkg instructions - 128-bit groups with four 32-bit elements. This is an architectural parameter of the instruction format.\"\n },\n {\n \"excerpt\": \"All of these instructions work on 128-bit element groups comprised of four 32-bit elements.\",\n \"line_number\": 520,\n \"parameter_name\": \"ZVKNED_ELEMENT_GROUP_SIZE\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"This defines the fixed element group structure for Zvkned (AES) instructions - 128-bit groups with four 32-bit elements.\"\n },\n {\n \"excerpt\": \"SHA-256: these instructions work on 128-bit element groups comprised of four 32-bit elements.\",\n \"line_number\": 560,\n \"parameter_name\": \"ZVKNHA_ZVKNHB_SHA256_ELEMENT_GROUP_SIZE\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"This defines the element group structure for SHA-256 instructions in Zvknh[ab] extensions.\"\n },\n {\n \"excerpt\": \"SHA-512: these instructions work on 256-bit element groups comprised of four 64-bit elements.\",\n \"line_number\": 561,\n \"parameter_name\": \"ZVKNHB_SHA512_ELEMENT_GROUP_SIZE\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"This defines the element group structure for SHA-512 instructions in Zvknhb extension.\"\n },\n {\n \"excerpt\": \"All of these instructions work on 128-bit element groups comprised of four 32-bit elements.\",\n \"line_number\": 625,\n \"parameter_name\": \"ZVKSED_ELEMENT_GROUP_SIZE\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"This defines the fixed element group structure for Zvksed (SM4) instructions - 128-bit groups with four 32-bit elements.\"\n },\n {\n \"excerpt\": \"All of these instructions work on 256-bit element groups comprised of eight 32-bit elements.\",\n \"line_number\": 665,\n \"parameter_name\": \"ZVKSH_ELEMENT_GROUP_SIZE\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"This defines the fixed element group structure for Zvksh (SM3) instructions - 256-bit groups with eight 32-bit elements.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"Where variables are concatenated, the order shown is how they would appear in a vector register from left to right.\",\n \"line_number\": 85,\n \"reason\": \"This is inside a [NOTE] block, which is non-normative informational content.\"\n },\n {\n \"excerpt\": \"For all of the vector crypto instructions in this specification, `EEW`=`SEW`.\",\n \"line_number\": 179,\n \"reason\": \"This is a fixed requirement that applies to ALL implementations - not a parameter choice.\"\n },\n {\n \"excerpt\": \"Instructions that violate the `vl` or `vstart` requirements are _reserved_.\",\n \"line_number\": 201,\n \"reason\": \"This describes what happens when constraints are violated - it's a behavioral rule, not an implementation choice.\"\n },\n {\n \"excerpt\": \"To help avoid side-channel timing attacks, these instructions shall be implemented with data-independent timing.\",\n \"line_number\": 489,\n \"reason\": \"This is a fixed security requirement that all implementations must satisfy - not a parameter.\"\n },\n {\n \"excerpt\": \"The number of element groups to be processed is `vl`/`EGS`.\",\n \"line_number\": 491,\n \"reason\": \"This describes runtime behavior controlled by the vl CSR value, not an implementation-defined parameter.\"\n }\n ]\n}\n```", + "input_tokens": 39472, + "output_tokens": 1666, + "latency_ms": 106872, + "timestamp": "2026-04-15T14:50:28.153385+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_059.json.license b/param_extraction/results/claude-sonnet-4/chunk_059.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_059.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_060.json b/param_extraction/results/claude-sonnet-4/chunk_060.json new file mode 100644 index 0000000000..ea7b123009 --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_060.json @@ -0,0 +1,104 @@ +{ + "chunk_id": "chunk_060", + "source_file": "vector-crypto.adoc", + "start_line": 3311, + "end_line": 4966, + "content_start_line": 3341, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "`zvknha`: `SEW` is any value other than 32", + "line_number": 3348, + "parameter_name": "ZVKNHA_SEW_SUPPORT", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "high", + "reasoning": "The zvknha extension only supports SEW=32 for vsha2ms.vv, making this a direct implementation choice about which SEW values are supported." + }, + { + "excerpt": "`zvknhb`: `SEW` is any value other than 32 or 64", + "line_number": 3349, + "parameter_name": "ZVKNHB_SEW_SUPPORT", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "high", + "reasoning": "The zvknhb extension supports SEW=32 and SEW=64 for vsha2ms.vv, making this a direct implementation choice about which SEW values are supported." + }, + { + "excerpt": "`SEW` is any value other than 32", + "line_number": 3421, + "parameter_name": "VSM3C_SEW_SUPPORT", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "high", + "reasoning": "The vsm3c.vi instruction only supports SEW=32, making this a direct implementation choice about which SEW values are supported." + }, + { + "excerpt": "`SEW` is any value other than 32", + "line_number": 3540, + "parameter_name": "VSM3ME_SEW_SUPPORT", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "high", + "reasoning": "The vsm3me.vv instruction only supports SEW=32, making this a direct implementation choice about which SEW values are supported." + }, + { + "excerpt": "`SEW` is any value other than 32", + "line_number": 3680, + "parameter_name": "VSM4K_SEW_SUPPORT", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "high", + "reasoning": "The vsm4k.vi instruction only supports SEW=32, making this a direct implementation choice about which SEW values are supported." + }, + { + "excerpt": "`SEW` is any value other than 32", + "line_number": 3825, + "parameter_name": "VSM4R_SEW_SUPPORT", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "high", + "reasoning": "The vsm4r instructions only support SEW=32, making this a direct implementation choice about which SEW values are supported." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "Four rounds of SHA-256 message schedule expansion are performed (`zvknha` and `zvknhb`)", + "line_number": 3365, + "reason": "This describes the behavior when SEW=32, not an implementation choice. The parameter is which SEW values are supported, not what happens when a specific SEW is used." + }, + { + "excerpt": "Four rounds of SHA-512 message schedule expansion are performed (`zvkhnb`)", + "line_number": 3366, + "reason": "This describes the behavior when SEW=64, not an implementation choice. The parameter is which SEW values are supported, not what happens when a specific SEW is used." + }, + { + "excerpt": "The round number is provided by the 5-bit `rnds` unsigned immediate. Legal values are 0 - 31", + "line_number": 3456, + "reason": "This is a fixed requirement that all implementations must support - the legal range of the immediate field is not implementation-defined." + }, + { + "excerpt": "The Round group number (`rnd`) comes from `uimm[2:0]`; the bits in `uimm[4:3]` are ignored.", + "line_number": 3698, + "reason": "This describes the fixed encoding format, not an implementation choice. All implementations must decode the immediate field the same way." + }, + { + "excerpt": "Only the low log2(2*`SEW`) bits of the shift-amount value are used, all other bits are ignored.", + "line_number": 3970, + "reason": "This is a fixed requirement for how shift amounts are processed, not an implementation choice. All implementations must behave this way." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"`zvknha`: `SEW` is any value other than 32\",\n \"line_number\": 3348,\n \"parameter_name\": \"ZVKNHA_SEW_SUPPORT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"The zvknha extension only supports SEW=32 for vsha2ms.vv, making this a direct implementation choice about which SEW values are supported.\"\n },\n {\n \"excerpt\": \"`zvknhb`: `SEW` is any value other than 32 or 64\",\n \"line_number\": 3349,\n \"parameter_name\": \"ZVKNHB_SEW_SUPPORT\", \n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"The zvknhb extension supports SEW=32 and SEW=64 for vsha2ms.vv, making this a direct implementation choice about which SEW values are supported.\"\n },\n {\n \"excerpt\": \"`SEW` is any value other than 32\",\n \"line_number\": 3421,\n \"parameter_name\": \"VSM3C_SEW_SUPPORT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\", \n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"The vsm3c.vi instruction only supports SEW=32, making this a direct implementation choice about which SEW values are supported.\"\n },\n {\n \"excerpt\": \"`SEW` is any value other than 32\",\n \"line_number\": 3540,\n \"parameter_name\": \"VSM3ME_SEW_SUPPORT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\", \n \"confidence\": \"high\",\n \"reasoning\": \"The vsm3me.vv instruction only supports SEW=32, making this a direct implementation choice about which SEW values are supported.\"\n },\n {\n \"excerpt\": \"`SEW` is any value other than 32\",\n \"line_number\": 3680,\n \"parameter_name\": \"VSM4K_SEW_SUPPORT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\", \n \"reasoning\": \"The vsm4k.vi instruction only supports SEW=32, making this a direct implementation choice about which SEW values are supported.\"\n },\n {\n \"excerpt\": \"`SEW` is any value other than 32\",\n \"line_number\": 3825,\n \"parameter_name\": \"VSM4R_SEW_SUPPORT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"The vsm4r instructions only support SEW=32, making this a direct implementation choice about which SEW values are supported.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"Four rounds of SHA-256 message schedule expansion are performed (`zvknha` and `zvknhb`)\",\n \"line_number\": 3365,\n \"reason\": \"This describes the behavior when SEW=32, not an implementation choice. The parameter is which SEW values are supported, not what happens when a specific SEW is used.\"\n },\n {\n \"excerpt\": \"Four rounds of SHA-512 message schedule expansion are performed (`zvkhnb`)\",\n \"line_number\": 3366,\n \"reason\": \"This describes the behavior when SEW=64, not an implementation choice. The parameter is which SEW values are supported, not what happens when a specific SEW is used.\"\n },\n {\n \"excerpt\": \"The round number is provided by the 5-bit `rnds` unsigned immediate. Legal values are 0 - 31\",\n \"line_number\": 3456,\n \"reason\": \"This is a fixed requirement that all implementations must support - the legal range of the immediate field is not implementation-defined.\"\n },\n {\n \"excerpt\": \"The Round group number (`rnd`) comes from `uimm[2:0]`; the bits in `uimm[4:3]` are ignored.\",\n \"line_number\": 3698,\n \"reason\": \"This describes the fixed encoding format, not an implementation choice. All implementations must decode the immediate field the same way.\"\n },\n {\n \"excerpt\": \"Only the low log2(2*`SEW`) bits of the shift-amount value are used, all other bits are ignored.\",\n \"line_number\": 3970,\n \"reason\": \"This is a fixed requirement for how shift amounts are processed, not an implementation choice. All implementations must behave this way.\"\n }\n ]\n}\n```", + "input_tokens": 32351, + "output_tokens": 1284, + "latency_ms": 101320, + "timestamp": "2026-04-15T14:53:05.872947+00:00", + "error": null, + "retry_count": 1 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_060.json.license b/param_extraction/results/claude-sonnet-4/chunk_060.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_060.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_062.json b/param_extraction/results/claude-sonnet-4/chunk_062.json new file mode 100644 index 0000000000..7cd6cbd39e --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_062.json @@ -0,0 +1,43 @@ +{ + "chunk_id": "chunk_062", + "source_file": "zabha.adoc", + "start_line": 1, + "end_line": 68, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [], + "skipped_non_parameters": [ + { + "excerpt": "Zabha omits _byte_ and _halfword_ support for `LR` and `SC` due to low utility.", + "line_number": 62, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. It explains a design decision but does not define an implementation parameter." + }, + { + "excerpt": "The same exception options as specified in the A extension are applicable in cases where the address is not naturally aligned.", + "line_number": 50, + "reason": "This refers to exception options defined elsewhere (A extension) rather than defining new implementation choices. It's a reference to existing behavior, not a new parameter." + }, + { + "excerpt": "Byte and halfword AMOs always sign-extend the value placed in `rd`, and ignore the stem:[XLEN-1:2^{(width + 3)}] bits of the original value in `rs2`.", + "line_number": 42, + "reason": "This describes fixed behavioral requirements ('always sign-extend', 'ignore') that all implementations must follow. There is no implementation choice here." + }, + { + "excerpt": "The Zabha extension depends upon the Zaamo standard extension.", + "line_number": 25, + "reason": "This is a fixed dependency requirement, not an implementation choice. All Zabha implementations must include Zaamo." + }, + { + "excerpt": "If Zacas extension is also implemented, Zabha further provides the `AMOCAS.[B|H]` instructions.", + "line_number": 30, + "reason": "This describes conditional instruction availability based on extension presence, but the choice of whether to implement Zacas is a separate parameter outside this extension's scope." + } + ], + "raw_response": "```json\n{\n \"parameters\": [],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"Zabha omits _byte_ and _halfword_ support for `LR` and `SC` due to low utility.\",\n \"line_number\": 62,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. It explains a design decision but does not define an implementation parameter.\"\n },\n {\n \"excerpt\": \"The same exception options as specified in the A extension are applicable in cases where the address is not naturally aligned.\",\n \"line_number\": 50,\n \"reason\": \"This refers to exception options defined elsewhere (A extension) rather than defining new implementation choices. It's a reference to existing behavior, not a new parameter.\"\n },\n {\n \"excerpt\": \"Byte and halfword AMOs always sign-extend the value placed in `rd`, and ignore the stem:[XLEN-1:2^{(width + 3)}] bits of the original value in `rs2`.\",\n \"line_number\": 42,\n \"reason\": \"This describes fixed behavioral requirements ('always sign-extend', 'ignore') that all implementations must follow. There is no implementation choice here.\"\n },\n {\n \"excerpt\": \"The Zabha extension depends upon the Zaamo standard extension.\",\n \"line_number\": 25,\n \"reason\": \"This is a fixed dependency requirement, not an implementation choice. All Zabha implementations must include Zaamo.\"\n },\n {\n \"excerpt\": \"If Zacas extension is also implemented, Zabha further provides the `AMOCAS.[B|H]` instructions.\",\n \"line_number\": 30,\n \"reason\": \"This describes conditional instruction availability based on extension presence, but the choice of whether to implement Zacas is a separate parameter outside this extension's scope.\"\n }\n ]\n}\n```", + "input_tokens": 6694, + "output_tokens": 457, + "latency_ms": 35380, + "timestamp": "2026-04-15T14:52:07.491013+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_062.json.license b/param_extraction/results/claude-sonnet-4/chunk_062.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_062.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_063.json b/param_extraction/results/claude-sonnet-4/chunk_063.json new file mode 100644 index 0000000000..c24f332b80 --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_063.json @@ -0,0 +1,43 @@ +{ + "chunk_id": "chunk_063", + "source_file": "zacas.adoc", + "start_line": 1, + "end_line": 225, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [], + "skipped_non_parameters": [ + { + "excerpt": "Some algorithms may load the previous data value of a memory location into the register used as the compare data value source by a Zacas instruction.", + "line_number": 108, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. It provides informative guidance about algorithm implementation, not architectural requirements." + }, + { + "excerpt": "Just as for AMOs in the A extension, `AMOCAS.W/D/Q` requires that the address held in `rs1` be naturally aligned to the size of the operand", + "line_number": 135, + "reason": "This is a fixed requirement ('requires') that all implementations must satisfy. There is no implementation choice - all implementations must enforce natural alignment." + }, + { + "excerpt": "An unsuccessful `AMOCAS.W/D/Q` may either not perform a memory write or may write back the old value loaded from memory.", + "line_number": 150, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. It describes possible behaviors but does not define a normative implementation choice." + }, + { + "excerpt": "An `AMOCAS.W/D/Q` instruction always requires write permissions.", + "line_number": 156, + "reason": "This is a fixed requirement ('always requires') that applies to all implementations. There is no implementation choice here." + }, + { + "excerpt": "The following example code sequence illustrates the use of `AMOCAS.Q` to implement the _enqueue_ operation", + "line_number": 160, + "reason": "This text is inside a [NOTE] block and provides an example code sequence. It is non-normative and does not define any architectural parameters." + } + ], + "raw_response": "```json\n{\n \"parameters\": [],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"Some algorithms may load the previous data value of a memory location into the register used as the compare data value source by a Zacas instruction.\",\n \"line_number\": 108,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. It provides informative guidance about algorithm implementation, not architectural requirements.\"\n },\n {\n \"excerpt\": \"Just as for AMOs in the A extension, `AMOCAS.W/D/Q` requires that the address held in `rs1` be naturally aligned to the size of the operand\",\n \"line_number\": 135,\n \"reason\": \"This is a fixed requirement ('requires') that all implementations must satisfy. There is no implementation choice - all implementations must enforce natural alignment.\"\n },\n {\n \"excerpt\": \"An unsuccessful `AMOCAS.W/D/Q` may either not perform a memory write or may write back the old value loaded from memory.\",\n \"line_number\": 150,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. It describes possible behaviors but does not define a normative implementation choice.\"\n },\n {\n \"excerpt\": \"An `AMOCAS.W/D/Q` instruction always requires write permissions.\",\n \"line_number\": 156,\n \"reason\": \"This is a fixed requirement ('always requires') that applies to all implementations. There is no implementation choice here.\"\n },\n {\n \"excerpt\": \"The following example code sequence illustrates the use of `AMOCAS.Q` to implement the _enqueue_ operation\",\n \"line_number\": 160,\n \"reason\": \"This text is inside a [NOTE] block and provides an example code sequence. It is non-normative and does not define any architectural parameters.\"\n }\n ]\n}\n```", + "input_tokens": 8913, + "output_tokens": 462, + "latency_ms": 8881, + "timestamp": "2026-04-15T14:52:19.393450+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_063.json.license b/param_extraction/results/claude-sonnet-4/chunk_063.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_063.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_064.json b/param_extraction/results/claude-sonnet-4/chunk_064.json new file mode 100644 index 0000000000..5f881da8d4 --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_064.json @@ -0,0 +1,54 @@ +{ + "chunk_id": "chunk_064", + "source_file": "zalasr.adoc", + "start_line": 1, + "end_line": 135, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "If the address is not naturally aligned, an address-misaligned exception or an access-fault exception will be generated. The access-fault exception can be generated for a memory access that would otherwise be able to complete except for the misalignment, if the misaligned access should not be emulated.", + "line_number": 22, + "parameter_name": "ZALASR_MISALIGNED_BEHAVIOR", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "medium", + "reasoning": "The implementation chooses whether to generate an address-misaligned exception or an access-fault exception for misaligned Zalasr instructions. This is a direct implementation choice between two exception types." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "The Zalasr instructions always sign-extend the value placed in _rd_ and ignore the upper bits of the value of _rs2_.", + "line_number": 19, + "reason": "This is a fixed behavioral requirement that all implementations must follow - not a parameter." + }, + { + "excerpt": "The instructions in the Zalasr extension require that the address held in _rs1_ be naturally aligned to the size in bytes (2^width^) of the operand.", + "line_number": 20, + "reason": "This is a fixed requirement ('require') that applies to all implementations - not an implementation choice." + }, + { + "excerpt": "The _aq_ bit is mandatory because the two encodings that would be produced are not seen as useful at this time.", + "line_number": 71, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. It explains design rationale but does not define implementation parameters." + }, + { + "excerpt": "This instruction loads 2^width^ bytes of memory from rs1 atomically and writes the result into rd.", + "line_number": 62, + "reason": "This describes the fixed behavior of the instruction that all implementations must follow - not a parameter." + }, + { + "excerpt": "The misaligned atomicity granule PMA, defined in Volume II of this manual, optionally relaxes this alignment requirement.", + "line_number": 25, + "reason": "This refers to a PMA (Physical Memory Attribute) which is a platform-level choice outside the ISA scope, not an architectural parameter of the Zalasr extension itself." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"If the address is not naturally aligned, an address-misaligned exception or an access-fault exception will be generated. The access-fault exception can be generated for a memory access that would otherwise be able to complete except for the misalignment, if the misaligned access should not be emulated.\",\n \"line_number\": 22,\n \"parameter_name\": \"ZALASR_MISALIGNED_BEHAVIOR\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The implementation chooses whether to generate an address-misaligned exception or an access-fault exception for misaligned Zalasr instructions. This is a direct implementation choice between two exception types.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"The Zalasr instructions always sign-extend the value placed in _rd_ and ignore the upper bits of the value of _rs2_.\",\n \"line_number\": 19,\n \"reason\": \"This is a fixed behavioral requirement that all implementations must follow - not a parameter.\"\n },\n {\n \"excerpt\": \"The instructions in the Zalasr extension require that the address held in _rs1_ be naturally aligned to the size in bytes (2^width^) of the operand.\",\n \"line_number\": 20,\n \"reason\": \"This is a fixed requirement ('require') that applies to all implementations - not an implementation choice.\"\n },\n {\n \"excerpt\": \"The _aq_ bit is mandatory because the two encodings that would be produced are not seen as useful at this time.\",\n \"line_number\": 71,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. It explains design rationale but does not define implementation parameters.\"\n },\n {\n \"excerpt\": \"This instruction loads 2^width^ bytes of memory from rs1 atomically and writes the result into rd.\",\n \"line_number\": 62,\n \"reason\": \"This describes the fixed behavior of the instruction that all implementations must follow - not a parameter.\"\n },\n {\n \"excerpt\": \"The misaligned atomicity granule PMA, defined in Volume II of this manual, optionally relaxes this alignment requirement.\",\n \"line_number\": 25,\n \"reason\": \"This refers to a PMA (Physical Memory Attribute) which is a platform-level choice outside the ISA scope, not an architectural parameter of the Zalasr extension itself.\"\n }\n ]\n}\n```", + "input_tokens": 7673, + "output_tokens": 635, + "latency_ms": 19241, + "timestamp": "2026-04-15T14:52:41.669860+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_064.json.license b/param_extraction/results/claude-sonnet-4/chunk_064.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_064.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_065.json b/param_extraction/results/claude-sonnet-4/chunk_065.json new file mode 100644 index 0000000000..e96fa501e9 --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_065.json @@ -0,0 +1,69 @@ +{ + "chunk_id": "chunk_065", + "source_file": "zawrs.adoc", + "start_line": 1, + "end_line": 103, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "bounds the stall duration to an implementation-define short timeout", + "line_number": 30, + "parameter_name": "WRS_STO_TIMEOUT_DURATION", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "The timeout duration for WRS.STO is explicitly implementation-defined. This is a direct architectural parameter that implementers must choose." + }, + { + "excerpt": "it does not complete within an implementation-specific bounded time limit", + "line_number": 73, + "parameter_name": "WRS_NTO_TW_TIMEOUT", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "When TW bit is set, WRS.NTO has an implementation-specific time limit before causing an illegal-instruction exception. This is a direct architectural parameter." + }, + { + "excerpt": "the `WRS.NTO` does not complete within an implementation-specific bounded time limit", + "line_number": 79, + "parameter_name": "WRS_NTO_VTW_TIMEOUT", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "value", + "confidence": "high", + "reasoning": "When VTW bit is set in VS/VU mode, WRS.NTO has an implementation-specific time limit before causing a virtual-instruction exception. This is a separate architectural parameter from the TW timeout." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "The instructions in the Zawrs extension are only useful in conjunction with the LR instruction, which is provided by the Zalrsc component of the A extension.", + "line_number": 37, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks." + }, + { + "excerpt": "Hart execution may be stalled while the following conditions are all satisfied", + "line_number": 58, + "reason": "This describes the behavioral conditions for stalling, not an implementation choice. The behavior is deterministic given the conditions." + }, + { + "excerpt": "While stalled, an implementation is permitted to occasionally terminate the stall and complete execution for any reason.", + "line_number": 64, + "reason": "This grants permission for early termination but doesn't define a specific parameter that implementers must choose. It's a behavioral allowance rather than a configurable parameter." + }, + { + "excerpt": "The duration of a `WRS.STO` instruction's timeout may vary significantly within and among implementations.", + "line_number": 87, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. It provides guidance about typical timeout ranges but is not a normative requirement." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"bounds the stall duration to an implementation-define short timeout\",\n \"line_number\": 30,\n \"parameter_name\": \"WRS_STO_TIMEOUT_DURATION\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"The timeout duration for WRS.STO is explicitly implementation-defined. This is a direct architectural parameter that implementers must choose.\"\n },\n {\n \"excerpt\": \"it does not complete within an implementation-specific bounded time limit\",\n \"line_number\": 73,\n \"parameter_name\": \"WRS_NTO_TW_TIMEOUT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"When TW bit is set, WRS.NTO has an implementation-specific time limit before causing an illegal-instruction exception. This is a direct architectural parameter.\"\n },\n {\n \"excerpt\": \"the `WRS.NTO` does not complete within an implementation-specific bounded time limit\",\n \"line_number\": 79,\n \"parameter_name\": \"WRS_NTO_VTW_TIMEOUT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"value\",\n \"confidence\": \"high\",\n \"reasoning\": \"When VTW bit is set in VS/VU mode, WRS.NTO has an implementation-specific time limit before causing a virtual-instruction exception. This is a separate architectural parameter from the TW timeout.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"The instructions in the Zawrs extension are only useful in conjunction with the LR instruction, which is provided by the Zalrsc component of the A extension.\",\n \"line_number\": 37,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks.\"\n },\n {\n \"excerpt\": \"Hart execution may be stalled while the following conditions are all satisfied\",\n \"line_number\": 58,\n \"reason\": \"This describes the behavioral conditions for stalling, not an implementation choice. The behavior is deterministic given the conditions.\"\n },\n {\n \"excerpt\": \"While stalled, an implementation is permitted to occasionally terminate the stall and complete execution for any reason.\",\n \"line_number\": 64,\n \"reason\": \"This grants permission for early termination but doesn't define a specific parameter that implementers must choose. It's a behavioral allowance rather than a configurable parameter.\"\n },\n {\n \"excerpt\": \"The duration of a `WRS.STO` instruction's timeout may vary significantly within and among implementations.\",\n \"line_number\": 87,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. It provides guidance about typical timeout ranges but is not a normative requirement.\"\n }\n ]\n}\n```", + "input_tokens": 6901, + "output_tokens": 774, + "latency_ms": 12396, + "timestamp": "2026-04-15T14:52:57.096204+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_065.json.license b/param_extraction/results/claude-sonnet-4/chunk_065.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_065.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_066.json b/param_extraction/results/claude-sonnet-4/chunk_066.json new file mode 100644 index 0000000000..3027b4b4a3 --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_066.json @@ -0,0 +1,89 @@ +{ + "chunk_id": "chunk_066", + "source_file": "zc.adoc", + "start_line": 1, + "end_line": 2587, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "It is implementation defined whether interrupts can also be taken during the sequence execution.", + "line_number": 1421, + "parameter_name": "INTERRUPTS_ALLOWED_IN_PUSHPOP", + "existing_udb_name": null, + "class": "SW_RULE", + "value_type": "binary", + "confidence": "high", + "reasoning": "Whether interrupts are allowed during PUSH/POP sequence execution is implementation-defined. This affects the observable behavior but software can handle this deterministically by proper interrupt management and understanding the re-execution semantics." + }, + { + "excerpt": "It is platform defined whether the core implementation waits for the bus responses before continuing to the final stage of the sequence, or handles errors responses after completing the PUSH instruction.", + "line_number": 1439, + "parameter_name": "PUSHPOP_BUS_FAULT_HANDLING", + "existing_udb_name": null, + "class": "SW_RULE", + "value_type": "binary", + "confidence": "high", + "reasoning": "The timing of bus fault handling (wait for responses vs. handle after completion) is platform-defined. Software can handle this deterministically by understanding the fault model and using appropriate error handling." + }, + { + "excerpt": "The jvt register is an XLEN-bit WARL read/write register that holds the jump table configuration, consisting of the jump table base address (BASE) and the jump table mode (MODE).", + "line_number": 2398, + "parameter_name": "JVT_BASE_MASK", + "existing_udb_name": "JVT_BASE_MASK", + "class": "NORM_CSR_WARL", + "value_type": "bitmask", + "confidence": "high", + "reasoning": "The jvt CSR is WARL, and the set of legal values for the BASE field (bits XLEN-1:6) varies by implementation. The parameter is the mask of supported base address bits." + }, + { + "excerpt": "If jvt is writable, the set of values the register may hold can vary by implementation.", + "line_number": 2404, + "parameter_name": "JVT_READ_ONLY", + "existing_udb_name": "JVT_READ_ONLY", + "class": "NORM_CSR_RW", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether the jvt CSR is read-only or read-write. This is a binary choice about the mutability of the register." + }, + { + "excerpt": "jvt.mode is a WARL field, so can only be programmed to modes which are implemented.", + "line_number": 2424, + "parameter_name": "JVT_BASE_TYPE", + "existing_udb_name": "JVT_BASE_TYPE", + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "medium", + "reasoning": "The jvt.mode field is WARL, and implementations choose which mode values are supported. Currently only mode 000000 (Jump table mode) is defined and must be implemented, but the parameter represents the set of legal mode values." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "NOTE: Zcb can be implemented on any CPU as the instructions are 16-bit versions of existing 32-bit instructions from the application class profile.", + "line_number": 130, + "reason": "This is inside a NOTE block and is therefore non-normative. It provides implementation guidance but does not define an architectural parameter." + }, + { + "excerpt": "This instruction loads a byte from the memory address formed by adding rs1' to the zero extended immediate uimm. The resulting byte is zero extended to XLEN bits and is written to rd'.", + "line_number": 306, + "reason": "This describes the operational behavior of the c.lbu instruction, not an implementation choice. The behavior is fixed for all implementations." + }, + { + "excerpt": "All encodings are currently reserved for all architectures, and have no conflicts with any existing extensions.", + "line_number": 126, + "reason": "This is a statement about encoding space allocation, not an implementation-defined parameter. It describes a fixed property of the specification." + }, + { + "excerpt": "For this encoding to decode as cm.jt, index<32, otherwise it decodes as cm.jalt", + "line_number": 2476, + "reason": "This describes the fixed decoding rule that applies to all implementations. It is not an implementation choice but a specification requirement." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"It is implementation defined whether interrupts can also be taken during the sequence execution.\",\n \"line_number\": 1421,\n \"parameter_name\": \"INTERRUPTS_ALLOWED_IN_PUSHPOP\",\n \"existing_udb_name\": null,\n \"class\": \"SW_RULE\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"Whether interrupts are allowed during PUSH/POP sequence execution is implementation-defined. This affects the observable behavior but software can handle this deterministically by proper interrupt management and understanding the re-execution semantics.\"\n },\n {\n \"excerpt\": \"It is platform defined whether the core implementation waits for the bus responses before continuing to the final stage of the sequence, or handles errors responses after completing the PUSH instruction.\",\n \"line_number\": 1439,\n \"parameter_name\": \"PUSHPOP_BUS_FAULT_HANDLING\",\n \"existing_udb_name\": null,\n \"class\": \"SW_RULE\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The timing of bus fault handling (wait for responses vs. handle after completion) is platform-defined. Software can handle this deterministically by understanding the fault model and using appropriate error handling.\"\n },\n {\n \"excerpt\": \"The jvt register is an XLEN-bit WARL read/write register that holds the jump table configuration, consisting of the jump table base address (BASE) and the jump table mode (MODE).\",\n \"line_number\": 2398,\n \"parameter_name\": \"JVT_BASE_MASK\",\n \"existing_udb_name\": \"JVT_BASE_MASK\",\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"bitmask\",\n \"confidence\": \"high\",\n \"reasoning\": \"The jvt CSR is WARL, and the set of legal values for the BASE field (bits XLEN-1:6) varies by implementation. The parameter is the mask of supported base address bits.\"\n },\n {\n \"excerpt\": \"If jvt is writable, the set of values the register may hold can vary by implementation.\",\n \"line_number\": 2404,\n \"parameter_name\": \"JVT_READ_ONLY\",\n \"existing_udb_name\": \"JVT_READ_ONLY\",\n \"class\": \"NORM_CSR_RW\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether the jvt CSR is read-only or read-write. This is a binary choice about the mutability of the register.\"\n },\n {\n \"excerpt\": \"jvt.mode is a WARL field, so can only be programmed to modes which are implemented.\",\n \"line_number\": 2424,\n \"parameter_name\": \"JVT_BASE_TYPE\",\n \"existing_udb_name\": \"JVT_BASE_TYPE\",\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The jvt.mode field is WARL, and implementations choose which mode values are supported. Currently only mode 000000 (Jump table mode) is defined and must be implemented, but the parameter represents the set of legal mode values.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"NOTE: Zcb can be implemented on any CPU as the instructions are 16-bit versions of existing 32-bit instructions from the application class profile.\",\n \"line_number\": 130,\n \"reason\": \"This is inside a NOTE block and is therefore non-normative. It provides implementation guidance but does not define an architectural parameter.\"\n },\n {\n \"excerpt\": \"This instruction loads a byte from the memory address formed by adding rs1' to the zero extended immediate uimm. The resulting byte is zero extended to XLEN bits and is written to rd'.\",\n \"line_number\": 306,\n \"reason\": \"This describes the operational behavior of the c.lbu instruction, not an implementation choice. The behavior is fixed for all implementations.\"\n },\n {\n \"excerpt\": \"All encodings are currently reserved for all architectures, and have no conflicts with any existing extensions.\",\n \"line_number\": 126,\n \"reason\": \"This is a statement about encoding space allocation, not an implementation-defined parameter. It describes a fixed property of the specification.\"\n },\n {\n \"excerpt\": \"For this encoding to decode as cm.jt, index<32, otherwise it decodes as cm.jalt\",\n \"line_number\": 2476,\n \"reason\": \"This describes the fixed decoding rule that applies to all implementations. It is not an implementation choice but a specification requirement.\"\n }\n ]\n}\n```", + "input_tokens": 31540, + "output_tokens": 1204, + "latency_ms": 23698, + "timestamp": "2026-04-15T15:05:24.460336+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_066.json.license b/param_extraction/results/claude-sonnet-4/chunk_066.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_066.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_067.json b/param_extraction/results/claude-sonnet-4/chunk_067.json new file mode 100644 index 0000000000..49ab81cf7c --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_067.json @@ -0,0 +1,54 @@ +{ + "chunk_id": "chunk_067", + "source_file": "zfa.adoc", + "start_line": 1, + "end_line": 261, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "Other _rm_ values are _reserved_.", + "line_number": 179, + "parameter_name": "FCVTMOD_RM_RESERVED_BEHAVIOR", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "medium", + "reasoning": "The behavior when reserved rm values are used in FCVTMOD.W.D is implementation-defined. The spec states they are reserved but doesn't specify what happens when they are used." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "The set of 32 constants was chosen by examining floating-point libraries, including the C standard math library, and to optimize fixed-point to floating-point conversion.", + "line_number": 60, + "reason": "This is inside a [NOTE] block, which is non-normative. It explains the rationale for the constant selection but doesn't define an implementation parameter." + }, + { + "excerpt": "The FLI._fmt_ instructions never set any floating-point exception flags.", + "line_number": 95, + "reason": "This is a fixed requirement that applies to all implementations. There is no implementation choice - all implementations must behave this way." + }, + { + "excerpt": "Zero and infinite inputs are copied to _rd_ unmodified.", + "line_number": 118, + "reason": "This describes the required behavior for specific input values. It's a fixed specification requirement, not an implementation choice." + }, + { + "excerpt": "For RV32 only, if the D extension is implemented, the FMVH.X.D instruction moves bits 63:32 of floating-point register _rs1_ into integer register _rd_.", + "line_number": 186, + "reason": "This describes the fixed operation of an instruction. The behavior is completely specified and not implementation-defined." + }, + { + "excerpt": "These instructions are encoded like their FLE and FLT counterparts, but with instruction bit 14 set to 1.", + "line_number": 245, + "reason": "This specifies the fixed encoding format for instructions. All implementations must use this encoding - there is no choice involved." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"Other _rm_ values are _reserved_.\",\n \"line_number\": 179,\n \"parameter_name\": \"FCVTMOD_RM_RESERVED_BEHAVIOR\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"medium\",\n \"reasoning\": \"The behavior when reserved rm values are used in FCVTMOD.W.D is implementation-defined. The spec states they are reserved but doesn't specify what happens when they are used.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"The set of 32 constants was chosen by examining floating-point libraries, including the C standard math library, and to optimize fixed-point to floating-point conversion.\",\n \"line_number\": 60,\n \"reason\": \"This is inside a [NOTE] block, which is non-normative. It explains the rationale for the constant selection but doesn't define an implementation parameter.\"\n },\n {\n \"excerpt\": \"The FLI._fmt_ instructions never set any floating-point exception flags.\",\n \"line_number\": 95,\n \"reason\": \"This is a fixed requirement that applies to all implementations. There is no implementation choice - all implementations must behave this way.\"\n },\n {\n \"excerpt\": \"Zero and infinite inputs are copied to _rd_ unmodified.\",\n \"line_number\": 118,\n \"reason\": \"This describes the required behavior for specific input values. It's a fixed specification requirement, not an implementation choice.\"\n },\n {\n \"excerpt\": \"For RV32 only, if the D extension is implemented, the FMVH.X.D instruction moves bits 63:32 of floating-point register _rs1_ into integer register _rd_.\",\n \"line_number\": 186,\n \"reason\": \"This describes the fixed operation of an instruction. The behavior is completely specified and not implementation-defined.\"\n },\n {\n \"excerpt\": \"These instructions are encoded like their FLE and FLT counterparts, but with instruction bit 14 set to 1.\",\n \"line_number\": 245,\n \"reason\": \"This specifies the fixed encoding format for instructions. All implementations must use this encoding - there is no choice involved.\"\n }\n ]\n}\n```", + "input_tokens": 9480, + "output_tokens": 581, + "latency_ms": 11620, + "timestamp": "2026-04-15T15:06:37.114752+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_067.json.license b/param_extraction/results/claude-sonnet-4/chunk_067.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_067.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_068.json b/param_extraction/results/claude-sonnet-4/chunk_068.json new file mode 100644 index 0000000000..77ebb2166e --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_068.json @@ -0,0 +1,43 @@ +{ + "chunk_id": "chunk_068", + "source_file": "zfh.adoc", + "start_line": 1, + "end_line": 186, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [], + "skipped_non_parameters": [ + { + "excerpt": "This extension primarily provides instructions that consume half-precision operands and produce half-precision results. However, it is also common to compute on half-precision data using higher intermediate precision.", + "line_number": 13, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks." + }, + { + "excerpt": "FLH and FSH are only guaranteed to execute atomically if the effective address is naturally aligned.", + "line_number": 32, + "reason": "This is a fixed requirement that applies to all implementations - there is no implementation choice here." + }, + { + "excerpt": "FCVT.L[U].H and FCVT.H.L[U] are RV64-only instructions.", + "line_number": 73, + "reason": "This is a fixed requirement based on the base ISA (RV64), not an implementation-defined parameter." + }, + { + "excerpt": "The Zfhmin extension includes the following instructions from the Zfh extension: FLH, FSH, FMV.X.H, FMV.H.X, FCVT.S.H, and FCVT.H.S.", + "line_number": 147, + "reason": "This defines the fixed contents of the Zfhmin extension - it is a specification requirement, not an implementation choice." + }, + { + "excerpt": "Zfhmin does not include the FSGNJ.H instruction, because it suffices to instead use the FSGNJ.S instruction to move half-precision values between floating-point registers.", + "line_number": 153, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. Additionally, it describes what is not included in Zfhmin, which is a fixed specification requirement." + } + ], + "raw_response": "```json\n{\n \"parameters\": [],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"This extension primarily provides instructions that consume half-precision operands and produce half-precision results. However, it is also common to compute on half-precision data using higher intermediate precision.\",\n \"line_number\": 13,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks.\"\n },\n {\n \"excerpt\": \"FLH and FSH are only guaranteed to execute atomically if the effective address is naturally aligned.\",\n \"line_number\": 32,\n \"reason\": \"This is a fixed requirement that applies to all implementations - there is no implementation choice here.\"\n },\n {\n \"excerpt\": \"FCVT.L[U].H and FCVT.H.L[U] are RV64-only instructions.\",\n \"line_number\": 73,\n \"reason\": \"This is a fixed requirement based on the base ISA (RV64), not an implementation-defined parameter.\"\n },\n {\n \"excerpt\": \"The Zfhmin extension includes the following instructions from the Zfh extension: FLH, FSH, FMV.X.H, FMV.H.X, FCVT.S.H, and FCVT.H.S.\",\n \"line_number\": 147,\n \"reason\": \"This defines the fixed contents of the Zfhmin extension - it is a specification requirement, not an implementation choice.\"\n },\n {\n \"excerpt\": \"Zfhmin does not include the FSGNJ.H instruction, because it suffices to instead use the FSGNJ.S instruction to move half-precision values between floating-point registers.\",\n \"line_number\": 153,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. Additionally, it describes what is not included in Zfhmin, which is a fixed specification requirement.\"\n }\n ]\n}\n```", + "input_tokens": 8158, + "output_tokens": 494, + "latency_ms": 7879, + "timestamp": "2026-04-15T14:54:31.147794+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_068.json.license b/param_extraction/results/claude-sonnet-4/chunk_068.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_068.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_069.json b/param_extraction/results/claude-sonnet-4/chunk_069.json new file mode 100644 index 0000000000..9d190b7094 --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_069.json @@ -0,0 +1,84 @@ +{ + "chunk_id": "chunk_069", + "source_file": "zfinx.adoc", + "start_line": 1, + "end_line": 162, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "In the standard privileged architecture defined in Volume II, the `mstatus` field FS is hardwired to 0 if the Zfinx extension is implemented, and FS no longer affects the trapping behavior of floating-point instructions or `fcsr` accesses.", + "line_number": 143, + "parameter_name": "MSTATUS_FS_LEGAL_VALUES", + "existing_udb_name": "MSTATUS_FS_LEGAL_VALUES", + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "When Zfinx is implemented, mstatus.FS is hardwired to 0, meaning the only legal value is 0. This constrains the WARL field's legal values based on the extension implementation." + }, + { + "excerpt": "The `misa` bits F, D, and Q are hardwired to 0 when the Zfinx extension is implemented.", + "line_number": 147, + "parameter_name": "MUTABLE_MISA_F", + "existing_udb_name": "MUTABLE_MISA_F", + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "When Zfinx is implemented, misa.F is hardwired to 0, constraining its legal values. This affects the WARL behavior of the misa.F field." + }, + { + "excerpt": "The `misa` bits F, D, and Q are hardwired to 0 when the Zfinx extension is implemented.", + "line_number": 147, + "parameter_name": "MUTABLE_MISA_D", + "existing_udb_name": "MUTABLE_MISA_D", + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "When Zfinx is implemented, misa.D is hardwired to 0, constraining its legal values. This affects the WARL behavior of the misa.D field." + }, + { + "excerpt": "The `misa` bits F, D, and Q are hardwired to 0 when the Zfinx extension is implemented.", + "line_number": 147, + "parameter_name": "MUTABLE_MISA_Q", + "existing_udb_name": "MUTABLE_MISA_Q", + "class": "NORM_CSR_WARL", + "value_type": "set", + "confidence": "high", + "reasoning": "When Zfinx is implemented, misa.Q is hardwired to 0, constraining its legal values. This affects the WARL behavior of the misa.Q field." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "The F extension uses separate `f` registers for floating-point computation, to reduce register pressure and simplify the provision of register-file ports for wide superscalars.", + "line_number": 13, + "reason": "This is inside a [NOTE] block, which is non-normative informational text. Parameters are never extracted from NOTE blocks." + }, + { + "excerpt": "The Zfinx extension adds all of the instructions that the F extension adds, _except_ for the transfer instructions FLW, FSW, FMV.W.X, FMV.X.W, C.FLW[SP], and C.FSW[SP].", + "line_number": 25, + "reason": "This is a fixed requirement defining what instructions are included in the extension. It's not an implementation choice - all Zfinx implementations must include these specific instructions." + }, + { + "excerpt": "Floating-point operands of width _w_ < XLEN bits occupy bits _w_-1:0 of an `x` register.", + "line_number": 40, + "reason": "This describes the fixed format for how narrow operands are stored in registers. It's a requirement that all implementations must follow, not a choice." + }, + { + "excerpt": "Double-precision operands in RV32Zdinx are held in aligned `x`-register pairs, i.e., register numbers must be even.", + "line_number": 75, + "reason": "This is a fixed requirement for how double-precision operands must be stored in RV32Zdinx. All implementations must follow this rule - it's not an implementation choice." + }, + { + "excerpt": "A future discoverability mechanism might be used to probe the existence of the Zfinx, Zhinx, and Zdinx extensions.", + "line_number": 149, + "reason": "This is inside a [NOTE] block discussing future possibilities, making it non-normative. It doesn't define any current implementation parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"In the standard privileged architecture defined in Volume II, the `mstatus` field FS is hardwired to 0 if the Zfinx extension is implemented, and FS no longer affects the trapping behavior of floating-point instructions or `fcsr` accesses.\",\n \"line_number\": 143,\n \"parameter_name\": \"MSTATUS_FS_LEGAL_VALUES\",\n \"existing_udb_name\": \"MSTATUS_FS_LEGAL_VALUES\",\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"When Zfinx is implemented, mstatus.FS is hardwired to 0, meaning the only legal value is 0. This constrains the WARL field's legal values based on the extension implementation.\"\n },\n {\n \"excerpt\": \"The `misa` bits F, D, and Q are hardwired to 0 when the Zfinx extension is implemented.\",\n \"line_number\": 147,\n \"parameter_name\": \"MUTABLE_MISA_F\",\n \"existing_udb_name\": \"MUTABLE_MISA_F\",\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"When Zfinx is implemented, misa.F is hardwired to 0, constraining its legal values. This affects the WARL behavior of the misa.F field.\"\n },\n {\n \"excerpt\": \"The `misa` bits F, D, and Q are hardwired to 0 when the Zfinx extension is implemented.\",\n \"line_number\": 147,\n \"parameter_name\": \"MUTABLE_MISA_D\",\n \"existing_udb_name\": \"MUTABLE_MISA_D\",\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"When Zfinx is implemented, misa.D is hardwired to 0, constraining its legal values. This affects the WARL behavior of the misa.D field.\"\n },\n {\n \"excerpt\": \"The `misa` bits F, D, and Q are hardwired to 0 when the Zfinx extension is implemented.\",\n \"line_number\": 147,\n \"parameter_name\": \"MUTABLE_MISA_Q\",\n \"existing_udb_name\": \"MUTABLE_MISA_Q\",\n \"class\": \"NORM_CSR_WARL\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"When Zfinx is implemented, misa.Q is hardwired to 0, constraining its legal values. This affects the WARL behavior of the misa.Q field.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"The F extension uses separate `f` registers for floating-point computation, to reduce register pressure and simplify the provision of register-file ports for wide superscalars.\",\n \"line_number\": 13,\n \"reason\": \"This is inside a [NOTE] block, which is non-normative informational text. Parameters are never extracted from NOTE blocks.\"\n },\n {\n \"excerpt\": \"The Zfinx extension adds all of the instructions that the F extension adds, _except_ for the transfer instructions FLW, FSW, FMV.W.X, FMV.X.W, C.FLW[SP], and C.FSW[SP].\",\n \"line_number\": 25,\n \"reason\": \"This is a fixed requirement defining what instructions are included in the extension. It's not an implementation choice - all Zfinx implementations must include these specific instructions.\"\n },\n {\n \"excerpt\": \"Floating-point operands of width _w_ < XLEN bits occupy bits _w_-1:0 of an `x` register.\",\n \"line_number\": 40,\n \"reason\": \"This describes the fixed format for how narrow operands are stored in registers. It's a requirement that all implementations must follow, not a choice.\"\n },\n {\n \"excerpt\": \"Double-precision operands in RV32Zdinx are held in aligned `x`-register pairs, i.e., register numbers must be even.\",\n \"line_number\": 75,\n \"reason\": \"This is a fixed requirement for how double-precision operands must be stored in RV32Zdinx. All implementations must follow this rule - it's not an implementation choice.\"\n },\n {\n \"excerpt\": \"A future discoverability mechanism might be used to probe the existence of the Zfinx, Zhinx, and Zdinx extensions.\",\n \"line_number\": 149,\n \"reason\": \"This is inside a [NOTE] block discussing future possibilities, making it non-normative. It doesn't define any current implementation parameter.\"\n }\n ]\n}\n```", + "input_tokens": 7572, + "output_tokens": 1260, + "latency_ms": 16318, + "timestamp": "2026-04-15T14:54:50.508537+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_069.json.license b/param_extraction/results/claude-sonnet-4/chunk_069.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_069.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_070.json b/param_extraction/results/claude-sonnet-4/chunk_070.json new file mode 100644 index 0000000000..c760058b20 --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_070.json @@ -0,0 +1,38 @@ +{ + "chunk_id": "chunk_070", + "source_file": "zicond.adoc", + "start_line": 1, + "end_line": 187, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [], + "skipped_non_parameters": [ + { + "excerpt": "If _rs2_ contains the value zero, this instruction writes the value zero to _rd_. Otherwise, this instruction copies the contents of _rs1_ to _rd_.", + "line_number": 44, + "reason": "This describes the fixed behavior of the czero.eqz instruction. All implementations must behave this way - it is not an implementation choice." + }, + { + "excerpt": "Furthermore, if the Zkt extension is implemented, this instruction's timing is independent of the data values in _rs1_ and _rs2_.", + "line_number": 47, + "reason": "This describes required behavior when Zkt is implemented. The timing independence is a fixed requirement, not an implementation parameter." + }, + { + "excerpt": "If _rs2_ contains a nonzero value, this instruction writes the value zero to _rd_. Otherwise, this instruction copies the contents of _rs1_ to _rd_.", + "line_number": 78, + "reason": "This describes the fixed behavior of the czero.nez instruction. All implementations must behave this way - it is not an implementation choice." + }, + { + "excerpt": "This instruction carries a syntactic dependency from both _rs1_ and _rs2_ to _rd_.", + "line_number": 46, + "reason": "This describes a fixed requirement about instruction dependencies that all implementations must follow. It is not a parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"If _rs2_ contains the value zero, this instruction writes the value zero to _rd_. Otherwise, this instruction copies the contents of _rs1_ to _rd_.\",\n \"line_number\": 44,\n \"reason\": \"This describes the fixed behavior of the czero.eqz instruction. All implementations must behave this way - it is not an implementation choice.\"\n },\n {\n \"excerpt\": \"Furthermore, if the Zkt extension is implemented, this instruction's timing is independent of the data values in _rs1_ and _rs2_.\",\n \"line_number\": 47,\n \"reason\": \"This describes required behavior when Zkt is implemented. The timing independence is a fixed requirement, not an implementation parameter.\"\n },\n {\n \"excerpt\": \"If _rs2_ contains a nonzero value, this instruction writes the value zero to _rd_. Otherwise, this instruction copies the contents of _rs1_ to _rd_.\",\n \"line_number\": 78,\n \"reason\": \"This describes the fixed behavior of the czero.nez instruction. All implementations must behave this way - it is not an implementation choice.\"\n },\n {\n \"excerpt\": \"This instruction carries a syntactic dependency from both _rs1_ and _rs2_ to _rd_.\",\n \"line_number\": 46,\n \"reason\": \"This describes a fixed requirement about instruction dependencies that all implementations must follow. It is not a parameter.\"\n }\n ]\n}\n```", + "input_tokens": 7492, + "output_tokens": 379, + "latency_ms": 6838, + "timestamp": "2026-04-15T14:55:00.379136+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_070.json.license b/param_extraction/results/claude-sonnet-4/chunk_070.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_070.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_071.json b/param_extraction/results/claude-sonnet-4/chunk_071.json new file mode 100644 index 0000000000..e5b0fe2f6f --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_071.json @@ -0,0 +1,54 @@ +{ + "chunk_id": "chunk_071", + "source_file": "zicsr.adoc", + "start_line": 1, + "end_line": 254, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "The hardware platform may define that accesses to certain CSRs are strongly ordered, as defined by the Memory-Ordering PMAs section in Volume II of this manual.", + "line_number": 244, + "parameter_name": "CSR_STRONG_ORDERING", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "set", + "confidence": "high", + "reasoning": "The platform/implementation chooses which CSRs have strongly ordered access semantics versus the default weakly ordered behavior. This is a direct implementation choice about memory ordering properties." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "While CSRs are primarily used by the privileged architecture, there are several uses in unprivileged code including for counters and timers, and for floating-point status.", + "line_number": 9, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks." + }, + { + "excerpt": "The CSRRW (Atomic Read/Write CSR) instruction atomically swaps values in the CSRs and integer registers.", + "line_number": 26, + "reason": "This describes the fixed behavior of the CSRRW instruction that all implementations must follow. It is not an implementation choice." + }, + { + "excerpt": "If rd=x0, then the instruction shall not read the CSR and shall not cause any of the side effects that might occur on a CSR read.", + "line_number": 30, + "reason": "This describes deterministic behavior based on register encoding. The behavior is fixed by the ISA specification, not chosen by the implementer." + }, + { + "excerpt": "In particular, unless specified otherwise, a CSR access is performed after the execution of any prior instructions in program order whose behavior modifies or is modified by the CSR state", + "line_number": 186, + "reason": "This describes the required ordering behavior that all implementations must follow. It is a fixed requirement, not an implementation choice." + }, + { + "excerpt": "For the RVWMO memory consistency model, CSR accesses are weakly ordered by default", + "line_number": 202, + "reason": "This states the default ordering behavior that applies to all implementations under RVWMO. It is not an implementation choice but a specification requirement." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"The hardware platform may define that accesses to certain CSRs are strongly ordered, as defined by the Memory-Ordering PMAs section in Volume II of this manual.\",\n \"line_number\": 244,\n \"parameter_name\": \"CSR_STRONG_ORDERING\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"The platform/implementation chooses which CSRs have strongly ordered access semantics versus the default weakly ordered behavior. This is a direct implementation choice about memory ordering properties.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"While CSRs are primarily used by the privileged architecture, there are several uses in unprivileged code including for counters and timers, and for floating-point status.\",\n \"line_number\": 9,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks.\"\n },\n {\n \"excerpt\": \"The CSRRW (Atomic Read/Write CSR) instruction atomically swaps values in the CSRs and integer registers.\",\n \"line_number\": 26,\n \"reason\": \"This describes the fixed behavior of the CSRRW instruction that all implementations must follow. It is not an implementation choice.\"\n },\n {\n \"excerpt\": \"If rd=x0, then the instruction shall not read the CSR and shall not cause any of the side effects that might occur on a CSR read.\",\n \"line_number\": 30,\n \"reason\": \"This describes deterministic behavior based on register encoding. The behavior is fixed by the ISA specification, not chosen by the implementer.\"\n },\n {\n \"excerpt\": \"In particular, unless specified otherwise, a CSR access is performed after the execution of any prior instructions in program order whose behavior modifies or is modified by the CSR state\",\n \"line_number\": 186,\n \"reason\": \"This describes the required ordering behavior that all implementations must follow. It is a fixed requirement, not an implementation choice.\"\n },\n {\n \"excerpt\": \"For the RVWMO memory consistency model, CSR accesses are weakly ordered by default\",\n \"line_number\": 202,\n \"reason\": \"This states the default ordering behavior that applies to all implementations under RVWMO. It is not an implementation choice but a specification requirement.\"\n }\n ]\n}\n```", + "input_tokens": 9068, + "output_tokens": 618, + "latency_ms": 11529, + "timestamp": "2026-04-15T14:55:14.952840+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_071.json.license b/param_extraction/results/claude-sonnet-4/chunk_071.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_071.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_072.json b/param_extraction/results/claude-sonnet-4/chunk_072.json new file mode 100644 index 0000000000..a17f2334dd --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_072.json @@ -0,0 +1,54 @@ +{ + "chunk_id": "chunk_072", + "source_file": "zifencei.adoc", + "start_line": 1, + "end_line": 129, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "For forward compatibility, base implementations shall ignore these fields, and standard software shall zero these fields.", + "line_number": 108, + "parameter_name": "FENCE_I_RESERVED_FIELD_BEHAVIOR", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation must choose how to handle reserved fields in FENCE.I (funct12, rs1, rd). The spec requires they be ignored, but this is still an implementation choice about how to handle reserved encodings." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "We considered but did not include a \"store instruction word\" instruction as in cite:[majc]. JIT compilers may generate a large trace of instructions before a single FENCE.I, and amortize any instruction cache snooping/invalidation overhead by writing translated instructions to memory regions that are known not to reside in the I-cache.", + "line_number": 11, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. It describes design rationale, not an architectural requirement." + }, + { + "excerpt": "The FENCE.I instruction was designed to support a wide variety of implementations. A simple implementation can flush the local instruction cache and the instruction pipeline when the FENCE.I is executed.", + "line_number": 19, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. It describes possible implementation strategies but does not define required parameters." + }, + { + "excerpt": "RISC-V does not guarantee that stores to instruction memory will be made visible to instruction fetches on a RISC-V hart until that hart executes a FENCE.I instruction.", + "line_number": 66, + "reason": "This describes the required behavior of FENCE.I that all implementations must follow. It is a fixed requirement, not an implementation choice." + }, + { + "excerpt": "A FENCE.I instruction orders all explicit memory accesses that precede the FENCE.I in program order before all instruction fetches that follow the FENCE.I in program order.", + "line_number": 74, + "reason": "This defines the mandatory ordering semantics of FENCE.I that all implementations must provide. It is a fixed requirement, not a parameter." + }, + { + "excerpt": "Because FENCE.I only orders stores with a hart's own instruction fetches, application code should only rely upon FENCE.I if the application thread will not be migrated to a different hart.", + "line_number": 113, + "reason": "This text is inside a [NOTE] block and describes software usage guidance, not an architectural parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"For forward compatibility, base implementations shall ignore these fields, and standard software shall zero these fields.\",\n \"line_number\": 108,\n \"parameter_name\": \"FENCE_I_RESERVED_FIELD_BEHAVIOR\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation must choose how to handle reserved fields in FENCE.I (funct12, rs1, rd). The spec requires they be ignored, but this is still an implementation choice about how to handle reserved encodings.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"We considered but did not include a \\\"store instruction word\\\" instruction as in cite:[majc]. JIT compilers may generate a large trace of instructions before a single FENCE.I, and amortize any instruction cache snooping/invalidation overhead by writing translated instructions to memory regions that are known not to reside in the I-cache.\",\n \"line_number\": 11,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. It describes design rationale, not an architectural requirement.\"\n },\n {\n \"excerpt\": \"The FENCE.I instruction was designed to support a wide variety of implementations. A simple implementation can flush the local instruction cache and the instruction pipeline when the FENCE.I is executed.\",\n \"line_number\": 19,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. It describes possible implementation strategies but does not define required parameters.\"\n },\n {\n \"excerpt\": \"RISC-V does not guarantee that stores to instruction memory will be made visible to instruction fetches on a RISC-V hart until that hart executes a FENCE.I instruction.\",\n \"line_number\": 66,\n \"reason\": \"This describes the required behavior of FENCE.I that all implementations must follow. It is a fixed requirement, not an implementation choice.\"\n },\n {\n \"excerpt\": \"A FENCE.I instruction orders all explicit memory accesses that precede the FENCE.I in program order before all instruction fetches that follow the FENCE.I in program order.\",\n \"line_number\": 74,\n \"reason\": \"This defines the mandatory ordering semantics of FENCE.I that all implementations must provide. It is a fixed requirement, not a parameter.\"\n },\n {\n \"excerpt\": \"Because FENCE.I only orders stores with a hart's own instruction fetches, application code should only rely upon FENCE.I if the application thread will not be migrated to a different hart.\",\n \"line_number\": 113,\n \"reason\": \"This text is inside a [NOTE] block and describes software usage guidance, not an architectural parameter.\"\n }\n ]\n}\n```", + "input_tokens": 7041, + "output_tokens": 695, + "latency_ms": 24548, + "timestamp": "2026-04-15T14:55:40.628399+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_072.json.license b/param_extraction/results/claude-sonnet-4/chunk_072.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_072.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_073.json b/param_extraction/results/claude-sonnet-4/chunk_073.json new file mode 100644 index 0000000000..920bb9448b --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_073.json @@ -0,0 +1,43 @@ +{ + "chunk_id": "chunk_073", + "source_file": "zihintntl.adoc", + "start_line": 1, + "end_line": 189, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [], + "skipped_non_parameters": [ + { + "excerpt": "The NTL instructions do not change architectural state, nor do they alter the architecturally visible effects of the target instruction.", + "line_number": 7, + "reason": "This is a fixed requirement that applies to all implementations - NTL instructions must not change architectural state. No implementation choice is involved." + }, + { + "excerpt": "NTL.P1 is encoded as ADD _x0, x0, x2_.", + "line_number": 14, + "reason": "This specifies a fixed encoding that all implementations must use. There is no implementation choice in the encoding." + }, + { + "excerpt": "The NTL instructions affect all memory-access instructions except the cache-management instructions in the Zicbom extension.", + "line_number": 82, + "reason": "This defines the fixed scope of NTL instructions - which instruction types they affect is not implementation-defined." + }, + { + "excerpt": "In the event that a trap is taken on the target instruction, implementations are discouraged from applying the NTL to the first instruction in the trap handler.", + "line_number": 149, + "reason": "This is a recommendation ('discouraged', 'recommended') about implementation behavior, but it's in a non-normative context and doesn't define a required architectural parameter." + }, + { + "excerpt": "A microarchitecture might use the NTL instructions to inform the cache replacement policy, or to decide which cache to allocate into, or to avoid cache allocation altogether.", + "line_number": 25, + "reason": "This text is inside a [NOTE] block, making it non-normative. Even though it describes implementation choices, parameters should not be extracted from NOTE blocks." + } + ], + "raw_response": "```json\n{\n \"parameters\": [],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"The NTL instructions do not change architectural state, nor do they alter the architecturally visible effects of the target instruction.\",\n \"line_number\": 7,\n \"reason\": \"This is a fixed requirement that applies to all implementations - NTL instructions must not change architectural state. No implementation choice is involved.\"\n },\n {\n \"excerpt\": \"NTL.P1 is encoded as ADD _x0, x0, x2_.\",\n \"line_number\": 14,\n \"reason\": \"This specifies a fixed encoding that all implementations must use. There is no implementation choice in the encoding.\"\n },\n {\n \"excerpt\": \"The NTL instructions affect all memory-access instructions except the cache-management instructions in the Zicbom extension.\",\n \"line_number\": 82,\n \"reason\": \"This defines the fixed scope of NTL instructions - which instruction types they affect is not implementation-defined.\"\n },\n {\n \"excerpt\": \"In the event that a trap is taken on the target instruction, implementations are discouraged from applying the NTL to the first instruction in the trap handler.\",\n \"line_number\": 149,\n \"reason\": \"This is a recommendation ('discouraged', 'recommended') about implementation behavior, but it's in a non-normative context and doesn't define a required architectural parameter.\"\n },\n {\n \"excerpt\": \"A microarchitecture might use the NTL instructions to inform the cache replacement policy, or to decide which cache to allocate into, or to avoid cache allocation altogether.\",\n \"line_number\": 25,\n \"reason\": \"This text is inside a [NOTE] block, making it non-normative. Even though it describes implementation choices, parameters should not be extracted from NOTE blocks.\"\n }\n ]\n}\n```", + "input_tokens": 8272, + "output_tokens": 451, + "latency_ms": 23915, + "timestamp": "2026-04-15T14:56:06.551379+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_073.json.license b/param_extraction/results/claude-sonnet-4/chunk_073.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_073.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_074.json b/param_extraction/results/claude-sonnet-4/chunk_074.json new file mode 100644 index 0000000000..a107b12a68 --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_074.json @@ -0,0 +1,49 @@ +{ + "chunk_id": "chunk_074", + "source_file": "zihintpause.adoc", + "start_line": 1, + "end_line": 56, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "The duration of its effect must be bounded and may be zero.", + "line_number": 5, + "parameter_name": "PAUSE_DURATION", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "range", + "confidence": "high", + "reasoning": "The implementation chooses the duration of the PAUSE effect, with the constraint that it must be bounded and may be zero. This is a direct implementation choice about timing behavior." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "Software can use the PAUSE instruction to reduce energy consumption while executing spin-wait code sequences.", + "line_number": 10, + "reason": "This is inside a [NOTE] block, which is non-normative. It describes software usage, not an implementation parameter." + }, + { + "excerpt": "The duration of a PAUSE instruction's effect may vary significantly within and among implementations.", + "line_number": 16, + "reason": "This is inside a [NOTE] block, which is non-normative. While it mentions implementation variation, it's informative guidance, not a normative parameter definition." + }, + { + "excerpt": "PAUSE is encoded as a FENCE instruction with _pred_=`W`, _succ_=`0`, _fm_=`0`, _rd_=`x0`, and _rs1_=`x0`.", + "line_number": 31, + "reason": "This is a fixed encoding requirement that all implementations must follow. There is no implementation choice here." + }, + { + "excerpt": "PAUSE does not _mandate_ any particular memory ordering\u2014hence, it truly is a HINT.", + "line_number": 40, + "reason": "This describes what PAUSE does not require, which is a fixed behavioral specification, not an implementation parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"The duration of its effect must be bounded and may be zero.\",\n \"line_number\": 5,\n \"parameter_name\": \"PAUSE_DURATION\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"range\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses the duration of the PAUSE effect, with the constraint that it must be bounded and may be zero. This is a direct implementation choice about timing behavior.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"Software can use the PAUSE instruction to reduce energy consumption while executing spin-wait code sequences.\",\n \"line_number\": 10,\n \"reason\": \"This is inside a [NOTE] block, which is non-normative. It describes software usage, not an implementation parameter.\"\n },\n {\n \"excerpt\": \"The duration of a PAUSE instruction's effect may vary significantly within and among implementations.\",\n \"line_number\": 16,\n \"reason\": \"This is inside a [NOTE] block, which is non-normative. While it mentions implementation variation, it's informative guidance, not a normative parameter definition.\"\n },\n {\n \"excerpt\": \"PAUSE is encoded as a FENCE instruction with _pred_=`W`, _succ_=`0`, _fm_=`0`, _rd_=`x0`, and _rs1_=`x0`.\",\n \"line_number\": 31,\n \"reason\": \"This is a fixed encoding requirement that all implementations must follow. There is no implementation choice here.\"\n },\n {\n \"excerpt\": \"PAUSE does not _mandate_ any particular memory ordering\u2014hence, it truly is a HINT.\",\n \"line_number\": 40,\n \"reason\": \"This describes what PAUSE does not require, which is a fixed behavioral specification, not an implementation parameter.\"\n }\n ]\n}\n```", + "input_tokens": 6174, + "output_tokens": 487, + "latency_ms": 27410, + "timestamp": "2026-04-15T14:56:37.005424+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_074.json.license b/param_extraction/results/claude-sonnet-4/chunk_074.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_074.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_075.json b/param_extraction/results/claude-sonnet-4/chunk_075.json new file mode 100644 index 0000000000..4fc03a6919 --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_075.json @@ -0,0 +1,64 @@ +{ + "chunk_id": "chunk_075", + "source_file": "zilsd.adoc", + "start_line": 1, + "end_line": 315, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "Even if naturally aligned, the memory access might not be performed atomically.", + "line_number": 33, + "parameter_name": "ZILSD_8BYTE_ATOMIC", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "The implementation chooses whether 8-byte aligned accesses are performed atomically or not. This is a direct implementation choice not controlled by any CSR field." + }, + { + "excerpt": "If the effective address is a multiple of 4, then each word access is required to be performed atomically.", + "line_number": 34, + "parameter_name": "ZILSD_4BYTE_WORD_ATOMIC", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "medium", + "reasoning": "While stated as 'required', this appears to be describing an implementation constraint that can be satisfied in different ways (single atomic access vs two atomic word accesses), making it an implementation choice." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "Operands containing `src` for store instructions and `dest` for load instructions are held in aligned `x`-register pairs, i.e., register numbers must be even.", + "line_number": 6, + "reason": "This is a fixed architectural requirement that all implementations must follow - register pairs must be even-numbered. No implementation choice." + }, + { + "excerpt": "As the access size is 64-bit, accesses are only considered naturally aligned for effective addresses that are a multiple of 8. In this case, these instructions are guaranteed to not raise an address-misaligned exception.", + "line_number": 31, + "reason": "This defines what constitutes natural alignment and the guaranteed behavior - it's a fixed rule, not an implementation choice." + }, + { + "excerpt": "To ensure resumable trap handling is possible for the load instructions, the base register must have its original value if a trap is taken.", + "line_number": 45, + "reason": "This is a fixed requirement for trap handling that all implementations must satisfy, not an optional behavior." + }, + { + "excerpt": "For the purposes of RVWMO and exception handling, LD and SD instructions are considered to be misaligned loads and stores", + "line_number": 89, + "reason": "This defines how these instructions are categorized for memory model purposes - it's a fixed classification, not an implementation choice." + }, + { + "excerpt": "If an implementation performs a doubleword load access atomically and the register file implements write-back for even/odd register pairs, the mentioned atomicity requirements are inherently fulfilled.", + "line_number": 48, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. It provides implementation guidance but is not a requirement." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"Even if naturally aligned, the memory access might not be performed atomically.\",\n \"line_number\": 33,\n \"parameter_name\": \"ZILSD_8BYTE_ATOMIC\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"The implementation chooses whether 8-byte aligned accesses are performed atomically or not. This is a direct implementation choice not controlled by any CSR field.\"\n },\n {\n \"excerpt\": \"If the effective address is a multiple of 4, then each word access is required to be performed atomically.\",\n \"line_number\": 34,\n \"parameter_name\": \"ZILSD_4BYTE_WORD_ATOMIC\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"medium\",\n \"reasoning\": \"While stated as 'required', this appears to be describing an implementation constraint that can be satisfied in different ways (single atomic access vs two atomic word accesses), making it an implementation choice.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"Operands containing `src` for store instructions and `dest` for load instructions are held in aligned `x`-register pairs, i.e., register numbers must be even.\",\n \"line_number\": 6,\n \"reason\": \"This is a fixed architectural requirement that all implementations must follow - register pairs must be even-numbered. No implementation choice.\"\n },\n {\n \"excerpt\": \"As the access size is 64-bit, accesses are only considered naturally aligned for effective addresses that are a multiple of 8. In this case, these instructions are guaranteed to not raise an address-misaligned exception.\",\n \"line_number\": 31,\n \"reason\": \"This defines what constitutes natural alignment and the guaranteed behavior - it's a fixed rule, not an implementation choice.\"\n },\n {\n \"excerpt\": \"To ensure resumable trap handling is possible for the load instructions, the base register must have its original value if a trap is taken.\",\n \"line_number\": 45,\n \"reason\": \"This is a fixed requirement for trap handling that all implementations must satisfy, not an optional behavior.\"\n },\n {\n \"excerpt\": \"For the purposes of RVWMO and exception handling, LD and SD instructions are considered to be misaligned loads and stores\",\n \"line_number\": 89,\n \"reason\": \"This defines how these instructions are categorized for memory model purposes - it's a fixed classification, not an implementation choice.\"\n },\n {\n \"excerpt\": \"If an implementation performs a doubleword load access atomically and the register file implements write-back for even/odd register pairs, the mentioned atomicity requirements are inherently fulfilled.\",\n \"line_number\": 48,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. It provides implementation guidance but is not a requirement.\"\n }\n ]\n}\n```", + "input_tokens": 9178, + "output_tokens": 760, + "latency_ms": 29101, + "timestamp": "2026-04-15T14:57:09.122498+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_075.json.license b/param_extraction/results/claude-sonnet-4/chunk_075.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_075.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_076.json b/param_extraction/results/claude-sonnet-4/chunk_076.json new file mode 100644 index 0000000000..4caf198848 --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_076.json @@ -0,0 +1,43 @@ +{ + "chunk_id": "chunk_076", + "source_file": "zimop.adoc", + "start_line": 1, + "end_line": 113, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [], + "skipped_non_parameters": [ + { + "excerpt": "It is sometimes desirable to define instruction-set extensions whose instructions, rather than raising illegal-instruction exceptions when the extension is not implemented, take no useful action (beyond writing `x[rd]`).", + "line_number": 12, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks." + }, + { + "excerpt": "The Zimop extension defines 32 MOP instructions named MOP.R.__n__, where __n__ is an integer between 0 and 31, inclusive.", + "line_number": 29, + "reason": "This defines a fixed requirement - the extension defines exactly 32 instructions with specific names. This is not an implementation choice but a specification of what the extension provides." + }, + { + "excerpt": "Unless redefined by another extension, these instructions simply write 0 to `x[rd]`.", + "line_number": 31, + "reason": "This describes the default behavior of MOP instructions. The behavior is fixed by the specification - they write 0 to x[rd] unless redefined by another extension. This is not an implementation parameter." + }, + { + "excerpt": "The Zimop extension additionally defines 8 MOP instructions named MOP.RR.__n__, where __n__ is an integer between 0 and 7, inclusive.", + "line_number": 38, + "reason": "Similar to the MOP.R case, this defines a fixed requirement - exactly 8 instructions with specific names. This is specification content, not an implementation choice." + }, + { + "excerpt": "This section defines the \"Zcmop\" extension, which defines eight 16-bit MOP instructions named C.MOP.__n__, where __n__ is an odd integer between 1 and 15, inclusive.", + "line_number": 62, + "reason": "This defines the fixed content of the Zcmop extension - exactly 8 instructions with specific names and encodings. This is not an implementation parameter but a specification requirement." + } + ], + "raw_response": "```json\n{\n \"parameters\": [],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"It is sometimes desirable to define instruction-set extensions whose instructions, rather than raising illegal-instruction exceptions when the extension is not implemented, take no useful action (beyond writing `x[rd]`).\",\n \"line_number\": 12,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks.\"\n },\n {\n \"excerpt\": \"The Zimop extension defines 32 MOP instructions named MOP.R.__n__, where __n__ is an integer between 0 and 31, inclusive.\",\n \"line_number\": 29,\n \"reason\": \"This defines a fixed requirement - the extension defines exactly 32 instructions with specific names. This is not an implementation choice but a specification of what the extension provides.\"\n },\n {\n \"excerpt\": \"Unless redefined by another extension, these instructions simply write 0 to `x[rd]`.\",\n \"line_number\": 31,\n \"reason\": \"This describes the default behavior of MOP instructions. The behavior is fixed by the specification - they write 0 to x[rd] unless redefined by another extension. This is not an implementation parameter.\"\n },\n {\n \"excerpt\": \"The Zimop extension additionally defines 8 MOP instructions named MOP.RR.__n__, where __n__ is an integer between 0 and 7, inclusive.\",\n \"line_number\": 38,\n \"reason\": \"Similar to the MOP.R case, this defines a fixed requirement - exactly 8 instructions with specific names. This is specification content, not an implementation choice.\"\n },\n {\n \"excerpt\": \"This section defines the \\\"Zcmop\\\" extension, which defines eight 16-bit MOP instructions named C.MOP.__n__, where __n__ is an odd integer between 1 and 15, inclusive.\",\n \"line_number\": 62,\n \"reason\": \"This defines the fixed content of the Zcmop extension - exactly 8 instructions with specific names and encodings. This is not an implementation parameter but a specification requirement.\"\n }\n ]\n}\n```", + "input_tokens": 7113, + "output_tokens": 531, + "latency_ms": 27168, + "timestamp": "2026-04-15T14:57:39.316143+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_076.json.license b/param_extraction/results/claude-sonnet-4/chunk_076.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_076.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_077.json b/param_extraction/results/claude-sonnet-4/chunk_077.json new file mode 100644 index 0000000000..27cc14f0f6 --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_077.json @@ -0,0 +1,74 @@ +{ + "chunk_id": "chunk_077", + "source_file": "zpm.adoc", + "start_line": 1, + "end_line": 223, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [ + { + "excerpt": "The current standard only supports PMLEN=XLEN-48 (i.e., PMLEN=16 in RV64) and PMLEN=XLEN-57 (i.e., PMLEN=7 in RV64). A setting has been reserved to potentially support other values of PMLEN in future standards.", + "line_number": 108, + "parameter_name": "PMLEN", + "existing_udb_name": "PMLEN", + "class": "NORM_DIRECT", + "value_type": "enum", + "confidence": "high", + "reasoning": "PMLEN is a direct implementation parameter that determines how many upper bits are masked. The spec defines specific supported values (16 or 7 for RV64) that implementations must choose from." + }, + { + "excerpt": "Pointer masking only applies to RV64. In RV32, trying to enable pointer masking will result in an illegal WARL write and not update the pointer masking configuration bits", + "line_number": 189, + "parameter_name": "POINTER_MASKING_RV32_SUPPORT", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "binary", + "confidence": "high", + "reasoning": "This is a direct implementation choice about whether pointer masking is supported in RV32. The spec states it only applies to RV64, making this a binary architectural parameter." + }, + { + "excerpt": "Profiles and implementations may choose to support an arbitrary subset of these extensions and must define valid ranges for their corresponding values of PMLEN.", + "line_number": 167, + "parameter_name": "SUPPORTED_PM_EXTENSIONS", + "existing_udb_name": null, + "class": "NORM_DIRECT", + "value_type": "set", + "confidence": "high", + "reasoning": "Implementations can choose which subset of pointer masking extensions (Ssnpm, Smnpm, Smmpm, etc.) to support. This is a direct implementation choice of selecting from a defined set." + } + ], + "skipped_non_parameters": [ + { + "excerpt": "RISC-V Pointer Masking (PM) is a feature that, when enabled, causes the CPU to ignore the upper bits of the effective address", + "line_number": 7, + "reason": "This describes what pointer masking does when enabled, not an implementation choice about whether to support it or how to configure it." + }, + { + "excerpt": "When MODE=Direct, all traps into machine mode cause the `pc` to be set to the address in the BASE field.", + "line_number": 45, + "reason": "This describes behavior when a specific mode is active, not an implementation parameter. The behavior is determined by runtime CSR values." + }, + { + "excerpt": "Future versions of the pointer masking extension may introduce the ability to freely configure the value of PMLEN.", + "line_number": 113, + "reason": "This is inside a NOTE block discussing future possibilities, not a current architectural parameter that implementations can choose." + }, + { + "excerpt": "Pointer masking applies to all explicit memory accesses generated by instructions on the CPU", + "line_number": 142, + "reason": "This is a fixed requirement about which accesses are subject to pointer masking, not an implementation choice." + }, + { + "excerpt": "The behavior is identical to applying the pointer masking transformation to every constituent aligned memory access.", + "line_number": 155, + "reason": "This describes required behavior for misaligned accesses, not an implementation parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [\n {\n \"excerpt\": \"The current standard only supports PMLEN=XLEN-48 (i.e., PMLEN=16 in RV64) and PMLEN=XLEN-57 (i.e., PMLEN=7 in RV64). A setting has been reserved to potentially support other values of PMLEN in future standards.\",\n \"line_number\": 108,\n \"parameter_name\": \"PMLEN\",\n \"existing_udb_name\": \"PMLEN\",\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"enum\",\n \"confidence\": \"high\",\n \"reasoning\": \"PMLEN is a direct implementation parameter that determines how many upper bits are masked. The spec defines specific supported values (16 or 7 for RV64) that implementations must choose from.\"\n },\n {\n \"excerpt\": \"Pointer masking only applies to RV64. In RV32, trying to enable pointer masking will result in an illegal WARL write and not update the pointer masking configuration bits\",\n \"line_number\": 189,\n \"parameter_name\": \"POINTER_MASKING_RV32_SUPPORT\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"binary\",\n \"confidence\": \"high\",\n \"reasoning\": \"This is a direct implementation choice about whether pointer masking is supported in RV32. The spec states it only applies to RV64, making this a binary architectural parameter.\"\n },\n {\n \"excerpt\": \"Profiles and implementations may choose to support an arbitrary subset of these extensions and must define valid ranges for their corresponding values of PMLEN.\",\n \"line_number\": 167,\n \"parameter_name\": \"SUPPORTED_PM_EXTENSIONS\",\n \"existing_udb_name\": null,\n \"class\": \"NORM_DIRECT\",\n \"value_type\": \"set\",\n \"confidence\": \"high\",\n \"reasoning\": \"Implementations can choose which subset of pointer masking extensions (Ssnpm, Smnpm, Smmpm, etc.) to support. This is a direct implementation choice of selecting from a defined set.\"\n }\n ],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"RISC-V Pointer Masking (PM) is a feature that, when enabled, causes the CPU to ignore the upper bits of the effective address\",\n \"line_number\": 7,\n \"reason\": \"This describes what pointer masking does when enabled, not an implementation choice about whether to support it or how to configure it.\"\n },\n {\n \"excerpt\": \"When MODE=Direct, all traps into machine mode cause the `pc` to be set to the address in the BASE field.\",\n \"line_number\": 45,\n \"reason\": \"This describes behavior when a specific mode is active, not an implementation parameter. The behavior is determined by runtime CSR values.\"\n },\n {\n \"excerpt\": \"Future versions of the pointer masking extension may introduce the ability to freely configure the value of PMLEN.\",\n \"line_number\": 113,\n \"reason\": \"This is inside a NOTE block discussing future possibilities, not a current architectural parameter that implementations can choose.\"\n },\n {\n \"excerpt\": \"Pointer masking applies to all explicit memory accesses generated by instructions on the CPU\",\n \"line_number\": 142,\n \"reason\": \"This is a fixed requirement about which accesses are subject to pointer masking, not an implementation choice.\"\n },\n {\n \"excerpt\": \"The behavior is identical to applying the pointer masking transformation to every constituent aligned memory access.\",\n \"line_number\": 155,\n \"reason\": \"This describes required behavior for misaligned accesses, not an implementation parameter.\"\n }\n ]\n}\n```", + "input_tokens": 11094, + "output_tokens": 930, + "latency_ms": 38551, + "timestamp": "2026-04-15T14:58:20.892855+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_077.json.license b/param_extraction/results/claude-sonnet-4/chunk_077.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_077.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/results/claude-sonnet-4/chunk_078.json b/param_extraction/results/claude-sonnet-4/chunk_078.json new file mode 100644 index 0000000000..ca7387b8f9 --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_078.json @@ -0,0 +1,43 @@ +{ + "chunk_id": "chunk_078", + "source_file": "ztso-st-ext.adoc", + "start_line": 1, + "end_line": 49, + "content_start_line": 1, + "model": "claude-sonnet-4", + "parameters": [], + "skipped_non_parameters": [ + { + "excerpt": "_The Ztso extension is meant to facilitate the porting of code originally written for the x86 or SPARC architectures, both of which use TSO by default. It also supports implementations which inherently provide RVTSO behavior and want to expose that fact to software._", + "line_number": 8, + "reason": "This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks." + }, + { + "excerpt": "All load operations behave as if they have an acquire-RCpc annotation", + "line_number": 17, + "reason": "This is a fixed requirement that all implementations supporting Ztso must satisfy. There is no implementation choice - it defines mandatory behavior." + }, + { + "excerpt": "All store operations behave as if they have a release-RCpc annotation.", + "line_number": 18, + "reason": "This is a fixed requirement that all implementations supporting Ztso must satisfy. There is no implementation choice - it defines mandatory behavior." + }, + { + "excerpt": "Additionally, if the Ztso extension is implemented, then vector memory instructions in the V extension and Zve family of extensions follow RVTSO at the instruction level.", + "line_number": 34, + "reason": "This is a conditional requirement ('if Ztso is implemented, then...') but not a parameter. It defines mandatory behavior when the extension is present." + }, + { + "excerpt": "Binaries compiled to run only under Ztso should indicate as such via a flag in the binary, so that platforms which do not implement Ztso can simply refuse to run them.", + "line_number": 42, + "reason": "This describes a software/toolchain requirement about binary flags, not an architectural implementation parameter." + } + ], + "raw_response": "```json\n{\n \"parameters\": [],\n \"skipped_non_parameters\": [\n {\n \"excerpt\": \"_The Ztso extension is meant to facilitate the porting of code originally written for the x86 or SPARC architectures, both of which use TSO by default. It also supports implementations which inherently provide RVTSO behavior and want to expose that fact to software._\",\n \"line_number\": 8,\n \"reason\": \"This text is inside a [NOTE] block and is therefore non-normative. Do not extract parameters from NOTE blocks.\"\n },\n {\n \"excerpt\": \"All load operations behave as if they have an acquire-RCpc annotation\",\n \"line_number\": 17,\n \"reason\": \"This is a fixed requirement that all implementations supporting Ztso must satisfy. There is no implementation choice - it defines mandatory behavior.\"\n },\n {\n \"excerpt\": \"All store operations behave as if they have a release-RCpc annotation.\",\n \"line_number\": 18,\n \"reason\": \"This is a fixed requirement that all implementations supporting Ztso must satisfy. There is no implementation choice - it defines mandatory behavior.\"\n },\n {\n \"excerpt\": \"Additionally, if the Ztso extension is implemented, then vector memory instructions in the V extension and Zve family of extensions follow RVTSO at the instruction level.\",\n \"line_number\": 34,\n \"reason\": \"This is a conditional requirement ('if Ztso is implemented, then...') but not a parameter. It defines mandatory behavior when the extension is present.\"\n },\n {\n \"excerpt\": \"Binaries compiled to run only under Ztso should indicate as such via a flag in the binary, so that platforms which do not implement Ztso can simply refuse to run them.\",\n \"line_number\": 42,\n \"reason\": \"This describes a software/toolchain requirement about binary flags, not an architectural implementation parameter.\"\n }\n ]\n}\n```", + "input_tokens": 6229, + "output_tokens": 475, + "latency_ms": 29803, + "timestamp": "2026-04-15T14:58:51.099637+00:00", + "error": null, + "retry_count": 0 +} diff --git a/param_extraction/results/claude-sonnet-4/chunk_078.json.license b/param_extraction/results/claude-sonnet-4/chunk_078.json.license new file mode 100644 index 0000000000..53e9027cad --- /dev/null +++ b/param_extraction/results/claude-sonnet-4/chunk_078.json.license @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear diff --git a/param_extraction/scripts/chunker.py b/param_extraction/scripts/chunker.py new file mode 100755 index 0000000000..cf24fc7819 --- /dev/null +++ b/param_extraction/scripts/chunker.py @@ -0,0 +1,738 @@ +#!/usr/bin/env python3 +# Copyright (c) 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear +""" +AsciiDoc-aware chunker for the RISC-V specification. + +Splits spec .adoc files into semantically coherent chunks that preserve +CSR section integrity and respect LLM context window limits. + +Chunking rules: + 1. Never split within a ==== section (CSR sections are atomic) + 2. Split at === or ==== boundaries + 3. Target chunk size: 2500-3500 lines (~35K-45K tokens) + 4. Include overlap at boundaries (heading + first paragraph of previous) + 5. Files under 2000 lines are a single chunk + +Output: + chunks/ directory with numbered chunk files and a manifest.json +""" + +from __future__ import annotations + +import argparse +import json +import re +import sys +from dataclasses import dataclass, field +from pathlib import Path + +SCRIPT_DIR = Path(__file__).resolve().parent +PROJECT_DIR = SCRIPT_DIR.parent +SPEC_DIR = PROJECT_DIR.parent / "ext" / "riscv-isa-manual" / "src" +CHUNKS_DIR = PROJECT_DIR / "chunks" + +TARGET_MIN_LINES = 2500 +TARGET_MAX_LINES = 3500 +SMALL_FILE_THRESHOLD = 2000 +OVERLAP_LINES = 30 + + +@dataclass +class Section: + """A section of an AsciiDoc file.""" + + line_start: int # 0-based + line_end: int # 0-based, exclusive + level: int # number of '=' chars (2-5) + title: str + children: list[Section] = field(default_factory=list) + + @property + def size(self) -> int: + return self.line_end - self.line_start + + +@dataclass +class ChunkInfo: + """Metadata for a single chunk.""" + + chunk_id: str + source_file: str + start_line: int # 1-based, inclusive (includes overlap) + end_line: int # 1-based, inclusive + content_start_line: int # 1-based, where new content starts (after overlap) + total_source_lines: int + section_headings: list[str] + overlap_from_line: int | None # 1-based start of overlap region, or None + line_count: int + + def to_dict(self) -> dict: + return { + "chunk_id": self.chunk_id, + "source_file": self.source_file, + "start_line": self.start_line, + "end_line": self.end_line, + "content_start_line": self.content_start_line, + "total_source_lines": self.total_source_lines, + "section_headings": self.section_headings, + "overlap_from_line": self.overlap_from_line, + "line_count": self.line_count, + } + + +def parse_sections(lines: list[str]) -> list[Section]: + """ + Parse AsciiDoc section headers and build a flat list of sections. + Each section spans from its header to the next header of the same or + higher level (or end of file). + """ + headers: list[tuple[int, int, str]] = [] # (line_idx, level, title) + for i, line in enumerate(lines): + m = re.match(r"^(={2,6})\s+(.+)", line.strip()) + if m: + headers.append((i, len(m.group(1)), m.group(2).strip())) + + if not headers: + return [ + Section( + line_start=0, + line_end=len(lines), + level=1, + title="(no sections)", + ) + ] + + sections: list[Section] = [] + total = len(lines) + + for idx, (start, level, title) in enumerate(headers): + end = total + for next_start, next_level, _ in headers[idx + 1 :]: + if next_level <= level: + end = next_start + break + sections.append( + Section( + line_start=start, + line_end=end, + level=level, + title=title, + ) + ) + + return sections + + +def build_atomic_blocks(sections: list[Section], total_lines: int) -> list[Section]: + """ + Build atomic blocks that cannot be split. + + An atomic block is: + - A ==== section including all its ===== children + - A === section's preamble (text before its first ==== child) + - Any == level section's preamble + + The key invariant: no chunk boundary falls inside a ==== section. + """ + blocks: list[Section] = [] + + level4_sections = [s for s in sections if s.level == 4] + level3_sections = [s for s in sections if s.level == 3] + level2_sections = [s for s in sections if s.level == 2] + + if level4_sections: + covered = set() + for s in level4_sections: + for line_idx in range(s.line_start, s.line_end): + covered.add(line_idx) + blocks.append(s) + + for s in level3_sections + level2_sections: + preamble_end = s.line_end + for child in level4_sections: + if s.line_start < child.line_start <= s.line_end: + preamble_end = min(preamble_end, child.line_start) + break + + if preamble_end > s.line_start + 1: + preamble_lines = set(range(s.line_start, preamble_end)) + uncovered = preamble_lines - covered + if uncovered: + blocks.append( + Section( + line_start=min(uncovered), + line_end=max(uncovered) + 1, + level=s.level, + title=s.title + " (preamble)", + ) + ) + + all_line_idxs = set(range(total_lines)) + block_covered = set() + for b in blocks: + for i in range(b.line_start, b.line_end): + block_covered.add(i) + + gaps = sorted(all_line_idxs - block_covered) + if gaps: + gap_start = gaps[0] + for i in range(1, len(gaps)): + if gaps[i] != gaps[i - 1] + 1: + blocks.append( + Section( + line_start=gap_start, + line_end=gaps[i - 1] + 1, + level=0, + title="(gap)", + ) + ) + gap_start = gaps[i] + blocks.append( + Section( + line_start=gap_start, + line_end=gaps[-1] + 1, + level=0, + title="(gap)", + ) + ) + + elif level3_sections: + blocks = list(level3_sections) + if level3_sections[0].line_start > 0: + blocks.insert( + 0, + Section( + line_start=0, + line_end=level3_sections[0].line_start, + level=1, + title="(preamble)", + ), + ) + else: + blocks = [ + Section( + line_start=0, + line_end=total_lines, + level=1, + title="(entire file)", + ) + ] + + blocks.sort(key=lambda b: b.line_start) + return blocks + + +def merge_tiny_blocks(blocks: list[Section], min_size: int = 5) -> list[Section]: + """Merge very small blocks into their neighbors.""" + if len(blocks) <= 1: + return blocks + + merged: list[Section] = [blocks[0]] + for b in blocks[1:]: + if b.size < min_size and merged: + merged[-1] = Section( + line_start=merged[-1].line_start, + line_end=b.line_end, + level=merged[-1].level, + title=merged[-1].title, + ) + else: + merged.append(b) + return merged + + +def pack_chunks( + blocks: list[Section], + total_lines: int, + target_min: int = TARGET_MIN_LINES, + target_max: int = TARGET_MAX_LINES, +) -> list[list[Section]]: + """ + Greedily pack atomic blocks into chunks. + + Each chunk accumulates blocks until adding the next block would exceed + target_max. If the current chunk hasn't reached target_min, keep adding. + """ + if not blocks: + return [] + + chunks: list[list[Section]] = [] + current: list[Section] = [] + current_size = 0 + + for block in blocks: + if current and current_size + block.size > target_max and current_size >= target_min: + chunks.append(current) + current = [block] + current_size = block.size + else: + current.append(block) + current_size += block.size + + if current: + chunks.append(current) + + return chunks + + +def get_overlap_text( + lines: list[str], + prev_chunk_blocks: list[Section], + max_lines: int = OVERLAP_LINES, +) -> tuple[int, list[str]]: + """ + Extract overlap context from the end of the previous chunk. + Returns (start_line_0based, overlap_lines). + """ + if not prev_chunk_blocks: + return (0, []) + + last_block = prev_chunk_blocks[-1] + overlap_start = max(last_block.line_start, last_block.line_end - max_lines) + + overlap = lines[overlap_start : last_block.line_end] + return (overlap_start, overlap) + + +def get_section_headings( + blocks: list[Section], + all_sections: list[Section], +) -> list[str]: + """Get a list of section headings covered by these blocks.""" + block_range_start = blocks[0].line_start + block_range_end = blocks[-1].line_end + headings = [] + for s in all_sections: + if s.line_start >= block_range_start and s.line_start < block_range_end: + prefix = "=" * s.level + headings.append(f"{prefix} {s.title}") + return headings + + +def chunk_file( + filepath: Path, + target_min: int = TARGET_MIN_LINES, + target_max: int = TARGET_MAX_LINES, + small_threshold: int = SMALL_FILE_THRESHOLD, +) -> list[tuple[str, ChunkInfo]]: + """ + Chunk a single spec file. Returns list of (chunk_text, metadata). + """ + text = filepath.read_text(encoding="utf-8") + lines = text.splitlines(keepends=True) + total_lines = len(lines) + + if total_lines == 0: + return [] + + all_sections = parse_sections([line.rstrip("\n") for line in lines]) + + if total_lines < small_threshold: + chunk_text = text + heading_list = [f"{'=' * s.level} {s.title}" for s in all_sections if s.level >= 2] + meta = ChunkInfo( + chunk_id="", + source_file=filepath.name, + start_line=1, + end_line=total_lines, + content_start_line=1, + total_source_lines=total_lines, + section_headings=heading_list[:10], + overlap_from_line=None, + line_count=total_lines, + ) + return [(chunk_text, meta)] + + blocks = build_atomic_blocks(all_sections, total_lines) + blocks = merge_tiny_blocks(blocks) + packed = pack_chunks(blocks, total_lines, target_min, target_max) + + results: list[tuple[str, ChunkInfo]] = [] + for chunk_idx, block_group in enumerate(packed): + block_start = block_group[0].line_start + block_end = block_group[-1].line_end + + overlap_start = None + overlap_text_lines: list[str] = [] + if chunk_idx > 0: + prev_blocks = packed[chunk_idx - 1] + ov_start_0, ov_lines = get_overlap_text(lines, prev_blocks) + if ov_lines: + overlap_start = ov_start_0 + overlap_text_lines = ov_lines + + if overlap_text_lines and overlap_start is not None: + actual_start = overlap_start + chunk_lines = lines[actual_start:block_end] + else: + actual_start = block_start + chunk_lines = lines[block_start:block_end] + + chunk_text = "".join(chunk_lines) + headings = get_section_headings(block_group, all_sections) + + meta = ChunkInfo( + chunk_id="", + source_file=filepath.name, + start_line=actual_start + 1, + end_line=block_end, + content_start_line=block_start + 1, + total_source_lines=total_lines, + section_headings=headings[:20], + overlap_from_line=(overlap_start + 1) + if overlap_start is not None and chunk_idx > 0 + else None, + line_count=block_end - actual_start, + ) + results.append((chunk_text, meta)) + + return results + + +def chunk_all_files( + spec_dir: Path = SPEC_DIR, + target_min: int = TARGET_MIN_LINES, + target_max: int = TARGET_MAX_LINES, +) -> list[tuple[str, ChunkInfo]]: + """Chunk all .adoc files in the spec directory.""" + all_chunks: list[tuple[str, ChunkInfo]] = [] + + adoc_files = sorted(spec_dir.glob("*.adoc")) + if not adoc_files: + print(f"No .adoc files found in {spec_dir}", file=sys.stderr) + return [] + + global_idx = 0 + for filepath in adoc_files: + file_chunks = chunk_file(filepath, target_min, target_max) + for chunk_text, meta in file_chunks: + global_idx += 1 + meta.chunk_id = f"chunk_{global_idx:03d}" + all_chunks.append((chunk_text, meta)) + + return all_chunks + + +def write_chunks( + chunks: list[tuple[str, ChunkInfo]], + output_dir: Path = CHUNKS_DIR, +) -> Path: + """Write chunk files and manifest to the output directory.""" + output_dir.mkdir(parents=True, exist_ok=True) + + for existing in output_dir.glob("chunk_*.txt"): + existing.unlink() + manifest_path = output_dir / "manifest.json" + if manifest_path.exists(): + manifest_path.unlink() + + manifest_entries: list[dict] = [] + + for chunk_text, meta in chunks: + header_lines = [ + f"# Chunk: {meta.chunk_id}", + f"# Source: {meta.source_file}", + f"# Lines: {meta.start_line}-{meta.end_line} (of {meta.total_source_lines})", + f"# Content starts: line {meta.content_start_line}", + f"# Line count: {meta.line_count}", + ] + if meta.overlap_from_line: + header_lines.append(f"# Overlap from line: {meta.overlap_from_line}") + header_lines.append(f"# Sections: {len(meta.section_headings)}") + for h in meta.section_headings: + header_lines.append(f"# {h}") + header_lines.append("#") + header_lines.append("") + + file_content = "\n".join(header_lines) + chunk_text + + chunk_path = output_dir / f"{meta.chunk_id}.txt" + chunk_path.write_text(file_content, encoding="utf-8") + + manifest_entries.append(meta.to_dict()) + + manifest = { + "total_chunks": len(chunks), + "total_files": len(set(m.source_file for _, m in chunks)), + "total_lines": sum(m.line_count for _, m in chunks), + "chunks": manifest_entries, + } + + manifest_path.write_text( + json.dumps(manifest, indent=2) + "\n", + encoding="utf-8", + ) + + return output_dir + + +# --- CLI --- + + +def cmd_run(args: argparse.Namespace) -> None: + """Chunk all spec files and write output.""" + spec_dir = Path(args.spec_dir) + if not spec_dir.exists(): + print(f"Error: spec directory not found: {spec_dir}", file=sys.stderr) + sys.exit(1) + + output_dir = Path(args.output_dir) + + print(f"Spec directory: {spec_dir}") + print(f"Output directory: {output_dir}") + print(f"Target chunk size: {args.min_lines}-{args.max_lines} lines") + print() + + chunks = chunk_all_files( + spec_dir=spec_dir, + target_min=args.min_lines, + target_max=args.max_lines, + ) + + write_chunks(chunks, output_dir) + + files_seen = set() + for _, meta in chunks: + files_seen.add(meta.source_file) + + print(f"Files processed: {len(files_seen)}") + print(f"Total chunks: {len(chunks)}") + print() + + by_file: dict[str, list[ChunkInfo]] = {} + for _, meta in chunks: + by_file.setdefault(meta.source_file, []).append(meta) + + for fname in sorted(by_file): + file_chunks = by_file[fname] + if len(file_chunks) == 1: + c = file_chunks[0] + print(f" {fname}: 1 chunk ({c.line_count} lines)") + else: + parts = ", ".join(f"{c.line_count}" for c in file_chunks) + print(f" {fname}: {len(file_chunks)} chunks ({parts} lines)") + + +def cmd_info(args: argparse.Namespace) -> None: + """Show information about a specific file's chunking.""" + filepath = Path(args.file) + if not filepath.exists(): + print(f"Error: file not found: {filepath}", file=sys.stderr) + sys.exit(1) + + file_chunks = chunk_file( + filepath, + target_min=args.min_lines, + target_max=args.max_lines, + ) + + lines = filepath.read_text().splitlines() + total = len(lines) + + print(f"File: {filepath.name}") + print(f"Total lines: {total}") + print(f"Chunks: {len(file_chunks)}") + print() + + for idx, (_chunk_text, meta) in enumerate(file_chunks): + print(f" Chunk {idx + 1}/{len(file_chunks)}:") + print(f" Lines: {meta.start_line}-{meta.end_line}") + print(f" Content starts: line {meta.content_start_line}") + print(f" Line count: {meta.line_count}") + if meta.overlap_from_line: + print(f" Overlap from: line {meta.overlap_from_line}") + print(f" Sections ({len(meta.section_headings)}):") + for h in meta.section_headings[:10]: + print(f" {h}") + if len(meta.section_headings) > 10: + print(f" ... and {len(meta.section_headings) - 10} more") + print() + + +def cmd_verify(args: argparse.Namespace) -> None: + """Run verification checks on chunking output.""" + spec_dir = Path(args.spec_dir) + chunks = chunk_all_files(spec_dir=spec_dir) + + errors: list[str] = [] + warnings: list[str] = [] + + # 1. All 74 files covered + all_adocs = sorted(spec_dir.glob("*.adoc")) + files_chunked = set(m.source_file for _, m in chunks) + for adoc in all_adocs: + if adoc.name not in files_chunked: + errors.append(f"File not chunked: {adoc.name}") + print(f"1. File coverage: {len(files_chunked)}/{len(all_adocs)} files") + + # 2. No CSR section splits + # A split occurs if a ==== section's content range (start..end) is + # cut by a chunk's CONTENT boundary (content_start_line), meaning + # part of the section's new content is in one chunk and part in + # another. Overlap regions don't count as splits. + print("2. CSR section integrity:") + csr_split_count = 0 + for adoc in all_adocs: + lines_raw = adoc.read_text().splitlines() + sections = parse_sections(lines_raw) + level4 = [s for s in sections if s.level == 4] + + file_chunks = [(t, m) for t, m in chunks if m.source_file == adoc.name] + if len(file_chunks) <= 1: + continue + + content_boundaries = [] + for _, meta in file_chunks: + content_boundaries.append(meta.content_start_line) + + for s4 in level4: + s4_start = s4.line_start + 1 # 1-based + s4_end = s4.line_end # 1-based, exclusive + for boundary in content_boundaries: + if s4_start < boundary < s4_end: + errors.append( + f"CSR section split in {adoc.name}: " + f"'{s4.title}' ({s4_start}-{s4_end}) " + f"split by content boundary at line {boundary}" + ) + csr_split_count += 1 + + if csr_split_count == 0: + print(" No CSR section splits ✓") + else: + print(f" {csr_split_count} CSR section splits found!") + + # 3. Chunk sizes + print("3. Chunk size analysis:") + target_min = TARGET_MIN_LINES + target_max = TARGET_MAX_LINES + tolerance = 0.20 + abs_min = int(target_min * (1 - tolerance)) + abs_max = int(target_max * (1 + tolerance)) + + multi_chunk_files = {} + for _, meta in chunks: + multi_chunk_files.setdefault(meta.source_file, []).append(meta) + + oversized = 0 + for fname, file_chunks in multi_chunk_files.items(): + if len(file_chunks) == 1: + continue + for meta in file_chunks: + if meta.line_count > abs_max: + warnings.append( + f"Oversized chunk: {meta.chunk_id} in {fname} " + f"({meta.line_count} lines > {abs_max})" + ) + oversized += 1 + elif meta.line_count < abs_min and meta.line_count < meta.total_source_lines: + lc = meta.line_count + if meta.overlap_from_line: + lc = meta.end_line - meta.start_line + 1 + if lc < abs_min: + pass + + size_dist = [m.line_count for _, m in chunks] + print( + f" Min: {min(size_dist)}, Max: {max(size_dist)}, " + f"Mean: {sum(size_dist) / len(size_dist):.0f}" + ) + + # 4. Overlap + print("4. Overlap integrity:") + overlap_count = sum(1 for _, m in chunks if m.overlap_from_line is not None) + multi_chunk_count = sum(len(v) - 1 for v in multi_chunk_files.values() if len(v) > 1) + print(f" Overlaps: {overlap_count}, Expected (multi-chunk non-first): {multi_chunk_count}") + + # 5. Metadata completeness + print("5. Metadata completeness:") + missing_meta = 0 + no_headings = [] + for _, meta in chunks: + if not meta.chunk_id: + missing_meta += 1 + if not meta.source_file: + missing_meta += 1 + if meta.start_line < 1 or meta.end_line < 1: + missing_meta += 1 + if not meta.section_headings and meta.line_count > 50: + no_headings.append(meta.source_file) + if missing_meta == 0 and not no_headings: + print(" All metadata fields populated ✓") + else: + if missing_meta: + errors.append(f"{missing_meta} chunks with incomplete metadata") + if no_headings: + warnings.append( + f"{len(no_headings)} chunks with no section headings: {', '.join(no_headings)}" + ) + + # 6. Full coverage: content boundaries should be contiguous + print("6. Line coverage per file:") + gap_count = 0 + for fname, file_chunks in multi_chunk_files.items(): + if len(file_chunks) <= 1: + continue + sorted_chunks = sorted(file_chunks, key=lambda m: m.content_start_line) + for i in range(1, len(sorted_chunks)): + prev_end = sorted_chunks[i - 1].end_line + curr_content_start = sorted_chunks[i].content_start_line + if curr_content_start > prev_end + 1: + errors.append( + f"Gap in {fname}: lines {prev_end + 1}-{curr_content_start - 1} not covered" + ) + gap_count += 1 + if gap_count == 0: + print(" No gaps in coverage ✓") + + # Summary + print() + print(f"{'=' * 50}") + print(f"Results: {len(errors)} errors, {len(warnings)} warnings") + if warnings: + print("\nWarnings:") + for w in warnings: + print(f" {w}") + if errors: + print("\nErrors:") + for e in errors: + print(f" {e}") + sys.exit(1) + else: + print("\nAll verification checks passed!") + + +def main() -> None: + parser = argparse.ArgumentParser( + description="AsciiDoc-aware chunker for RISC-V spec files", + ) + subparsers = parser.add_subparsers(dest="command", required=True) + + p_run = subparsers.add_parser("run", help="Chunk all spec files and write output") + p_run.add_argument("--spec-dir", default=str(SPEC_DIR), help="Path to spec .adoc files") + p_run.add_argument("--output-dir", default=str(CHUNKS_DIR), help="Output directory for chunks") + p_run.add_argument( + "--min-lines", type=int, default=TARGET_MIN_LINES, help="Minimum chunk size in lines" + ) + p_run.add_argument( + "--max-lines", type=int, default=TARGET_MAX_LINES, help="Maximum chunk size in lines" + ) + p_run.set_defaults(func=cmd_run) + + p_info = subparsers.add_parser("info", help="Show chunking for a specific file") + p_info.add_argument("file", help="Path to a .adoc file") + p_info.add_argument("--min-lines", type=int, default=TARGET_MIN_LINES) + p_info.add_argument("--max-lines", type=int, default=TARGET_MAX_LINES) + p_info.set_defaults(func=cmd_info) + + p_verify = subparsers.add_parser("verify", help="Verify chunking output") + p_verify.add_argument("--spec-dir", default=str(SPEC_DIR)) + p_verify.set_defaults(func=cmd_verify) + + args = parser.parse_args() + args.func(args) + + +if __name__ == "__main__": + main() diff --git a/param_extraction/scripts/export_udb_params.py b/param_extraction/scripts/export_udb_params.py new file mode 100644 index 0000000000..6547b072ea --- /dev/null +++ b/param_extraction/scripts/export_udb_params.py @@ -0,0 +1,791 @@ +#!/usr/bin/env python3 +""" +Phase 1, Step 1: Export all UDB parameters to structured JSON. + +Reads every spec/std/isa/param/*.yaml file (excluding MOCK_* test fixtures), +extracts metadata, derives value types from JSON Schema structures, +cross-references with CSR definitions to find WARL connections, +and heuristically classifies each parameter. + +Output: data/ground_truth.json +""" + +import yaml +import json +import re +from pathlib import Path +from collections import defaultdict + +REPO_ROOT = Path(__file__).resolve().parent.parent.parent +PARAM_DIR = REPO_ROOT / "spec" / "std" / "isa" / "param" +CSR_DIR = REPO_ROOT / "spec" / "std" / "isa" / "csr" +SPEC_DIR = REPO_ROOT / "ext" / "riscv-isa-manual" / "src" +OUTPUT_DIR = Path(__file__).resolve().parent.parent / "data" + + +def load_yaml(path): + with open(path, encoding="utf-8") as f: + return yaml.safe_load(f) + + +# --------------------------------------------------------------------------- +# Schema analysis: derive the "value type" from JSON Schema structures +# --------------------------------------------------------------------------- + +def derive_value_type(schema): + """ + Analyze a JSON Schema object and return a structured description + of the parameter's value type. + + Returns a dict with: + - type: one of "binary", "enum", "range", "set", "bitmask", + "value", "conditional", "unknown" + - details: type-specific metadata + """ + if schema is None: + return {"type": "unknown", "details": {}} + + # Conditional schema (oneOf with "when" clauses) + if "oneOf" in schema and isinstance(schema["oneOf"], list): + branches = schema["oneOf"] + if branches and isinstance(branches[0], dict) and "when" in branches[0]: + branch_types = [] + for branch in branches: + inner = branch.get("schema", {}) + branch_types.append({ + "condition": _summarize_when(branch.get("when", {})), + "inner_type": derive_value_type(inner), + }) + return {"type": "conditional", "details": {"branches": branch_types}} + + # rv32/rv64 split at top level + if "rv32" in schema and "rv64" in schema and len(schema) == 2: + return { + "type": "conditional", + "details": { + "branches": [ + {"condition": "rv32", "inner_type": derive_value_type(schema["rv32"])}, + {"condition": "rv64", "inner_type": derive_value_type(schema["rv64"])}, + ] + }, + } + + schema_type = schema.get("type") + + # Boolean + if schema_type == "boolean": + return {"type": "binary", "details": {"choices": [True, False]}} + + # Integer + if schema_type == "integer": + if "enum" in schema: + vals = schema["enum"] + if len(vals) == 2: + return {"type": "binary", "details": {"choices": vals}} + return {"type": "enum", "details": {"values": vals}} + if "minimum" in schema or "maximum" in schema: + return { + "type": "range", + "details": { + "minimum": schema.get("minimum"), + "maximum": schema.get("maximum"), + }, + } + return {"type": "value", "details": {"base": "integer"}} + + # String + if schema_type == "string": + if "enum" in schema: + vals = schema["enum"] + if len(vals) == 2: + return {"type": "binary", "details": {"choices": vals}} + return {"type": "enum", "details": {"values": vals}} + return {"type": "value", "details": {"base": "string"}} + + # Array + if schema_type == "array": + items = schema.get("items", {}) + min_items = schema.get("minItems") + max_items = schema.get("maxItems") + + # Fixed-length boolean array = bitmask + if _is_boolean_array(schema): + return { + "type": "bitmask", + "details": {"length": max_items or min_items}, + } + + # Array of enum items = set (subset selection) + if isinstance(items, dict) and "enum" in items: + return { + "type": "set", + "details": { + "universe": items["enum"], + "min_items": min_items, + "max_items": max_items, + }, + } + if isinstance(items, dict) and items.get("type") == "integer" and "enum" in items: + return { + "type": "set", + "details": { + "universe": items["enum"], + "min_items": min_items, + "max_items": max_items, + }, + } + + return { + "type": "set", + "details": { + "element_type": items.get("type", "mixed"), + "min_items": min_items, + "max_items": max_items, + }, + } + + # Top-level enum without explicit type + if "enum" in schema: + vals = schema["enum"] + if len(vals) == 2: + return {"type": "binary", "details": {"choices": vals}} + return {"type": "enum", "details": {"values": vals}} + + # Fallback: schema has allOf, $ref, or other complex structures + if "$ref" in schema: + return {"type": "value", "details": {"ref": schema["$ref"]}} + + if "allOf" in schema: + return {"type": "value", "details": {"complex": "allOf"}} + + return {"type": "unknown", "details": {"raw_keys": list(schema.keys())}} + + +def _is_boolean_array(schema): + """Check if this array schema represents a fixed-length boolean array (bitmask).""" + items = schema.get("items", {}) + additional = schema.get("additionalItems", {}) + + if isinstance(items, dict) and items.get("type") == "boolean": + return True + + # Tuple-style: items is a list (positional) + additionalItems is boolean + if isinstance(items, list): + all_bool_or_const = all( + i.get("type") == "boolean" or "const" in i + for i in items + if isinstance(i, dict) + ) + additional_bool = isinstance(additional, dict) and additional.get("type") == "boolean" + if all_bool_or_const and (additional_bool or not additional): + return True + + return False + + +def _summarize_when(when): + """Produce a human-readable summary of a 'when' condition.""" + param = when.get("param", {}) + if param: + return f"{param.get('name', '?')} == {param.get('equal', '?')}" + return str(when) + + +# --------------------------------------------------------------------------- +# definedBy extraction +# --------------------------------------------------------------------------- + +def flatten_defined_by(defined_by): + """ + Convert the definedBy condition tree into a flat, readable structure. + + Returns a dict with: + - extensions: list of extension names involved + - params: list of parameter conditions involved + - raw: the original structure for full fidelity + - summary: human-readable string + """ + if defined_by is None: + return {"extensions": [], "params": [], "raw": None, "summary": "none"} + + extensions = [] + params = [] + _collect_conditions(defined_by, extensions, params) + + summary = _summarize_defined_by(defined_by) + + return { + "extensions": sorted(set(extensions)), + "params": params, + "raw": defined_by, + "summary": summary, + } + + +def _collect_conditions(node, extensions, params): + """Recursively collect extension names and param conditions.""" + if not isinstance(node, dict): + return + + if "name" in node and isinstance(node["name"], str): + ext_name = node["name"] + if ext_name not in ("allOf", "anyOf", "noneOf"): + extensions.append(ext_name) + + if "extension" in node: + ext = node["extension"] + if isinstance(ext, dict): + _collect_conditions(ext, extensions, params) + elif isinstance(ext, str): + extensions.append(ext) + + if "param" in node: + p = node["param"] + if isinstance(p, dict): + if "name" in p: + params.append({ + "name": p["name"], + "condition": {k: v for k, v in p.items() if k != "name" and k != "reason"}, + }) + if "allOf" in p: + for item in p["allOf"]: + _collect_conditions({"param": item}, extensions, params) + + for key in ("allOf", "anyOf", "noneOf"): + if key in node: + for item in node[key]: + _collect_conditions(item, extensions, params) + + +def _summarize_defined_by(node): + """Produce a compact human-readable summary.""" + if not isinstance(node, dict): + return str(node) + + if "extension" in node: + ext = node["extension"] + if isinstance(ext, dict): + if "name" in ext: + ver = ext.get("version", "") + return f"ext:{ext['name']}" + (f"({ver})" if ver else "") + if "allOf" in ext: + parts = [_summarize_defined_by({"extension": e}) for e in ext["allOf"]] + return " AND ".join(parts) + if "anyOf" in ext: + parts = [_summarize_defined_by({"extension": e}) for e in ext["anyOf"]] + return "(" + " OR ".join(parts) + ")" + if "noneOf" in ext: + parts = [_summarize_defined_by({"extension": e}) for e in ext["noneOf"]] + return "NONE(" + ", ".join(parts) + ")" + + if "allOf" in node: + parts = [_summarize_defined_by(item) for item in node["allOf"]] + return " AND ".join(parts) + + if "param" in node: + p = node["param"] + if isinstance(p, dict) and "name" in p: + conds = [f"{k}={v}" for k, v in p.items() if k not in ("name", "reason")] + return f"param:{p['name']}({', '.join(conds)})" + + return str(node)[:80] + + +# --------------------------------------------------------------------------- +# CSR cross-reference: find params mentioned in CSR IDL code +# --------------------------------------------------------------------------- + +def build_csr_param_xref(csr_dir, param_names): + """ + Scan all CSR YAML files for references to known parameter names + in IDL code fields (sw_write, type(), reset_value(), legal?). + + Returns: + - param_to_csrs: {param_name: [{csr, field, context}]} + - csr_to_params: {csr_name: [param_name]} + """ + param_to_csrs = defaultdict(list) + csr_to_params = defaultdict(set) + + idl_field_keys = [ + "sw_write(csr_value)", "type()", "reset_value()", + "legal?(csr_value)", "sw_read()", + ] + + # Build a regex that matches any param name as a whole word + # Sort by length descending so longer names match first + sorted_names = sorted(param_names, key=len, reverse=True) + if not sorted_names: + return dict(param_to_csrs), dict(csr_to_params) + + param_pattern = re.compile(r'\b(' + '|'.join(re.escape(n) for n in sorted_names) + r')\b') + + csr_files = list(csr_dir.rglob("*.yaml")) + for csr_path in csr_files: + try: + data = load_yaml(csr_path) + except Exception: + continue + + if not isinstance(data, dict) or data.get("kind") != "csr": + continue + + csr_name = data.get("name", csr_path.stem) + fields = data.get("fields", {}) + + # Check CSR-level IDL + for key in idl_field_keys: + idl_code = data.get(key) + if isinstance(idl_code, str): + for match in param_pattern.finditer(idl_code): + pname = match.group(1) + param_to_csrs[pname].append({ + "csr": csr_name, + "field": "(csr-level)", + "idl_key": key, + }) + csr_to_params[csr_name].add(pname) + + # Check field-level IDL + if isinstance(fields, dict): + for field_name, field_data in fields.items(): + if not isinstance(field_data, dict): + continue + for key in idl_field_keys: + idl_code = field_data.get(key) + if isinstance(idl_code, str): + for match in param_pattern.finditer(idl_code): + pname = match.group(1) + param_to_csrs[pname].append({ + "csr": csr_name, + "field": field_name, + "idl_key": key, + }) + csr_to_params[csr_name].add(pname) + + # Also check type() which returns CsrFieldType + type_func = field_data.get("type()") + if isinstance(type_func, str): + for match in param_pattern.finditer(type_func): + pname = match.group(1) + param_to_csrs[pname].append({ + "csr": csr_name, + "field": field_name, + "idl_key": "type()", + }) + csr_to_params[csr_name].add(pname) + + # Deduplicate + for pname in param_to_csrs: + seen = set() + deduped = [] + for ref in param_to_csrs[pname]: + key = (ref["csr"], ref["field"], ref["idl_key"]) + if key not in seen: + seen.add(key) + deduped.append(ref) + param_to_csrs[pname] = deduped + + return dict(param_to_csrs), {k: sorted(v) for k, v in csr_to_params.items()} + + +# --------------------------------------------------------------------------- +# Classification logic +# --------------------------------------------------------------------------- + +# Patterns in parameter names that indicate CSR-related parameters +CSR_NAME_PATTERNS = [ + (r'^MTVEC_', 'mtvec'), + (r'^STVEC_', 'stvec'), + (r'^VSTVEC_', 'vstvec'), + (r'^MSTATUS_', 'mstatus'), + (r'^MISA_', 'misa'), + (r'^MUTABLE_MISA_', 'misa'), + (r'^SATP_', 'satp'), + (r'^DCSR_', 'dcsr'), + (r'^JVT_', 'jvt'), + (r'^MSTATEEN_', 'mstateen'), + (r'^HSTATEEN_', 'hstateen'), + (r'^SSTATEEN_', 'sstateen'), + (r'^HPM_', 'hpmcounter/hpmevent'), + (r'^COUNTINHIBIT_', 'mcountinhibit'), + (r'^MCOUNTENABLE_', 'mcounteren'), + (r'^SCOUNTENABLE_', 'scounteren'), + (r'^HCOUNTENABLE_', 'hcounteren'), +] + +# Parameters that are clearly about trap/reporting behavior (not CSR fields) +TRAP_REPORT_PATTERNS = [ + r'^TRAP_ON_', + r'^REPORT_', + r'^PRECISE_', +] + +# Parameters known to be direct architectural choices +DIRECT_ARCH_NAMES = { + 'MXLEN', 'SXLEN', 'UXLEN', 'VSXLEN', 'VUXLEN', + 'PHYS_ADDR_WIDTH', 'NUM_PMP_ENTRIES', 'PMP_GRANULARITY', + 'VLEN', 'ELEN', 'CACHE_BLOCK_SIZE', 'PMA_GRANULARITY', + 'ASID_WIDTH', 'VMID_WIDTH', 'PMLEN', + 'ARCH_ID_VALUE', 'IMP_ID_VALUE', 'VENDOR_ID_BANK', 'VENDOR_ID_OFFSET', + 'CONFIG_PTR_ADDRESS', 'NUM_EXTERNAL_GUEST_INTERRUPTS', + 'MARCHID_IMPLEMENTED', 'MIMPID_IMPLEMENTED', +} + + +def classify_parameter(param_data, csr_refs, value_type_info): + """ + Heuristically assign a classification to a parameter. + + Classification hierarchy: + NORM_DIRECT - Normative, directly configurable (not CSR-controlled) + NORM_CSR_WARL - Normative, parameter is legal values of a WARL CSR field + NORM_CSR_RW - Normative, whether a CSR/field is RO vs RW + SW_RULE - Software-deterministic (impl-defined but determinate with correct SW) + NON_ISA - Platform-level, not ISA architectural + NON_NORM - Non-normative / informational + UNKNOWN - Cannot confidently classify + """ + name = param_data.get("name", "") + desc = param_data.get("description", "").lower() + long_name = param_data.get("long_name", "").lower() + + has_csr_refs = len(csr_refs) > 0 + has_sw_write_ref = any(r["idl_key"] == "sw_write(csr_value)" for r in csr_refs) + has_type_ref = any(r["idl_key"] == "type()" for r in csr_refs) + + classification = "UNKNOWN" + confidence = "low" + reasoning = "" + + # --- Check for HW_ prefix first (hardware update behavior, SW-deterministic) --- + # Must come before CSR checks because HW_ params are referenced in CSR type() + # but are conceptually SW rules, not CSR-controlled parameters + if name.startswith("HW_"): + classification = "SW_RULE" + confidence = "medium" + reasoning = "Hardware update behavior (HW_ prefix) — software-deterministic with correct fencing" + return classification, confidence, reasoning + + # --- Check for existence/availability parameters --- + # Params with _IMPLEMENTED or _AVAILABLE suffix control whether a CSR/feature + # exists at all. They may be referenced in CSR IDL (because the CSR behavior + # depends on whether it exists), but the parameter itself is a direct + # architectural choice, not a WARL/RW control. + if name.endswith("_IMPLEMENTED") or name.endswith("_AVAILABLE"): + classification = "NORM_DIRECT" + confidence = "high" + reasoning = f"Feature/CSR existence parameter ('{name.split('_')[-1]}' suffix)" + return classification, confidence, reasoning + + # --- Check for direct architectural parameters --- + if name in DIRECT_ARCH_NAMES: + classification = "NORM_DIRECT" + confidence = "high" + reasoning = f"Well-known architectural parameter '{name}'" + return classification, confidence, reasoning + + # --- Check for trap/report behavior (normative, not CSR-controlled) --- + for pattern in TRAP_REPORT_PATTERNS: + if re.match(pattern, name): + classification = "NORM_DIRECT" + confidence = "high" + reasoning = f"Trap/report behavior parameter (matches {pattern})" + return classification, confidence, reasoning + + # --- Check for CSR WARL field parameters --- + # If the parameter is referenced in sw_write() of a CSR field, + # it controls the legal write values — classic WARL parameter + if has_sw_write_ref: + csr_fields = [(r["csr"], r["field"]) for r in csr_refs if r["idl_key"] == "sw_write(csr_value)"] + classification = "NORM_CSR_WARL" + confidence = "high" + reasoning = f"Referenced in sw_write() of {csr_fields[0][0]}.{csr_fields[0][1]}" + return classification, confidence, reasoning + + # If referenced in type() of a CSR field, it controls read-write behavior + if has_type_ref: + csr_fields = [(r["csr"], r["field"]) for r in csr_refs if r["idl_key"] == "type()"] + classification = "NORM_CSR_RW" + confidence = "high" + reasoning = f"Controls type (RO/RW) of {csr_fields[0][0]}.{csr_fields[0][1]}" + return classification, confidence, reasoning + + # --- Check name patterns that suggest CSR association --- + for pattern, csr in CSR_NAME_PATTERNS: + if re.match(pattern, name): + # _TYPE suffix with rw/read-only values = controls field RO/RW behavior + if name.endswith("_TYPE"): + classification = "NORM_CSR_RW" + confidence = "medium" if has_csr_refs else "low" + reasoning = f"CSR field type control parameter for '{csr}' (determines RO/RW behavior)" + return classification, confidence, reasoning + + if has_csr_refs: + classification = "NORM_CSR_WARL" + confidence = "medium" + reasoning = f"Name pattern suggests CSR '{csr}' association, confirmed by IDL references" + else: + classification = "NORM_CSR_WARL" + confidence = "low" + reasoning = f"Name pattern suggests CSR '{csr}' association, but no IDL cross-reference found" + return classification, confidence, reasoning + + # --- Check for SW-rule parameters --- + sw_rule_keywords = [ + "implementation-defined whether", + "implementation may choose", + "implementation defined", + "imprecise", + "unpredictable", + ] + for kw in sw_rule_keywords: + if kw in desc: + if "dirty" in desc or "fence" in desc or "cache" in desc: + classification = "SW_RULE" + confidence = "medium" + reasoning = f"Description contains '{kw}' with dirty/fence/cache context" + return classification, confidence, reasoning + + # --- Check for endianness parameters --- + if "ENDIANNESS" in name: + if has_csr_refs: + classification = "NORM_CSR_WARL" + confidence = "high" + reasoning = "Endianness parameter controlled via mstatus/mstatush WARL bits" + else: + classification = "NORM_DIRECT" + confidence = "medium" + reasoning = "Endianness parameter" + return classification, confidence, reasoning + + # --- Check for translation mode parameters --- + if "TRANSLATION" in name or "MODE" in name: + if has_csr_refs: + classification = "NORM_CSR_WARL" + confidence = "medium" + reasoning = "Translation/mode parameter with CSR references" + else: + classification = "NORM_DIRECT" + confidence = "medium" + reasoning = "Translation/mode parameter" + return classification, confidence, reasoning + + # --- Check for TINST/TVAL parameters --- + if name.startswith("TINST_") or "TVAL" in name: + classification = "NORM_DIRECT" + confidence = "medium" + reasoning = "Trap value reporting parameter" + return classification, confidence, reasoning + + # --- Check for FOLLOW/FORCE/IGNORE parameters (behavioral choices) --- + if name.startswith("FOLLOW_") or name.startswith("FORCE_") or name.startswith("IGNORE_"): + classification = "NORM_DIRECT" + confidence = "medium" + reasoning = "Implementation behavioral choice parameter" + return classification, confidence, reasoning + + # --- Check for LRSC parameters --- + if "LRSC" in name: + classification = "NORM_DIRECT" + confidence = "medium" + reasoning = "Load-reserved/store-conditional behavior parameter" + return classification, confidence, reasoning + + # --- Check for MISALIGNED parameters --- + if "MISALIGNED" in name: + classification = "NORM_DIRECT" + confidence = "medium" + reasoning = "Misaligned access behavior parameter" + return classification, confidence, reasoning + + # --- Check for HW_ prefix (hardware update behavior) --- + if name.startswith("HW_"): + classification = "SW_RULE" + confidence = "medium" + reasoning = "Hardware update behavior — may be software-deterministic" + return classification, confidence, reasoning + + # --- Fallback: if it has CSR refs, lean toward CSR-related --- + if has_csr_refs: + # Distinguish: sw_write/type refs → CSR-controlled; sw_read/reset refs → incidental + has_write_or_type = any( + r["idl_key"] in ("sw_write(csr_value)", "type()", "legal?(csr_value)") + for r in csr_refs + ) + if has_write_or_type: + classification = "NORM_CSR_WARL" + confidence = "low" + reasoning = "Has CSR write/type IDL references but no strong name/description signal" + else: + classification = "NORM_DIRECT" + confidence = "low" + reasoning = "Has CSR read/reset IDL references only (incidental, not controlling WARL behavior)" + return classification, confidence, reasoning + + # --- Default --- + classification = "NORM_DIRECT" + confidence = "low" + reasoning = "No strong signals; defaulting to direct normative parameter" + return classification, confidence, reasoning + + +# --------------------------------------------------------------------------- +# Main export logic +# --------------------------------------------------------------------------- + +def export_single_param(yaml_path, param_csr_refs): + """Read one param YAML and produce a structured dict.""" + data = load_yaml(yaml_path) + if not isinstance(data, dict): + return None + + name = data.get("name", yaml_path.stem) + schema = data.get("schema", {}) + defined_by = data.get("definedBy") + requirements = data.get("requirements") + description = data.get("description", "") + long_name = data.get("long_name", "") + + value_type_info = derive_value_type(schema) + defined_by_info = flatten_defined_by(defined_by) + csr_refs = param_csr_refs.get(name, []) + + classification, confidence, reasoning = classify_parameter( + data, csr_refs, value_type_info + ) + + has_requirements = requirements is not None + req_summary = None + if has_requirements: + if isinstance(requirements, dict): + req_summary = requirements.get("reason", requirements.get("idl()", "")[:200]) + elif isinstance(requirements, str): + req_summary = requirements[:200] + + result = { + "name": name, + "long_name": long_name.strip() if isinstance(long_name, str) else str(long_name), + "description": description.strip() if isinstance(description, str) else str(description), + "defined_by": defined_by_info, + "value_type": value_type_info, + "has_requirements": has_requirements, + "requirements_summary": req_summary, + "csr_references": csr_refs, + "classification": classification, + "classification_confidence": confidence, + "classification_reasoning": reasoning, + "source_file": str(yaml_path.relative_to(REPO_ROOT)), + } + + return result + + +def main(): + OUTPUT_DIR.mkdir(parents=True, exist_ok=True) + + # Step 1: Collect all non-MOCK parameter names + param_files = sorted(PARAM_DIR.glob("*.yaml")) + real_params = [f for f in param_files if not f.stem.startswith("MOCK_")] + print(f"Found {len(real_params)} real parameter files (excluded {len(param_files) - len(real_params)} MOCK files)") + + param_names = [f.stem for f in real_params] + + # Step 2: Build CSR cross-reference + print("Building CSR cross-reference...") + param_to_csrs, csr_to_params = build_csr_param_xref(CSR_DIR, param_names) + params_with_csr_refs = sum(1 for v in param_to_csrs.values() if v) + print(f" {params_with_csr_refs} parameters referenced in CSR IDL code") + + # Step 3: Export each parameter + print("Exporting parameters...") + results = [] + for pf in real_params: + entry = export_single_param(pf, param_to_csrs) + if entry: + results.append(entry) + + # Step 4: Compute statistics + stats = compute_statistics(results) + + output = { + "metadata": { + "total_parameters": len(results), + "source": str(PARAM_DIR.relative_to(REPO_ROOT)), + "csr_source": str(CSR_DIR.relative_to(REPO_ROOT)), + }, + "statistics": stats, + "parameters": results, + } + + out_path = OUTPUT_DIR / "ground_truth.json" + with open(out_path, "w", encoding="utf-8") as f: + json.dump(output, f, indent=2, ensure_ascii=False, default=str) + + print(f"\nWritten {len(results)} parameters to {out_path}") + print_summary(stats) + + +def compute_statistics(results): + """Compute summary statistics over the exported parameters.""" + class_counts = defaultdict(int) + type_counts = defaultdict(int) + confidence_counts = defaultdict(int) + ext_counts = defaultdict(int) + + params_with_csr_refs = 0 + params_with_requirements = 0 + + for r in results: + class_counts[r["classification"]] += 1 + type_counts[r["value_type"]["type"]] += 1 + confidence_counts[r["classification_confidence"]] += 1 + + if r["csr_references"]: + params_with_csr_refs += 1 + if r["has_requirements"]: + params_with_requirements += 1 + + for ext in r["defined_by"]["extensions"]: + ext_counts[ext] += 1 + + return { + "by_classification": dict(sorted(class_counts.items())), + "by_value_type": dict(sorted(type_counts.items())), + "by_confidence": dict(sorted(confidence_counts.items())), + "params_with_csr_references": params_with_csr_refs, + "params_with_requirements": params_with_requirements, + "top_defining_extensions": dict( + sorted(ext_counts.items(), key=lambda x: -x[1])[:15] + ), + } + + +def print_summary(stats): + """Print a human-readable summary to stdout.""" + print("\n" + "=" * 60) + print("PARAMETER EXPORT SUMMARY") + print("=" * 60) + + print("\nBy Classification:") + for cls, count in sorted(stats["by_classification"].items()): + print(f" {cls:20s} {count:4d}") + + print("\nBy Value Type:") + for vt, count in sorted(stats["by_value_type"].items()): + print(f" {vt:20s} {count:4d}") + + print("\nBy Confidence:") + for conf, count in sorted(stats["by_confidence"].items()): + print(f" {conf:20s} {count:4d}") + + print(f"\nWith CSR references: {stats['params_with_csr_references']}") + print(f"With requirements IDL: {stats['params_with_requirements']}") + + print("\nTop Defining Extensions:") + for ext, count in list(stats["top_defining_extensions"].items())[:10]: + print(f" {ext:20s} {count:4d}") + + +if __name__ == "__main__": + main() diff --git a/param_extraction/scripts/extract.py b/param_extraction/scripts/extract.py new file mode 100755 index 0000000000..995221db51 --- /dev/null +++ b/param_extraction/scripts/extract.py @@ -0,0 +1,942 @@ +#!/usr/bin/env python3 +# Copyright (c) 2026 Contributors to the RISCV UnifiedDB +# SPDX-License-Identifier: BSD-3-Clause-Clear +""" +LLM extraction pipeline for RISC-V architectural parameters. + +Assembles prompts from Phase 2 templates, sends them to LLM APIs, +parses structured JSON responses, and stores results per chunk and model. + +Modes: + pilot — run extraction on machine.adoc chunks only (for prompt validation) + run — run extraction on all chunks + merge — merge per-chunk results into a single all_results_{model}.json + status — show progress (which chunks have been processed) +""" + +from __future__ import annotations + +import argparse +import json +import logging +import os +import re +import sys +import time +from dataclasses import dataclass +from datetime import datetime +from pathlib import Path + +SCRIPT_DIR = Path(__file__).resolve().parent +PROJECT_DIR = SCRIPT_DIR.parent +CHUNKS_DIR = PROJECT_DIR / "chunks" +RESULTS_DIR = PROJECT_DIR / "results" +PROMPTS_DIR = PROJECT_DIR / "prompts" / "v1" +DATA_DIR = PROJECT_DIR / "data" + +PROMPT_VERSION = os.environ.get("PROMPT_VERSION", "v1") + +sys.path.insert(0, str(SCRIPT_DIR)) +from run_prompt import ( # noqa: E402 + estimate_tokens, + format_examples_section, + format_param_names_section, + load_examples, + load_system_prompt, + load_udb_param_names, +) + +logger = logging.getLogger("extract") + +# Rate limit: 30K input tokens per minute for this API tier. +# We track token expenditure and sleep as needed. +RATE_LIMIT_TOKENS_PER_MIN = 30_000 + + +class RateLimiter: + """Token-bucket rate limiter respecting Anthropic's per-minute input token limit. + + Uses 75% of the nominal limit as effective budget to account for token + estimation inaccuracies and API-side accounting differences. + """ + + SAFETY_FACTOR = 0.75 + + def __init__(self, tokens_per_min: int = RATE_LIMIT_TOKENS_PER_MIN) -> None: + self.tokens_per_min = tokens_per_min + self.effective_limit = int(tokens_per_min * self.SAFETY_FACTOR) + self._log: list[tuple[float, int]] = [] + + def _prune(self, now: float) -> None: + cutoff = now - 60.0 + self._log = [(t, n) for t, n in self._log if t > cutoff] + + def wait_if_needed(self, estimated_tokens: int) -> float: + """Block until we have budget for `estimated_tokens`. Returns seconds waited.""" + total_waited = 0.0 + while True: + now = time.monotonic() + self._prune(now) + used = sum(n for _, n in self._log) + if used + estimated_tokens <= self.effective_limit: + break + if not self._log: + break + oldest_ts = self._log[0][0] + wait = max(oldest_ts + 61.0 - now, 5.0) + logger.info( + " Rate limit: %d/%d tokens used (effective %d), waiting %.0fs", + used, + self.tokens_per_min, + self.effective_limit, + wait, + ) + time.sleep(wait) + total_waited += wait + return total_waited + + def record(self, tokens: int) -> None: + self._log.append((time.monotonic(), tokens)) + + +REQUIRED_PARAM_FIELDS = { + "excerpt", + "line_number", + "parameter_name", + "existing_udb_name", + "class", + "value_type", + "confidence", + "reasoning", +} + +VALID_CLASSES = { + "NORM_DIRECT", + "NORM_CSR_WARL", + "NORM_CSR_RW", + "SW_RULE", + "NON_ISA", + "NON_NORM", + "DOC_RULE", + "UNKNOWN", +} + +VALID_VALUE_TYPES = {"binary", "enum", "range", "set", "bitmask", "value"} + +# Source files with no architectural parameters (boilerplate, non-normative, +# formal proofs, examples, or top-level include wrappers). Skipping these +# saves ~23% of input tokens with zero recall loss. +SKIP_SOURCE_FILES: set[str] = { + "bibliography.adoc", + "bitmanip-examples.adoc", + "calling-convention.adoc", + "colophon.adoc", + "index.adoc", + "mm-alloy.adoc", + "mm-eplan.adoc", + "mm-formal.adoc", + "mm-herd.adoc", + "priv-history.adoc", + "priv-insns.adoc", + "priv-preface.adoc", + "priv-rationale.adoc", + "rationale.adoc", + "riscv-privileged.adoc", + "riscv-unprivileged.adoc", + "rv-32-64g.adoc", + "symbols.adoc", + "vector-examples.adoc", +} + +MODEL_ALIASES: dict[str, dict[str, str]] = { + "claude": { + "provider": "anthropic", + "model_id": "claude-sonnet-4-20250514", + "display_name": "claude-sonnet-4", + }, + "gpt4o": { + "provider": "openai", + "model_id": "gpt-4o-2024-11-20", + "display_name": "gpt-4o", + }, + "gemini": { + "provider": "google", + "model_id": "gemini-2.5-pro", + "display_name": "gemini-2.5-pro", + }, +} + + +@dataclass +class ExtractionResult: + chunk_id: str + source_file: str + start_line: int + end_line: int + content_start_line: int + model: str + parameters: list[dict] + skipped_non_parameters: list[dict] + raw_response: str + input_tokens: int + output_tokens: int + latency_ms: int + timestamp: str + error: str | None = None + retry_count: int = 0 + + def to_dict(self) -> dict: + return { + "chunk_id": self.chunk_id, + "source_file": self.source_file, + "start_line": self.start_line, + "end_line": self.end_line, + "content_start_line": self.content_start_line, + "model": self.model, + "parameters": self.parameters, + "skipped_non_parameters": self.skipped_non_parameters, + "raw_response": self.raw_response, + "input_tokens": self.input_tokens, + "output_tokens": self.output_tokens, + "latency_ms": self.latency_ms, + "timestamp": self.timestamp, + "error": self.error, + "retry_count": self.retry_count, + } + + +# --- Prompt assembly --- + + +def build_user_message(chunk_text: str, chunk_meta: dict) -> str: + """Build the user message from examples + param names + chunk.""" + examples = load_examples() + param_names = load_udb_param_names() + + parts = [ + format_examples_section(examples), + format_param_names_section(param_names), + _format_chunk(chunk_text, chunk_meta), + ] + return "\n\n---\n\n".join(parts) + + +def _format_chunk(chunk_text: str, meta: dict) -> str: + lines = [ + "## Specification Text to Analyze", + "", + f"File: `{meta['source_file']}`", + f"Lines: {meta['start_line']}-{meta['end_line']}", + "", + "Analyze the following specification text and extract all architectural parameters.", + f"Include line numbers relative to the original file (starting from line {meta['start_line']}).", + "", + "```", + chunk_text, + "```", + ] + return "\n".join(lines) + + +# --- LLM API callers --- + + +def call_anthropic(system_prompt: str, user_message: str, model_id: str) -> dict: + """Call the Anthropic API with 429 backoff. Returns {text, input_tokens, output_tokens}.""" + try: + import anthropic + except ImportError: + raise RuntimeError("Install anthropic: pip install anthropic") + + client = anthropic.Anthropic(max_retries=0) + + max_429_retries = 5 + for retry_429 in range(max_429_retries + 1): + try: + t0 = time.monotonic() + response = client.messages.create( + model=model_id, + max_tokens=8192, + temperature=0, + system=system_prompt, + messages=[{"role": "user", "content": user_message}], + ) + latency = int((time.monotonic() - t0) * 1000) + + text = response.content[0].text + return { + "text": text, + "input_tokens": response.usage.input_tokens, + "output_tokens": response.usage.output_tokens, + "latency_ms": latency, + } + except anthropic.RateLimitError: + if retry_429 >= max_429_retries: + raise + wait = 30 * (2**retry_429) + logger.warning( + " 429 rate limit, backing off %ds (attempt %d/%d)", + wait, + retry_429 + 1, + max_429_retries, + ) + time.sleep(wait) + + raise RuntimeError("Unreachable") + + +def call_openai(system_prompt: str, user_message: str, model_id: str) -> dict: + """Call the OpenAI API. Returns {text, input_tokens, output_tokens}.""" + try: + import openai + except ImportError: + raise RuntimeError("Install openai: pip install openai") + + client = openai.OpenAI() + t0 = time.monotonic() + response = client.chat.completions.create( + model=model_id, + temperature=0, + max_tokens=8192, + messages=[ + {"role": "system", "content": system_prompt}, + {"role": "user", "content": user_message}, + ], + ) + latency = int((time.monotonic() - t0) * 1000) + + text = response.choices[0].message.content + usage = response.usage + return { + "text": text, + "input_tokens": usage.prompt_tokens, + "output_tokens": usage.completion_tokens, + "latency_ms": latency, + } + + +def call_google(system_prompt: str, user_message: str, model_id: str) -> dict: + """Call the Google Gemini API. Returns {text, input_tokens, output_tokens}.""" + try: + from google import genai + from google.genai import types + except ImportError: + raise RuntimeError("Install google-genai: pip install google-genai") + + client = genai.Client() + t0 = time.monotonic() + response = client.models.generate_content( + model=model_id, + contents=user_message, + config=types.GenerateContentConfig( + system_instruction=system_prompt, + temperature=0, + max_output_tokens=8192, + ), + ) + latency = int((time.monotonic() - t0) * 1000) + + text = response.text + input_tokens = response.usage_metadata.prompt_token_count or 0 + output_tokens = response.usage_metadata.candidates_token_count or 0 + + return { + "text": text, + "input_tokens": input_tokens, + "output_tokens": output_tokens, + "latency_ms": latency, + } + + +def call_llm( + provider: str, + system_prompt: str, + user_message: str, + model_id: str, +) -> dict: + """Dispatch to the appropriate LLM provider.""" + callers = { + "anthropic": call_anthropic, + "openai": call_openai, + "google": call_google, + } + caller = callers.get(provider) + if not caller: + raise ValueError(f"Unknown provider: {provider}") + return caller(system_prompt, user_message, model_id) + + +# --- JSON parsing and validation --- + + +def extract_json_from_response(text: str) -> dict | None: + """Extract JSON object from LLM response text, handling markdown fences.""" + text = text.strip() + + fence_match = re.search(r"```(?:json)?\s*\n(.*?)```", text, re.DOTALL) + if fence_match: + text = fence_match.group(1).strip() + + if text.startswith("{"): + try: + return json.loads(text) + except json.JSONDecodeError: + pass + + brace_start = text.find("{") + brace_end = text.rfind("}") + if brace_start != -1 and brace_end > brace_start: + try: + return json.loads(text[brace_start : brace_end + 1]) + except json.JSONDecodeError: + pass + + return None + + +def validate_result(data: dict) -> tuple[list[dict], list[dict], list[str]]: + """ + Validate extracted JSON against expected schema. + Returns (parameters, skipped, warnings). + """ + warnings: list[str] = [] + + if "parameters" not in data: + warnings.append("Missing 'parameters' key in response") + params = [] + else: + params = data["parameters"] + if not isinstance(params, list): + warnings.append("'parameters' is not a list") + params = [] + + skipped = data.get("skipped_non_parameters", []) + if not isinstance(skipped, list): + skipped = [] + + validated_params: list[dict] = [] + for i, p in enumerate(params): + if not isinstance(p, dict): + warnings.append(f"Parameter {i} is not a dict") + continue + + missing = REQUIRED_PARAM_FIELDS - set(p.keys()) + if missing: + warnings.append( + f"Parameter {i} ({p.get('parameter_name', '?')}) missing fields: {missing}" + ) + + cls = p.get("class", "") + if cls and cls not in VALID_CLASSES: + warnings.append(f"Parameter {p.get('parameter_name', '?')}: invalid class '{cls}'") + + vt = p.get("value_type", "") + if vt and vt not in VALID_VALUE_TYPES: + warnings.append(f"Parameter {p.get('parameter_name', '?')}: invalid value_type '{vt}'") + + validated_params.append(p) + + return validated_params, skipped, warnings + + +# --- Core extraction --- + + +def process_chunk( + chunk_meta: dict, + chunk_text: str, + model_alias: str, + system_prompt: str, + delay_seconds: float = 1.0, + max_retries: int = 1, + rate_limiter: RateLimiter | None = None, +) -> ExtractionResult: + """Process a single chunk through the LLM pipeline.""" + model_info = MODEL_ALIASES[model_alias] + provider = model_info["provider"] + model_id = model_info["model_id"] + display_name = model_info["display_name"] + + user_message = build_user_message(chunk_text, chunk_meta) + est_tokens = estimate_tokens(system_prompt + user_message) + + logger.info( + "Processing %s (%s, lines %d-%d, ~%d tokens)", + chunk_meta["chunk_id"], + chunk_meta["source_file"], + chunk_meta["start_line"], + chunk_meta["end_line"], + est_tokens, + ) + + if rate_limiter: + rate_limiter.wait_if_needed(est_tokens) + + last_error = None + for attempt in range(max_retries + 1): + try: + if attempt > 0: + logger.info(" Retry %d/%d for %s", attempt, max_retries, chunk_meta["chunk_id"]) + time.sleep(delay_seconds * 2) + + api_result = call_llm(provider, system_prompt, user_message, model_id) + if rate_limiter: + rate_limiter.record(api_result["input_tokens"]) + raw_text = api_result["text"] + + parsed = extract_json_from_response(raw_text) + if parsed is None: + if attempt < max_retries: + last_error = "JSON parse failed" + logger.warning(" JSON parse failed, will retry") + continue + logger.error(" JSON parse failed after all retries") + return ExtractionResult( + chunk_id=chunk_meta["chunk_id"], + source_file=chunk_meta["source_file"], + start_line=chunk_meta["start_line"], + end_line=chunk_meta["end_line"], + content_start_line=chunk_meta["content_start_line"], + model=display_name, + parameters=[], + skipped_non_parameters=[], + raw_response=raw_text, + input_tokens=api_result["input_tokens"], + output_tokens=api_result["output_tokens"], + latency_ms=api_result["latency_ms"], + timestamp=datetime.now(datetime.UTC).isoformat(), + error="JSON parse failed", + retry_count=attempt, + ) + + params, skipped, warnings = validate_result(parsed) + for w in warnings: + logger.warning(" Validation: %s", w) + + logger.info( + " Found %d parameters, %d skipped (%d input, %d output tokens, %dms)", + len(params), + len(skipped), + api_result["input_tokens"], + api_result["output_tokens"], + api_result["latency_ms"], + ) + + return ExtractionResult( + chunk_id=chunk_meta["chunk_id"], + source_file=chunk_meta["source_file"], + start_line=chunk_meta["start_line"], + end_line=chunk_meta["end_line"], + content_start_line=chunk_meta["content_start_line"], + model=display_name, + parameters=params, + skipped_non_parameters=skipped, + raw_response=raw_text, + input_tokens=api_result["input_tokens"], + output_tokens=api_result["output_tokens"], + latency_ms=api_result["latency_ms"], + timestamp=datetime.now(datetime.UTC).isoformat(), + retry_count=attempt, + ) + + except Exception as exc: + last_error = str(exc) + logger.error(" API error: %s", last_error) + if attempt < max_retries: + time.sleep(delay_seconds * 2) + + return ExtractionResult( + chunk_id=chunk_meta["chunk_id"], + source_file=chunk_meta["source_file"], + start_line=chunk_meta["start_line"], + end_line=chunk_meta["end_line"], + content_start_line=chunk_meta["content_start_line"], + model=display_name, + parameters=[], + skipped_non_parameters=[], + raw_response="", + input_tokens=0, + output_tokens=0, + latency_ms=0, + timestamp=datetime.now(datetime.UTC).isoformat(), + error=last_error or "Unknown error", + retry_count=max_retries, + ) + + +# --- Orchestration --- + + +def load_manifest() -> dict: + manifest_path = CHUNKS_DIR / "manifest.json" + if not manifest_path.exists(): + raise FileNotFoundError(f"Manifest not found: {manifest_path}. Run chunker.py first.") + with open(manifest_path) as f: + return json.load(f) + + +def load_chunk_text(chunk_id: str) -> str: + """Load chunk text from file, stripping the metadata header.""" + chunk_path = CHUNKS_DIR / f"{chunk_id}.txt" + if not chunk_path.exists(): + raise FileNotFoundError(f"Chunk file not found: {chunk_path}") + + text = chunk_path.read_text(encoding="utf-8") + lines = text.splitlines(keepends=True) + + content_start = 0 + for i, line in enumerate(lines): + if line.strip() == "#": + content_start = i + 1 + break + if not line.startswith("#"): + content_start = i + break + + if content_start < len(lines) and lines[content_start].strip() == "": + content_start += 1 + + return "".join(lines[content_start:]) + + +def get_result_path(model_alias: str, chunk_id: str) -> Path: + display = MODEL_ALIASES[model_alias]["display_name"] + if PROMPT_VERSION != "v1": + model_dir = RESULTS_DIR / PROMPT_VERSION / display + else: + model_dir = RESULTS_DIR / display + model_dir.mkdir(parents=True, exist_ok=True) + return model_dir / f"{chunk_id}.json" + + +def is_chunk_done(model_alias: str, chunk_id: str) -> bool: + result_path = get_result_path(model_alias, chunk_id) + if not result_path.exists(): + return False + try: + with open(result_path) as f: + data = json.load(f) + return data.get("error") is None + except (json.JSONDecodeError, KeyError): + return False + + +def run_extraction( + model_alias: str, + chunk_filter: list[str] | None = None, + source_filter: str | None = None, + delay: float = 1.0, + skip_done: bool = True, + max_retries: int = 1, + include_skipped_sources: bool = False, +) -> list[ExtractionResult]: + """Run extraction on selected chunks.""" + manifest = load_manifest() + system_prompt = load_system_prompt() + + chunks_to_process = manifest["chunks"] + + if not include_skipped_sources: + before = len(chunks_to_process) + chunks_to_process = [ + c for c in chunks_to_process if c["source_file"] not in SKIP_SOURCE_FILES + ] + n_skipped_sources = before - len(chunks_to_process) + if n_skipped_sources: + logger.info( + "Skipping %d chunks from non-parameter source files", + n_skipped_sources, + ) + + if source_filter: + chunks_to_process = [c for c in chunks_to_process if source_filter in c["source_file"]] + if chunk_filter: + chunks_to_process = [c for c in chunks_to_process if c["chunk_id"] in chunk_filter] + + limiter = RateLimiter() + + results: list[ExtractionResult] = [] + total = len(chunks_to_process) + skipped = 0 + + for idx, chunk_meta in enumerate(chunks_to_process): + chunk_id = chunk_meta["chunk_id"] + + if skip_done and is_chunk_done(model_alias, chunk_id): + logger.info("Skipping %s (already done)", chunk_id) + skipped += 1 + continue + + chunk_text = load_chunk_text(chunk_id) + result = process_chunk( + chunk_meta=chunk_meta, + chunk_text=chunk_text, + model_alias=model_alias, + system_prompt=system_prompt, + delay_seconds=delay, + max_retries=max_retries, + rate_limiter=limiter, + ) + + result_path = get_result_path(model_alias, chunk_id) + with open(result_path, "w") as f: + json.dump(result.to_dict(), f, indent=2) + f.write("\n") + + results.append(result) + + if delay > 0 and idx < total - 1: + time.sleep(delay) + + logger.info( + "Done: %d processed, %d skipped, %d total", + len(results), + skipped, + total, + ) + return results + + +def merge_results(model_alias: str) -> Path: + """Merge per-chunk results into a single file.""" + display = MODEL_ALIASES[model_alias]["display_name"] + if PROMPT_VERSION != "v1": + model_dir = RESULTS_DIR / PROMPT_VERSION / display + else: + model_dir = RESULTS_DIR / display + + if not model_dir.exists(): + raise FileNotFoundError(f"No results directory: {model_dir}") + + chunk_files = sorted(model_dir.glob("chunk_*.json")) + if not chunk_files: + raise FileNotFoundError(f"No chunk results in {model_dir}") + + all_results: list[dict] = [] + total_params = 0 + total_skipped = 0 + total_input_tokens = 0 + total_output_tokens = 0 + errors = 0 + + for cf in chunk_files: + with open(cf) as f: + data = json.load(f) + all_results.append(data) + total_params += len(data.get("parameters", [])) + total_skipped += len(data.get("skipped_non_parameters", [])) + total_input_tokens += data.get("input_tokens", 0) + total_output_tokens += data.get("output_tokens", 0) + if data.get("error"): + errors += 1 + + output = { + "model": display, + "total_chunks": len(all_results), + "total_parameters": total_params, + "total_skipped": total_skipped, + "total_input_tokens": total_input_tokens, + "total_output_tokens": total_output_tokens, + "errors": errors, + "results": all_results, + } + + if PROMPT_VERSION != "v1": + output_path = RESULTS_DIR / PROMPT_VERSION / f"all_results_{display}.json" + else: + output_path = RESULTS_DIR / f"all_results_{display}.json" + with open(output_path, "w") as f: + json.dump(output, f, indent=2) + f.write("\n") + + logger.info( + "Merged %d chunks -> %s (%d params, %d skipped, %d errors, %d/%d tokens)", + len(all_results), + output_path.name, + total_params, + total_skipped, + errors, + total_input_tokens, + total_output_tokens, + ) + return output_path + + +# --- CLI --- + + +def setup_logging(verbose: bool = False) -> None: + level = logging.DEBUG if verbose else logging.INFO + logging.basicConfig( + level=level, + format="%(asctime)s [%(levelname)s] %(message)s", + datefmt="%H:%M:%S", + ) + + +def cmd_pilot(args: argparse.Namespace) -> None: + """Pilot extraction on machine.adoc only.""" + setup_logging(args.verbose) + logger.info("Pilot run: model=%s, source=machine.adoc", args.model) + results = run_extraction( + model_alias=args.model, + source_filter="machine.adoc", + delay=args.delay, + skip_done=not args.force, + max_retries=args.retries, + ) + _print_summary(results, args.model) + + +def cmd_run(args: argparse.Namespace) -> None: + """Run extraction on all chunks.""" + setup_logging(args.verbose) + source = args.source if args.source else None + include_all = getattr(args, "include_all", False) + logger.info("Full run: model=%s, source=%s", args.model, source or "all") + results = run_extraction( + model_alias=args.model, + source_filter=source, + delay=args.delay, + skip_done=not args.force, + max_retries=args.retries, + include_skipped_sources=include_all, + ) + _print_summary(results, args.model) + + +def cmd_merge(args: argparse.Namespace) -> None: + """Merge per-chunk results.""" + setup_logging(args.verbose) + output_path = merge_results(args.model) + print(f"Merged results written to: {output_path}") + + +def cmd_status(args: argparse.Namespace) -> None: + """Show extraction progress.""" + setup_logging(False) + manifest = load_manifest() + total_chunks = manifest["total_chunks"] + processable = [c for c in manifest["chunks"] if c["source_file"] not in SKIP_SOURCE_FILES] + print( + f"Total chunks: {total_chunks} ({len(processable)} with parameters, " + f"{total_chunks - len(processable)} skipped)" + ) + + for _alias, info in MODEL_ALIASES.items(): + display = info["display_name"] + if PROMPT_VERSION != "v1": + model_dir = RESULTS_DIR / PROMPT_VERSION / display + else: + model_dir = RESULTS_DIR / display + if not model_dir.exists(): + print(f" {display}: not started") + continue + + done_files = list(model_dir.glob("chunk_*.json")) + done = 0 + errored = 0 + total_params = 0 + total_input = 0 + total_output = 0 + for df in done_files: + try: + with open(df) as f: + data = json.load(f) + if data.get("error"): + errored += 1 + else: + done += 1 + total_params += len(data.get("parameters", [])) + total_input += data.get("input_tokens", 0) + total_output += data.get("output_tokens", 0) + except (json.JSONDecodeError, KeyError): + errored += 1 + + print( + f" {display}: {done}/{total_chunks} done, {errored} errors, " + f"{total_params} params, {total_input:,}+{total_output:,} tokens" + ) + + +def _print_summary(results: list[ExtractionResult], model_alias: str) -> None: + if not results: + print("No chunks processed (all skipped or none matched filter).") + return + + display = MODEL_ALIASES[model_alias]["display_name"] + total_params = sum(len(r.parameters) for r in results) + total_skipped = sum(len(r.skipped_non_parameters) for r in results) + total_input = sum(r.input_tokens for r in results) + total_output = sum(r.output_tokens for r in results) + total_latency = sum(r.latency_ms for r in results) + error_count = sum(1 for r in results if r.error) + + print(f"\n{'=' * 50}") + print(f"Extraction Summary: {display}") + print(f"{'=' * 50}") + print(f" Chunks processed: {len(results)}") + print(f" Parameters found: {total_params}") + print(f" Non-params skipped: {total_skipped}") + print(f" Errors: {error_count}") + print(f" Input tokens: {total_input:,}") + print(f" Output tokens: {total_output:,}") + print(f" Total latency: {total_latency / 1000:.1f}s") + if error_count: + print("\n Errors:") + for r in results: + if r.error: + print(f" {r.chunk_id}: {r.error}") + + +def main() -> None: + parser = argparse.ArgumentParser( + description="LLM extraction pipeline for RISC-V parameters", + ) + subparsers = parser.add_subparsers(dest="command", required=True) + + # Shared args + def add_common_args(p: argparse.ArgumentParser) -> None: + p.add_argument( + "--model", + required=True, + choices=list(MODEL_ALIASES.keys()), + help="Model alias to use", + ) + p.add_argument( + "--delay", type=float, default=1.0, help="Delay between API calls in seconds" + ) + p.add_argument("--retries", type=int, default=1, help="Max retries on parse failure") + p.add_argument( + "--force", action="store_true", help="Re-process chunks even if results exist" + ) + p.add_argument("-v", "--verbose", action="store_true") + + p_pilot = subparsers.add_parser("pilot", help="Pilot on machine.adoc") + add_common_args(p_pilot) + p_pilot.set_defaults(func=cmd_pilot) + + p_run = subparsers.add_parser("run", help="Run on all chunks") + add_common_args(p_run) + p_run.add_argument("--source", help="Filter to a specific source file") + p_run.add_argument( + "--include-all", + action="store_true", + help="Include non-parameter source files (normally skipped)", + ) + p_run.set_defaults(func=cmd_run) + + p_merge = subparsers.add_parser("merge", help="Merge per-chunk results") + p_merge.add_argument("--model", required=True, choices=list(MODEL_ALIASES.keys())) + p_merge.add_argument("-v", "--verbose", action="store_true") + p_merge.set_defaults(func=cmd_merge) + + p_status = subparsers.add_parser("status", help="Show progress") + p_status.set_defaults(func=cmd_status) + + args = parser.parse_args() + args.func(args) + + +if __name__ == "__main__": + main() diff --git a/param_extraction/scripts/generate_report.py b/param_extraction/scripts/generate_report.py new file mode 100644 index 0000000000..0d0ed2b10a --- /dev/null +++ b/param_extraction/scripts/generate_report.py @@ -0,0 +1,241 @@ +#!/usr/bin/env python3 +""" +Phase 1, Final: Generate a comprehensive human-readable report and CSV +from the ground truth and spec mapping data. + +Produces: + - data/phase1_report.txt (human-readable summary) + - data/parameters_catalog.csv (spreadsheet-ready catalog) + - data/udb_param_names.txt (flat list for LLM prompt inclusion) + +Reads: + - data/ground_truth.json + - data/spec_mappings.json +""" + +import json +import csv +from pathlib import Path +from collections import defaultdict + +DATA_DIR = Path(__file__).resolve().parent.parent / "data" + + +def main(): + # Load data + with open(DATA_DIR / "ground_truth.json", encoding="utf-8") as f: + gt = json.load(f) + with open(DATA_DIR / "spec_mappings.json", encoding="utf-8") as f: + sm = json.load(f) + + params = gt["parameters"] + mappings = {m["parameter_name"]: m for m in sm["mappings"]} + + # Generate flat name list (for LLM prompts) + names = sorted(p["name"] for p in params) + names_path = DATA_DIR / "udb_param_names.txt" + with open(names_path, "w") as f: + for name in names: + f.write(name + "\n") + print(f"Written {len(names)} parameter names to {names_path}") + + # Generate CSV catalog + csv_path = DATA_DIR / "parameters_catalog.csv" + generate_csv(params, mappings, csv_path) + print(f"Written CSV catalog to {csv_path}") + + # Generate human-readable report + report_path = DATA_DIR / "phase1_report.txt" + generate_report(params, mappings, gt["statistics"], sm["metadata"], report_path) + print(f"Written report to {report_path}") + + +def generate_csv(params, mappings, out_path): + """Generate a CSV file suitable for review or import into a spreadsheet.""" + rows = [] + for p in params: + m = mappings.get(p["name"], {}) + candidates = m.get("candidates", []) + best = candidates[0] if candidates else {} + + rows.append({ + "parameter_name": p["name"], + "long_name": p["long_name"], + "classification": p["classification"], + "classification_confidence": p["classification_confidence"], + "classification_reasoning": p["classification_reasoning"], + "value_type": p["value_type"]["type"], + "value_details": _format_value_details(p["value_type"]), + "defined_by_extensions": ", ".join(p["defined_by"]["extensions"]), + "defined_by_summary": p["defined_by"]["summary"], + "has_requirements": p["has_requirements"], + "num_csr_references": len(p["csr_references"]), + "csr_names": ", ".join(sorted(set( + r["csr"] for r in p["csr_references"] + ))), + "spec_file": best.get("file", ""), + "spec_line": best.get("line_number", ""), + "spec_score": best.get("score", 0), + "spec_is_normative": best.get("is_normative", ""), + "spec_in_note": best.get("in_note", ""), + "spec_text": best.get("line_text", "")[:200], + "description": p["description"][:300], + }) + + with open(out_path, "w", newline="", encoding="utf-8") as f: + writer = csv.DictWriter(f, fieldnames=list(rows[0].keys())) + writer.writeheader() + writer.writerows(rows) + + +def _format_value_details(value_type): + """Format value type details into a compact string.""" + vt = value_type["type"] + details = value_type.get("details", {}) + + if vt == "binary": + choices = details.get("choices", []) + return f"choices: {choices}" + elif vt == "enum": + vals = details.get("values", []) + if len(vals) <= 5: + return f"values: {vals}" + return f"{len(vals)} values" + elif vt == "range": + return f"[{details.get('minimum', '?')}..{details.get('maximum', '?')}]" + elif vt == "set": + universe = details.get("universe", []) + if universe: + return f"subset of {universe}" + return f"set of {details.get('element_type', '?')}" + elif vt == "bitmask": + return f"{details.get('length', '?')}-bit mask" + elif vt == "conditional": + branches = details.get("branches", []) + return f"{len(branches)} conditional branches" + return str(details)[:80] + + +def generate_report(params, mappings, stats, mapping_meta, out_path): + """Generate a comprehensive human-readable report.""" + lines = [] + w = lines.append + + w("=" * 72) + w("PHASE 1 REPORT: UDB Parameter Ground Truth") + w("RISC-V Architectural Parameter Extraction Project") + w("=" * 72) + w("") + + # --- Overview --- + w("1. OVERVIEW") + w("-" * 40) + w(f" Total real parameters in UDB: {len(params)}") + w(f" Spec files searched: {mapping_meta['spec_files_searched']}") + w(f" Total spec lines: {mapping_meta['total_spec_lines']}") + w(f" Parameters with spec matches: {mapping_meta['params_with_matches']} ({mapping_meta['params_with_matches']*100//len(params)}%)") + w(f" Parameters with strong matches: {mapping_meta['params_with_strong_matches']} ({mapping_meta['params_with_strong_matches']*100//len(params)}%)") + w("") + + # --- Classification breakdown --- + w("2. CLASSIFICATION BREAKDOWN") + w("-" * 40) + for cls, count in sorted(stats["by_classification"].items()): + pct = count * 100 // len(params) + w(f" {cls:20s} {count:4d} ({pct:2d}%)") + w("") + w(" Classification descriptions:") + w(" NORM_DIRECT = Normative, directly configurable (not CSR-controlled)") + w(" NORM_CSR_WARL = Normative, legal values of a WARL CSR field") + w(" NORM_CSR_RW = Normative, controls whether CSR field is RO/RW") + w(" SW_RULE = Software-deterministic (impl-defined but deterministic w/ correct SW)") + w("") + + # --- Value type breakdown --- + w("3. VALUE TYPE BREAKDOWN") + w("-" * 40) + for vt, count in sorted(stats["by_value_type"].items()): + pct = count * 100 // len(params) + w(f" {vt:20s} {count:4d} ({pct:2d}%)") + w("") + w(" Value type descriptions:") + w(" binary = Exactly 2 choices (boolean or 2-value enum)") + w(" enum = Finite set of 3+ discrete values") + w(" range = Continuous integer range with min/max bounds") + w(" set = Subset selection from a fixed universe of values") + w(" bitmask = Fixed-length boolean array (one bit per feature)") + w(" conditional = Schema varies based on another parameter (e.g., MXLEN)") + w(" value = Single unconstrained value") + w("") + + # --- Confidence breakdown --- + w("4. CLASSIFICATION CONFIDENCE") + w("-" * 40) + for conf, count in sorted(stats["by_confidence"].items()): + pct = count * 100 // len(params) + w(f" {conf:20s} {count:4d} ({pct:2d}%)") + w("") + + # --- Extension breakdown --- + w("5. DEFINING EXTENSIONS (Top 15)") + w("-" * 40) + for ext, count in list(stats["top_defining_extensions"].items())[:15]: + w(f" {ext:20s} {count:4d}") + w("") + + # --- Detailed parameter listing by classification --- + w("6. PARAMETER LISTING BY CLASSIFICATION") + w("-" * 40) + + by_class = defaultdict(list) + for p in params: + by_class[p["classification"]].append(p) + + for cls in ["NORM_DIRECT", "NORM_CSR_WARL", "NORM_CSR_RW", "SW_RULE", "UNKNOWN"]: + class_params = by_class.get(cls, []) + if not class_params: + continue + + w(f"\n --- {cls} ({len(class_params)} parameters) ---") + for p in sorted(class_params, key=lambda x: x["name"]): + m = mappings.get(p["name"], {}) + candidates = m.get("candidates", []) + best = candidates[0] if candidates else {} + + vt = p["value_type"] + vt_str = vt["type"] + if vt["type"] == "binary": + choices = vt.get("details", {}).get("choices", []) + vt_str = f"binary({choices})" + elif vt["type"] == "enum": + vals = vt.get("details", {}).get("values", []) + vt_str = f"enum({len(vals)} vals)" + + spec_loc = "" + if best: + spec_loc = f" -> {best.get('file', '?')}:{best.get('line_number', '?')}" + if best.get("is_normative"): + spec_loc += " [NORM]" + + csr_str = "" + if p["csr_references"]: + csrs = sorted(set(r["csr"] for r in p["csr_references"]))[:3] + csr_str = f" CSRs: {', '.join(csrs)}" + + w(f" {p['name']}") + w(f" Type: {vt_str} | Exts: {p['defined_by']['summary']}{csr_str}") + if spec_loc: + w(f" Spec:{spec_loc}") + w(f" Conf: {p['classification_confidence']} | {p['classification_reasoning'][:90]}") + + w("") + w("=" * 72) + w("END OF REPORT") + w("=" * 72) + + with open(out_path, "w", encoding="utf-8") as f: + f.write("\n".join(lines)) + + +if __name__ == "__main__": + main() diff --git a/param_extraction/scripts/map_params_to_spec.py b/param_extraction/scripts/map_params_to_spec.py new file mode 100644 index 0000000000..eeef251c16 --- /dev/null +++ b/param_extraction/scripts/map_params_to_spec.py @@ -0,0 +1,413 @@ +#!/usr/bin/env python3 +""" +Phase 1, Step 2: Map UDB parameters to their source locations in the RISC-V spec. + +For each parameter, searches the spec .adoc files for sentences that describe +the implementation choice that parameter represents. Uses multiple search +strategies: keyword matching from descriptions, CSR name references, +known WARL/implementation-defined language patterns, and exact name matches. + +Reads: data/ground_truth.json +Output: data/spec_mappings.json +""" + +import json +import re +from pathlib import Path +from collections import defaultdict + +REPO_ROOT = Path(__file__).resolve().parent.parent.parent +SPEC_DIR = REPO_ROOT / "ext" / "riscv-isa-manual" / "src" +DATA_DIR = Path(__file__).resolve().parent.parent / "data" + + +# --------------------------------------------------------------------------- +# Spec file loading and indexing +# --------------------------------------------------------------------------- + +def load_spec_files(): + """Load all .adoc files from the spec directory, returning {filename: [lines]}.""" + spec_files = {} + for adoc in sorted(SPEC_DIR.glob("*.adoc")): + with open(adoc, encoding="utf-8") as f: + spec_files[adoc.name] = f.readlines() + return spec_files + + +def is_note_block(lines, line_idx): + """ + Check if a given line is inside a NOTE/TIP/WARNING block (non-normative). + AsciiDoc NOTE blocks are delimited by '===='. + Also checks for explicit [NOTE]/[TIP]/[WARNING] markers. + """ + note_markers = {"[NOTE]", "[TIP]", "[WARNING]", "[IMPORTANT]", "[CAUTION]"} + + # Look backwards from this line for the nearest block marker + depth = 0 + for i in range(line_idx - 1, max(line_idx - 30, -1), -1): + if i < 0: + break + stripped = lines[i].strip() + if stripped == "====": + depth += 1 + if depth == 1: + # Check if the line before this ==== is a note marker + for j in range(i - 1, max(i - 3, -1), -1): + if j >= 0 and lines[j].strip() in note_markers: + return True + return False + return False + + +# --------------------------------------------------------------------------- +# Search strategy: build search terms from parameter metadata +# --------------------------------------------------------------------------- + +def build_search_terms(param): + """ + Build a list of (pattern, weight, reason) tuples to search for this parameter. + Higher weight = more likely to be a relevant match. + """ + name = param["name"] + desc = param.get("description", "") + long_name = param.get("long_name", "") + csr_refs = param.get("csr_references", []) + defined_by = param.get("defined_by", {}) + value_type = param.get("value_type", {}) + + terms = [] + + # Strategy 0: The parameter name itself (may appear verbatim in spec) + # Match as a whole word, case-sensitive for ALL_CAPS names + if name == name.upper() and len(name) >= 3: + terms.append(( + re.compile(rf'\b{re.escape(name)}\b'), + 6, + f"Exact parameter name '{name}'", + )) + # Also search for the name in italic/emphasis form: _NAME_ + terms.append(( + re.compile(rf'_{re.escape(name)}_'), + 6, + f"Parameter name in emphasis '_{name}_'", + )) + + # Strategy 0b: Search for key segments of multi-word param names + name_segments = name.split('_') + # For short distinctive segments (>=4 chars, not common words), search directly + common_words = {'MODE', 'TYPE', 'VALUE', 'WIDTH', 'LEGAL', 'VALUES', 'READ', + 'ONLY', 'WHEN', 'ZERO', 'BASE', 'TRAP', 'REPORT'} + for seg in name_segments: + if len(seg) >= 4 and seg not in common_words: + terms.append(( + re.compile(rf'\b{re.escape(seg)}\b', re.IGNORECASE), + 1, + f"Name segment '{seg}'", + )) + + # Strategy 1: CSR name + field name (for CSR-related params) + # Cap to avoid score inflation for params with hundreds of CSR refs + csr_names_seen = set() + fields_seen = set() + MAX_CSR_TERMS = 10 + csr_term_count = 0 + for ref in csr_refs: + if csr_term_count >= MAX_CSR_TERMS: + break + csr = ref["csr"] + field = ref["field"] + if csr not in csr_names_seen: + terms.append(( + re.compile(rf'`{re.escape(csr)}`', re.IGNORECASE), + 3, + f"CSR name '{csr}' in backticks", + )) + csr_names_seen.add(csr) + csr_term_count += 1 + if field != "(csr-level)" and field not in fields_seen: + terms.append(( + re.compile(rf'\b{re.escape(field)}\b', re.IGNORECASE), + 2, + f"CSR field name '{field}'", + )) + fields_seen.add(field) + csr_term_count += 1 + + # Strategy 2: Extract key nouns/phrases from parameter description (cap to avoid noise) + desc_keywords = _extract_description_keywords(name, desc) + for kw, weight in desc_keywords[:12]: + terms.append(( + re.compile(rf'\b{re.escape(kw)}\b', re.IGNORECASE), + weight, + f"Description keyword '{kw}'", + )) + + # Strategy 3: Look for WARL near CSR names (for WARL params) + if param.get("classification") in ("NORM_CSR_WARL", "NORM_CSR_RW"): + for csr in csr_names_seen: + terms.append(( + re.compile(rf'WARL.*`{re.escape(csr)}`|`{re.escape(csr)}`.*WARL', re.IGNORECASE), + 5, + f"WARL + CSR '{csr}'", + )) + + # Strategy 4: Specific value mentions for enum/binary params + if value_type.get("type") == "binary": + choices = value_type.get("details", {}).get("choices", []) + if choices == [True, False]: + # For boolean params, look for "may" / "optionally" / "read-only" patterns + terms.append(( + re.compile(r'\b(may\s+optionally|optionally|read-only\s+zero|read-only\s+0)\b', re.IGNORECASE), + 1, + "Optional/read-only pattern for boolean param", + )) + + return terms + + +def _extract_description_keywords(name, description): + """ + Extract meaningful search keywords from the parameter's description. + Returns list of (keyword, weight) tuples. + """ + keywords = [] + + # Extract CSR names from description (things in backticks) + backtick_refs = re.findall(r'`([a-zA-Z][a-zA-Z0-9_.]*)`', description) + for ref in backtick_refs: + keywords.append((ref, 3)) + + # Look for capitalized CSR field references like MODE, BASE, etc. + field_refs = re.findall(r'\b([A-Z]{2,}(?:\.[A-Z]+)?)\b', description) + for ref in field_refs: + if ref not in ('WARL', 'WLRL', 'CSR', 'ISA', 'RISC', 'TODO', 'XLEN', + 'MXLEN', 'AND', 'NOT', 'THE', 'FOR', 'WHEN', 'SXLEN', + 'UXLEN', 'ALL', 'PMP', 'HPM', 'AMO', 'NMI'): + keywords.append((ref, 2)) + + # Extract meaningful phrases based on parameter name segments + name_parts = name.split('_') + # Find multi-word concepts in the name + name_to_phrase = { + 'ENDIANNESS': 'endian', + 'MISALIGNED': 'misaligned', + 'ALIGNMENT': 'align', + 'TRANSLATION': 'translation', + 'RESERVATION': 'reservation', + 'GRANULARITY': 'granularity', + 'BREAKPOINT': 'breakpoint', + 'INSTRUCTION': 'instruction', + 'VECTORED': 'vectored', + 'IMPLEMENTED': 'implemented', + } + for part in name_parts: + phrase = name_to_phrase.get(part) + if phrase: + keywords.append((phrase, 2)) + + return keywords + + +# --------------------------------------------------------------------------- +# Core matching engine +# --------------------------------------------------------------------------- + +def find_spec_locations(param, spec_files): + """ + Search all spec files for text related to this parameter. + + Returns a list of candidate matches, sorted by relevance score. + Each match: {file, line_number, line_text, score, reasons, is_normative, in_note} + """ + search_terms = build_search_terms(param) + if not search_terms: + return [] + + candidates = defaultdict(lambda: { + "score": 0, "reasons": [], "is_normative": False, "in_note": False, + }) + + for filename, lines in spec_files.items(): + for line_idx, line in enumerate(lines): + line_stripped = line.strip() + if not line_stripped or line_stripped.startswith("//"): + continue + + # Skip table-heavy lines (pipes indicate table cells, not prose) + if line_stripped.count('|') >= 3: + continue + + line_key = (filename, line_idx + 1) + + # Track which strategy categories matched to prevent score inflation + segment_score = 0 + max_segment_score = 3 # cap contribution from name-segment matches + normative_bonus_applied = False + + for pattern, weight, reason in search_terms: + if pattern.search(line): + entry = candidates[line_key] + entry["file"] = filename + entry["line_number"] = line_idx + 1 + entry["line_text"] = line_stripped + + if "Name segment" in reason: + segment_score += weight + entry["score"] += min(weight, max_segment_score - (segment_score - weight)) + if segment_score - weight < max_segment_score: + entry["reasons"].append(reason) + else: + entry["score"] += weight + entry["reasons"].append(reason) + + if not normative_bonus_applied and ("[#norm:" in line or "[[norm:" in line): + entry["is_normative"] = True + entry["score"] += 2 + normative_bonus_applied = True + + if is_note_block(lines, line_idx): + entry["in_note"] = True + entry["score"] -= 3 + + # Convert to list, filter low-score noise, sort by score descending + results = [] + MAX_SCORE = 50 + for key, entry in candidates.items(): + if entry["score"] >= 3: + entry["score"] = min(entry["score"], MAX_SCORE) + entry["reasons"] = list(set(entry["reasons"])) + results.append(entry) + + results.sort(key=lambda x: (-x["score"], x["file"], x["line_number"])) + return results[:10] + + +# --------------------------------------------------------------------------- +# Context extraction: get surrounding lines for each match +# --------------------------------------------------------------------------- + +def extract_context(spec_files, filename, line_number, context_lines=2): + """Get the matched line plus surrounding context lines.""" + lines = spec_files.get(filename, []) + if not lines: + return "" + + start = max(0, line_number - 1 - context_lines) + end = min(len(lines), line_number + context_lines) + + context_parts = [] + for i in range(start, end): + prefix = ">>>" if i == line_number - 1 else " " + context_parts.append(f"{prefix} {i+1:5d}| {lines[i].rstrip()}") + + return "\n".join(context_parts) + + +# --------------------------------------------------------------------------- +# Main mapping logic +# --------------------------------------------------------------------------- + +def main(): + # Load ground truth + gt_path = DATA_DIR / "ground_truth.json" + if not gt_path.exists(): + print(f"ERROR: {gt_path} not found. Run export_udb_params.py first.") + return + + with open(gt_path, encoding="utf-8") as f: + ground_truth = json.load(f) + + params = ground_truth["parameters"] + print(f"Loaded {len(params)} parameters from ground truth") + + # Load spec files + print(f"Loading spec files from {SPEC_DIR}...") + spec_files = load_spec_files() + total_lines = sum(len(lines) for lines in spec_files.values()) + print(f" {len(spec_files)} files, {total_lines} total lines") + + # Map each parameter + print("Mapping parameters to spec text...") + mappings = [] + params_with_matches = 0 + params_with_strong_matches = 0 + + for i, param in enumerate(params): + candidates = find_spec_locations(param, spec_files) + + has_match = len(candidates) > 0 + best_score = candidates[0]["score"] if candidates else 0 + has_strong = best_score >= 5 + + if has_match: + params_with_matches += 1 + if has_strong: + params_with_strong_matches += 1 + + # Add context to top candidates + for cand in candidates[:5]: + cand["context"] = extract_context( + spec_files, cand["file"], cand["line_number"] + ) + + entry = { + "parameter_name": param["name"], + "classification": param["classification"], + "value_type": param["value_type"]["type"], + "num_candidates": len(candidates), + "best_score": best_score, + "candidates": candidates[:5], + } + mappings.append(entry) + + if (i + 1) % 20 == 0: + print(f" Processed {i+1}/{len(params)} parameters...") + + # Output + output = { + "metadata": { + "total_parameters": len(params), + "params_with_matches": params_with_matches, + "params_with_strong_matches": params_with_strong_matches, + "spec_files_searched": len(spec_files), + "total_spec_lines": total_lines, + }, + "mappings": mappings, + } + + out_path = DATA_DIR / "spec_mappings.json" + with open(out_path, "w", encoding="utf-8") as f: + json.dump(output, f, indent=2, ensure_ascii=False) + + print(f"\nWritten mappings to {out_path}") + print(f"\n{'='*60}") + print(f"SPEC MAPPING SUMMARY") + print(f"{'='*60}") + print(f"Total parameters: {len(params)}") + print(f"With any match (score>=3): {params_with_matches} ({params_with_matches*100//len(params)}%)") + print(f"With strong match (>=5): {params_with_strong_matches} ({params_with_strong_matches*100//len(params)}%)") + print(f"No matches found: {len(params) - params_with_matches}") + + # Show a few examples of strong matches + print(f"\n--- Sample strong matches ---") + shown = 0 + for m in mappings: + if m["best_score"] >= 7 and shown < 5: + cand = m["candidates"][0] + print(f"\n {m['parameter_name']} (score={cand['score']}, {m['classification']})") + print(f" File: {cand['file']}:{cand['line_number']}") + print(f" Text: {cand['line_text'][:120]}") + shown += 1 + + # Show parameters with no matches + no_match = [m["parameter_name"] for m in mappings if m["num_candidates"] == 0] + if no_match: + print(f"\n--- Parameters with NO spec matches ({len(no_match)}) ---") + for nm in no_match[:20]: + print(f" {nm}") + if len(no_match) > 20: + print(f" ... and {len(no_match) - 20} more") + + +if __name__ == "__main__": + main() diff --git a/param_extraction/scripts/run_prompt.py b/param_extraction/scripts/run_prompt.py new file mode 100644 index 0000000000..7aed208b48 --- /dev/null +++ b/param_extraction/scripts/run_prompt.py @@ -0,0 +1,451 @@ +#!/usr/bin/env python3 +""" +Prompt assembler for RISC-V architectural parameter extraction. + +Combines system prompt + few-shot examples + UDB parameter names + spec chunk +into a complete prompt suitable for LLM analysis. + +Three operational modes: + assemble — build and print a complete prompt for a given spec chunk + chunk — split a spec file into overlapping chunks suitable for LLM context + estimate — report token estimates for each prompt layer +""" + +from __future__ import annotations + +import argparse +import json +import sys +from pathlib import Path +from typing import TypedDict + +SCRIPT_DIR = Path(__file__).resolve().parent +PROJECT_DIR = SCRIPT_DIR.parent +PROMPT_DIR = PROJECT_DIR / "prompts" / "v1" +DATA_DIR = PROJECT_DIR / "data" + +CHARS_PER_TOKEN = 3.8 + +CONTEXT_LIMITS: dict[str, int] = { + "gpt-4o": 128_000, + "gpt-4-turbo": 128_000, + "claude-3-5-sonnet": 200_000, + "claude-3-opus": 200_000, + "gemini-1.5-pro": 1_000_000, + "llama-3-70b": 8_192, + "default": 128_000, +} + +RESERVED_OUTPUT_TOKENS = 4_096 +SYSTEM_OVERHEAD_TOKENS = 200 + +class ChunkMeta(TypedDict): + file: str + start_line: int + end_line: int + total_lines: int + chunk_index: int + total_chunks: int + + +def estimate_tokens(text: str) -> int: + """Rough token estimate using chars/token ratio.""" + return max(1, int(len(text) / CHARS_PER_TOKEN)) + + +def load_system_prompt() -> str: + path = PROMPT_DIR / "system_prompt.txt" + if not path.exists(): + raise FileNotFoundError(f"System prompt not found: {path}") + return path.read_text(encoding="utf-8").strip() + + +def load_examples() -> dict: + path = PROMPT_DIR / "examples.json" + if not path.exists(): + raise FileNotFoundError(f"Examples not found: {path}") + with open(path, encoding="utf-8") as f: + return json.load(f) + + +def load_udb_param_names() -> list[str]: + path = DATA_DIR / "udb_param_names.txt" + if not path.exists(): + raise FileNotFoundError(f"UDB param names not found: {path}") + names = [ + line.strip() + for line in path.read_text(encoding="utf-8").splitlines() + if line.strip() + ] + return sorted(set(names)) + + +def format_examples_section(examples: dict) -> str: + """Format few-shot examples into a clear prompt section.""" + lines = ["## Few-Shot Examples", ""] + lines.append("### Positive Examples (extract these)") + lines.append("") + + for i, ex in enumerate(examples.get("positive_examples", []), 1): + lines.append(f"**Example {i}** — `{ex['input_file']}`, line {ex['input_line']}") + lines.append("") + lines.append("Input text:") + lines.append(f"> {ex['input_excerpt']}") + lines.append("") + lines.append("Expected output:") + lines.append("```json") + lines.append(json.dumps(ex["expected_output"], indent=2)) + lines.append("```") + lines.append("") + + lines.append("### Negative Examples (do NOT extract these)") + lines.append("") + + for i, ex in enumerate(examples.get("negative_examples", []), 1): + lines.append(f"**Non-parameter {i}** — `{ex['input_file']}`, line {ex['input_line']}") + lines.append("") + lines.append("Input text:") + lines.append(f"> {ex['input_excerpt']}") + lines.append("") + lines.append(f"Why not a parameter: {ex['reason_for_rejection']}") + lines.append("") + + return "\n".join(lines) + + +def format_param_names_section(names: list[str]) -> str: + """Format UDB parameter names as a reference list.""" + lines = [ + "## Known UDB Parameter Names", + "", + "When a parameter you find matches one of these known names, use the exact name.", + "For new parameters not in this list, suggest a descriptive UPPER_SNAKE_CASE name.", + "", + ] + lines.append(", ".join(names)) + return "\n".join(lines) + + +def format_chunk_section( + chunk_text: str, meta: ChunkMeta +) -> str: + """Format the spec chunk with metadata for the LLM.""" + lines = [ + "## Specification Text to Analyze", + "", + f"File: `{meta['file']}`", + f"Lines: {meta['start_line']}-{meta['end_line']} " + f"(chunk {meta['chunk_index']}/{meta['total_chunks']})", + "", + "Analyze the following specification text and extract all architectural parameters.", + "Include line numbers relative to the original file (starting from " + f"line {meta['start_line']}).", + "", + "```", + chunk_text, + "```", + ] + return "\n".join(lines) + + +def assemble_prompt( + chunk_text: str, + meta: ChunkMeta, + model: str = "default", + include_examples: bool = True, + include_param_names: bool = True, +) -> dict[str, str]: + """ + Assemble the complete prompt from all layers. + + Returns a dict with 'system' and 'user' keys suitable for chat API calls. + """ + system_prompt = load_system_prompt() + + user_parts: list[str] = [] + + if include_examples: + examples = load_examples() + user_parts.append(format_examples_section(examples)) + + if include_param_names: + names = load_udb_param_names() + user_parts.append(format_param_names_section(names)) + + user_parts.append(format_chunk_section(chunk_text, meta)) + + user_message = "\n\n---\n\n".join(user_parts) + + total_tokens = ( + estimate_tokens(system_prompt) + + estimate_tokens(user_message) + + SYSTEM_OVERHEAD_TOKENS + + RESERVED_OUTPUT_TOKENS + ) + + limit = CONTEXT_LIMITS.get(model, CONTEXT_LIMITS["default"]) + if total_tokens > limit: + raise ValueError( + f"Assembled prompt ({total_tokens:,} est. tokens) exceeds " + f"{model} context limit ({limit:,} tokens). " + f"Reduce chunk size or disable examples/param names." + ) + + return { + "system": system_prompt, + "user": user_message, + "estimated_tokens": total_tokens, + "model": model, + } + + +# --- Chunking logic --- + + +def detect_section_boundaries(lines: list[str]) -> list[int]: + """ + Find AsciiDoc section headers (lines starting with == or more). + Returns a list of 0-based line indices that are section starts. + """ + boundaries = [] + for i, line in enumerate(lines): + stripped = line.strip() + if stripped.startswith("== ") or stripped.startswith("=== ") or \ + stripped.startswith("==== ") or stripped.startswith("===== "): + boundaries.append(i) + return boundaries + + +def chunk_spec_file( + filepath: Path, + max_chunk_tokens: int = 40_000, + overlap_lines: int = 20, +) -> list[tuple[str, ChunkMeta]]: + """ + Split a spec file into chunks that respect section boundaries. + + Strategy: + 1. Find all section headers in the file. + 2. Greedily accumulate sections until the chunk would exceed max_chunk_tokens. + 3. Emit the chunk and start a new one with `overlap_lines` of overlap. + """ + text = filepath.read_text(encoding="utf-8") + lines = text.splitlines(keepends=True) + total_lines = len(lines) + + if total_lines == 0: + return [] + + boundaries = detect_section_boundaries(lines) + + if not boundaries: + boundaries = [0] + if boundaries[0] != 0: + boundaries.insert(0, 0) + + chunks: list[tuple[str, ChunkMeta]] = [] + current_start = 0 + chunk_index = 0 + + while current_start < total_lines: + candidate_sections = [b for b in boundaries if b >= current_start] + if not candidate_sections: + candidate_sections = [current_start] + + chunk_end = current_start + for i, sec_start in enumerate(candidate_sections): + next_boundary = ( + candidate_sections[i + 1] if i + 1 < len(candidate_sections) else total_lines + ) + candidate_text = "".join(lines[current_start:next_boundary]) + if estimate_tokens(candidate_text) > max_chunk_tokens and chunk_end > current_start: + break + chunk_end = next_boundary + + if chunk_end <= current_start: + chunk_end = min(current_start + int(max_chunk_tokens * CHARS_PER_TOKEN / 80), total_lines) + + chunk_text = "".join(lines[current_start:chunk_end]) + chunk_index += 1 + meta: ChunkMeta = { + "file": filepath.name, + "start_line": current_start + 1, + "end_line": chunk_end, + "total_lines": total_lines, + "chunk_index": chunk_index, + "total_chunks": 0, + } + chunks.append((chunk_text, meta)) + + if chunk_end >= total_lines: + break + + current_start = max(current_start + 1, chunk_end - overlap_lines) + + for _, meta in chunks: + meta["total_chunks"] = len(chunks) + + return chunks + + +# --- CLI --- + + +def cmd_assemble(args: argparse.Namespace) -> None: + """Assemble and print a complete prompt for a spec chunk.""" + filepath = Path(args.file) + if not filepath.exists(): + print(f"Error: file not found: {filepath}", file=sys.stderr) + sys.exit(1) + + text = filepath.read_text(encoding="utf-8") + lines = text.splitlines(keepends=True) + total_lines = len(lines) + + start = max(1, args.start_line) if args.start_line else 1 + end = min(args.end_line, total_lines) if args.end_line else total_lines + + chunk_text = "".join(lines[start - 1 : end]) + meta: ChunkMeta = { + "file": filepath.name, + "start_line": start, + "end_line": end, + "total_lines": total_lines, + "chunk_index": 1, + "total_chunks": 1, + } + + prompt = assemble_prompt( + chunk_text, + meta, + model=args.model, + include_examples=not args.no_examples, + include_param_names=not args.no_param_names, + ) + + if args.output_json: + json.dump(prompt, sys.stdout, indent=2) + print() + else: + print("=" * 70) + print("SYSTEM PROMPT") + print("=" * 70) + print(prompt["system"]) + print() + print("=" * 70) + print("USER MESSAGE") + print("=" * 70) + print(prompt["user"]) + print() + print("=" * 70) + print(f"Estimated tokens: {prompt['estimated_tokens']:,}") + print(f"Model: {prompt['model']}") + print("=" * 70) + + +def cmd_chunk(args: argparse.Namespace) -> None: + """Split a spec file into chunks and show their boundaries.""" + filepath = Path(args.file) + if not filepath.exists(): + print(f"Error: file not found: {filepath}", file=sys.stderr) + sys.exit(1) + + chunks = chunk_spec_file( + filepath, + max_chunk_tokens=args.max_tokens, + overlap_lines=args.overlap, + ) + + if args.output_json: + output = [] + for chunk_text, meta in chunks: + output.append({ + "meta": meta, + "text": chunk_text if args.include_text else None, + "estimated_tokens": estimate_tokens(chunk_text), + }) + json.dump(output, sys.stdout, indent=2) + print() + else: + print(f"File: {filepath.name}") + print(f"Total lines: {chunks[0][1]['total_lines'] if chunks else 0}") + print(f"Chunks: {len(chunks)}") + print() + for chunk_text, meta in chunks: + tokens = estimate_tokens(chunk_text) + print( + f" Chunk {meta['chunk_index']}/{meta['total_chunks']}: " + f"lines {meta['start_line']}-{meta['end_line']} " + f"({meta['end_line'] - meta['start_line'] + 1} lines, " + f"~{tokens:,} tokens)" + ) + + +def cmd_estimate(args: argparse.Namespace) -> None: + """Report token estimates for each prompt layer.""" + system_prompt = load_system_prompt() + examples = load_examples() + param_names = load_udb_param_names() + + system_tokens = estimate_tokens(system_prompt) + examples_text = format_examples_section(examples) + examples_tokens = estimate_tokens(examples_text) + names_text = format_param_names_section(param_names) + names_tokens = estimate_tokens(names_text) + + fixed_total = system_tokens + examples_tokens + names_tokens + SYSTEM_OVERHEAD_TOKENS + + print("Prompt Layer Token Estimates") + print("=" * 50) + print(f" System prompt: {system_tokens:>6,} tokens") + print(f" Few-shot examples: {examples_tokens:>6,} tokens") + print(f" UDB param names: {names_tokens:>6,} tokens") + print(f" System overhead: {SYSTEM_OVERHEAD_TOKENS:>6,} tokens") + print(f" Reserved for output: {RESERVED_OUTPUT_TOKENS:>6,} tokens") + print(f" {'─' * 36}") + print(f" Fixed overhead: {fixed_total:>6,} tokens") + print() + + print("Available for spec chunk per model:") + for model, limit in sorted(CONTEXT_LIMITS.items()): + available = limit - fixed_total - RESERVED_OUTPUT_TOKENS + print(f" {model:<25s} {available:>8,} tokens (~{int(available * CHARS_PER_TOKEN):,} chars)") + + +def main() -> None: + parser = argparse.ArgumentParser( + description="Prompt assembler for RISC-V parameter extraction", + formatter_class=argparse.RawDescriptionHelpFormatter, + ) + subparsers = parser.add_subparsers(dest="command", required=True) + + # --- assemble --- + p_asm = subparsers.add_parser("assemble", help="Build a complete prompt for a spec chunk") + p_asm.add_argument("file", help="Path to the .adoc spec file") + p_asm.add_argument("--start-line", type=int, default=None, help="Start line (1-based)") + p_asm.add_argument("--end-line", type=int, default=None, help="End line (1-based)") + p_asm.add_argument("--model", default="default", help="Target model for context limit check") + p_asm.add_argument("--no-examples", action="store_true", help="Omit few-shot examples") + p_asm.add_argument("--no-param-names", action="store_true", help="Omit UDB param name list") + p_asm.add_argument("--output-json", action="store_true", help="Output as JSON") + p_asm.set_defaults(func=cmd_assemble) + + # --- chunk --- + p_chunk = subparsers.add_parser("chunk", help="Split a spec file into chunks") + p_chunk.add_argument("file", help="Path to the .adoc spec file") + p_chunk.add_argument("--max-tokens", type=int, default=40_000, help="Max tokens per chunk") + p_chunk.add_argument("--overlap", type=int, default=20, help="Overlap lines between chunks") + p_chunk.add_argument("--output-json", action="store_true", help="Output as JSON") + p_chunk.add_argument("--include-text", action="store_true", help="Include chunk text in JSON") + p_chunk.set_defaults(func=cmd_chunk) + + # --- estimate --- + p_est = subparsers.add_parser("estimate", help="Report token estimates for prompt layers") + p_est.set_defaults(func=cmd_estimate) + + args = parser.parse_args() + args.func(args) + + +if __name__ == "__main__": + main() diff --git a/param_extraction/scripts/validate_prompt.py b/param_extraction/scripts/validate_prompt.py new file mode 100644 index 0000000000..67143f44ff --- /dev/null +++ b/param_extraction/scripts/validate_prompt.py @@ -0,0 +1,380 @@ +#!/usr/bin/env python3 +""" +Validation script for Phase 2 deliverables. + +Checks: +1. taxonomy.md completeness and consistency +2. examples.json structure, coverage, and spec text accuracy +3. system_prompt.txt output schema and taxonomy coverage +4. run_prompt.py assembly correctness and token budgets +5. Chunk boundary integrity +""" + +from __future__ import annotations + +import json +import sys +from pathlib import Path + +SCRIPT_DIR = Path(__file__).resolve().parent +PROJECT_DIR = SCRIPT_DIR.parent +PROMPT_DIR = PROJECT_DIR / "prompts" / "v1" +DATA_DIR = PROJECT_DIR / "data" +SPEC_DIR = PROJECT_DIR.parent / "ext" / "riscv-isa-manual" / "src" + +EXPECTED_CLASSES = { + "NORM_DIRECT", "NORM_CSR_WARL", "NORM_CSR_RW", "SW_RULE", + "NON_ISA", "NON_NORM", "DOC_RULE", "UNKNOWN", +} + +EXPECTED_VALUE_TYPES = {"binary", "enum", "range", "set", "bitmask", "value"} + +REQUIRED_OUTPUT_FIELDS = { + "excerpt", "line_number", "parameter_name", "existing_udb_name", + "class", "value_type", "confidence", "reasoning", +} + +errors: list[str] = [] +warnings: list[str] = [] +checks_passed = 0 + + +def check(condition: bool, message: str, *, warn_only: bool = False) -> None: + global checks_passed + if condition: + checks_passed += 1 + elif warn_only: + warnings.append(f" WARNING: {message}") + else: + errors.append(f" FAIL: {message}") + + +def validate_taxonomy() -> None: + print("\n1. Validating taxonomy.md") + print("-" * 40) + + path = PROMPT_DIR.parent.parent / "taxonomy.md" + check(path.exists(), "taxonomy.md exists") + if not path.exists(): + return + + text = path.read_text(encoding="utf-8") + + for cls in EXPECTED_CLASSES: + check( + f"`{cls}`" in text or f"### `{cls}`" in text, + f"taxonomy.md defines class {cls}", + ) + + for vt in EXPECTED_VALUE_TYPES: + check(f"`{vt}`" in text, f"taxonomy.md defines value type {vt}") + + check("Decision Tree" in text, "taxonomy.md has a decision tree section") + check("Disambiguation" in text, "taxonomy.md has disambiguation guidance") + + lines = text.splitlines() + check(len(lines) >= 50, f"taxonomy.md has sufficient content ({len(lines)} lines)") + + +def validate_examples() -> None: + print("\n2. Validating examples.json") + print("-" * 40) + + path = PROMPT_DIR / "examples.json" + check(path.exists(), "examples.json exists") + if not path.exists(): + return + + with open(path, encoding="utf-8") as f: + data = json.load(f) + + pos = data.get("positive_examples", []) + neg = data.get("negative_examples", []) + + check(len(pos) >= 5, f"At least 5 positive examples (got {len(pos)})") + check(len(neg) >= 3, f"At least 3 negative examples (got {len(neg)})") + + classes_covered = set() + for ex in pos: + check("input_excerpt" in ex, f"Positive example has input_excerpt") + check("input_file" in ex, f"Positive example has input_file") + check("expected_output" in ex, f"Positive example has expected_output") + + out = ex.get("expected_output", {}) + for field in REQUIRED_OUTPUT_FIELDS: + check( + field in out, + f"Positive example {out.get('parameter_name', '?')} has field '{field}'", + ) + + cls = out.get("class") + if cls: + classes_covered.add(cls) + check( + cls in EXPECTED_CLASSES, + f"Example class '{cls}' is a valid class", + ) + + vt = out.get("value_type") + if vt: + check( + vt in EXPECTED_VALUE_TYPES, + f"Example value_type '{vt}' is valid", + ) + + normative_classes = {"NORM_DIRECT", "NORM_CSR_WARL", "NORM_CSR_RW", "SW_RULE"} + for cls in normative_classes: + check( + cls in classes_covered, + f"Positive examples cover class {cls}", + ) + + for ex in neg: + check("input_excerpt" in ex, "Negative example has input_excerpt") + check("reason_for_rejection" in ex, "Negative example has reason_for_rejection") + check( + ex.get("expected_output") is None, + "Negative example has null expected_output", + ) + + udb_names = set() + names_path = DATA_DIR / "udb_param_names.txt" + if names_path.exists(): + udb_names = { + line.strip() + for line in names_path.read_text().splitlines() + if line.strip() + } + + for ex in pos: + out = ex.get("expected_output", {}) + udb_name = out.get("existing_udb_name") + if udb_name and udb_names: + check( + udb_name in udb_names, + f"Example UDB name '{udb_name}' exists in udb_param_names.txt", + ) + + for ex in pos: + spec_file = ex.get("input_file", "") + spec_path = SPEC_DIR / spec_file + if spec_path.exists(): + spec_text = spec_path.read_text(encoding="utf-8") + excerpt = ex["input_excerpt"] + first_sentence = excerpt.split("\n")[0][:80] + check( + first_sentence in spec_text or first_sentence.replace(">=", "{ge}") in spec_text, + f"Excerpt for {ex.get('expected_output', {}).get('parameter_name', '?')} found in {spec_file}", + warn_only=True, + ) + + +def validate_system_prompt() -> None: + print("\n3. Validating system_prompt.txt") + print("-" * 40) + + path = PROMPT_DIR / "system_prompt.txt" + check(path.exists(), "system_prompt.txt exists") + if not path.exists(): + return + + text = path.read_text(encoding="utf-8") + + for cls in EXPECTED_CLASSES: + check( + cls in text or f"**{cls}**" in text, + f"System prompt mentions class {cls}", + ) + + for vt in EXPECTED_VALUE_TYPES: + check(f"**{vt}**" in text or f"- **{vt}**" in text, f"System prompt mentions value type {vt}") + + check('"parameters"' in text, "System prompt defines output schema with 'parameters' key") + check('"excerpt"' in text, "System prompt output schema has 'excerpt' field") + check('"reasoning"' in text, "System prompt output schema has 'reasoning' field") + check('"line_number"' in text, "System prompt output schema has 'line_number' field") + + check("JSON" in text, "System prompt mentions JSON output format") + + check("NOTE" in text, "System prompt warns about NOTE blocks") + check('"may"' in text or "'may'" in text, "System prompt discusses 'may' disambiguation") + + from run_prompt import estimate_tokens + tokens = estimate_tokens(text) + check(tokens <= 1200, f"System prompt is ≤1200 tokens ({tokens} estimated)", warn_only=True) + + +def validate_assembler() -> None: + print("\n4. Validating run_prompt.py assembly") + print("-" * 40) + + from run_prompt import ( + assemble_prompt, + chunk_spec_file, + estimate_tokens, + load_system_prompt, + load_examples, + load_udb_param_names, + ) + + system = load_system_prompt() + check(len(system) > 100, "System prompt loads successfully") + + examples = load_examples() + check(len(examples.get("positive_examples", [])) >= 5, "Examples load successfully") + + names = load_udb_param_names() + check(len(names) >= 100, f"UDB param names load successfully ({len(names)} names)") + + test_file = SPEC_DIR / "machine.adoc" + if not test_file.exists(): + print(" SKIP: machine.adoc not available for assembly test") + return + + text = test_file.read_text(encoding="utf-8") + lines = text.splitlines(keepends=True) + chunk_text = "".join(lines[3334:3400]) + meta = { + "file": "machine.adoc", + "start_line": 3335, + "end_line": 3400, + "total_lines": len(lines), + "chunk_index": 1, + "total_chunks": 1, + } + + prompt = assemble_prompt(chunk_text, meta, model="gpt-4o") + check("system" in prompt, "Assembled prompt has 'system' key") + check("user" in prompt, "Assembled prompt has 'user' key") + check("estimated_tokens" in prompt, "Assembled prompt has 'estimated_tokens'") + + total = prompt["estimated_tokens"] + check(total < 128_000, f"Assembled prompt fits in gpt-4o context ({total:,} tokens)") + + check( + "NUM_PMP_ENTRIES" in prompt["user"], + "UDB param names appear in user message", + ) + check( + "Few-Shot Examples" in prompt["user"], + "Few-shot examples appear in user message", + ) + check( + "Specification Text" in prompt["user"], + "Spec chunk header appears in user message", + ) + + try: + assemble_prompt(chunk_text, meta, model="llama-3-70b") + errors.append(" FAIL: Should have raised ValueError for llama-3-70b context overflow") + except ValueError: + check(True, "Context overflow correctly raises ValueError for small models") + + prompt_no_extras = assemble_prompt( + chunk_text, meta, + model="default", + include_examples=False, + include_param_names=False, + ) + check( + "Few-Shot Examples" not in prompt_no_extras["user"], + "Examples correctly omitted when disabled", + ) + check( + prompt_no_extras["estimated_tokens"] < prompt["estimated_tokens"], + "Token count is lower without examples/names", + ) + + +def validate_chunking() -> None: + print("\n5. Validating chunking logic") + print("-" * 40) + + from run_prompt import chunk_spec_file + + test_file = SPEC_DIR / "machine.adoc" + if not test_file.exists(): + print(" SKIP: machine.adoc not available for chunking test") + return + + chunks = chunk_spec_file(test_file, max_chunk_tokens=40_000) + check(len(chunks) >= 1, f"Chunking produces at least 1 chunk ({len(chunks)} chunks)") + + all_text = test_file.read_text(encoding="utf-8") + total_lines = len(all_text.splitlines()) + + check( + chunks[0][1]["start_line"] == 1, + "First chunk starts at line 1", + ) + check( + chunks[-1][1]["end_line"] == total_lines, + f"Last chunk ends at last line ({chunks[-1][1]['end_line']} == {total_lines})", + ) + + for chunk_text, meta in chunks: + check( + meta["total_chunks"] == len(chunks), + f"Chunk {meta['chunk_index']} total_chunks is correct", + ) + + if len(chunks) > 1: + for i in range(1, len(chunks)): + prev_end = chunks[i - 1][1]["end_line"] + curr_start = chunks[i][1]["start_line"] + check( + curr_start <= prev_end, + f"Chunks {i} and {i+1} overlap (prev_end={prev_end}, curr_start={curr_start})", + ) + + small_chunks = chunk_spec_file(test_file, max_chunk_tokens=5_000) + check( + len(small_chunks) > len(chunks), + f"Smaller max_tokens produces more chunks ({len(small_chunks)} > {len(chunks)})", + ) + + for _, meta in small_chunks: + from run_prompt import estimate_tokens + chunk_text = _ + tokens = estimate_tokens(chunk_text) + check( + tokens < 8_000, + f"Chunk {meta['chunk_index']} with 5K limit is under 8K tokens ({tokens:,})", + warn_only=True, + ) + + +def main() -> None: + global checks_passed + + print("=" * 60) + print("Phase 2 Deliverable Validation") + print("=" * 60) + + validate_taxonomy() + validate_examples() + validate_system_prompt() + validate_assembler() + validate_chunking() + + print() + print("=" * 60) + print(f"Results: {checks_passed} passed, {len(errors)} failed, {len(warnings)} warnings") + print("=" * 60) + + if warnings: + print("\nWarnings:") + for w in warnings: + print(w) + + if errors: + print("\nErrors:") + for e in errors: + print(e) + sys.exit(1) + else: + print("\nAll checks passed!") + + +if __name__ == "__main__": + main() diff --git a/param_extraction/taxonomy.md b/param_extraction/taxonomy.md new file mode 100644 index 0000000000..96a5849291 --- /dev/null +++ b/param_extraction/taxonomy.md @@ -0,0 +1,199 @@ +# Architectural Parameter Classification Taxonomy + +This document defines the classification system used to categorize architectural +parameters extracted from the RISC-V privileged and unprivileged specifications. + +Every parameter gets exactly one **class** and one **value type**. + +--- + +## Parameter Classes + +### `NORM_DIRECT` — Normative, Directly Configurable + +An implementation-defined choice that the spec explicitly leaves to the +implementer. Not controlled by or derived from any CSR field. + +**How to identify**: The spec says an implementer "may", "can", or "optionally" +choose a value, or describes a quantity whose value is not fixed by the spec. +The choice is made at design time and does not change at runtime via CSR writes. + +**Typical spec wording**: +- "Implementations may implement zero, 16, or 64 PMP entries" +- "The number of bits in a single vector register, _VLEN_ ≥ ELEN" +- "MXLEN is a constant" + +**Examples**: `MXLEN`, `NUM_PMP_ENTRIES`, `PHYS_ADDR_WIDTH`, `VLEN`, `ELEN`, +`CACHE_BLOCK_SIZE`, `TRAP_ON_UNIMPLEMENTED_INSTRUCTION` + +**Disambiguation**: +- If the choice is controlled by a CSR field's legal values → `NORM_CSR_WARL` +- If the choice is about whether a CSR field is read-only vs read-write → `NORM_CSR_RW` +- If the behavior becomes determinate when software follows spec rules → `SW_RULE` + +--- + +### `NORM_CSR_WARL` — Normative, CSR WARL Legal Values + +The parameter defines the set of legal values that a WARL (Write Any, Read +Legal) CSR field will accept. When software writes an illegal value, the field +retains its previous value or takes an implementation-defined legal value. + +**How to identify**: The spec describes a CSR field as "WARL" and the legal +values are implementation-defined. The parameter IS the set of legal values. + +**Typical spec wording**: +- "The `mtvec` register is an MXLEN-bit WARL read/write register" +- "The MODE field is WARL" +- "A write to `hgatp` with an unsupported MODE value..." + +**Examples**: `MTVEC_MODES`, `SATP_MODE_BARE`, `MSTATUS_FS_LEGAL_VALUES`, +`GSTAGE_MODE_BARE`, `SV39X4_TRANSLATION` + +**Disambiguation**: +- If the field is described as WARL but the parameter controls whether the + field is read-only vs read-write (not which values are legal) → `NORM_CSR_RW` +- If the WARL behavior is described in a NOTE block → still `NORM_CSR_WARL` + (WARL field definitions are normative even when discussed in notes) + +--- + +### `NORM_CSR_RW` — Normative, CSR Read-Write Behavior + +The parameter controls whether a CSR or CSR field is read-only, read-write, +or has a specific fixed value. This is about the mutability of the field, not +the set of legal values. + +**How to identify**: The spec says a field "may be read-only zero", "can be +read-only", or that the field's type (RO/RW) depends on implementation choices. + +**Typical spec wording**: +- "The `mtvec` register ... can contain a read-only value" +- "Bits of `misa` that correspond to implemented extensions are writable..." +- "MBE, SBE, and UBE bits in `mstatus` are WARL fields" (where the parameter + controls whether they are read-only-0, read-only-1, or read-write) + +**Examples**: `MTVEC_ACCESS`, `MUTABLE_MISA_C`, `M_MODE_ENDIANNESS`, +`HSTATEEN_CONTEXT_TYPE`, `SCOUNTENABLE_EN` + +**Disambiguation**: +- If the parameter controls which values are legal in a writable field → `NORM_CSR_WARL` +- If the parameter controls whether a CSR/feature exists at all → `NORM_DIRECT` + (e.g., `TIME_CSR_IMPLEMENTED`, `MISA_CSR_IMPLEMENTED`) + +--- + +### `SW_RULE` — Software-Deterministic + +Behavior that appears implementation-defined but whose outcome is fully +determined if software follows the spec's prescribed rules (e.g., fencing, +cache operations, proper sequencing). + +**How to identify**: The spec describes hardware behavior that varies by +implementation, but also prescribes software rules that make the outcome +predictable. Often involves hardware state updates that software can control +through proper synchronization. + +**Typical spec wording**: +- "It is implementation-defined whether FS transitions to Dirty" + (but software can prevent this by managing FS correctly) +- "dirtiness might not be tracked at all" + (but software can use fencing to ensure correctness) + +**Examples**: `HW_MSTATUS_FS_DIRTY_UPDATE`, `HW_MSTATUS_VS_DIRTY_UPDATE` + +**Disambiguation**: +- If the behavior is truly a fixed design choice with no software workaround → `NORM_DIRECT` +- The key question: "Can software guarantee a specific outcome regardless of + the implementation choice?" If yes → `SW_RULE`. If no → `NORM_DIRECT`. + +--- + +### `NON_ISA` — Non-ISA / Platform + +A choice that is outside the ISA scope — platform-level, electrical, or +physical rather than architectural. These are not governed by the ISA +specification. + +**How to identify**: The choice involves physical characteristics, platform +integration, or debug infrastructure rather than instruction execution behavior. + +**Typical spec wording**: +- "The reset vector is platform-specified" +- "NMI vector address is implementation-specific" + +**Examples**: Reset vector address, NMI vector, physical memory attributes, +debug transport mechanism + +--- + +### `NON_NORM` — Non-Normative + +Text that appears in a NOTE, TIP, WARNING, or other informative block. These +blocks describe rationale, design intent, or implementation suggestions but +do not constitute requirements. + +**How to identify**: The text is enclosed in AsciiDoc `[NOTE]`/`====` blocks, +or is explicitly labeled as informative. + +**Critical rule**: Even if a NOTE block discusses implementation choices using +words like "may" or "optionally", the content is non-normative and should NOT +be extracted as a parameter. Only normative prose outside of such blocks +defines actual parameters. + +**Example of a false positive (do NOT extract)**: +> [NOTE] +> Some platforms may choose to disallow speculatively writing FS to close a +> potential side channel. + +This is a suggestion, not a requirement — no parameter. + +--- + +### `DOC_RULE` — Documentation Rule + +A requirement about how something should be documented, reported, or +described, rather than about architectural behavior. + +**How to identify**: The spec requires reporting or documenting a value, but +the value itself is not an architectural choice that affects execution. + +**Examples**: Requirements about what must appear in documentation, how +extensions should be described + +--- + +### `UNKNOWN` — Needs Further Analysis + +Cannot be confidently classified into any of the above categories. Use this +sparingly — it flags items for human review. + +--- + +## Value Types + +Value types are orthogonal to classes. Every parameter has exactly one. + +| Type | Definition | Example | +|---|---|---| +| `binary` | Exactly 2 choices (boolean, or 2-value enum) | `TRAP_ON_UNIMPLEMENTED_INSTRUCTION` (true/false) | +| `enum` | Finite set of 3+ discrete values | `LRSC_RESERVATION_STRATEGY` (4 choices) | +| `range` | Integer range with min/max bounds | `NUM_PMP_ENTRIES` (0-64) | +| `set` | Subset selection from a fixed universe | `MTVEC_MODES` (subset of {0, 1}) | +| `bitmask` | Fixed-length boolean array (one bit per feature) | `SCOUNTENABLE_EN` (32 booleans) | +| `value` | Single unconstrained value (no enumerated choices or bounds) | `VLEN` (any power of 2 ≥ ELEN) | + +--- + +## Decision Tree + +When classifying a parameter, follow this order: + +1. **Is the text in a NOTE/TIP/WARNING block?** → `NON_NORM` +2. **Is the choice about platform/physical/debug, not ISA?** → `NON_ISA` +3. **Is it about documenting/reporting, not behavior?** → `DOC_RULE` +4. **Does the text describe a WARL CSR field's legal values?** → `NORM_CSR_WARL` +5. **Does the text describe whether a CSR field is RO/RW/fixed?** → `NORM_CSR_RW` +6. **Does the behavior become deterministic with proper software?** → `SW_RULE` +7. **Is it a normative implementation choice?** → `NORM_DIRECT` +8. **None of the above?** → `UNKNOWN`