smmu 1.8.0

//! Fault Detection and Classification for ARM SMMU v3
//!
//! This module implements comprehensive fault detection per ARM SMMU v3 Section 6.1:
//! - Translation fault detection with full context capture
//! - Permission fault checking with bitwise operations
//! - Address range validation (32/48/52-bit support)
//! - All 15 ARM SMMU v3 fault types with proper classification
//!
//! # ARM SMMU v3 Compliance
//!
//! All fault detection follows the ARM SMMU v3 specification for:
//! - Fault syndrome generation
//! - Stage attribution (Stage 1 vs Stage 2)
//! - Fault priority ordering
//! - Recoverable vs non-recoverable classification

use crate::types::{
    AccessType, FaultRecord, FaultSyndrome, FaultType, PagePermissions, SecurityState, StreamID, TranslationStage,
    IOVA, PA, PASID,
};

/// Address size configuration for validation
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AddressSize {
    /// 32-bit address space (4GB)
    Bits32,
    /// 48-bit address space (256TB)
    Bits48,
    /// 52-bit address space (4PB)
    Bits52,
}

impl AddressSize {
    /// Get the maximum address for this address size
    #[must_use]
    pub const fn max_address(self) -> u64 {
        match self {
            Self::Bits32 => 0xFFFF_FFFF,
            Self::Bits48 => 0x0000_FFFF_FFFF_FFFF,
            Self::Bits52 => 0x000F_FFFF_FFFF_FFFF,
        }
    }

    /// Check if an address exceeds this address size
    #[must_use]
    pub const fn exceeds(self, addr: u64) -> bool {
        addr > self.max_address()
    }
}

/// Fault detection result
pub type FaultDetectionResult = Result<(), FaultRecord>;

/// Translation fault detector
///
/// Detects translation faults (unmapped pages) with full context capture.
#[derive(Debug, Clone)]
pub struct TranslationFaultDetector {
    timestamp_generator: u64,
}

impl TranslationFaultDetector {
    /// Create a new translation fault detector
    #[must_use]
    pub const fn new() -> Self {
        Self { timestamp_generator: 0 }
    }

    /// Detect a translation fault with full context
    ///
    /// # Arguments
    ///
    /// * `stream_id` - Source stream identifier
    /// * `pasid` - Process Address Space ID
    /// * `iova` - Faulting virtual address
    /// * `access_type` - Type of access that faulted
    /// * `security_state` - Security state context
    /// * `fault_level` - Translation table level where fault occurred (0-3)
    ///
    /// # Returns
    ///
    /// FaultRecord containing complete fault information including syndrome
    #[must_use]
    pub fn detect_translation_fault(
        &mut self,
        stream_id: StreamID,
        pasid: PASID,
        iova: IOVA,
        access_type: AccessType,
        security_state: SecurityState,
        fault_level: u8,
    ) -> FaultRecord {
        // Generate ARM SMMU v3 fault syndrome for translation fault
        let syndrome = FaultSyndrome::builder()
            .syndrome_register(0x0100_0000 | (u32::from(fault_level) << 16))
            .fault_level(fault_level)
            .write_not_read(access_type == AccessType::Write)
            .valid_syndrome(true)
            .build();

        self.timestamp_generator += 1;

        FaultRecord::builder()
            .stream_id(stream_id)
            .pasid(pasid)
            .address(iova)
            .fault_type(FaultType::TranslationFault)
            .access_type(access_type)
            .security_state(security_state)
            .syndrome(syndrome)
            .timestamp(self.timestamp_generator)
            .build()
    }

    /// Detect a translation fault with stage information
    ///
    /// # Arguments
    ///
    /// * `stream_id` - Source stream identifier
    /// * `pasid` - Process Address Space ID
    /// * `iova` - Faulting virtual address
    /// * `access_type` - Type of access that faulted
    /// * `security_state` - Security state context
    /// * `stage` - Translation stage where fault occurred
    /// * `fault_level` - Translation table level (0-3)
    #[must_use]
    pub fn detect_stage_translation_fault(
        &mut self,
        stream_id: StreamID,
        pasid: PASID,
        iova: IOVA,
        access_type: AccessType,
        security_state: SecurityState,
        stage: TranslationStage,
        fault_level: u8,
    ) -> FaultRecord {
        // Include stage information in syndrome.
        // BUG-RUST-06: Stage-2 indicator is bit 7 (0x80), matching the C++ reference
        // implementation (smmu.cpp ~line 2328).  The previous value of 0x0100_0000 was
        // the same as the base fault-class bits, making Stage-1 and Stage-2 syndromes
        // identical.
        let stage_bits = match stage {
            TranslationStage::Stage2 => 0x0000_0080u32,  // bit 7 = Stage-2 indicator
            _ => 0x0000_0000u32,                          // Stage-1 / other: no extra bits
        };

        let syndrome = FaultSyndrome::builder()
            .syndrome_register(0x0100_0000u32 | stage_bits | (u32::from(fault_level) << 16))
            .fault_level(fault_level)
            .write_not_read(access_type == AccessType::Write)
            .valid_syndrome(true)
            .build();

        self.timestamp_generator += 1;

        FaultRecord::builder()
            .stream_id(stream_id)
            .pasid(pasid)
            .address(iova)
            .fault_type(FaultType::TranslationFault)
            .access_type(access_type)
            .security_state(security_state)
            .syndrome(syndrome)
            .timestamp(self.timestamp_generator)
            .build()
    }
}

impl Default for TranslationFaultDetector {
    fn default() -> Self {
        Self::new()
    }
}

/// Permission fault detector
///
/// Detects permission violations with bitwise permission checking.
#[derive(Debug, Clone)]
pub struct PermissionFaultDetector {
    timestamp_generator: u64,
}

impl PermissionFaultDetector {
    /// Create a new permission fault detector
    #[must_use]
    pub const fn new() -> Self {
        Self { timestamp_generator: 0 }
    }

    /// Check if permissions allow the requested access
    ///
    /// # Arguments
    ///
    /// * `permissions` - Page permissions
    /// * `access_type` - Requested access type
    ///
    /// # Returns
    ///
    /// `true` if access is allowed, `false` otherwise
    #[must_use]
    pub const fn check_permission(permissions: PagePermissions, access_type: AccessType) -> bool {
        match access_type {
            AccessType::None => true, // No access requested always succeeds
            AccessType::Read => permissions.read(),
            AccessType::Write => permissions.write(),
            AccessType::Execute => permissions.execute(),
            AccessType::ReadWrite => permissions.read() && permissions.write(),
            AccessType::ReadExecute => permissions.read() && permissions.execute(),
            AccessType::WriteExecute => permissions.write() && permissions.execute(),
            AccessType::ReadWriteExecute => permissions.read() && permissions.write() && permissions.execute(),
            // Bug-4 fix: privileged variants — privilege bit does not affect R/W/X permission check.
            AccessType::ReadPrivileged => permissions.read(),
            AccessType::WritePrivileged => permissions.write(),
            AccessType::ReadWritePrivileged => permissions.read() && permissions.write(),
            AccessType::ExecutePrivileged => permissions.execute(),
            // BUG-RUST-5 fix: compound-execute privileged variants.
            AccessType::ReadExecutePrivileged => permissions.read() && permissions.execute(),
            AccessType::WriteExecutePrivileged => permissions.write() && permissions.execute(),
            AccessType::ReadWriteExecutePrivileged => permissions.read() && permissions.write() && permissions.execute(),
        }
    }

    /// Detect a permission fault with full context
    ///
    /// # Arguments
    ///
    /// * `stream_id` - Source stream identifier
    /// * `pasid` - Process Address Space ID
    /// * `iova` - Faulting virtual address
    /// * `access_type` - Type of access that was denied
    /// * `security_state` - Security state context
    /// * `permissions` - Page permissions that caused the violation
    /// * `fault_level` - Translation table level (0-3)
    ///
    /// # Returns
    ///
    /// FaultRecord containing complete permission fault information
    #[must_use]
    pub fn detect_permission_fault(
        &mut self,
        stream_id: StreamID,
        pasid: PASID,
        iova: IOVA,
        access_type: AccessType,
        security_state: SecurityState,
        _permissions: PagePermissions,
        fault_level: u8,
    ) -> FaultRecord {
        // Generate ARM SMMU v3 fault syndrome for permission fault
        let syndrome = FaultSyndrome::builder()
            .syndrome_register(0x0400_0000 | (u32::from(fault_level) << 16))
            .fault_level(fault_level)
            .write_not_read(access_type == AccessType::Write)
            .valid_syndrome(true)
            .build();

        self.timestamp_generator += 1;

        FaultRecord::builder()
            .stream_id(stream_id)
            .pasid(pasid)
            .address(iova)
            .fault_type(FaultType::PermissionFault)
            .access_type(access_type)
            .security_state(security_state)
            .syndrome(syndrome)
            .timestamp(self.timestamp_generator)
            .build()
    }

    /// Validate access permissions and return fault if denied
    ///
    /// # Arguments
    ///
    /// * `stream_id` - Source stream identifier
    /// * `pasid` - Process Address Space ID
    /// * `iova` - Virtual address being accessed
    /// * `access_type` - Requested access type
    /// * `permissions` - Page permissions
    /// * `security_state` - Security state context
    /// * `fault_level` - Translation table level (0-3)
    ///
    /// # Returns
    ///
    /// `Ok(())` if access is permitted, `Err(FaultRecord)` otherwise
    pub fn validate_permissions(
        &mut self,
        stream_id: StreamID,
        pasid: PASID,
        iova: IOVA,
        access_type: AccessType,
        permissions: PagePermissions,
        security_state: SecurityState,
        fault_level: u8,
    ) -> FaultDetectionResult {
        if Self::check_permission(permissions, access_type) {
            Ok(())
        } else {
            Err(self.detect_permission_fault(
                stream_id,
                pasid,
                iova,
                access_type,
                security_state,
                permissions,
                fault_level,
            ))
        }
    }
}

impl Default for PermissionFaultDetector {
    fn default() -> Self {
        Self::new()
    }
}

/// Address validator
///
/// Validates address ranges and detects address-related faults.
#[derive(Debug, Clone)]
pub struct AddressValidator {
    input_address_size: AddressSize,
    output_address_size: AddressSize,
    timestamp_generator: u64,
}

impl AddressValidator {
    /// Create a new address validator
    ///
    /// # Arguments
    ///
    /// * `input_size` - Input address size configuration (IOVA/IPA)
    /// * `output_size` - Output address size configuration (PA)
    #[must_use]
    pub const fn new(input_size: AddressSize, output_size: AddressSize) -> Self {
        Self {
            input_address_size: input_size,
            output_address_size: output_size,
            timestamp_generator: 0,
        }
    }

    /// Validate input address size
    ///
    /// # Arguments
    ///
    /// * `stream_id` - Source stream identifier
    /// * `pasid` - Process Address Space ID
    /// * `iova` - Virtual address to validate
    /// * `access_type` - Access type
    /// * `security_state` - Security state context
    ///
    /// # Returns
    ///
    /// `Ok(())` if address is valid, `Err(FaultRecord)` otherwise
    pub fn validate_input_address(
        &mut self,
        stream_id: StreamID,
        pasid: PASID,
        iova: IOVA,
        access_type: AccessType,
        security_state: SecurityState,
    ) -> FaultDetectionResult {
        if self.input_address_size.exceeds(iova.as_u64()) {
            self.timestamp_generator += 1;

            let syndrome = FaultSyndrome::builder()
                .syndrome_register(0x0200_0000)
                .fault_level(0)
                .write_not_read(access_type == AccessType::Write)
                .valid_syndrome(true)
                .build();

            Err(FaultRecord::builder()
                .stream_id(stream_id)
                .pasid(pasid)
                .address(iova)
                .fault_type(FaultType::AddressSizeFault)
                .access_type(access_type)
                .security_state(security_state)
                .syndrome(syndrome)
                .timestamp(self.timestamp_generator)
                .build())
        } else {
            Ok(())
        }
    }

    /// Validate output address size
    ///
    /// # Arguments
    ///
    /// * `stream_id` - Source stream identifier
    /// * `pasid` - Process Address Space ID
    /// * `iova` - Original virtual address (for fault reporting)
    /// * `pa` - Physical address to validate
    /// * `access_type` - Access type
    /// * `security_state` - Security state context
    ///
    /// # Returns
    ///
    /// `Ok(())` if address is valid, `Err(FaultRecord)` otherwise
    pub fn validate_output_address(
        &mut self,
        stream_id: StreamID,
        pasid: PASID,
        iova: IOVA,
        pa: PA,
        access_type: AccessType,
        security_state: SecurityState,
    ) -> FaultDetectionResult {
        if self.output_address_size.exceeds(pa.as_u64()) {
            self.timestamp_generator += 1;

            let syndrome = FaultSyndrome::builder()
                .syndrome_register(0x0900_0000)
                .fault_level(3)
                .write_not_read(access_type == AccessType::Write)
                .valid_syndrome(true)
                .build();

            Err(FaultRecord::builder()
                .stream_id(stream_id)
                .pasid(pasid)
                .address(iova)
                .fault_type(FaultType::OutputAddressRangeFault)
                .access_type(access_type)
                .security_state(security_state)
                .syndrome(syndrome)
                .timestamp(self.timestamp_generator)
                .build())
        } else {
            Ok(())
        }
    }

    /// Validate address alignment
    ///
    /// # Arguments
    ///
    /// * `stream_id` - Source stream identifier
    /// * `pasid` - Process Address Space ID
    /// * `iova` - Virtual address to validate
    /// * `access_type` - Access type
    /// * `security_state` - Security state context
    /// * `required_alignment` - Required alignment in bytes
    ///
    /// # Returns
    ///
    /// `Ok(())` if address is properly aligned, `Err(FaultRecord)` otherwise
    pub fn validate_alignment(
        &mut self,
        stream_id: StreamID,
        pasid: PASID,
        iova: IOVA,
        access_type: AccessType,
        security_state: SecurityState,
        required_alignment: u64,
    ) -> FaultDetectionResult {
        if iova.as_u64() & (required_alignment - 1) != 0 {
            self.timestamp_generator += 1;

            let syndrome = FaultSyndrome::builder()
                .syndrome_register(0x0800_0000)
                .fault_level(0)
                .write_not_read(access_type == AccessType::Write)
                .valid_syndrome(true)
                .build();

            Err(FaultRecord::builder()
                .stream_id(stream_id)
                .pasid(pasid)
                .address(iova)
                .fault_type(FaultType::AlignmentFault)
                .access_type(access_type)
                .security_state(security_state)
                .syndrome(syndrome)
                .timestamp(self.timestamp_generator)
                .build())
        } else {
            Ok(())
        }
    }

    /// Get the configured input address size
    #[must_use]
    pub const fn input_address_size(&self) -> AddressSize {
        self.input_address_size
    }

    /// Get the configured output address size
    #[must_use]
    pub const fn output_address_size(&self) -> AddressSize {
        self.output_address_size
    }
}

impl Default for AddressValidator {
    fn default() -> Self {
        Self::new(AddressSize::Bits48, AddressSize::Bits48)
    }
}

/// Comprehensive fault detector
///
/// Combines all fault detection capabilities into a single interface.
#[derive(Debug, Clone)]
pub struct FaultDetector {
    translation_detector: TranslationFaultDetector,
    permission_detector: PermissionFaultDetector,
    address_validator: AddressValidator,
}

impl FaultDetector {
    /// Create a new fault detector with default configuration (48-bit addresses)
    #[must_use]
    pub fn new() -> Self {
        Self {
            translation_detector: TranslationFaultDetector::new(),
            permission_detector: PermissionFaultDetector::new(),
            address_validator: AddressValidator::new(AddressSize::Bits48, AddressSize::Bits48),
        }
    }

    /// Create a new fault detector with custom address sizes
    #[must_use]
    pub fn with_address_sizes(input_size: AddressSize, output_size: AddressSize) -> Self {
        Self {
            translation_detector: TranslationFaultDetector::new(),
            permission_detector: PermissionFaultDetector::new(),
            address_validator: AddressValidator::new(input_size, output_size),
        }
    }

    /// Get the translation fault detector
    #[must_use]
    pub fn translation_detector(&mut self) -> &mut TranslationFaultDetector {
        &mut self.translation_detector
    }

    /// Get the permission fault detector
    #[must_use]
    pub fn permission_detector(&mut self) -> &mut PermissionFaultDetector {
        &mut self.permission_detector
    }

    /// Get the address validator
    #[must_use]
    pub fn address_validator(&mut self) -> &mut AddressValidator {
        &mut self.address_validator
    }
}

impl Default for FaultDetector {
    fn default() -> Self {
        Self::new()
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn test_stream_id(value: u32) -> StreamID {
        StreamID::new(value).unwrap()
    }

    fn test_pasid(value: u32) -> PASID {
        PASID::new(value).unwrap()
    }

    fn test_iova(value: u64) -> IOVA {
        IOVA::new(value).unwrap()
    }

    fn test_pa(value: u64) -> PA {
        PA::new(value).unwrap()
    }

    #[test]
    fn test_address_size_max_values() {
        assert_eq!(AddressSize::Bits32.max_address(), 0xFFFF_FFFF);
        assert_eq!(AddressSize::Bits48.max_address(), 0x0000_FFFF_FFFF_FFFF);
        assert_eq!(AddressSize::Bits52.max_address(), 0x000F_FFFF_FFFF_FFFF);
    }

    #[test]
    fn test_address_size_exceeds() {
        assert!(AddressSize::Bits32.exceeds(0x1_0000_0000));
        assert!(!AddressSize::Bits32.exceeds(0xFFFF_FFFF));

        assert!(AddressSize::Bits48.exceeds(0x0001_0000_0000_0000));
        assert!(!AddressSize::Bits48.exceeds(0x0000_FFFF_FFFF_FFFF));
    }

    #[test]
    fn test_translation_fault_detection() {
        let mut detector = TranslationFaultDetector::new();

        let fault = detector.detect_translation_fault(
            test_stream_id(42),
            test_pasid(7),
            test_iova(0x1000),
            AccessType::Read,
            SecurityState::NonSecure,
            2,
        );

        assert_eq!(fault.fault_type(), FaultType::TranslationFault);
        assert_eq!(fault.stream_id(), test_stream_id(42));
        assert_eq!(fault.pasid(), test_pasid(7));
        assert_eq!(fault.syndrome().fault_level(), 2);
    }

    #[test]
    fn test_permission_checking() {
        let perms = PagePermissions::new(true, false, false);

        assert!(PermissionFaultDetector::check_permission(perms, AccessType::Read));
        assert!(!PermissionFaultDetector::check_permission(perms, AccessType::Write));
        assert!(!PermissionFaultDetector::check_permission(perms, AccessType::Execute));
    }

    #[test]
    fn test_permission_fault_detection() {
        let mut detector = PermissionFaultDetector::new();
        let perms = PagePermissions::new(true, false, false);

        let fault = detector.detect_permission_fault(
            test_stream_id(100),
            test_pasid(5),
            test_iova(0x2000),
            AccessType::Write,
            SecurityState::NonSecure,
            perms,
            3,
        );

        assert_eq!(fault.fault_type(), FaultType::PermissionFault);
        assert_eq!(fault.access_type(), AccessType::Write);
    }

    #[test]
    fn test_address_validation_input() {
        let mut validator = AddressValidator::new(AddressSize::Bits32, AddressSize::Bits48);

        // Valid 32-bit address
        assert!(validator
            .validate_input_address(
                test_stream_id(1),
                test_pasid(0),
                test_iova(0xFFFF_FFFF),
                AccessType::Read,
                SecurityState::NonSecure,
            )
            .is_ok());

        // Invalid - exceeds 32-bit
        let result = validator.validate_input_address(
            test_stream_id(1),
            test_pasid(0),
            test_iova(0x1_0000_0000),
            AccessType::Read,
            SecurityState::NonSecure,
        );

        assert!(result.is_err());
        let fault = result.unwrap_err();
        assert_eq!(fault.fault_type(), FaultType::AddressSizeFault);
    }

    #[test]
    fn test_address_validation_output() {
        let mut validator = AddressValidator::new(AddressSize::Bits48, AddressSize::Bits32);

        // Invalid - PA exceeds 32-bit
        let result = validator.validate_output_address(
            test_stream_id(1),
            test_pasid(0),
            test_iova(0x1000),
            test_pa(0x1_0000_0000),
            AccessType::Read,
            SecurityState::NonSecure,
        );

        assert!(result.is_err());
        let fault = result.unwrap_err();
        assert_eq!(fault.fault_type(), FaultType::OutputAddressRangeFault);
    }

    #[test]
    fn test_alignment_validation() {
        let mut validator = AddressValidator::default();

        // Aligned to 4KB
        assert!(validator
            .validate_alignment(
                test_stream_id(1),
                test_pasid(0),
                test_iova(0x1000),
                AccessType::Read,
                SecurityState::NonSecure,
                0x1000,
            )
            .is_ok());

        // Not aligned to 4KB
        let result = validator.validate_alignment(
            test_stream_id(1),
            test_pasid(0),
            test_iova(0x1001),
            AccessType::Read,
            SecurityState::NonSecure,
            0x1000,
        );

        assert!(result.is_err());
        let fault = result.unwrap_err();
        assert_eq!(fault.fault_type(), FaultType::AlignmentFault);
    }

    #[test]
    fn test_comprehensive_detector() {
        let mut detector = FaultDetector::new();

        // Test translation detector access
        let fault = detector.translation_detector().detect_translation_fault(
            test_stream_id(1),
            test_pasid(0),
            test_iova(0x1000),
            AccessType::Read,
            SecurityState::NonSecure,
            0,
        );
        assert_eq!(fault.fault_type(), FaultType::TranslationFault);

        // Test permission detector access
        let perms = PagePermissions::new(false, false, false);
        let result = detector.permission_detector().validate_permissions(
            test_stream_id(1),
            test_pasid(0),
            test_iova(0x2000),
            AccessType::Read,
            perms,
            SecurityState::NonSecure,
            0,
        );
        assert!(result.is_err());

        // Test address validator access
        let result = detector.address_validator().validate_alignment(
            test_stream_id(1),
            test_pasid(0),
            test_iova(0x1001),
            AccessType::Read,
            SecurityState::NonSecure,
            0x1000,
        );
        assert!(result.is_err());
    }
}