Experimental support for targets without SPIR-V capabilities (#319)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: maleadt

.github/workflows/Test.yml

@@ -148,6 +148,14 @@ jobs:
           Pkg.activate(".")
           Pkg.test(; test_args=`--quickfail --verbose --platform=pocl`)
 
+      - name: Upload compilation dumps
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: compilation-dumps-${{ matrix.version }}-${{ matrix.os }}-${{ matrix.arch }}-${{ matrix.memory_backend }}-pocl-${{ matrix.pocl }}
+          path: ${{ runner.temp }}/opencl-compilation-dumps/
+          if-no-files-found: ignore
+
       - uses: julia-actions/julia-processcoverage@v1
       - uses: codecov/codecov-action@v7
         with:

Project.toml

@@ -23,6 +23,7 @@ SPIRVIntrinsics = "71d1d633-e7e8-4a92-83a1-de8814b09ba8"
 SPIRV_LLVM_Backend_jll = "4376b9bf-cff8-51b6-bb48-39421dff0d0c"
 SPIRV_Tools_jll = "6ac6d60f-d740-5983-97d7-a4482c0689f4"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
+spirv2clc_jll = "f0274c0c-8c8a-59f1-85b7-f7d60330c5fb"
 
 [sources]
 SPIRVIntrinsics = {path = "lib/intrinsics"}
@@ -46,3 +47,4 @@ SPIRV_LLVM_Backend_jll = "22"
 SPIRV_Tools_jll = "2025.1"
 StaticArrays = "1"
 julia = "1.10"
+spirv2clc_jll = "0.2.0"

src/OpenCL.jl

@@ -2,7 +2,7 @@ module OpenCL
 
 using GPUCompiler
 using LLVM, LLVM.Interop
-using SPIRV_LLVM_Backend_jll, SPIRV_Tools_jll
+using SPIRV_LLVM_Backend_jll, SPIRV_Tools_jll, spirv2clc_jll
 using Adapt
 using Reexport
 using GPUArrays

src/compiler/capabilities.jl

@@ -40,6 +40,49 @@ end
 
 has_opencl_c_feature(dev, feat) = feat in opencl_c_features(dev)
 
+# OpenCL 3.0: CL_DEVICE_OPENCL_C_ALL_VERSIONS lists every OpenCL C version the device accepts as
+# an array of cl_name_version {cl_version (4 bytes); char name[64]}. This is the query to trust:
+# the legacy CL_DEVICE_OPENCL_C_VERSION string reports "1.2" on both NVIDIA and pocl even though
+# pocl accepts up to 3.0. Returns the highest version, falling back to the legacy string (or 1.2)
+# on devices that don't support the 3.0 query.
+function max_opencl_c_version(dev::cl.Device)::VersionNumber
+    CL_DEVICE_OPENCL_C_ALL_VERSIONS = 0x1066
+    try
+        sz = Ref{Csize_t}(0)
+        cl.clGetDeviceInfo(dev, CL_DEVICE_OPENCL_C_ALL_VERSIONS, 0, C_NULL, sz)
+        if sz[] != 0
+            buf = Vector{UInt8}(undef, sz[])
+            cl.clGetDeviceInfo(dev, CL_DEVICE_OPENCL_C_ALL_VERSIONS, sz[], buf, C_NULL)
+            entry = 68  # sizeof(cl_name_version)
+            best = v"0"
+            for off in 0:entry:(length(buf) - entry)
+                ver = reinterpret(UInt32, buf[(off + 1):(off + 4)])[1]  # cl_version bitfield
+                vn = VersionNumber(ver >> 22, (ver >> 12) & 0x3ff)      # major[31:22], minor[21:12]
+                vn > best && (best = vn)
+            end
+            best > v"0" && return best
+        end
+    catch
+    end
+    return legacy_opencl_c_version(dev)
+end
+
+# Pre-3.0 fallback: parse the "OpenCL C <major>.<minor> <vendor>" string.
+function legacy_opencl_c_version(dev::cl.Device)::VersionNumber
+    CL_DEVICE_OPENCL_C_VERSION = 0x103d
+    try
+        sz = Ref{Csize_t}(0)
+        cl.clGetDeviceInfo(dev, CL_DEVICE_OPENCL_C_VERSION, 0, C_NULL, sz)
+        buf = Vector{UInt8}(undef, sz[])
+        cl.clGetDeviceInfo(dev, CL_DEVICE_OPENCL_C_VERSION, sz[], buf, C_NULL)
+        str = String(buf[1:(end - 1)])  # drop the trailing NUL
+        m = match(r"OpenCL C (\d+)\.(\d+)", str)
+        m !== nothing && return VersionNumber(parse(Int, m[1]), parse(Int, m[2]))
+    catch
+    end
+    return v"1.2"  # conservative default
+end
+
 const FEATURES = Feature[
     Feature(:fp16, dev -> "cl_khr_fp16" in dev.extensions),
     Feature(:fp64, dev -> "cl_khr_fp64" in dev.extensions),

src/compiler/compilation.jl

@@ -5,6 +5,8 @@ Base.@kwdef struct OpenCLCompilerParams <: AbstractCompilerParams
     sub_group_size::Union{Nothing,Int} = nothing
     # optional features the target device supports, exposed to kernels via `has_feature`
     features::FeatureSet = zero(FeatureSet)
+    # requested backend policy; kept here so the cache keys on it (the backends share a context)
+    program_backend::Symbol = :auto
 end
 
 const OpenCLCompilerConfig = CompilerConfig{SPIRVCompilerTarget, OpenCLCompilerParams}
@@ -140,16 +142,21 @@ end
 const _toolchain = Ref{Any}()
 const _compiler_configs = Dict{UInt, OpenCLCompilerConfig}()
 function compiler_config(dev::cl.Device; kwargs...)
-    h = hash(dev, hash(kwargs))
+    # key on the policy, not the resolved backend: resolving queries the device, so defer it to link
+    backend = program_backend()
+    h = hash(dev, hash(backend, hash(kwargs)))
     config = get(_compiler_configs, h, nothing)
     if config === nothing
-        config = _compiler_config(dev; kwargs...)
+        config = _compiler_config(dev, backend; kwargs...)
         _compiler_configs[h] = config
     end
     return config
 end
 @inline _sub_group_size(dev) = "cl_intel_required_subgroup_size" in dev.extensions ? cl.sub_group_size(dev) : nothing
-@noinline function _compiler_config(dev; kernel=true, name=nothing, always_inline=false,
+
+const SPIRV_VERSION = v"1.4"
+
+@noinline function _compiler_config(dev, backend; kernel=true, name=nothing, always_inline=false,
                                      sub_group_size::Union{Nothing,Int}=_sub_group_size(dev), kwargs...)
     supports_fp16 = "cl_khr_fp16" in dev.extensions
     supports_fp64 = "cl_khr_fp64" in dev.extensions
@@ -159,8 +166,10 @@ end
     end
 
     # create GPUCompiler objects
-    target = SPIRVCompilerTarget(; supports_fp16, supports_fp64, validate=true, kwargs...)
-    params = OpenCLCompilerParams(; sub_group_size, features=device_features(dev))
+    target = SPIRVCompilerTarget(; version=SPIRV_VERSION, supports_fp16, supports_fp64,
+                                   validate=true, kwargs...)
+    params = OpenCLCompilerParams(; sub_group_size, features=device_features(dev),
+                                    program_backend=backend)
     CompilerConfig(target, params; kernel, name, always_inline)
 end
 
@@ -180,21 +189,158 @@ function compile(@nospecialize(job::CompilerJob))
     end
 end
 
+function run_and_collect(cmd)
+    stdout = Pipe()
+    proc = run(pipeline(ignorestatus(cmd); stdout, stderr=stdout), wait=false)
+    close(stdout.in)
+
+    reader = Threads.@spawn String(read(stdout))
+    Base.wait(proc)
+    log = strip(fetch(reader))
+
+    return proc, log
+end
+
+# How kernels are fed to the driver:
+# - `:auto`   — SPIR-V (clCreateProgramWithIL) when the device supports IL programs, otherwise
+#               OpenCL C source translated from the SPIR-V via spirv2clc.
+# - `:spirv`  — always SPIR-V IL; error if the device doesn't support it.
+# - `:opencl` — always OpenCL C source. Useful to exercise pocl's source path on a device that
+#               also supports IL.
+# Task-local, like `cl.device`/`cl.queue`; `resolve_program_backend` maps it to a concrete backend.
+
+"""
+    program_backend() -> Symbol
+
+The requested program backend for the current task (`:auto`, `:spirv`, or `:opencl`).
+"""
+program_backend() = get(task_local_storage(), :CLProgramBackend, :auto)::Symbol
+
+"""
+    program_backend!(mode::Symbol)
+    program_backend!(f::Function, mode::Symbol)
+
+Select how kernels are fed to the driver for the current task: `:auto` (default), `:spirv` (SPIR-V
+IL), or `:opencl` (OpenCL C source). The second form applies `mode` only for the duration of `f`.
+"""
+function program_backend!(mode::Symbol)
+    mode in (:auto, :spirv, :opencl) ||
+        throw(ArgumentError("invalid program backend $mode (expected :auto, :spirv or :opencl)"))
+    task_local_storage(:CLProgramBackend, mode)
+    return mode
+end
+
+function program_backend!(f::Base.Callable, mode::Symbol)
+    old = program_backend()
+    program_backend!(mode)
+    try
+        f()
+    finally
+        program_backend!(old)
+    end
+end
+
+# Map the policy to a concrete backend for `dev`. Done in `link`, off the per-launch path.
+function resolve_program_backend(dev::cl.Device, mode::Symbol = program_backend())
+    mode === :opencl && return :opencl
+    mode in (:auto, :spirv) ||
+        throw(ArgumentError("invalid program backend $mode (expected :auto, :spirv or :opencl)"))
+    if "cl_khr_il_program" in dev.extensions
+        return :spirv
+    elseif mode === :spirv
+        error("Device '$(dev.name)' does not support SPIR-V IL programs")
+    else  # :auto
+        @warn "Device '$(dev.name)' lacks IL support; using OpenCL C translation." maxlog=1 _id=Symbol(dev.name)
+        return :opencl
+    end
+end
+
+# Dump compilation artifacts (`extension => data` pairs sharing one random base name, e.g.
+# `dump_artifacts(".spv" => spv, ".cl" => src)`) to a directory for later inspection. The
+# directory is `JULIA_OPENCL_DUMP_DIR` if set, else `$RUNNER_TEMP/opencl-compilation-dumps` on
+# GitHub Actions, else `tempdir()`. On CI the files are surfaced as downloadable artifacts
+# (`buildkite-agent artifact upload`, or a GitHub Actions `::notice`). Returns the written paths.
+function dump_artifacts(artifacts::Pair{String}...)
+    on_github = get(ENV, "GITHUB_ACTIONS", "false") == "true"
+    dir = if haskey(ENV, "JULIA_OPENCL_DUMP_DIR")
+        mkpath(ENV["JULIA_OPENCL_DUMP_DIR"])
+    elseif on_github
+        mkpath(joinpath(get(ENV, "RUNNER_TEMP", tempdir()), "opencl-compilation-dumps"))
+    else
+        tempdir()
+    end
+    stem = tempname(dir; cleanup=false)
+
+    paths = String[]
+    for (ext, data) in artifacts
+        path = stem * ext
+        write(path, data)
+        push!(paths, path)
+    end
+
+    if parse(Bool, get(ENV, "BUILDKITE", "false"))
+        for path in paths
+            run(`buildkite-agent artifact upload $path`)
+        end
+    elseif on_github
+        println("::notice title=OpenCL compilation dump::wrote $(join(basename.(paths), ", ")) to $dir")
+    end
+
+    return paths
+end
+
 # link into an executable kernel
 function link(@nospecialize(job::CompilerJob), compiled)
-    prog = if "cl_khr_il_program" in cl.device().extensions
-        cl.Program(; il=compiled.obj)
+    spirv_bitcode = compiled.obj
+    clc_source = nothing
+    build_options = ""
+
+    dev = cl.device()
+    backend = resolve_program_backend(dev, job.config.params.program_backend)
+
+    prog = if backend === :spirv
+        cl.Program(; il=spirv_bitcode)
     else
-        error("Your device does not support SPIR-V, which is currently required for native execution.")
-        # XXX: kpet/spirv2clc#87, caused by KhronosGroup/SPIRV-LLVM-Translator#2029
-        source = mktempdir() do dir
-            il = joinpath(dir, "kernel.spv")
-            write(il, compiled.obj)
-            cmd = `spirv2clc $il`
-            read(cmd, String)
+        # Target the device's highest OpenCL C version
+        clc_version = max_opencl_c_version(dev)
+        cl_std = "CL$(clc_version.major).$(clc_version.minor)"
+
+        # Be consistent with the SPIR-V version we generated code for
+        spv = job.config.target.version
+        spirv_version = "$(spv.major).$(spv.minor)"
+
+        spirv_path = tempname(cleanup=false) * ".spv"
+        write(spirv_path, spirv_bitcode)
+        proc, log = run_and_collect(`$(spirv2clc_jll.spirv2clc()) --spirv-version=$spirv_version --cl-std=$cl_std $spirv_path`)
+        rm(spirv_path)
+        if !success(proc)
+            spv_file, = dump_artifacts(".spv" => spirv_bitcode)
+            error("Failed to translate SPIR-V to OpenCL C source code:\n$(log)\n" *
+                  "If you think this is a bug, please file an issue and attach $spv_file")
         end
-        cl.Program(; source)
+
+        clc_source = strip(log)
+        build_options = "-cl-std=$cl_std"
+        cl.Program(; source=clc_source)
+    end
+
+    # optionally dump the artifacts of every kernel (e.g. to debug a runtime miscompile)
+    if haskey(ENV, "JULIA_OPENCL_DUMP_DIR")
+        clc_source === nothing ? dump_artifacts(".spv" => spirv_bitcode) :
+                                 dump_artifacts(".spv" => spirv_bitcode, ".cl" => clc_source)
+    end
+
+    try
+        cl.build!(prog; options=build_options)
+    catch e
+        files = clc_source === nothing ?
+            dump_artifacts(".spv" => spirv_bitcode) :
+            dump_artifacts(".spv" => spirv_bitcode, ".cl" => clc_source)
+
+        # `build!` already renders the source and build log; keep that and point at the artifacts
+        msg = sprint(showerror, e)
+        msg *= "\nIf you think this is a bug, please file an issue and attach $(join(files, " and "))"
+        error(msg)
     end
-    cl.build!(prog)
     (; kernel=cl.Kernel(prog, compiled.entry), compiled.device_rng)
 end

test/execution.jl

@@ -139,7 +139,7 @@ end
         OpenCL.code_llvm(io, () -> nothing, (); dump_module = true, backend = :llvm)
     end
     if Int === Int64
-        @test occursin("target triple = \"spirv64-unknown-unknown-unknown\"", llvm_backend_llvm)
+        @test occursin("target triple = \"spirv64v1.4-unknown-unknown-unknown\"", llvm_backend_llvm)
     end
 
     llvm_backend_khronos = sprint() do io