Add erratum notes to README and a tool to check & repair erratum

erratum_check.py will automatically scan bio_code! segments
in a .rs file, flag patterns that could be a problem, and
can automatically patch these, if requested.
This commit is contained in:
bunnie 2026-02-20 20:55:34 +08:00
parent a6a8341223
commit a97675592c
2 changed files with 1082 additions and 1 deletions

View file

@ -69,4 +69,89 @@ level flags, configured by the host; writes to bits [31:24] are ignored.
- x30 r/- halt until ((x27 & events) != 0), and return unmasked `events` value
Core ID & debug:
- x31 r/- [31:30] -> core ID; [29:0] -> cpu clocks since reset
- x31 r/- [31:30] -> core ID; [29:0] -> cpu clocks since reset
### ERRATUM
BUG 1: ("phantom rs1"): For lui/auipc/jal (U&J type instructions),
the 5-bit field at instruction bits [19:15] is not gated off. If that field
decodes to register 16-19 (x16-x19) for just these instruction types,
a spurious pending read is made from the corresponding FIFO,
which affects correctnes and can block execution.
BUG 2: ("phantom rs2"): For non-R/S/B-type instructions, the 5-bit
field at instruction bits [24:20] should be gated off but isn't.
When that field equals 20 (0b10100), a spurious `quantum` signal
triggers, which can affect the instruction fetch pipeline.
For coders compiling from C, these erratum are transparently
patched by the `clang2rustasm.py` script. Thus these erratum
are primarily a challenge to coders hand-writing in assembly.
For assembly hand-coders, there is a script called `erratum_check.py`
which will inspect code inside a `bio_code!` macro for patterns
that match the above bugs. It can also auto-patch, if you so desire,
using `--autopatch`.
#### Examples
The primary pitfalls happen in dealing with immediates, as follows.
Bug 1 example:
`lui a1, 0xa2f96`
Here, the `9` in the second digit of `0xa2f96` translates to register
number x18, which triggers the bug. The fix is to create the constant
with a sequence such as:
```
lui a1, 0xa2f06
lui a2, 0x9 # can't use 0x90 because that triggers the bug
slli a2, a2, 4 # shift 0x9 into place
add a1, a1, a2 # Final result. Note that a2 is side-effected.
```
Bug 2 example:
`slli x1, x2, 20`
Workaround (splitting the shift):
`slli x1, x2, 19`
`slli x1, x1, 1`
Add, xor, andi, ori are also affected, and the fix requires
using a temporary variable to compose an intermediate.
Loads are affected, but not stores. Loads with an offset of
20 (or containing any coding of 0x14 in the bit field) are
worked around by pre-decrementing the source register, adding
the the decrement to the offset, and then re-incrementing the
source register.
#### Root Cause
The root cause was a misunderstanding of the register field
decoders in the PicoRV. I got confused over the register names
and when I checked for gating, I looked at the output variables
of the register file, and not the input. Turns out the inputs
to the register file are very simple:
```
decoded_rs1 <= mem_rdata_latched[19:15];
decoded_rs2 <= mem_rdata_latched[24:20];
```
The good news is that on the write-side, there is an additional
signal that detects writes, so the bug is not triggered for write
pattern. While hand-coded test cases were used to check the function
of the implementation, coverage was limited. Realistic code-freeze
dates would have informed deeper investment in automated test tooling, but,
management issues are not the topic of this readme.
The hardware fix would be to extract the intermediate signals that indicate
the decoded instruction type and use them to gate the `quantum`
and FIFO access lines. However, this would require a full mask
spin and at a couple million dollars. That's just not going to happen;
thus, I get to live with owning this bug for the rest of my life.

View file

@ -0,0 +1,996 @@
#!/usr/bin/env python3
"""
rs_errata_check.py - Check and patch RISC-V assembly errata in Rust .rs files.
Scans Rust source files for bio_code! and bio_code_aligned! macros, extracts
the inline assembly strings, checks each instruction for known BIO coprocessor
errata, and optionally patches the file in-place.
Usage:
python3 rs_errata_check.py <file.rs> [file2.rs ...] # check only (default)
python3 rs_errata_check.py --autopatch <file.rs> ... # patch in-place
Errata covered:
BUG 1 ("phantom rs1"): For lui/auipc/jal, bits [19:15] of the instruction
encoding are not gated. If that field = 16-19, a spurious FIFO read occurs.
BUG 2 ("phantom rs2"): For non-R/S/B-type instructions, bits [24:20] = 20
triggers a spurious quantum signal.
Exit codes:
0 - No errata found (or all patched with --autopatch)
1 - Errata found (check mode)
2 - Usage / file error
"""
import argparse
import re
import sys
import os
# ============================================================================
# Constants
# ============================================================================
# Temp register for errata workarounds. Saved/restored via stack.
ERRATA_TEMP = "t0"
ERRATA_STACK_OFFSET = -4 # bits[4:0] = 0b11100, safe (not 20)
# Bug 1: register numbers that trigger phantom rs1 reads
BUG1_BAD_REGS = {16, 17, 18, 19}
# Register ABI name mapping (for display/normalization)
ABI_TO_X = {
"zero": "x0", "ra": "x1", "sp": "x2", "gp": "x3",
"tp": "x4", "t0": "x5", "t1": "x6", "t2": "x7",
"s0": "x8", "fp": "x8", "s1": "x9",
"a0": "x10", "a1": "x11", "a2": "x12", "a3": "x13",
"a4": "x14", "a5": "x15", "a6": "x16", "a7": "x17",
"s2": "x18", "s3": "x19", "s4": "x20", "s5": "x21",
"s6": "x22", "s7": "x23", "s8": "x24", "s9": "x25",
"s10": "x26", "s11": "x27",
"t3": "x28", "t4": "x29", "t5": "x30", "t6": "x31",
}
# ============================================================================
# Instruction parsing helpers (adapted from clang2rustasm.py errata system)
# ============================================================================
def _parse_instruction(instr_str):
"""
Parse an instruction string into (mnemonic, [operands]).
Handles both regular "add a0, a1, a2" and memory "lw a0, 4(sp)" forms.
Returns (mnemonic, operands_list) or (None, []) if not parseable.
"""
if instr_str is None:
return None, []
s = instr_str.strip()
# Labels (e.g. "20:") are not instructions
if re.match(r'^\d+\s*:', s):
return None, []
# Bare label like "20: lw x8, 0(x8)" - extract instruction after colon
m = re.match(r'^\d+\s*:\s*(.*)', s)
if m:
s = m.group(1).strip()
if not s:
return None, []
# Directives
if s.startswith('.'):
return None, []
parts = s.split(None, 1)
if not parts:
return None, []
mnemonic = parts[0].lower()
if len(parts) == 1:
return mnemonic, []
operands = [op.strip() for op in parts[1].split(',')]
return mnemonic, operands
def _parse_mem_operand(operand):
"""
Parse a memory operand like "4(sp)" or "-8(x2)".
Returns (offset_int, base_reg_str) or (None, None) if not a memory operand.
"""
m = re.match(r'^(-?\d+)\((\w+)\)$', operand.strip())
if m:
return int(m.group(1)), m.group(2)
return None, None
def _imm_to_int(s):
"""Parse an immediate string (decimal or 0x hex) to int. Returns None on failure."""
s = s.strip()
try:
return int(s, 0)
except (ValueError, TypeError):
return None
def _has_relocation(instr_str):
"""Check if instruction contains a relocation like %hi(...) or %lo(...)."""
return '%' in instr_str if instr_str else False
def _is_label_ref(s):
"""Check if a string looks like a label reference (e.g. '20f', '30b')."""
return bool(re.match(r'^\d+[fb]$', s.strip()))
# ============================================================================
# Bug detection functions
# ============================================================================
def _u_type_phantom_rs1(imm20):
"""U-type (lui/auipc): instruction bits [19:15] = imm[7:3]."""
field = (imm20 >> 3) & 0x1F
return field in BUG1_BAD_REGS
def _u_type_phantom_rs2(imm20):
"""Bug 2 for U-type: instruction bits [24:20] = imm[12:8]."""
field = (imm20 >> 8) & 0x1F
return field == 20
def _j_type_phantom_rs1(imm21):
"""J-type (jal): instruction bits [19:15] = imm[19:15]."""
field = (imm21 >> 15) & 0x1F
return field in BUG1_BAD_REGS
def _j_type_phantom_rs2(imm21):
"""
Bug 2 for J-type (jal): bits [24:20].
J-type: inst[30:21] = imm[10:1], inst[20] = imm[11]
So inst[24:20] = {imm[4:1], imm[11]}
field = ((imm >> 1) & 0xF) << 1 | ((imm >> 11) & 1)
"""
field = (((imm21 >> 1) & 0xF) << 1) | ((imm21 >> 11) & 1)
return field == 20
def _i_type_imm_has_bug2(imm12):
"""For I-type, bits [24:20] = imm[4:0]. Bug when lower 5 bits = 20."""
encoded = imm12 & 0xFFF
return (encoded & 0x1F) == 20
# ============================================================================
# Patch generation helpers
# ============================================================================
def _save_temp():
return f"sw {ERRATA_TEMP}, {ERRATA_STACK_OFFSET}(sp)"
def _restore_temp():
return f"lw {ERRATA_TEMP}, {ERRATA_STACK_OFFSET}(sp)"
def _build_constant_in_reg(temp_reg, diff):
"""
Build instructions to load `diff` into temp_reg.
Careful not to trigger errata in generated code.
Returns list of instruction strings.
"""
instrs = []
if diff == 0:
return []
lowest_bit = (diff & -diff).bit_length() - 1
shifted_val = diff >> lowest_bit
if shifted_val < 2048:
if _i_type_imm_has_bug2(shifted_val):
instrs.append(f"addi {temp_reg}, zero, {shifted_val - 1}")
instrs.append(f"addi {temp_reg}, {temp_reg}, 1")
else:
instrs.append(f"addi {temp_reg}, zero, {shifted_val}")
remaining_shift = lowest_bit
while remaining_shift > 0:
if remaining_shift >= 20:
instrs.append(f"slli {temp_reg}, {temp_reg}, 19")
remaining_shift -= 19
elif _i_type_imm_has_bug2(remaining_shift):
instrs.append(f"slli {temp_reg}, {temp_reg}, {remaining_shift - 1}")
instrs.append(f"slli {temp_reg}, {temp_reg}, 1")
remaining_shift = 0
else:
instrs.append(f"slli {temp_reg}, {temp_reg}, {remaining_shift}")
remaining_shift = 0
else:
if shifted_val < (1 << 20):
upper = shifted_val >> 12
lower = shifted_val & 0xFFF
if lower >= 0x800:
upper += 1
lower = lower - 0x1000
if not _u_type_phantom_rs1(upper) and not _u_type_phantom_rs2(upper):
instrs.append(f"lui {temp_reg}, {upper}")
if lower != 0:
if _i_type_imm_has_bug2(lower):
instrs.append(f"addi {temp_reg}, {temp_reg}, {lower - 1}")
instrs.append(f"addi {temp_reg}, {temp_reg}, 1")
else:
instrs.append(f"addi {temp_reg}, {temp_reg}, {lower}")
else:
instrs.append(f"addi {temp_reg}, zero, {(shifted_val >> 10) & 0x7FF}")
instrs.append(f"slli {temp_reg}, {temp_reg}, 10")
rest = shifted_val & 0x3FF
if rest:
instrs.append(f"addi {temp_reg}, {temp_reg}, {rest}")
remaining_shift = lowest_bit
while remaining_shift > 0:
chunk = min(remaining_shift, 19) if remaining_shift >= 20 else remaining_shift
if _i_type_imm_has_bug2(chunk):
instrs.append(f"slli {temp_reg}, {temp_reg}, {chunk - 1}")
instrs.append(f"slli {temp_reg}, {temp_reg}, 1")
else:
instrs.append(f"slli {temp_reg}, {temp_reg}, {chunk}")
remaining_shift -= chunk
return instrs
# ============================================================================
# Instruction-specific checkers/patchers
#
# Each function returns:
# None - instruction is safe, no patch needed
# (bug_desc, [patched_instructions]) - errata found; patched_instructions
# is a list of replacement instruction strings
# ============================================================================
def _check_lui(mnemonic, operands, original_instr):
"""Check/patch lui rd, imm20 for Bug 1 and Bug 2."""
if len(operands) != 2:
return None
rd = operands[0]
imm = _imm_to_int(operands[1])
if imm is None:
return None
imm20 = imm & 0xFFFFF
has_bug1 = _u_type_phantom_rs1(imm20)
has_bug2 = _u_type_phantom_rs2(imm20)
if not has_bug1 and not has_bug2:
return None
bugs = []
if has_bug1:
bugs.append("B1:phantom-rs1")
if has_bug2:
bugs.append("B2:bits24:20=20")
bug_desc = "+".join(bugs)
safe_imm20 = imm20
if has_bug1:
safe_imm20 = safe_imm20 & ~(0x1F << 3)
if has_bug2:
safe_imm20 = safe_imm20 & ~(0x1F << 8)
diff = (imm20 - safe_imm20) & 0xFFFFF
fixup_instrs = _build_constant_in_reg(ERRATA_TEMP, diff)
patch = []
if safe_imm20 != 0:
patch.append(f"lui {rd}, 0x{safe_imm20:x}")
else:
patch.append(f"addi {rd}, zero, 0")
if diff != 0:
patch.append(_save_temp())
patch.extend(fixup_instrs)
patch.append(f"slli {ERRATA_TEMP}, {ERRATA_TEMP}, 12")
patch.append(f"add {rd}, {rd}, {ERRATA_TEMP}")
patch.append(_restore_temp())
return (bug_desc, patch)
def _check_auipc(mnemonic, operands, original_instr):
"""Check/patch auipc rd, imm20 for Bug 1 and Bug 2."""
if len(operands) != 2:
return None
rd = operands[0]
imm = _imm_to_int(operands[1])
if imm is None:
return None
imm20 = imm & 0xFFFFF
has_bug1 = _u_type_phantom_rs1(imm20)
has_bug2 = _u_type_phantom_rs2(imm20)
if not has_bug1 and not has_bug2:
return None
bugs = []
if has_bug1:
bugs.append("B1:phantom-rs1")
if has_bug2:
bugs.append("B2:bits24:20=20")
bug_desc = "+".join(bugs)
safe_imm20 = imm20
if has_bug1:
safe_imm20 = safe_imm20 & ~(0x1F << 3)
if has_bug2:
safe_imm20 = safe_imm20 & ~(0x1F << 8)
diff = (imm20 - safe_imm20) & 0xFFFFF
patch = []
patch.append(f"auipc {rd}, 0x{safe_imm20:x}")
if diff != 0:
patch.append(_save_temp())
fixup_instrs = _build_constant_in_reg(ERRATA_TEMP, diff)
patch.extend(fixup_instrs)
patch.append(f"slli {ERRATA_TEMP}, {ERRATA_TEMP}, 12")
patch.append(f"add {rd}, {rd}, {ERRATA_TEMP}")
patch.append(_restore_temp())
return (bug_desc, patch)
def _check_jal(mnemonic, operands, original_instr):
"""Check jal for Bug 1 and Bug 2 (warns only - numeric jal is rare)."""
if len(operands) == 1:
return None # pseudo form with label
if len(operands) != 2:
return None
rd = operands[0]
if _is_label_ref(operands[1]):
return None # label reference, can't analyze statically
imm = _imm_to_int(operands[1])
if imm is None:
return None
imm21 = imm & 0x1FFFFF
has_bug1 = _j_type_phantom_rs1(imm21)
has_bug2 = _j_type_phantom_rs2(imm21)
if not has_bug1 and not has_bug2:
return None
bugs = []
if has_bug1:
bugs.append("B1:phantom-rs1")
if has_bug2:
bugs.append("B2:bits24:20=20")
bug_desc = "+".join(bugs) + " WARNING:manual-review-needed"
# Can't auto-patch jal reliably, keep original with warning
return (bug_desc, [original_instr])
def _check_shift_imm(mnemonic, operands, original_instr):
"""Check/patch slli/srli/srai where shamt == 20."""
if len(operands) != 3:
return None
rd, rs1, shamt_str = operands
shamt = _imm_to_int(shamt_str)
if shamt is None:
return None
if (shamt & 0x1F) != 20:
return None
patch = [
f"{mnemonic} {rd}, {rs1}, {shamt - 1}",
f"{mnemonic} {rd}, {rd}, 1",
]
return (f"B2:shamt={shamt}", patch)
def _check_load(mnemonic, operands, original_instr):
"""Check/patch load instructions where offset triggers Bug 2."""
if len(operands) != 2:
return None
rd = operands[0]
offset, base = _parse_mem_operand(operands[1])
if offset is None:
return None
offset_enc = offset & 0xFFF
if (offset_enc & 0x1F) != 20:
return None
# Find a safe adjustment delta
delta = None
new_offset = None
for adj in [-4, 4, -8, 8, -12, 12, -16, 16]:
candidate = offset - adj
candidate_enc = candidate & 0xFFF
if (candidate_enc & 0x1F) != 20:
adj_enc = adj & 0xFFF
neg_adj_enc = (-adj) & 0xFFF
if (adj_enc & 0x1F) != 20 and (neg_adj_enc & 0x1F) != 20:
if -2048 <= candidate <= 2047:
delta = adj
new_offset = candidate
break
if delta is None:
delta = -4
new_offset = offset + 4
patch = []
if rd == base:
patch.append(f"addi {ERRATA_TEMP}, {base}, {delta}")
patch.append(f"{mnemonic} {rd}, {new_offset}({ERRATA_TEMP})")
else:
patch.append(f"addi {base}, {base}, {delta}")
patch.append(f"{mnemonic} {rd}, {new_offset}({base})")
patch.append(f"addi {base}, {base}, {-delta}")
return (f"B2:offset={offset},bits[4:0]={offset_enc & 0x1F}", patch)
def _check_store(mnemonic, operands, original_instr):
"""Stores are S-type: bits[24:20] = rs2 register, hardware handles correctly."""
return None
def _check_i_type_alu(mnemonic, operands, original_instr):
"""Check/patch addi/andi/ori/xori/slti/sltiu where imm triggers Bug 2."""
if len(operands) != 3:
return None
rd, rs1, imm_str = operands
imm = _imm_to_int(imm_str)
if imm is None:
return None
imm_enc = imm & 0xFFF
if (imm_enc & 0x1F) != 20:
return None
patch = []
if mnemonic == 'addi':
new_imm = imm - 1
new_enc = new_imm & 0xFFF
if (new_enc & 0x1F) == 20:
new_imm = imm + 1
patch.append(f"addi {rd}, {rs1}, {new_imm}")
patch.append(f"addi {rd}, {rd}, -1")
else:
patch.append(f"addi {rd}, {rs1}, {new_imm}")
patch.append(f"addi {rd}, {rd}, 1")
elif mnemonic in ('andi', 'ori', 'xori'):
r_type_op = {'andi': 'and', 'ori': 'or', 'xori': 'xor'}[mnemonic]
patch.append(_save_temp())
if (imm_enc & 0x1F) == 20:
patch.append(f"addi {ERRATA_TEMP}, zero, {imm - 1}")
patch.append(f"addi {ERRATA_TEMP}, {ERRATA_TEMP}, 1")
else:
patch.append(f"addi {ERRATA_TEMP}, zero, {imm}")
patch.append(f"{r_type_op} {rd}, {rs1}, {ERRATA_TEMP}")
patch.append(_restore_temp())
elif mnemonic in ('slti', 'sltiu'):
r_type_op = {'slti': 'slt', 'sltiu': 'sltu'}[mnemonic]
patch.append(_save_temp())
patch.append(f"addi {ERRATA_TEMP}, zero, {imm - 1}")
patch.append(f"addi {ERRATA_TEMP}, {ERRATA_TEMP}, 1")
patch.append(f"{r_type_op} {rd}, {rs1}, {ERRATA_TEMP}")
patch.append(_restore_temp())
else:
return None
return (f"B2:imm={imm},bits[4:0]={imm_enc & 0x1F}", patch)
def _check_jalr(mnemonic, operands, original_instr):
"""Check/patch jalr where offset triggers Bug 2."""
if len(operands) != 2:
return None
rd = operands[0]
offset, rs1 = _parse_mem_operand(operands[1])
if offset is None:
return None
offset_enc = offset & 0xFFF
if (offset_enc & 0x1F) != 20:
return None
delta = -4
new_offset = offset + 4
new_offset_enc = new_offset & 0xFFF
if (new_offset_enc & 0x1F) == 20:
delta = -8
new_offset = offset + 8
patch = []
if rd == rs1:
patch.append(_save_temp())
patch.append(f"addi {ERRATA_TEMP}, {rs1}, {delta}")
patch.append(f"jalr {rd}, {new_offset}({ERRATA_TEMP})")
patch.append(_restore_temp())
else:
patch.append(f"addi {rs1}, {rs1}, {delta}")
patch.append(f"jalr {rd}, {new_offset}({rs1})")
patch.append(f"addi {rs1}, {rs1}, {-delta}")
return (f"B2:offset={offset}", patch)
# Fence/system instructions: safe
def _check_fence_or_system(mnemonic, operands, original_instr):
return None
# ============================================================================
# Dispatch table
# ============================================================================
ERRATA_DISPATCH = {
'lui': _check_lui,
'auipc': _check_auipc,
'jal': _check_jal,
'slli': _check_shift_imm,
'srli': _check_shift_imm,
'srai': _check_shift_imm,
'lw': _check_load,
'lh': _check_load,
'lb': _check_load,
'lhu': _check_load,
'lbu': _check_load,
'addi': _check_i_type_alu,
'andi': _check_i_type_alu,
'ori': _check_i_type_alu,
'xori': _check_i_type_alu,
'slti': _check_i_type_alu,
'sltiu': _check_i_type_alu,
'jalr': _check_jalr,
'sw': _check_store,
'sh': _check_store,
'sb': _check_store,
'fence': _check_fence_or_system,
'ecall': _check_fence_or_system,
'ebreak': _check_fence_or_system,
}
# ============================================================================
# Rust file parsing: extract assembly from bio_code! macros
# ============================================================================
class MacroSpan:
"""Represents the location of a bio_code! or bio_code_aligned! macro in the file."""
def __init__(self, macro_name, fn_name, start_line, end_line):
self.macro_name = macro_name # "bio_code" or "bio_code_aligned"
self.fn_name = fn_name # first argument to the macro
self.start_line = start_line # 0-indexed line number of macro opening
self.end_line = end_line # 0-indexed line number of closing ");"
class AsmLine:
"""An assembly instruction extracted from a quoted string inside a bio_code! macro."""
def __init__(self, file_line_idx, instr_text, leading_whitespace, quote_char,
prefix_text, suffix_text, has_trailing_comma, full_line):
self.file_line_idx = file_line_idx # 0-indexed line in the file
self.instr_text = instr_text # the assembly text inside the quotes
self.leading_whitespace = leading_whitespace
self.quote_char = quote_char # " or '
self.prefix_text = prefix_text # text before the opening quote on this line
self.suffix_text = suffix_text # text after the closing quote (includes comma, comment)
self.has_trailing_comma = has_trailing_comma
self.full_line = full_line # the complete original line
def find_macro_spans(lines):
"""
Find all bio_code! and bio_code_aligned! macro invocations in the file.
Returns list of MacroSpan.
"""
spans = []
i = 0
# Match the macro invocation line:
# bio_code!(fn_name, START, END,
# bio_code_aligned!(fn_name, START, END,
# The macro may also use square brackets: bio_code![...] but parens are standard.
macro_pat = re.compile(
r'^(\s*)(?:#\[.*\]\s*)?' # optional attributes like #[rustfmt::skip]
r'(bio_code(?:_aligned)?)\s*!\s*\(\s*'
r'(\w+)' # fn_name
)
while i < len(lines):
m = macro_pat.match(lines[i])
if m:
macro_name = m.group(2)
fn_name = m.group(3)
start_line = i
# Find the closing ");", handling multi-line macros
depth = 0
j = i
found_end = False
while j < len(lines):
line = lines[j]
for ch in line:
if ch == '(':
depth += 1
elif ch == ')':
depth -= 1
if depth == 0:
found_end = True
break
if found_end:
spans.append(MacroSpan(macro_name, fn_name, start_line, j))
i = j + 1
break
j += 1
else:
# Never found closing paren
i += 1
else:
i += 1
return spans
def extract_asm_lines(lines, span):
"""
Extract AsmLine objects from a macro span.
Each assembly instruction is a quoted string on its own line:
"mv x4, x17", // comment
"li x9, 0x1000000",
We need to identify lines containing quoted assembly strings (as opposed to
the macro header line, label-only lines, directive lines, etc.).
"""
asm_lines = []
# The first line is the macro invocation header; skip it.
# Assembly strings start from the line after the header (or the header itself
# if the first string is on the same line, but typically they're on separate lines).
# We also need to handle the macro args (fn_name, START_LABEL, END_LABEL) which
# may span the first line or first few lines.
# Strategy: scan each line in the span for quoted strings that look like assembly.
# A line with assembly looks like:
# "instruction here", // optional comment
# "20: instruction",
# "20:", // label-only lines
# ".p2align 2",
# We skip the macro opening line's arguments.
# Find where the header arguments end (after the third comma following the macro name)
header_end = _find_header_end(lines, span)
for idx in range(header_end, span.end_line + 1):
line = lines[idx]
asm = _extract_asm_from_line(line, idx)
if asm is not None:
asm_lines.append(asm)
return asm_lines
def _find_header_end(lines, span):
"""
Find the line index where the macro header arguments end.
The header is: macro_name!(fn_name, START_LABEL, END_LABEL,
After the third comma, the assembly strings begin.
Returns the line index where assembly strings start.
"""
comma_count = 0
for idx in range(span.start_line, span.end_line + 1):
line = lines[idx]
in_string = False
for ch in line:
if ch == '"' and not in_string:
in_string = True
elif ch == '"' and in_string:
in_string = False
elif ch == ',' and not in_string:
comma_count += 1
if comma_count >= 3:
# The assembly starts on the next line (or the rest of this line)
return idx + 1
# Fallback: start from line after the macro opening
return span.start_line + 1
def _extract_asm_from_line(line, line_idx):
"""
Extract assembly text from a single line containing a quoted string.
Returns AsmLine or None.
"""
# Match: optional whitespace, opening quote, content, closing quote, optional comma, optional comment
m = re.match(
r'^(\s*)' # leading whitespace
r'(.*?)' # prefix before quote (e.g. nothing, or part of multi-string line)
r'"([^"]*)"' # quoted string
r'(\s*,?)' # optional trailing comma
r'(\s*(?://.*)?)' # optional comment
r'\s*$',
line
)
if not m:
return None
leading_ws = m.group(1)
prefix = m.group(2)
instr_text = m.group(3)
comma_part = m.group(4)
comment_part = m.group(5)
has_comma = ',' in comma_part
suffix = comma_part + comment_part
return AsmLine(
file_line_idx=line_idx,
instr_text=instr_text,
leading_whitespace=leading_ws,
quote_char='"',
prefix_text=prefix,
suffix_text=suffix,
has_trailing_comma=has_comma,
full_line=line,
)
# ============================================================================
# Check a single instruction for errata
# ============================================================================
class ErrataFinding:
"""One errata finding on a specific instruction."""
def __init__(self, asm_line, bug_desc, patched_instrs):
self.asm_line = asm_line # AsmLine object
self.bug_desc = bug_desc # human-readable bug description
self.patched_instrs = patched_instrs # list of replacement instruction strings
def check_instruction(asm_line):
"""
Check a single AsmLine for errata.
Returns ErrataFinding or None.
"""
instr_text = asm_line.instr_text.strip()
# Skip empty, labels-only, directives, comments
if not instr_text:
return None
# Skip lines that are only comments inside the string
if instr_text.startswith('//'):
return None
# Skip relocation references
if _has_relocation(instr_text):
return None
# Handle "label: instruction" form - check the instruction part
label_prefix = ""
lm = re.match(r'^(\d+\s*:\s*)(.*)', instr_text)
if lm:
label_prefix = lm.group(1)
instr_text = lm.group(2).strip()
if not instr_text:
return None # label-only
# Strip inline assembly comments (after //)
# Actually in the Rust bio_code! format, comments are outside the quotes.
# But some inline comments may be inside with "// comment" style.
# Let's be safe:
comment_pos = instr_text.find('//')
if comment_pos >= 0:
instr_text = instr_text[:comment_pos].strip()
if not instr_text:
return None
mnemonic, operands = _parse_instruction(instr_text)
if mnemonic is None:
return None
check_fn = ERRATA_DISPATCH.get(mnemonic)
if check_fn is None:
return None # not in dispatch table
result = check_fn(mnemonic, operands, instr_text)
if result is None:
return None
bug_desc, patched_instrs = result
# If there was a label prefix, prepend it to the first patched instruction
if label_prefix and patched_instrs:
patched_instrs = [label_prefix + patched_instrs[0]] + patched_instrs[1:]
return ErrataFinding(asm_line, bug_desc, patched_instrs)
# ============================================================================
# File-level checking
# ============================================================================
def check_file(filepath):
"""
Check a .rs file for errata.
Returns (lines, list_of_findings, list_of_macro_spans).
"""
with open(filepath, 'r') as f:
lines = f.readlines()
# Strip trailing newlines but remember them
raw_lines = [line.rstrip('\n').rstrip('\r') for line in lines]
spans = find_macro_spans(raw_lines)
findings = []
for span in spans:
asm_lines = extract_asm_lines(raw_lines, span)
for asm_line in asm_lines:
finding = check_instruction(asm_line)
if finding is not None:
findings.append(finding)
return raw_lines, findings, spans
# ============================================================================
# Reporting (check mode)
# ============================================================================
def report_findings(filepath, findings):
"""Print a human-readable report of errata findings."""
if not findings:
print(f"{filepath}: OK (no errata found)")
return
print(f"{filepath}: {len(findings)} errata finding(s)")
for f in findings:
line_num = f.asm_line.file_line_idx + 1 # 1-indexed for display
instr = f.asm_line.instr_text.strip()
print(f" line {line_num}: {f.bug_desc}")
print(f" original: {instr}")
if f.patched_instrs:
print(f" patched ({len(f.patched_instrs)} instructions):")
for pi in f.patched_instrs:
print(f" {pi}")
print()
# ============================================================================
# Patching (--autopatch mode)
# ============================================================================
def apply_patches(raw_lines, findings):
"""
Apply all patches to the file lines.
Returns new list of lines.
Strategy: process findings in reverse line order so that inserting/replacing
lines doesn't shift indices of earlier findings.
"""
# Group findings by line index. There should be at most one finding per line.
by_line = {}
for f in findings:
idx = f.asm_line.file_line_idx
if idx in by_line:
# Multiple findings on same line shouldn't happen, take the first
pass
else:
by_line[idx] = f
result = list(raw_lines)
# Process in reverse order
for line_idx in sorted(by_line.keys(), reverse=True):
finding = by_line[line_idx]
asm = finding.asm_line
patched = finding.patched_instrs
if not patched:
continue
# Build replacement lines
ws = asm.leading_whitespace
prefix = asm.prefix_text
replacement = []
# Add errata comment
replacement.append(f"{ws}// ERRATA {finding.bug_desc} patch for: {asm.instr_text.strip()}")
for i, pinstr in enumerate(patched):
is_last = (i == len(patched) - 1)
# The last patched instruction gets the original line's trailing comma and comment
if is_last:
comma = "," if asm.has_trailing_comma else ""
# Preserve the original comment if any
comment_match = re.search(r'(//.*)', asm.suffix_text)
comment = f" {comment_match.group(1)}" if comment_match else ""
replacement.append(f'{ws}{prefix}"{pinstr}"{comma}{comment}')
else:
replacement.append(f'{ws}{prefix}"{pinstr}",')
result[line_idx:line_idx + 1] = replacement
return result
def patch_file(filepath, raw_lines, findings):
"""Write patched file back to disk."""
patched_lines = apply_patches(raw_lines, findings)
with open(filepath, 'w') as f:
for line in patched_lines:
f.write(line + '\n')
return len(findings)
# ============================================================================
# Main
# ============================================================================
def parse_args():
parser = argparse.ArgumentParser(
description="Check and patch RISC-V assembly errata in Rust .rs files"
)
parser.add_argument(
"files",
nargs="+",
help=".rs files to check",
)
parser.add_argument(
"--autopatch",
action="store_true",
help="Automatically patch errata in-place (replaces files)",
)
parser.add_argument(
"-v", "--verbose",
action="store_true",
help="Show detailed output even when no errata found",
)
return parser.parse_args()
def main():
args = parse_args()
total_findings = 0
total_files_with_findings = 0
total_patched = 0
for filepath in args.files:
if not os.path.exists(filepath):
print(f"Error: file not found: {filepath}", file=sys.stderr)
sys.exit(2)
raw_lines, findings, spans = check_file(filepath)
if args.verbose or findings:
if not findings:
macro_names = [s.fn_name for s in spans]
print(f"{filepath}: OK ({len(spans)} macro(s) scanned: {', '.join(macro_names)})")
else:
total_files_with_findings += 1
total_findings += len(findings)
if findings:
if args.autopatch:
count = patch_file(filepath, raw_lines, findings)
total_patched += count
print(f"{filepath}: patched {count} errata finding(s) in-place")
else:
report_findings(filepath, findings)
# Summary
if len(args.files) > 1 or args.verbose:
print(f"\nSummary: {len(args.files)} file(s) scanned, "
f"{total_findings} finding(s) in {total_files_with_findings} file(s)")
if args.autopatch:
print(f" {total_patched} patches applied")
if total_findings > 0 and not args.autopatch:
sys.exit(1)
sys.exit(0)
if __name__ == "__main__":
main()