ab_riscv_interpreter/v/zvexx/

perm.rs

//! ZveXx permutation instructions

#[cfg(test)]
mod tests;
pub mod zvexx_perm_helpers;

use crate::v::vector_registers::VectorRegistersExt;
use crate::v::zvexx::zvexx_helpers;
use crate::{
    ExecutableInstruction, ExecutableInstructionCsr, ExecutableInstructionOperands, ExecutionError,
    ExecutionResult, FetchInstructionResult, InstructionFetcher, OpaqueThreadedExecutionResult,
    PackedAddress, ProgramCounter, RegisterFile, Rs1Rs2OperandValues, Rs1Rs2Operands,
    ThreadedExecutableInstruction, ThreadedExecutionResult, VirtualMemory,
};
use ab_riscv_macros::instruction_execution;
use ab_riscv_primitives::prelude::*;

#[instruction_execution]
const impl<Reg> ExecutableInstructionOperands for ZveXxPermInstruction<Reg> where Reg: Register {}

#[instruction_execution]
const impl<Reg, Env> ExecutableInstructionCsr<Env> for ZveXxPermInstruction<Reg> where Reg: Register {}

#[instruction_execution]
impl<Reg, Regs, Env, Memory, PC> ExecutableInstruction<Regs, Env, Memory, PC>
    for ZveXxPermInstruction<Reg>
where
    Reg: Register,
    Regs: RegisterFile<Reg>,
    Env: VectorRegistersExt<Reg>,
    [(); SUPPORTED_ELEN_VLEN::<{ Env::ELEN }, { Env::VLEN }>]:,
    Memory: VirtualMemory,
    PC: ProgramCounter<Reg::Type, Memory>,
{
    #[inline(always)]
    #[cfg_attr(feature = "no-panic", no_panic_const::no_panic)]
    fn execute(
        self,
        Rs1Rs2OperandValues {
            rs1_value,
            rs2_value: _,
        }: Rs1Rs2OperandValues<<Self::Reg as Register>::Type>,
        _regs: &mut Regs,
        env: &mut Env,
        _memory: &mut Memory,
        program_counter: &mut PC,
    ) -> ExecutionResult<Self::Reg> {
        match self {
            // vmv.x.s rd, vs2
            // Copies sign-extended element 0 of vs2 (at current SEW) to GPR rd.
            // Requires valid vtype (needs SEW to know element width).
            // Does not use vl or masking; always reads element 0.
            // Resets vstart per spec §6.3.
            Self::VmvXS { rd, vs2 } => {
                if !env.vector_instructions_allowed() {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                }
                let Some(vtype) = env.vtype() else {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                };
                let sew = vtype.vsew();
                // SAFETY: element 0 is always within register vs2, byte offset 0;
                // VLEN.bytes() >= sew.bytes() for all legal vtype configurations.
                let raw =
                    unsafe { zvexx_perm_helpers::read_element_0_u64(env.read_vregs(), vs2, sew) };
                let sign_extended = zvexx_perm_helpers::sign_extend_to_reg::<Reg>(raw, sew);
                env.mark_vs_dirty();
                env.reset_vstart();

                return ExecutionResult::Continue {
                    rd,
                    value: sign_extended,
                };
            }
            // vmv.s.x vd, rs1
            // Copies scalar GPR rs1 (zero-extended / truncated to SEW) into element 0 of vd.
            // When vl == 0, the write is suppressed but vstart is still reset.
            // Resets vstart per spec §6.3.
            Self::VmvSX { vd, rs1: _ } => {
                if !env.vector_instructions_allowed() {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                }
                let Some(vtype) = env.vtype() else {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                };
                let sew = vtype.vsew();
                let vl = env.vl();
                let vstart = env.vstart();
                // Per spec §16.1: update only when vstart < vl.
                if vstart < vl {
                    let scalar = rs1_value.as_i64().cast_unsigned();
                    // SAFETY: element 0 always fits.
                    unsafe {
                        zvexx_perm_helpers::write_element_0_u64(env.write_vregs(), vd, sew, scalar);
                    }
                }
                env.mark_vs_dirty();
                env.reset_vstart();
            }
            // vslideup.vx vd, vs2, rs1: _, vm
            // Slides elements of vs2 up by the scalar offset in rs1.
            // Elements vd[0..offset] are unchanged (tail-undisturbed for those positions).
            // Elements vd[i] for offset <= i < vl get vs2[i - offset].
            // Per spec §16.3.1: vd must not overlap vs2.
            Self::VslideupVx {
                vd,
                vs2,
                rs1: _,
                vm,
            } => {
                if !env.vector_instructions_allowed() {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                }
                let Some(vtype) = env.vtype() else {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                };
                let group_regs = vtype.vlmul().register_count();
                zvexx_perm_helpers::check_vreg_group_alignment::<Reg, _, _>(
                    program_counter,
                    vd,
                    group_regs,
                )?;
                zvexx_perm_helpers::check_vreg_group_alignment::<Reg, _, _>(
                    program_counter,
                    vs2,
                    group_regs,
                )?;
                // vd must not overlap vs2
                zvexx_perm_helpers::check_no_overlap::<Reg, _, _>(
                    program_counter,
                    vd,
                    vs2,
                    group_regs,
                )?;
                if !vm && vd == VReg::V0 {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                }
                let sew = vtype.vsew();
                let offset = rs1_value.as_u64();
                // SAFETY: alignment and no-overlap verified above; vl <= VLMAX.
                unsafe {
                    zvexx_perm_helpers::execute_slideup(env, vd, vs2, vm, sew, offset);
                }
            }
            // vslideup.vi vd, vs2, uimm, vm
            // Same as vslideup.vx but offset is a 5-bit unsigned immediate.
            Self::VslideupVi { vd, vs2, uimm, vm } => {
                if !env.vector_instructions_allowed() {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                }
                let Some(vtype) = env.vtype() else {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                };
                let group_regs = vtype.vlmul().register_count();
                zvexx_perm_helpers::check_vreg_group_alignment::<Reg, _, _>(
                    program_counter,
                    vd,
                    group_regs,
                )?;
                zvexx_perm_helpers::check_vreg_group_alignment::<Reg, _, _>(
                    program_counter,
                    vs2,
                    group_regs,
                )?;
                zvexx_perm_helpers::check_no_overlap::<Reg, _, _>(
                    program_counter,
                    vd,
                    vs2,
                    group_regs,
                )?;
                if !vm && vd == VReg::V0 {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                }
                let sew = vtype.vsew();
                let offset = u64::from(uimm);
                // SAFETY: same as VslideupVx.
                unsafe {
                    zvexx_perm_helpers::execute_slideup(env, vd, vs2, vm, sew, offset);
                }
            }
            // vslidedown.vx vd, vs2, rs1: _, vm
            // Element vd[i] = vs2[i + offset] if i + offset < VLMAX, else 0.
            // vd may overlap vs2 for slidedown.
            Self::VslidedownVx {
                vd,
                vs2,
                rs1: _,
                vm,
            } => {
                if !env.vector_instructions_allowed() {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                }
                let Some(vtype) = env.vtype() else {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                };
                let group_regs = vtype.vlmul().register_count();
                zvexx_perm_helpers::check_vreg_group_alignment::<Reg, _, _>(
                    program_counter,
                    vd,
                    group_regs,
                )?;
                zvexx_perm_helpers::check_vreg_group_alignment::<Reg, _, _>(
                    program_counter,
                    vs2,
                    group_regs,
                )?;
                if !vm && vd == VReg::V0 {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                }
                let sew = vtype.vsew();
                let vlmax = env.vlmax_for_vtype(vtype);
                let offset = rs1_value.as_u64();
                // SAFETY: alignment verified above; vl <= VLMAX; offset clamped in helper.
                unsafe {
                    zvexx_perm_helpers::execute_slidedown(env, vd, vs2, vm, sew, vlmax, offset);
                }
            }
            // vslidedown.vi vd, vs2, uimm, vm
            // Same as vslidedown.vx but offset is a 5-bit unsigned immediate.
            Self::VslidedownVi { vd, vs2, uimm, vm } => {
                if !env.vector_instructions_allowed() {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                }
                let Some(vtype) = env.vtype() else {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                };
                let group_regs = vtype.vlmul().register_count();
                zvexx_perm_helpers::check_vreg_group_alignment::<Reg, _, _>(
                    program_counter,
                    vd,
                    group_regs,
                )?;
                zvexx_perm_helpers::check_vreg_group_alignment::<Reg, _, _>(
                    program_counter,
                    vs2,
                    group_regs,
                )?;
                if !vm && vd == VReg::V0 {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                }
                let sew = vtype.vsew();
                let vlmax = env.vlmax_for_vtype(vtype);
                let offset = u64::from(uimm);
                // SAFETY: same as VslidedownVx.
                unsafe {
                    zvexx_perm_helpers::execute_slidedown(env, vd, vs2, vm, sew, vlmax, offset);
                }
            }
            // vslide1up.vx vd, vs2, rs1: _, vm
            // Element 0 of vd gets the scalar value rs1 (written at SEW width).
            // Elements vd[i] for 1 <= i < vl get vs2[i - 1].
            // vd must not overlap vs2.
            Self::Vslide1upVx {
                vd,
                vs2,
                rs1: _,
                vm,
            } => {
                if !env.vector_instructions_allowed() {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                }
                let Some(vtype) = env.vtype() else {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                };
                let group_regs = vtype.vlmul().register_count();
                zvexx_perm_helpers::check_vreg_group_alignment::<Reg, _, _>(
                    program_counter,
                    vd,
                    group_regs,
                )?;
                zvexx_perm_helpers::check_vreg_group_alignment::<Reg, _, _>(
                    program_counter,
                    vs2,
                    group_regs,
                )?;
                zvexx_perm_helpers::check_no_overlap::<Reg, _, _>(
                    program_counter,
                    vd,
                    vs2,
                    group_regs,
                )?;
                if !vm && vd == VReg::V0 {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                }
                let sew = vtype.vsew();
                let scalar = rs1_value.as_i64().cast_unsigned();
                // SAFETY: alignment and no-overlap verified; vl <= VLMAX.
                unsafe {
                    zvexx_perm_helpers::execute_slide1up(env, vd, vs2, vm, sew, scalar);
                }
            }
            // vslide1down.vx vd, vs2, rs1: _, vm
            // Element vd[i] = vs2[i + 1] for 0 <= i < vl - 1.
            // Element vd[vl - 1] gets the scalar value rs1.
            // vd may overlap vs2 for slide1down.
            Self::Vslide1downVx {
                vd,
                vs2,
                rs1: _,
                vm,
            } => {
                if !env.vector_instructions_allowed() {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                }
                let Some(vtype) = env.vtype() else {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                };
                let group_regs = vtype.vlmul().register_count();
                zvexx_perm_helpers::check_vreg_group_alignment::<Reg, _, _>(
                    program_counter,
                    vd,
                    group_regs,
                )?;
                zvexx_perm_helpers::check_vreg_group_alignment::<Reg, _, _>(
                    program_counter,
                    vs2,
                    group_regs,
                )?;
                if !vm && vd == VReg::V0 {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                }
                let sew = vtype.vsew();
                let scalar = rs1_value.as_i64().cast_unsigned();
                // SAFETY: alignment verified; vl <= VLMAX; overlap permitted by spec.
                unsafe {
                    zvexx_perm_helpers::execute_slide1down(env, vd, vs2, vm, sew, scalar);
                }
            }
            // vrgather.vv vd, vs2, vs1, vm
            // vd[i] = (vs1[i] < VLMAX) ? vs2[vs1[i]] : 0
            // vd must not overlap vs1 or vs2.
            Self::VrgatherVv { vd, vs2, vs1, vm } => {
                if !env.vector_instructions_allowed() {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                }
                let Some(vtype) = env.vtype() else {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                };
                let group_regs = vtype.vlmul().register_count();
                zvexx_perm_helpers::check_vreg_group_alignment::<Reg, _, _>(
                    program_counter,
                    vd,
                    group_regs,
                )?;
                zvexx_perm_helpers::check_vreg_group_alignment::<Reg, _, _>(
                    program_counter,
                    vs2,
                    group_regs,
                )?;
                zvexx_perm_helpers::check_vreg_group_alignment::<Reg, _, _>(
                    program_counter,
                    vs1,
                    group_regs,
                )?;
                zvexx_perm_helpers::check_no_overlap::<Reg, _, _>(
                    program_counter,
                    vd,
                    vs2,
                    group_regs,
                )?;
                zvexx_perm_helpers::check_no_overlap::<Reg, _, _>(
                    program_counter,
                    vd,
                    vs1,
                    group_regs,
                )?;
                if !vm && vd == VReg::V0 {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                }
                let sew = vtype.vsew();
                let vlmax = env.vlmax_for_vtype(vtype);
                // SAFETY: all alignment and overlap constraints verified above; vl <= VLMAX.
                unsafe {
                    zvexx_perm_helpers::execute_rgather_vv(env, vd, vs2, vs1, vm, sew, vlmax);
                }
            }
            // vrgather.vx vd, vs2, rs1: _, vm
            // All active elements of vd get vs2[rs1] if rs1 < VLMAX, else 0.
            // vd must not overlap vs2.
            Self::VrgatherVx {
                vd,
                vs2,
                rs1: _,
                vm,
            } => {
                if !env.vector_instructions_allowed() {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                }
                let Some(vtype) = env.vtype() else {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                };
                let group_regs = vtype.vlmul().register_count();
                zvexx_perm_helpers::check_vreg_group_alignment::<Reg, _, _>(
                    program_counter,
                    vd,
                    group_regs,
                )?;
                zvexx_perm_helpers::check_vreg_group_alignment::<Reg, _, _>(
                    program_counter,
                    vs2,
                    group_regs,
                )?;
                zvexx_perm_helpers::check_no_overlap::<Reg, _, _>(
                    program_counter,
                    vd,
                    vs2,
                    group_regs,
                )?;
                if !vm && vd == VReg::V0 {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                }
                let sew = vtype.vsew();
                let vlmax = env.vlmax_for_vtype(vtype);
                let index = rs1_value.as_u64();
                // SAFETY: alignment and no-overlap verified; vl <= VLMAX.
                unsafe {
                    zvexx_perm_helpers::execute_rgather_scalar(env, vd, vs2, vm, sew, vlmax, index);
                }
            }
            // vrgather.vi vd, vs2, uimm, vm
            // Same as vrgather.vx but index is a 5-bit unsigned immediate.
            Self::VrgatherVi { vd, vs2, uimm, vm } => {
                if !env.vector_instructions_allowed() {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                }
                let Some(vtype) = env.vtype() else {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                };
                let group_regs = vtype.vlmul().register_count();
                zvexx_perm_helpers::check_vreg_group_alignment::<Reg, _, _>(
                    program_counter,
                    vd,
                    group_regs,
                )?;
                zvexx_perm_helpers::check_vreg_group_alignment::<Reg, _, _>(
                    program_counter,
                    vs2,
                    group_regs,
                )?;
                zvexx_perm_helpers::check_no_overlap::<Reg, _, _>(
                    program_counter,
                    vd,
                    vs2,
                    group_regs,
                )?;
                if !vm && vd == VReg::V0 {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                }
                let sew = vtype.vsew();
                let vlmax = env.vlmax_for_vtype(vtype);
                let index = u64::from(uimm);
                // SAFETY: same as VrgatherVx.
                unsafe {
                    zvexx_perm_helpers::execute_rgather_scalar(env, vd, vs2, vm, sew, vlmax, index);
                }
            }
            // vrgatherei16.vv vd, vs2, vs1, vm
            // Like vrgather.vv but vs1 always uses EEW=16 (regardless of SEW).
            // EMUL_vs1 = (16 / SEW) * LMUL; must be in [1/8, 8] else illegal.
            // vd must not overlap vs1 or vs2.
            Self::Vrgatherei16Vv { vd, vs2, vs1, vm } => {
                if !env.vector_instructions_allowed() {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                }
                let Some(vtype) = env.vtype() else {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                };
                let group_regs = vtype.vlmul().register_count();
                zvexx_perm_helpers::check_vreg_group_alignment::<Reg, _, _>(
                    program_counter,
                    vd,
                    group_regs,
                )?;
                zvexx_perm_helpers::check_vreg_group_alignment::<Reg, _, _>(
                    program_counter,
                    vs2,
                    group_regs,
                )?;
                // Compute EMUL for vs1 index register (EEW=16).
                let index_group_regs = vtype
                    .vlmul()
                    .index_register_count(
                        ab_riscv_primitives::instructions::v::Eew::E16,
                        vtype.vsew(),
                    )
                    .ok_or(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    })?;
                zvexx_perm_helpers::check_vreg_group_alignment::<Reg, _, _>(
                    program_counter,
                    vs1,
                    index_group_regs,
                )?;
                zvexx_perm_helpers::check_no_overlap::<Reg, _, _>(
                    program_counter,
                    vd,
                    vs2,
                    group_regs,
                )?;
                // vd and vs1 have different group sizes (group_regs vs index_group_regs),
                // so the symmetric helper would use the wrong size for one of the intervals.
                zvexx_perm_helpers::check_no_overlap_asymmetric::<Reg, _, _>(
                    program_counter,
                    vd,
                    group_regs,
                    vs1,
                    index_group_regs,
                )?;
                if !vm && vd == VReg::V0 {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                }
                let sew = vtype.vsew();
                let vlmax = env.vlmax_for_vtype(vtype);
                // SAFETY: all alignment and overlap constraints verified; vl <= VLMAX;
                // vs1 uses EEW=16 with computed index_group_regs.
                unsafe {
                    zvexx_perm_helpers::execute_rgatherei16(
                        env,
                        vd,
                        vs2,
                        vs1,
                        vm,
                        sew,
                        vlmax,
                        index_group_regs,
                    );
                }
            }
            // vmerge.vvm / vmv.v.v
            // When vm=true: vmv.v.v vd, vs1 - broadcast all active elements from vs1.
            //   vs2 is ignored; no overlap restriction on vd/vs2.
            // When vm=false: vmerge.vvm vd, vs2, vs1, v0
            //   vd[i] = v0[i] ? vs1[i] : vs2[i]
            //   vd must not overlap v0 (mask source).
            Self::VmergeVvm { vd, vs2, vs1, vm } => {
                if !env.vector_instructions_allowed() {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                }
                let Some(vtype) = env.vtype() else {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                };
                let group_regs = vtype.vlmul().register_count();
                zvexx_perm_helpers::check_vreg_group_alignment::<Reg, _, _>(
                    program_counter,
                    vd,
                    group_regs,
                )?;
                zvexx_perm_helpers::check_vreg_group_alignment::<Reg, _, _>(
                    program_counter,
                    vs1,
                    group_regs,
                )?;
                if !vm {
                    // vmerge: vs2 is read, vd must not overlap v0
                    zvexx_perm_helpers::check_vreg_group_alignment::<Reg, _, _>(
                        program_counter,
                        vs2,
                        group_regs,
                    )?;
                    zvexx_perm_helpers::check_no_overlap::<Reg, _, _>(
                        program_counter,
                        vd,
                        VReg::V0,
                        group_regs,
                    )?;
                }
                let sew = vtype.vsew();
                // SAFETY: alignment and overlap verified above; vl <= VLMAX.
                unsafe {
                    zvexx_perm_helpers::execute_merge_vv(env, vd, vs2, vs1, vm, sew);
                }
            }
            // vmerge.vxm / vmv.v.x
            // When vm=true: vmv.v.x vd, rs1 - broadcast scalar to all active elements.
            // When vm=false: vmerge.vxm - vd[i] = v0[i] ? rs1 : vs2[i]
            Self::VmergeVxm {
                vd,
                vs2,
                rs1: _,
                vm,
            } => {
                if !env.vector_instructions_allowed() {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                }
                let Some(vtype) = env.vtype() else {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                };
                let group_regs = vtype.vlmul().register_count();
                zvexx_perm_helpers::check_vreg_group_alignment::<Reg, _, _>(
                    program_counter,
                    vd,
                    group_regs,
                )?;
                if !vm {
                    zvexx_perm_helpers::check_vreg_group_alignment::<Reg, _, _>(
                        program_counter,
                        vs2,
                        group_regs,
                    )?;
                    zvexx_perm_helpers::check_no_overlap::<Reg, _, _>(
                        program_counter,
                        vd,
                        VReg::V0,
                        group_regs,
                    )?;
                }
                let sew = vtype.vsew();
                let scalar = rs1_value.as_i64().cast_unsigned();
                // SAFETY: alignment and overlap verified above; vl <= VLMAX.
                unsafe {
                    zvexx_perm_helpers::execute_merge_scalar(env, vd, vs2, vm, sew, scalar);
                }
            }
            // vmerge.vim / vmv.v.i
            // When vm=true: vmv.v.i vd, simm5 - broadcast sign-extended immediate.
            // When vm=false: vmerge.vim - vd[i] = v0[i] ? simm5 : vs2[i]
            Self::VmergeVim { vd, vs2, simm5, vm } => {
                if !env.vector_instructions_allowed() {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                }
                let Some(vtype) = env.vtype() else {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                };
                let group_regs = vtype.vlmul().register_count();
                zvexx_perm_helpers::check_vreg_group_alignment::<Reg, _, _>(
                    program_counter,
                    vd,
                    group_regs,
                )?;
                if !vm {
                    zvexx_perm_helpers::check_vreg_group_alignment::<Reg, _, _>(
                        program_counter,
                        vs2,
                        group_regs,
                    )?;
                    zvexx_perm_helpers::check_no_overlap::<Reg, _, _>(
                        program_counter,
                        vd,
                        VReg::V0,
                        group_regs,
                    )?;
                }
                let sew = vtype.vsew();
                // Sign-extend imm to u64 so the low sew_bytes are correct for all SEW.
                let scalar = i64::from(simm5).cast_unsigned();
                // SAFETY: alignment and overlap verified above; vl <= VLMAX.
                unsafe {
                    zvexx_perm_helpers::execute_merge_scalar(env, vd, vs2, vm, sew, scalar);
                }
            }
            // vcompress.vm vd, vs2, vs1
            // Packs active elements of vs2 (where vs1 mask bit is set) sequentially into vd.
            // Always unmasked (vm=1 in encoding); vs1 is the explicit mask operand.
            // vd must not overlap vs1 or vs2.
            Self::VcompressVm { vd, vs2, vs1 } => {
                if !env.vector_instructions_allowed() {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                }
                let Some(vtype) = env.vtype() else {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                };
                // Spec §16.5: vstart must be zero.
                if env.vstart() != Vstart::ZERO {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                }
                let group_regs = vtype.vlmul().register_count();
                zvexx_perm_helpers::check_vreg_group_alignment::<Reg, _, _>(
                    program_counter,
                    vd,
                    group_regs,
                )?;
                zvexx_perm_helpers::check_vreg_group_alignment::<Reg, _, _>(
                    program_counter,
                    vs2,
                    group_regs,
                )?;
                // vs1 is always a single mask register (no LMUL grouping)
                zvexx_perm_helpers::check_no_overlap::<Reg, _, _>(
                    program_counter,
                    vd,
                    vs2,
                    group_regs,
                )?;
                // vs1 is a mask register; check it doesn't overlap vd
                zvexx_perm_helpers::check_no_overlap::<Reg, _, _>(
                    program_counter,
                    vd,
                    vs1,
                    ::core::num::NonZeroU8::new(1).expect("Not zero; qed"),
                )?;
                let sew = vtype.vsew();
                let vl = env.vl();
                unsafe {
                    zvexx_perm_helpers::execute_compress(env, vd, vs2, vs1, vl, sew);
                }
            }
            // vmv1r.v vd, vs2
            // Whole register move: copies 1 register.
            // No masking, no vtype/vl dependency.
            Self::Vmv1rV { vd, vs2 } => {
                if !env.vector_instructions_allowed() {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                }
                // SAFETY: both vd.to_bits() and vs2.to_bits() are always in [0, 32) by VReg
                // invariant; copying 1 register always fits.
                unsafe {
                    zvexx_perm_helpers::execute_whole_reg_move::<1, _>(env.write_vregs(), vd, vs2);
                }
                env.mark_vs_dirty();
                env.reset_vstart();
            }
            // vmv2r.v vd, vs2
            // Whole register move: copies 2 registers.
            // vd and vs2 must be aligned to 2 (checked here per spec §17.6).
            Self::Vmv2rV { vd, vs2 } => {
                if !env.vector_instructions_allowed() {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                }
                if !vd.to_bits().is_multiple_of(2) || !vs2.to_bits().is_multiple_of(2) {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                }
                // SAFETY: alignment verified; 2 registers from aligned base always stay in [0, 32).
                unsafe {
                    zvexx_perm_helpers::execute_whole_reg_move::<2, _>(env.write_vregs(), vd, vs2);
                }
                env.mark_vs_dirty();
                env.reset_vstart();
            }
            // vmv4r.v vd, vs2
            // Whole register move: copies 4 registers.
            Self::Vmv4rV { vd, vs2 } => {
                if !env.vector_instructions_allowed() {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                }
                if !vd.to_bits().is_multiple_of(4) || !vs2.to_bits().is_multiple_of(4) {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                }
                // SAFETY: alignment verified; 4 registers from aligned base always stay in [0, 32).
                unsafe {
                    zvexx_perm_helpers::execute_whole_reg_move::<4, _>(env.write_vregs(), vd, vs2);
                }
                env.mark_vs_dirty();
                env.reset_vstart();
            }
            // vmv8r.v vd, vs2
            // Whole register move: copies 8 registers.
            Self::Vmv8rV { vd, vs2 } => {
                if !env.vector_instructions_allowed() {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                }
                if !vd.to_bits().is_multiple_of(8) || !vs2.to_bits().is_multiple_of(8) {
                    ::core::hint::cold_path();
                    return ExecutionResult::Err(ExecutionError::IllegalInstruction {
                        address: PackedAddress::new(
                            program_counter.old_pc(zvexx_helpers::INSTRUCTION_SIZE),
                        ),
                    });
                }
                // SAFETY: alignment verified; 8 registers from aligned base always stay in [0, 32).
                unsafe {
                    zvexx_perm_helpers::execute_whole_reg_move::<8, _>(env.write_vregs(), vd, vs2);
                }
                env.mark_vs_dirty();
                env.reset_vstart();
            }
        }

        ExecutionResult::ContinueNoWrite
    }
}