wai-quantum 0.5.0

//! The gate kernel for OpenCL devices, and what names an OpenCL member: the
//! kernel's text (`lanes64.cl`), its implementation id, a device's identity
//! and the mutants a conforming device must be caught running. No device is
//! touched here, so all of it is testable on any host; the OpenCL member itself
//! is `quantum_fabric_opencl`.
//!
//! **Why the kernel is bit-exact.** OpenCL C's `long` is a 64-bit integer on
//! every full-profile device, so the kernel is the same transcription of
//! [`lanes::exact_row`] and [`lanes::apply_words`] as the CUDA kernel
//! ([`super::cuda`]): each `fx(a, b) = (a·b + 2^29) >> 30` and each row's sum
//! of four is exact in 64 bits, the lane keeps the sum's low 32 bits, and a sum
//! outside 32 bits records the gate's op-log index, the lowest winning.
//!
//! Each work-item owns one amplitude pair and a launch is one gate, so no
//! work-item reads what another writes within a launch, and neither the
//! work-group size the runtime picks nor the order work-items run in can change
//! a bit. The member's probe checks the device's products and shifts against
//! [`lanes::mul_wide`] and [`lanes::fxmul_wide`] before the device is a member,
//! and its certificates check whole runs against the CPU's pinned corpus
//! digests.
//!
//! [`lanes::exact_row`]: super::lanes
//! [`lanes::apply_words`]: super::lanes::apply_words
//! [`lanes::mul_wide`]: super::lanes::mul_wide
//! [`lanes::fxmul_wide`]: super::lanes::fxmul_wide

use super::FabricClass;
use super::wgsl::{Detector, Mutant};

/// The kernel, `lanes64.cl`, exactly as it is built.
pub const SOURCE: &str = include_str!("lanes64.cl");

/// The implementation name the id starts with.
pub const IMPLEMENTATION: &str = "opencl-lanes64";

/// Version of the host-side layout: interleaved `int2` lanes, one launch per
/// gate with the gate's words as kernel arguments, the report word (the
/// lowest out-of-range op index, `u32::MAX` for none), the probe's `int2`
/// cases and `uint4` outputs, and the launch shape ([`GLOBAL_MAX`], the
/// work-group size left to the runtime). Bumped on any change to them; it is
/// part of the implementation id.
pub const HOST_LAYOUT: u32 = 1;

/// Work-items per launch, at most; the kernel strides over the rest.
pub const GLOBAL_MAX: u64 = 1 << 20;

/// The options the kernel is built with: OpenCL C 1.2, and nothing that
/// relaxes arithmetic, though the kernel has no floating point for it to
/// touch.
pub const BUILD_OPTIONS: &str = "-cl-std=CL1.2";

const DOMAIN_IMPLEMENTATION: &[u8] = b"wai:quantum-fabric-opencl\x01";
const DOMAIN_MEMBER: &[u8] = b"wai:quantum-fabric-opencl-member\x01";

fn hex(bytes: &[u8]) -> String {
    bytes.iter().map(|b| format!("{b:02x}")).collect()
}

/// A length-prefixed byte string, so that no field reads as part of another.
fn put(o: &mut Vec<u8>, bytes: &[u8]) {
    o.extend_from_slice(&(bytes.len() as u64).to_be_bytes());
    o.extend_from_slice(bytes);
}

/// `"opencl-lanes64/<16 hex>"`: the first 8 bytes of
/// BLAKE3(`"wai:quantum-fabric-opencl\x01"` ‖ put([`SOURCE`]) ‖
/// put([`BUILD_OPTIONS`]) ‖ [`HOST_LAYOUT`] as a big-endian `u32`), in hex. Any
/// edit to the kernel's text, its build options or the host layout changes it.
/// The device and its compiler are part of the member id instead.
pub fn implementation_id() -> String {
    implementation_id_of(SOURCE)
}

/// [`implementation_id`] for another kernel text, such as a mutant's.
pub fn implementation_id_of(source: &str) -> String {
    let mut o = DOMAIN_IMPLEMENTATION.to_vec();
    put(&mut o, source.as_bytes());
    put(&mut o, BUILD_OPTIONS.as_bytes());
    o.extend_from_slice(&HOST_LAYOUT.to_be_bytes());
    format!("{IMPLEMENTATION}/{}", hex(&blake3::hash(&o).as_bytes()[..8]))
}

/// The kind of device an OpenCL platform reports.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum DeviceKind {
    Gpu,
    Cpu,
    /// An accelerator, or any type the platform reports that is neither.
    Accelerator,
}

impl DeviceKind {
    fn name(self) -> &'static str {
        match self {
            DeviceKind::Gpu => "gpu",
            DeviceKind::Cpu => "cpu",
            DeviceKind::Accelerator => "accelerator",
        }
    }
}

/// What an OpenCL member is, as its id hashes it. The member fills it from the
/// runtime; the fields are plain values here so that the id is testable
/// without a device.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct DeviceIdentity {
    /// The platform's name, version and vendor, as it reports them.
    pub platform: String,
    pub platform_version: String,
    pub vendor: String,
    /// The device's name, its OpenCL version string and its driver's version.
    pub name: String,
    pub version: String,
    pub driver: String,
    pub kind: DeviceKind,
    /// The device's UUID in hex where the platform reports one
    /// (`cl_khr_device_uuid`), else empty.
    pub uuid: String,
    pub compute_units: u32,
    /// The device's global memory, bytes.
    pub memory: u64,
}

impl DeviceIdentity {
    /// [`FabricClass::Gpu`] for a GPU and [`FabricClass::Cpu`] for a CPU. An
    /// OpenCL accelerator may be an FPGA, a DSP or anything else, so it has no
    /// class, and discovery refuses it.
    pub fn class(&self) -> Option<FabricClass> {
        match self.kind {
            DeviceKind::Gpu => Some(FabricClass::Gpu),
            DeviceKind::Cpu => Some(FabricClass::Cpu),
            DeviceKind::Accelerator => None,
        }
    }

    /// The leading letters and digits of the vendor's first word other than
    /// "the", lowercase: `"Maker Corporation"` is `"maker"`,
    /// `"Maker(R) Corporation"` is `"maker"`, `"The pocl project"` is `"pocl"`.
    pub fn vendor_slug(&self) -> String {
        let word = self.vendor.split_whitespace().find(|w| !w.eq_ignore_ascii_case("the")).unwrap_or("");
        let slug: String = word.chars().take_while(|c| c.is_ascii_alphanumeric()).map(|c| c.to_ascii_lowercase()).collect();
        if slug.is_empty() { "unknown".into() } else { slug }
    }

    /// `"local/opencl-<kind>-<d12>"`. `d12` is the first 12 hex digits of
    /// BLAKE3(`"wai:quantum-fabric-opencl-member\x01"` ‖ put of the platform,
    /// its version, the vendor, the name, the version, the driver, the kind and
    /// the UUID ‖ compute units ‖ memory), the numbers big-endian. It sorts
    /// after every `local/cpu-<arch>` and `local/gpu-…`, so with no energy
    /// figures [`place`](super::place) keeps the CPU reference.
    pub fn member_id(&self) -> String {
        let mut o = DOMAIN_MEMBER.to_vec();
        for s in [&self.platform, &self.platform_version, &self.vendor, &self.name, &self.version, &self.driver] {
            put(&mut o, s.as_bytes());
        }
        put(&mut o, self.kind.name().as_bytes());
        put(&mut o, self.uuid.as_bytes());
        o.extend_from_slice(&self.compute_units.to_be_bytes());
        o.extend_from_slice(&self.memory.to_be_bytes());
        format!("local/opencl-{}-{}", self.kind.name(), hex(&blake3::hash(&o).as_bytes()[..6]))
    }

    /// The key a runner declares in CI: `"opencl-<kind>-<vendor>"`, for
    /// instance `"opencl-gpu-maker"`.
    pub fn key(&self) -> String {
        format!("opencl-{}-{}", self.kind.name(), self.vendor_slug())
    }
}

/// The mutants: textual edits of [`SOURCE`] that a conforming device must be
/// caught running, each by the detector named. Each `find` occurs exactly
/// once in [`SOURCE`].
pub const MUTANTS: [Mutant; 6] = [
    // The rounding constant is half what it should be.
    Mutant { name: "O1", find: "((i64)a * (i64)b + ((i64)1 << 29)) >> 30;", replace: "((i64)a * (i64)b + ((i64)1 << 28)) >> 30;", detector: Detector::Probe },
    // The product is shifted by one bit too few.
    Mutant { name: "O2", find: "((i64)a * (i64)b + ((i64)1 << 29)) >> 30;", replace: "((i64)a * (i64)b + ((i64)1 << 29)) >> 29;", detector: Detector::Probe },
    // The probe's product is taken in 32 bits.
    Mutant { name: "O3", find: "u64 prod = (u64)((i64)c.x * (i64)c.y);", replace: "u64 prod = (u64)(uint)(c.x * c.y);", detector: Detector::Probe },
    // The control test is inverted.
    Mutant { name: "O4", find: "if ((i & (u64)ctrl) != (u64)ctrl) {", replace: "if ((i & (u64)ctrl) == (u64)ctrl) {", detector: Detector::Certificate },
    // A sign of row 0's real part is wrong, on the imaginary part of the
    // top-right entry, which `Y` has.
    Mutant { name: "O5", find: "fx(m2, a1.x) - fx(m3, a1.y);", replace: "fx(m2, a1.x) + fx(m3, a1.y);", detector: Detector::Certificate },
    // The range guard never fires.
    Mutant { name: "O6", find: "if (!(fits32(o0r) && fits32(o0i) && fits32(o1r) && fits32(o1i))) {", replace: "if (0) {", detector: Detector::Range },
];

/// [`SOURCE`] with `m` applied. Panics unless `m.find` occurs exactly once.
pub fn mutate(m: &Mutant) -> String {
    let n = SOURCE.matches(m.find).count();
    assert_eq!(n, 1, "mutant {}: `{}` occurs {n} times in the kernel", m.name, m.find);
    SOURCE.replacen(m.find, m.replace, 1)
}

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

    fn identity() -> DeviceIdentity {
        DeviceIdentity {
            platform: "a platform".into(),
            platform_version: "OpenCL 3.0".into(),
            vendor: "Graphics Corporation".into(),
            name: "a device".into(),
            version: "OpenCL 3.0 CUDA".into(),
            driver: "595.84".into(),
            kind: DeviceKind::Gpu,
            uuid: "00112233445566778899aabbccddeeff".into(),
            compute_units: 20,
            memory: 6 << 30,
        }
    }

    #[test]
    fn every_field_of_the_identity_is_in_the_member_id() {
        let base = identity();
        let id = base.member_id();
        assert!(id.starts_with("local/opencl-gpu-") && id.len() == "local/opencl-gpu-".len() + 12, "{id}");
        for other in ["local/cpu-x86_64", "local/cpu-aarch64", "local/gpu-cuda-ffffffffffff"] {
            assert!(id.as_str() > other, "{id} sorts after {other}");
        }
        let cpu = DeviceIdentity { kind: DeviceKind::Cpu, ..identity() }.member_id();
        assert!(cpu.as_str() > "local/cpu-x86_64", "a CPU device sorts after the CPU reference: {cpu}");
        let variants = [
            DeviceIdentity { platform: "another".into(), ..identity() },
            DeviceIdentity { platform_version: "OpenCL 1.2".into(), ..identity() },
            DeviceIdentity { vendor: "Cores(R) Corporation".into(), ..identity() },
            DeviceIdentity { name: "another".into(), ..identity() },
            DeviceIdentity { version: "OpenCL 1.2".into(), ..identity() },
            DeviceIdentity { driver: "595.85".into(), ..identity() },
            DeviceIdentity { kind: DeviceKind::Cpu, ..identity() },
            DeviceIdentity { kind: DeviceKind::Accelerator, ..identity() },
            DeviceIdentity { uuid: String::new(), ..identity() },
            DeviceIdentity { compute_units: 21, ..identity() },
            DeviceIdentity { memory: 8 << 30, ..identity() },
        ];
        for v in variants {
            assert_ne!(v.member_id(), id, "{v:?}");
        }
        assert_eq!(base.key(), "opencl-gpu-graphics");
        assert_eq!(DeviceIdentity { vendor: "Cores(R) Corporation".into(), kind: DeviceKind::Cpu, ..identity() }.key(), "opencl-cpu-cores");
        assert_eq!(DeviceIdentity { vendor: "The pocl project".into(), kind: DeviceKind::Cpu, ..identity() }.key(), "opencl-cpu-pocl");
        assert_eq!(DeviceIdentity { vendor: String::new(), ..identity() }.key(), "opencl-gpu-unknown");
        assert_eq!(base.class(), Some(FabricClass::Gpu));
        assert_eq!(DeviceIdentity { kind: DeviceKind::Cpu, ..identity() }.class(), Some(FabricClass::Cpu));
        assert_eq!(DeviceIdentity { kind: DeviceKind::Accelerator, ..identity() }.class(), None);
    }

    #[test]
    fn the_implementation_id_follows_the_kernel_text() {
        let id = implementation_id();
        assert!(id.starts_with("opencl-lanes64/") && id.len() == "opencl-lanes64/".len() + 16, "{id}");
        for m in &MUTANTS {
            assert_ne!(implementation_id_of(&mutate(m)), id, "mutant {}", m.name);
        }
    }

    #[test]
    fn every_mutant_edits_the_kernel_once_and_names_distinct_edits() {
        let mut seen = std::collections::BTreeSet::new();
        for m in &MUTANTS {
            let edited = mutate(m);
            assert_ne!(edited, SOURCE, "mutant {} changes nothing", m.name);
            assert!(seen.insert(edited), "mutant {} duplicates another", m.name);
        }
        for d in [Detector::Probe, Detector::Certificate, Detector::Range] {
            assert!(MUTANTS.iter().any(|m| m.detector == d), "no mutant for {d:?}");
        }
    }
}