amv-diffusion 2.1.0__py3-none-any.whl

termux_diffusion/hardware.py

@@ -0,0 +1,985 @@
+# Copyright (c) 2026 Uno Kim / AMEVA Foundation. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0 OR Commercial-License
+"""Hardware acceleration detection, Vulkan/OpenCL/NPU/TPU probing, and CMake flag generation.
+
+This module probes the Android device for available GPU, NPU, TPU, and CPU compute backends
+by checking for the actual existence of system driver libraries on disk.
+"""
+
+import ctypes
+import logging
+import os
+import platform
+import re
+import shutil
+import subprocess
+import sys
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple, Any
+
+from .exceptions import PlatformNotSupportedError, RuntimeRequiredError
+from .npu import NPUProfile, NPUVendor, detect_npu_capabilities, get_optimal_heterogeneous_pipeline
+
+logger = logging.getLogger("termux_diffusion.hardware")
+
+
+class ComputeBackend(Enum):
+    """Available hardware compute backends, ordered by expected throughput."""
+    CPU_NEON = "cpu"
+    OPENCL = "opencl"
+    VULKAN = "vulkan"
+    NPU = "npu"
+    TPU = "tpu"
+
+
+@dataclass
+class GPUDriverInfo:
+    """Detected GPU driver metadata from the device."""
+    name: str = "Unknown"
+    vendor: str = "Unknown"
+    api: str = "Unknown"
+    library_path: str = ""
+    version: str = ""
+    usable: bool = False
+
+
+@dataclass
+class HardwareProfile:
+    """Complete hardware capability profile for the current device."""
+    cpu_arch: str = ""
+    cpu_cores: int = 0
+    cpu_features: List[str] = field(default_factory=list)
+    has_dotprod: bool = False
+    has_fp16: bool = False
+    has_i8mm: bool = False
+    has_sve: bool = False
+    vulkan_available: bool = False
+    vulkan_driver: Optional[GPUDriverInfo] = None
+    opencl_available: bool = False
+    opencl_driver: Optional[GPUDriverInfo] = None
+    npu_profile: Optional[NPUProfile] = None
+    soc_name: str = "Unknown"
+    gpu_name: str = "Unknown"
+    recommended_backend: ComputeBackend = ComputeBackend.CPU_NEON
+    recommended_ngl: int = 0
+    cmake_extra_flags: List[str] = field(default_factory=list)
+
+    @property
+    def soc_model(self) -> str:
+        return self.soc_name
+
+    @property
+    def cpu_count(self) -> int:
+        return self.cpu_cores
+
+    @property
+    def recommended_threads(self) -> int:
+        return max(1, self.cpu_cores // 2) if self.cpu_cores > 2 else self.cpu_cores
+
+    @property
+    def threads(self) -> int:
+        return self.recommended_threads
+
+
+# ------------------------------------------------------------------------------
+# 1. CPU & GPU Feature Detection
+# ------------------------------------------------------------------------------
+
+# [중요] Vulkan ICD 탐색 순서: Android Bionic ICD 최우선.
+# Termux Mesa($PREFIX/lib/libvulkan.so)를 시스템 ICD보다 먼저 로드하면
+# Bionic linker 이중 dispatch 테이블 충돌로 SIGABRT 가 발생합니다.
+# ameva-runtime 의 ICD 탐색 정책과 동일하게 유지합니다.
+_VULKAN_LIB_SEARCH_PATHS = [
+    "/system/lib64/libvulkan.so",   # Android Bionic ICD (최우선 — A35/S25/S21 모두 존재)
+    "/system/lib/libvulkan.so",
+    "/vendor/lib64/libvulkan.so",
+    "/vendor/lib/libvulkan.so",
+    # Termux Mesa: 시스템 ICD 가 없는 순수 Linux/PRoot 환경 전용 fallback
+    os.path.join(os.environ.get("PREFIX", "/data/data/com.termux/files/usr"), "lib64", "libvulkan.so"),
+    os.path.join(os.environ.get("PREFIX", "/data/data/com.termux/files/usr"), "lib", "libvulkan.so"),
+]
+
+_OPENCL_LIB_SEARCH_PATHS = [
+    "/vendor/lib64/libOpenCL.so",
+    "/system/lib64/libOpenCL.so",
+    "/system/vendor/lib64/libOpenCL.so",
+    "/vendor/lib/libOpenCL.so",
+    "/system/lib/libOpenCL.so",
+    "/vendor/lib64/egl/libGLES_mali.so",
+    "/system/vendor/lib64/egl/libGLES_mali.so",
+]
+
+
+def _find_vulkan_driver_path() -> Optional[str]:
+    """Find the first genuinely accessible Vulkan driver library on the filesystem."""
+    for p in _VULKAN_LIB_SEARCH_PATHS:
+        p_obj = Path(p)
+        try:
+            if p_obj.is_file() and p_obj.stat().st_size >= 1024:
+                return str(p_obj.resolve())
+        except (OSError, PermissionError):
+            continue
+    return None
+
+
+def _read_cpuinfo_features() -> List[str]:
+    """Parse /proc/cpuinfo to extract ARM CPU feature flags."""
+    cpuinfo_path = Path("/proc/cpuinfo")
+    if not cpuinfo_path.exists():
+        return []
+
+    try:
+        text = cpuinfo_path.read_text(encoding="utf-8", errors="ignore")
+        for line in text.splitlines():
+            if line.lower().startswith("features"):
+                parts = line.split(":", 1)
+                if len(parts) == 2:
+                    return parts[1].strip().split()
+        return []
+    except Exception as e:
+        logger.debug("Could not read /proc/cpuinfo: %s", e)
+        return []
+
+
+from .platform import is_android_termux
+
+
+def _detect_soc_name() -> str:
+    """Identify the SoC model from Android system properties."""
+    if not is_android_termux():
+        return "Unknown"
+    prop_keys = [
+        "ro.soc.model",
+        "ro.chipname",
+        "ro.hardware.chipname",
+        "ro.board.platform",
+        "ro.hardware",
+        "ro.product.board",
+    ]
+    for key in prop_keys:
+        try:
+            result = subprocess.run(
+                ["getprop", key],
+                capture_output=True,
+                text=True,
+                timeout=2.0,
+            )
+            val = result.stdout.strip()
+            if val and val != "unknown":
+                return val
+        except (FileNotFoundError, subprocess.TimeoutExpired, OSError):
+            continue
+    return "Unknown"
+
+
+def _detect_device_model() -> str:
+    """Identify Android device model for hardware profile matching."""
+    if not is_android_termux():
+        return "Unknown"
+    for prop in ["ro.product.model", "ro.product.device", "ro.build.product"]:
+        try:
+            result = subprocess.run(
+                ["getprop", prop],
+                capture_output=True,
+                text=True,
+                timeout=2.0,
+            )
+            val = result.stdout.strip()
+            if val and val != "unknown":
+                return val
+        except Exception:
+            continue
+    return "Unknown"
+
+
+def _detect_gpu_name() -> str:
+    """Identify the GPU model from Android properties and hardware nodes."""
+    if not is_android_termux():
+        return "Unknown"
+    # 1. Check Adreno kgsl sysfs node
+    kgsl_model = Path("/sys/class/kgsl/kgsl-3d0/gpu_model")
+    if kgsl_model.exists():
+        try:
+            val = kgsl_model.read_text(encoding="utf-8").strip()
+            if val:
+                return f"Adreno ({val})"
+        except PermissionError as _perm_err:
+            logger.warning("[hardware] kgsl gpu_model read PermissionError: %s", _perm_err)
+        except OSError as _os_err:
+            logger.warning("[hardware] kgsl gpu_model read OSError: %s", _os_err)
+        # 예상 밖 예외는 재발생
+
+    # 2. Check Android system properties
+    for prop in ["ro.hardware.vulkan", "ro.hardware.egl", "ro.board.platform"]:
+        try:
+            result = subprocess.run(
+                ["getprop", prop],
+                capture_output=True,
+                text=True,
+                timeout=2.0,
+            )
+            val = result.stdout.strip()
+            if val and val != "unknown":
+                if "adreno" in val.lower():
+                    return f"Qualcomm Adreno ({val})"
+                if "mali" in val.lower():
+                    return f"ARM Mali ({val})"
+                return val.capitalize()
+        except (FileNotFoundError, subprocess.TimeoutExpired, OSError):
+            continue
+    return "Unknown"
+
+
+
+
+def _probe_vulkan_driver() -> Optional[GPUDriverInfo]:
+    """Probe for a usable Vulkan driver via ameva-runtime SSOT."""
+    try:
+        from ameva_runtime import vulkan as avr
+        report = avr.Doctor().run_self_test(verbose=False)
+        if report.overall_success or report.recommended_backend in ("vulkan", "vulkan_driver_only") or getattr(report, "passed_stages", 0) >= 7:
+            return GPUDriverInfo(
+                name=f"Vulkan Driver ({report.device_name})",
+                vendor=report.device_name,
+                api=f"Vulkan {getattr(report, 'driver_version', '1.3')}",
+                library_path=getattr(report, "loader_path", "") or _find_vulkan_driver_path() or "/system/lib64/libvulkan.so",
+                version=getattr(report, "driver_version", ""),
+                usable=True,
+            )
+    except Exception as e:
+        logger.debug("[termux-diffusion] ameva-runtime probe exception: %s", e)
+
+    # 안전 폴백: 시스템 기본 Bionic 경로 검사
+    detected_path = _find_vulkan_driver_path()
+    if detected_path and Path(detected_path).is_file():
+        gpu_name = _detect_gpu_name()
+        return GPUDriverInfo(
+            name=f"Vulkan Driver ({gpu_name})",
+            vendor=gpu_name,
+            api="Vulkan",
+            library_path=detected_path,
+            version="",
+            usable=True,
+        )
+    return None
+
+
+def _probe_opencl_driver() -> Optional[GPUDriverInfo]:
+    """Probe for a usable OpenCL driver by checking library paths."""
+    for lib_path in _OPENCL_LIB_SEARCH_PATHS:
+        p = Path(lib_path)
+        if p.is_file():
+            try:
+                size = p.stat().st_size
+                if size < 1024:
+                    continue
+                gpu_name = _detect_gpu_name()
+                return GPUDriverInfo(
+                    name=f"OpenCL Driver ({gpu_name})",
+                    vendor=gpu_name,
+                    api="OpenCL",
+                    library_path=lib_path,
+                    version="",
+                    usable=True,
+                )
+            except PermissionError as pe:
+                logger.warning(
+                    "OpenCL driver found at '%s' but access was denied (SELinux permission): %s",
+                    lib_path,
+                    pe,
+                )
+                continue
+            except OSError as oe:
+                logger.debug("OpenCL driver stat note on '%s': %s", lib_path, oe)
+                continue
+    return None
+
+
+# ------------------------------------------------------------------------------
+# 2. Main Hardware Profiler
+# ------------------------------------------------------------------------------
+
+def detect_hardware_profile() -> HardwareProfile:
+    """Run comprehensive hardware detection across CPU, GPU, NPU, and TPU."""
+    profile = HardwareProfile()
+    
+    # CPU Architecture
+    profile.cpu_arch = platform.machine().lower()
+    profile.cpu_cores = os.cpu_count() or 1
+    
+    # ARM CPU ISA Features
+    features = _read_cpuinfo_features()
+    profile.cpu_features = features
+    profile.has_dotprod = "asimddp" in features
+    profile.has_fp16 = "fphp" in features or "asimdhp" in features
+    profile.has_i8mm = "i8mm" in features
+    profile.has_sve = "sve" in features or "sve2" in features
+    
+    # SoC and GPU identification
+    profile.soc_name = _detect_soc_name()
+    profile.gpu_name = _detect_gpu_name()
+    
+    # Vulkan & OpenCL driver probe
+    vulkan_info = _probe_vulkan_driver()
+    if vulkan_info and vulkan_info.usable:
+        profile.vulkan_available = True
+        profile.vulkan_driver = vulkan_info
+    
+    opencl_info = _probe_opencl_driver()
+    if opencl_info and opencl_info.usable:
+        profile.opencl_available = True
+        profile.opencl_driver = opencl_info
+
+    # NPU / TPU driver probe
+    npu_info = detect_npu_capabilities()
+    profile.npu_profile = npu_info
+    
+    # Recommend optimal backend: Vulkan > OpenCL > CPU NEON
+    if profile.vulkan_available:
+        # Check Qualcomm Adreno 600 series lacking VK_KHR_8bit_storage (e.g. Snapdragon 865 / SM8250 / Adreno 650)
+        is_adreno_650 = (
+            "650" in str(profile.gpu_name).lower()
+            or "sm8250" in str(profile.soc_name).lower()
+            or "kona" in str(profile.soc_name).lower()
+            or "snapdragon 865" in str(profile.soc_name).lower()
+        )
+        # Check integer dot product capability on ARM Mali GPUs (e.g. Exynos 1280 / Mali-G68 lacking VK_KHR_shader_integer_dot_product)
+        is_mali = (
+            "mali" in str(profile.gpu_name).lower()
+            or "s5e8825" in str(profile.soc_name).lower()
+            or "exynos 1280" in str(profile.soc_name).lower()
+        )
+        if is_adreno_650:
+            if profile.opencl_available:
+                profile.recommended_backend = ComputeBackend.OPENCL
+                profile.recommended_ngl = 32
+            else:
+                profile.recommended_backend = ComputeBackend.CPU_NEON
+                profile.recommended_ngl = 0
+        elif is_mali and not profile.has_dotprod:
+            # Under auto mode, Mali without int_dot routes to CPU NEON to avoid descriptor pool exhaustion / shader faults
+            profile.recommended_backend = ComputeBackend.CPU_NEON
+            profile.recommended_ngl = 0
+        else:
+            profile.recommended_backend = ComputeBackend.VULKAN
+            profile.recommended_ngl = 99
+    elif profile.opencl_available:
+        profile.recommended_backend = ComputeBackend.OPENCL
+        profile.recommended_ngl = 32
+    else:
+        profile.recommended_backend = ComputeBackend.CPU_NEON
+        profile.recommended_ngl = 0
+    
+    # Generate CMake flags
+    profile.cmake_extra_flags = _build_cmake_flags(profile)
+    
+    return profile
+
+
+def _build_cmake_flags(profile: HardwareProfile, backend: Optional[str] = None) -> List[str]:
+    """Generate optimal CMake flags for ARM64 Android Bionic."""
+    flags = []
+    prefix = os.environ.get("PREFIX", "/data/data/com.termux/files/usr")
+    
+    target_backend = backend.lower().strip() if backend else "auto"
+    
+    if target_backend == "cpu":
+        flags.append("-DSD_VULKAN=OFF")
+        flags.append("-DSD_OPENCL=OFF")
+    elif (target_backend in ("auto", "vulkan")) and profile.vulkan_available and profile.vulkan_driver:
+        flags.append("-DSD_VULKAN=ON")
+        flags.append(f"-DVulkan_LIBRARY={profile.vulkan_driver.library_path}")
+        flags.append(f"-DVulkan_INCLUDE_DIR={prefix}/include")
+        flags.append("-DGGML_VULKAN_COOPMAT_GLSLC_SUPPORT=OFF")
+        flags.append("-DGGML_VULKAN_COOPMAT2_GLSLC_SUPPORT=OFF")
+        flags.append("-DGGML_VULKAN_COOPMAT2_DECODE_VECTOR_GLSLC_SUPPORT=OFF")
+        flags.append("-DGGML_VULKAN_BFLOAT16_GLSLC_SUPPORT=OFF")
+        flags.append("-DCMAKE_EXE_LINKER_FLAGS=-L/system/lib64 -Wl,-rpath,/system/lib64 -L/vendor/lib64 -Wl,-rpath,/vendor/lib64")
+    elif (target_backend in ("auto", "opencl")) and profile.opencl_available and profile.opencl_driver:
+        flags.append("-DSD_OPENCL=ON")
+        flags.append(f"-DOpenCL_LIBRARY={profile.opencl_driver.library_path}")
+        flags.append(f"-DOpenCL_INCLUDE_DIR={prefix}/include")
+        flags.append("-DCMAKE_EXE_LINKER_FLAGS=-L/vendor/lib64 -Wl,-rpath,/vendor/lib64 -L/system/lib64 -Wl,-rpath,/system/lib64")
+    else:
+        flags.append("-DSD_VULKAN=OFF")
+        flags.append("-DSD_OPENCL=OFF")
+    
+    # CPU ISA optimization flags
+    march_parts = ["armv8-a"]
+    if profile.cpu_arch in ("aarch64", "arm64"):
+        march_parts = ["armv8.2-a"]
+        if profile.has_dotprod:
+            march_parts.append("dotprod")
+        if profile.has_fp16:
+            march_parts.append("fp16")
+        if profile.has_i8mm:
+            march_parts.append("i8mm")
+    
+    if len(march_parts) > 1:
+        march_str = "+".join(march_parts)
+        flags.append(f"-DCMAKE_C_FLAGS=-O2 -march={march_str} -D_GNU_SOURCE")
+        flags.append(f"-DCMAKE_CXX_FLAGS=-O2 -march={march_str} -D_GNU_SOURCE -Wno-deprecated-literal-operator")
+    else:
+        flags.append("-DCMAKE_C_FLAGS=-O2 -D_GNU_SOURCE")
+        flags.append("-DCMAKE_CXX_FLAGS=-O2 -D_GNU_SOURCE -Wno-deprecated-literal-operator")
+    
+    return flags
+
+
+# ------------------------------------------------------------------------------
+# 3. Device Selection for generate()
+# ------------------------------------------------------------------------------
+
+def _resolve_ameva_runtime() -> Optional[Any]:
+    try:
+        import importlib.util
+        spec = importlib.util.find_spec("ameva_runtime")
+        if spec is not None:
+            import ameva_runtime
+            return ameva_runtime
+    except (ImportError, AttributeError):
+        pass
+    return None
+
+
+GPU_RUNTIME_MIN_VERSION = "2.0.0"
+
+
+def _require_gpu_runtime(requested_device: str) -> None:
+    """Stop with the shared AMU_ERR_RUNTIME_REQUIRED explanation unless ameva-runtime is usable.
+
+    Every GPU request (vulkan, gpu, opencl) goes through here. There is no CPU fallback: the
+    caller gets RuntimeRequiredError and the CLI exits with status 69.
+    """
+    try:
+        from ameva_device import AmevaRuntimeRequiredError, require_ameva_runtime
+    except ImportError as exc:
+        raise RuntimeRequiredError(
+            "[AMU_ERR_RUNTIME_REQUIRED] termux-diffusion: GPU execution (device='%s') needs ameva-runtime (AMUDA), "
+            "and the shared check library 'ameva-device-sdk' is missing from this installation.\n"
+            "Nothing was run, and no CPU fallback was used.\n"
+            "Install:\n"
+            "  pip install \"ameva-runtime>=%s\"\n"
+            "  npm install -g @ameva/runtime\n"
+            "  Releases and documentation: https://github.com/uno-km/ameva-runtime-releases\n"
+            "To run on the CPU instead, use --device cpu.\n" % (requested_device, GPU_RUNTIME_MIN_VERSION)
+        ) from exc
+    try:
+        require_ameva_runtime(
+            "termux-diffusion", "GPU execution (device='%s')" % requested_device,
+            min_version=GPU_RUNTIME_MIN_VERSION,
+        )
+    except AmevaRuntimeRequiredError as exc:
+        raise RuntimeRequiredError(str(exc)) from exc
+
+
+def resolve_device_backend(requested_device: str) -> Tuple[str, int]:
+    """Resolve the user's device= argument to an actual backend and ngl count.
+    
+    Zero-Silent-Fallback & Strict Option Rules:
+    - 'cpu': User explicitly requested CPU. 100% pure ARM NEON execution without touching GPU.
+    - 'vulkan' / 'gpu': Explicit GPU mode. Halts immediately with Fail-Fast if GPU driver missing.
+    - 'opencl': Explicit OpenCL mode. Halts immediately if OpenCL missing.
+    - 'auto': Evaluates hardware capabilities (int_dot on Mali, Vulkan driver).
+    """
+    req = requested_device.lower().strip()
+
+    # Rule 1: Strict CPU Priority - If user explicitly passed CPU, NEVER touch GPU or fail-fast probes
+    if req == "cpu":
+        return "cpu", 0
+
+    # Rule 2: every GPU request (vulkan, gpu, opencl) needs ameva-runtime (AMUDA). An explicit
+    # request stops here with the shared install guidance; there is no CPU fallback.
+    if req in ("vulkan", "gpu", "opencl", "cl"):
+        _require_gpu_runtime(req)
+
+    ameva_mod = _resolve_ameva_runtime()
+
+    if req == "auto":
+        if ameva_mod is None:
+            sys.stderr.write(
+                "[termux-diffusion] GPU not used: ameva-runtime (AMUDA) is not installed, so this run uses the CPU. "
+                "To enable the GPU: pip install ameva-runtime (https://github.com/uno-km/ameva-runtime-releases)\n"
+            )
+            sys.stderr.flush()
+            return "cpu", 0
+
+    profile = detect_hardware_profile()
+    
+    if req == "auto":
+        backend = profile.recommended_backend
+        ngl = profile.recommended_ngl
+        logger.info(
+            "Auto-detected optimal backend: %s (SoC: %s, GPU: %s)",
+            backend.value, profile.soc_name, profile.gpu_name
+        )
+        return backend.value, ngl
+    
+    if req in ("npu", "tpu"):
+        npu_desc = (
+            f"{profile.npu_profile.chipset_name} / {profile.npu_profile.dsp_architecture}"
+            if (profile.npu_profile and profile.npu_profile.available)
+            else "Hardware not detected"
+        )
+        raise PlatformNotSupportedError(
+            f"Native NPU/TPU acceleration ({npu_desc}) requires Qualcomm QNN / LiteRT C++ Graph Runtime (scheduled for v2.0 roadmap). "
+            f"Currently, full hardware acceleration is supported via Vulkan GPU (device='vulkan') and ARM NEON (device='cpu'). "
+            f"Please use device='vulkan' or device='auto'."
+        )
+
+    if req in ("vulkan", "gpu"):
+        if profile.vulkan_available:
+            return "vulkan", 99
+        raise PlatformNotSupportedError(
+            "[ERROR: AMEVA-DIFFUSION-E003] Vulkan GPU acceleration was explicitly requested (device='vulkan' / 'gpu'), "
+            "but no accessible Vulkan driver (.so) was found on this system. "
+            "Execution halted strictly without silent fallback to prevent unexpected CPU execution."
+        )
+    
+    if req == "opencl":
+        if profile.opencl_available:
+            return "opencl", 32
+        raise PlatformNotSupportedError(
+            "OpenCL acceleration was explicitly requested (device='opencl'), "
+            "but no accessible OpenCL driver (.so) was found on this system. "
+            "Execution halted strictly without silent fallback to prevent unexpected CPU execution."
+        )
+
+    raise ValueError(f"Unknown computing device '{requested_device}'. Supported: 'auto', 'cpu', 'vulkan', 'opencl'.")
+
+
+def get_sd_cli_gpu_args(device: str, ngl: int) -> List[str]:
+    """Build the sd-cli command-line arguments for GPU/NPU offloading."""
+    args: List[str] = []
+    if device == "cpu":
+        args.append("--offload-to-cpu")
+    return args
+
+
+def format_hardware_report(profile: HardwareProfile) -> str:
+    """Format a human-readable hardware capability report for doctor/diagnostics."""
+    lines = [
+        "=== Hardware Acceleration Profile ===",
+        f"SoC: {profile.soc_name}",
+        f"GPU Architecture: {profile.gpu_name}",
+        f"CPU Architecture: {profile.cpu_arch} ({profile.cpu_cores} cores)",
+        f"ARM SIMD Extensions: DotProd={'[OK]' if profile.has_dotprod else '[FAIL]'} "
+        f"FP16={'[OK]' if profile.has_fp16 else '[FAIL]'} "
+        f"I8MM={'[OK]' if profile.has_i8mm else '[FAIL]'} "
+        f"SVE={'[OK]' if profile.has_sve else '[FAIL]'}",
+        f"GPU Vulkan: {'Available [OK]' if profile.vulkan_available else 'Not Found [WARN]'}",
+    ]
+    if profile.vulkan_driver:
+        lines.append(f"  -> Vulkan Lib: {profile.vulkan_driver.library_path}")
+    lines.append(f"GPU OpenCL: {'Available [OK]' if profile.opencl_available else 'Not Found [WARN]'}")
+    if profile.opencl_driver:
+        lines.append(f"  -> OpenCL Lib: {profile.opencl_driver.library_path}")
+    
+    if profile.npu_profile and profile.npu_profile.available:
+        lines.append(f"NPU / TPU Hardware: Detected [INFO] ({profile.npu_profile.dsp_architecture})")
+        lines.append(f"  -> Peak Hardware Spec: {profile.npu_profile.tops_rating} TOPS")
+        lines.append(f"  -> Driver Library: {profile.npu_profile.driver_library}")
+        lines.append(f"  -> Runtime Status: Native QNN C++ execution scheduled for v2.0 (Active: Vulkan GPU & ARM NEON)")
+    else:
+        lines.append("NPU / TPU Hardware: Not Detected (CPU/GPU pipeline active)")
+        
+    lines.append(f"Recommended Compute Backend: {profile.recommended_backend.value}")
+    lines.append(f"Recommended GPU/NPU Offload Layers: {profile.recommended_ngl}")
+    if profile.cmake_extra_flags:
+        lines.append(f"CMake Build Flags: {' '.join(profile.cmake_extra_flags)}")
+    lines.append("=" * 40)
+    return "\n".join(lines)
+
+
+# ------------------------------------------------------------------------------
+# 4. Profile Gating Manager (Runtime Model/Preset Safety)
+# ------------------------------------------------------------------------------
+
+import json
+
+@dataclass
+class ProfileGatingManager:
+    """Manages runtime matching against validated-vulkan-profiles.json for safe device/model execution."""
+    profiles: List[Dict] = field(default_factory=list)
+
+    @classmethod
+    def load_from_json(cls, json_path: Optional[Path] = None) -> "ProfileGatingManager":
+        if json_path is None:
+            json_path = Path(__file__).parent / "data" / "validated-vulkan-profiles.json"
+        if json_path.is_file():
+            try:
+                data = json.loads(json_path.read_text(encoding="utf-8"))
+                return cls(profiles=data.get("profiles", []))
+            except Exception as e:
+                logger.warning("Failed to load validated-vulkan-profiles.json: %s", e)
+        return cls(profiles=[])
+
+    def find_matching_profile(self, model_name: str, soc_name: str = "", gpu_name: str = "") -> Optional[Dict]:
+        model_clean = model_name.strip().upper()
+        soc_clean = soc_name.strip().upper()
+        gpu_clean = gpu_name.strip().upper()
+
+        for prof in self.profiles:
+            target_model = prof.get("device_model", "").strip().upper()
+            if target_model and (target_model == model_clean or target_model in model_clean or model_clean in target_model):
+                return prof
+            aliases = [a.strip().upper() for a in prof.get("device_aliases", [])]
+            if any(a == model_clean or a in model_clean for a in aliases):
+                return prof
+
+        # Fallback matching by SoC / GPU
+        for prof in self.profiles:
+            prof_soc = prof.get("soc", "").strip().upper()
+            prof_gpu = prof.get("gpu", "").strip().upper()
+            if prof_soc and soc_clean and (prof_soc in soc_clean or soc_clean in prof_soc):
+                return prof
+            if prof_gpu and gpu_clean and (prof_gpu in gpu_clean or gpu_clean in prof_gpu):
+                return prof
+        return None
+
+    def validate_execution(self, preset_or_model: str, device: str, user_explicit: bool = False) -> Tuple[bool, Optional[str]]:
+        """Validate if the requested model/preset and device backend are safe for current hardware.
+        
+        Strict User Policy:
+        If user explicitly requested GPU execution (user_explicit=True), bypass safety gating
+        and let the native engine execute directly, failing fast if the hardware driver crashes.
+        """
+        if user_explicit:
+            logger.info("Explicit GPU device requested by user. Bypassing safety gating check for '%s'.", preset_or_model)
+            return True, None
+
+        device_clean = device.lower().strip()
+        if device_clean not in ("vulkan", "gpu"):
+            return True, None
+
+        dev_model = _detect_device_model()
+        soc_name = _detect_soc_name()
+        gpu_name = _detect_gpu_name()
+        matched = self.find_matching_profile(dev_model, soc_name, gpu_name)
+        if not matched:
+            return True, None
+
+        # 1. Check blocked list
+        blocked = matched.get("blocked", [])
+        preset_clean = preset_or_model.lower().strip()
+        for blk in blocked:
+            fam = blk.get("model_family", "").lower()
+            backend = blk.get("backend", "").lower()
+            if backend in (device_clean, "all") and fam in preset_clean:
+                reason = blk.get("reason", "Incompatible hardware backend configuration")
+                return False, (
+                    f"Model '{preset_or_model}' is blocked on device '{matched.get('device_model')}' "
+                    f"under backend '{device_clean}' due to: {reason}."
+                )
+
+        # 2. Check preset gating if preset exists in profile
+        presets = matched.get("presets", {})
+        if preset_clean in presets:
+            p_info = presets[preset_clean]
+            if p_info.get("status") == "pending_device_validation" and not p_info.get("auto_activation", True):
+                return False, (
+                    f"Preset '{preset_clean}' is currently pending device validation on '{matched.get('device_model')}' "
+                    f"and auto_activation is disabled."
+                )
+
+        return True, None
+
+
+_gating_manager: Optional[ProfileGatingManager] = None
+
+
+def get_profile_gating_manager() -> ProfileGatingManager:
+    """Get singleton instance of ProfileGatingManager."""
+    global _gating_manager
+    if _gating_manager is None:
+        _gating_manager = ProfileGatingManager.load_from_json()
+    return _gating_manager
+
+
+def resolve_hardware(model_name: str = "sdxs-512-dreamshaper", backend: str = "vulkan") -> Dict[str, Any]:
+    """Resolves execution plan via ameva-runtime HAL SSOT."""
+    try:
+        from ameva_runtime.adapters import DiffusionAdapter
+    except ImportError as err:
+        raise PlatformNotSupportedError(
+            "[ERROR: AMEVA-DIFFUSION-E001] ameva-runtime HAL is not installed.\n"
+            "Run: pip install ameva-runtime\n"
+            "Raw Cause: " + str(err)
+        ) from err
+
+    adapter = DiffusionAdapter()
+    plan = adapter.bind(model_name=model_name, requested_backend=backend)
+    if backend == "vulkan" and plan.backend != "vulkan":
+        raise PlatformNotSupportedError(
+            f"[ERROR: AMEVA-DIFFUSION-E003] Vulkan requested but unsupported on this hardware.\n"
+            f"Diagnosis: {plan.diagnosis_reason}"
+        )
+    return plan.to_dict()
+
+
+
+
+# Standard Unified Interface Bridges
+def is_termux() -> bool:
+    try:
+        from .platform import is_android_termux
+        return is_android_termux()
+    except Exception:
+        import os
+        return bool(os.environ.get("TERMUX_VERSION") or os.environ.get("TERMUX_APP_PID"))
+
+
+def is_android() -> bool:
+    return is_termux()
+
+
+def detect_hardware() -> HardwareProfile:
+    """Standard Unified Hardware Detection for termux-diffusion."""
+    return detect_hardware_profile()
+
+
+resolve_device = resolve_device_backend
+
+
+def get_optimal_threads() -> int:
+    """Standard Unified Optimal Threads Calculator for termux-diffusion."""
+    return detect_hardware().recommended_threads
+
+
+def bind_hardware(engine: Any, requested_device: str = "auto", **kwargs) -> Optional[Any]:
+    """Standard Unified Hardware Binding Interface for termux-diffusion."""
+    device, ngl = resolve_device_backend(requested_device)
+    if hasattr(engine, "device"):
+        setattr(engine, "device", device)
+    return engine
+
+
+def get_kernel_physical_memory_gb() -> Tuple[float, float]:
+    """Retrieve deterministic physical memory metrics (MemTotal, MemAvailable) in GiB.
+
+    Directly parses Linux kernel /proc/meminfo to avoid string heuristics.
+    Falls back to psutil or conservative defaults if /proc/meminfo is inaccessible.
+    """
+    mem_total_bytes = 0
+    mem_avail_bytes = 0
+    meminfo_path = Path("/proc/meminfo")
+
+    if meminfo_path.exists():
+        try:
+            with open(meminfo_path, "r", encoding="utf-8") as f:
+                for line in f:
+                    if line.startswith("MemTotal:"):
+                        parts = line.split()
+                        if len(parts) >= 2:
+                            mem_total_bytes = int(parts[1]) * 1024
+                    elif line.startswith("MemAvailable:"):
+                        parts = line.split()
+                        if len(parts) >= 2:
+                            mem_avail_bytes = int(parts[1]) * 1024
+                    if mem_total_bytes > 0 and mem_avail_bytes > 0:
+                        break
+        except Exception as e:
+            logger.warning("Failed to parse /proc/meminfo: %s", e)
+
+    if mem_total_bytes == 0:
+        try:
+            import psutil
+            vm = psutil.virtual_memory()
+            mem_total_bytes = vm.total
+            mem_avail_bytes = vm.available
+        except Exception:
+            # Conservative fallback
+            mem_total_bytes = 4 * (1024 ** 3)
+            mem_avail_bytes = 2 * (1024 ** 3)
+
+    return round(mem_total_bytes / (1024 ** 3), 2), round(mem_avail_bytes / (1024 ** 3), 2)
+
+
+_LAST_CPU_SAMPLE: Optional[Tuple[float, float, float]] = None
+
+
+def get_live_cpu_percent() -> float:
+    """Retrieve instantaneous CPU utilization percentage (0-100%) from Linux /proc/stat."""
+    global _LAST_CPU_SAMPLE
+    now = time.time()
+    stat_path = Path("/proc/stat")
+
+    try:
+        if stat_path.exists():
+            with open(stat_path, "r", encoding="utf-8") as f:
+                first_line = f.readline()
+                if first_line.startswith("cpu "):
+                    parts = [float(x) for x in first_line.split()[1:8]]
+                    idle = parts[3] + (parts[4] if len(parts) > 4 else 0.0)
+                    total = sum(parts)
+                    work = total - idle
+
+                    if _LAST_CPU_SAMPLE is not None:
+                        last_work, last_total, last_time = _LAST_CPU_SAMPLE
+                        delta_total = total - last_total
+                        delta_work = work - last_work
+                        _LAST_CPU_SAMPLE = (work, total, now)
+                        if delta_total > 0 and (now - last_time) >= 0.1:
+                            pct = (delta_work / delta_total) * 100.0
+                            return round(min(100.0, max(0.0, pct)), 1)
+                    _LAST_CPU_SAMPLE = (work, total, now)
+    except (OSError, PermissionError):
+        pass
+
+    try:
+        load1, _, _ = os.getloadavg()
+        cpu_cnt = os.cpu_count() or 8
+        pct = (load1 / cpu_cnt) * 100.0
+        return round(min(100.0, max(0.0, pct)), 1)
+    except (OSError, AttributeError):
+        pass
+
+    try:
+        import psutil
+        return round(float(psutil.cpu_percent(interval=None)), 1)
+    except Exception:
+        return 0.0
+
+
+def get_live_gpu_percent() -> Optional[int]:
+    """Query Linux/Android kernel sysfs GPU load percentage across Adreno and Mali chips."""
+    kgsl_paths = [
+        Path("/sys/class/kgsl/kgsl-3d0/gpu_busy_percentage"),
+        Path("/sys/class/kgsl/kgsl-3d0/gpubusy"),
+    ]
+    for p in kgsl_paths:
+        try:
+            if p.is_file():
+                content = p.read_text().strip()
+                if " " in content:
+                    parts = content.split()
+                    busy_val, total_val = int(parts[0]), int(parts[1])
+                    if total_val > 0:
+                        return int(round((busy_val / total_val) * 100))
+                else:
+                    return int(content.replace("%", ""))
+        except (OSError, PermissionError):
+            pass
+
+    mali_paths = [
+        Path("/sys/class/misc/mali0/device/utilization"),
+        Path("/sys/devices/platform/17000000.gpu/utilization"),
+        Path("/sys/kernel/gpu/gpu_busy"),
+    ]
+    for p in mali_paths:
+        try:
+            if p.is_file():
+                content = p.read_text().strip().replace("%", "")
+                return int(content)
+        except (OSError, PermissionError):
+            pass
+
+    return None
+
+
+def get_system_resource_metrics() -> Dict[str, Any]:
+    """Deterministic system health probe returning RAM, CPU, GPU, and process memory."""
+    mem_total_gb, mem_avail_gb = get_kernel_physical_memory_gb()
+    mem_used_gb = round(max(0.0, mem_total_gb - mem_avail_gb), 2)
+    mem_pct = round((mem_used_gb / mem_total_gb) * 100.0, 1) if mem_total_gb > 0 else 0.0
+
+    cpu_pct = get_live_cpu_percent()
+    gpu_busy = get_live_gpu_percent()
+
+    rss_mb = 0.0
+    try:
+        with open(f"/proc/{os.getpid()}/status", "r", encoding="utf-8") as f:
+            for line in f:
+                if line.startswith("VmRSS:"):
+                    parts = line.split()
+                    if len(parts) >= 2:
+                        rss_mb = round(int(parts[1]) / 1024.0, 1)
+                    break
+    except Exception:
+        pass
+
+    return {
+        "ram_total_gb": mem_total_gb,
+        "ram_avail_gb": mem_avail_gb,
+        "ram_used_gb": mem_used_gb,
+        "ram_percent": mem_pct,
+        "cpu_percent": cpu_pct,
+        "gpu_percent": gpu_busy,
+        "process_rss_mb": rss_mb,
+    }
+
+
+class TermuxExecutionGuard:
+    """Execution context guard that manages Android partial wake locks and scheduling niceness.
+
+    Prevents CPU sleep / Doze throttling during model inference and restores state cleanly.
+    """
+    def __init__(self, enable_wake_lock: bool = True, boost_priority: bool = True, safe_mode: bool = False):
+        self.is_termux_env = is_termux() or os.path.exists("/data/data/com.termux")
+        self.enable_wake_lock = enable_wake_lock
+        self.boost_priority = boost_priority and not safe_mode
+        self.safe_mode = safe_mode
+        self.wake_lock_acquired = False
+
+    def __enter__(self):
+        if self.is_termux_env:
+            if self.safe_mode:
+                try:
+                    os.nice(10)
+                    logger.info("[TermuxGuard] Safe Mode active: Process niceness demoted (+10) to preserve SurfaceFlinger and background apps")
+                except Exception:
+                    pass
+            elif self.boost_priority:
+                try:
+                    os.nice(-20)
+                    logger.info("[TermuxGuard] Process niceness boosted to highest priority (-20)")
+                except Exception:
+                    try:
+                        os.nice(-10)
+                    except Exception:
+                        pass
+
+            if self.enable_wake_lock:
+                wake_bin = shutil.which("termux-wake-lock") or "/data/data/com.termux/files/usr/bin/termux-wake-lock"
+                if os.path.exists(wake_bin):
+                    try:
+                        subprocess.run([wake_bin], check=False, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+                        self.wake_lock_acquired = True
+                        logger.info("[TermuxGuard] Android PARTIAL_WAKE_LOCK acquired via termux-wake-lock")
+                    except Exception as e:
+                        logger.warning("[TermuxGuard] Could not invoke termux-wake-lock: %s", e)
+                else:
+                    try:
+                        subprocess.run(
+                            ["am", "startservice", "--user", "0", "-a", "com.termux.service_wake_lock", "com.termux/.app.TermuxService"],
+                            check=False, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL
+                        )
+                        self.wake_lock_acquired = True
+                        logger.info("[TermuxGuard] Android PARTIAL_WAKE_LOCK acquired via TermuxService Intent")
+                    except Exception as e:
+                        logger.warning("[TermuxGuard] Could not start TermuxService wake_lock: %s", e)
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if self.is_termux_env and self.wake_lock_acquired:
+            wake_unlock = shutil.which("termux-wake-unlock") or "/data/data/com.termux/files/usr/bin/termux-wake-unlock"
+            if os.path.exists(wake_unlock):
+                try:
+                    subprocess.run([wake_unlock], check=False, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+                    logger.info("[TermuxGuard] Android PARTIAL_WAKE_LOCK released cleanly")
+                except Exception:
+                    pass
+            else:
+                try:
+                    subprocess.run(
+                        ["am", "startservice", "--user", "0", "-a", "com.termux.service_wake_unlock", "com.termux/.app.TermuxService"],
+                        check=False, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL
+                    )
+                    logger.info("[TermuxGuard] Android PARTIAL_WAKE_LOCK released via TermuxService Intent")
+                except Exception:
+                    pass
+
+