OpenCL kernel binary cache invalidation strategy across driver updates

Recommended policy

Use an application-managed cache keyed by CL_DEVICE_VENDOR, CL_DEVICE_NAME, and the major.minor portion of CL_DEVICE_DRIVER_VERSION. Optionally append a hash of CL_DEVICE_EXTENSIONS when the kernel depends on optional features. Store the binary with a checksum. On CL_INVALID_BINARY, compare the stored checksum to the cached file: mismatch means corruption, match means incompatibility. In both cases delete only that application-owned cache entry and recompile from source with clCreateProgramWithSource plus clBuildProgram, then refresh the cached binary with clGetProgramInfo(CL_PROGRAM_BINARIES). There is no standard API to purge a single entry from an ICD vendor cache directory, so do not delete files inside opaque vendor directories.

Confirmed facts

• The OpenCL specification guarantees binary compatibility only for the same device name and driver version pair.
• clCreateProgramWithBinary returns CL_INVALID_BINARY with no reason code.
• No standard OpenCL API enumerates, invalidates, or reports the age of cached binaries.
• Device index is not stable across reboots on multi-GPU systems; PCI bus ID requires a platform-specific extension.

Likely explanation

A minor driver patch often preserves the same major.minor version, so the cache can survive it. A build-number-only change should not by itself force invalidation. If the driver changes ISA or compiler internals within the same major.minor string, the binary will be rejected even though the key matches; the checksum test cannot detect that, only the CL_INVALID_BINARY result can.

Steps for this case

1. Query CL_DEVICE_VENDOR, CL_DEVICE_NAME, and CL_DEVICE_DRIVER_VERSION for each device.
2. Build the key as vendor|name|driver-major.minor; add an extensions hash only if your kernel depends on optional features.
3. Before loading, verify the cached file exists and its checksum matches the stored value.
4. Call clCreateProgramWithBinary. On CL_INVALID_BINARY:
• Checksum mismatch: treat as cache corruption; delete the file.
• Checksum match: treat as binary incompatibility; delete the file.
5. Recompile from source: clCreateProgramWithSource, clBuildProgram, then clGetProgramInfo(CL_PROGRAM_BINARIES) to write the new binary and checksum.
6. On multi-GPU systems with identical name/vendor/driver, add a stable device identifier if available, for example PCI bus ID through a platform extension. Otherwise use the process-local device index and document that it can change after a reboot.

Verification

Confirm the key before reuse by re-querying the same device-info fields and comparing them to the stored key. After a failed binary load, retry from source; if clBuildProgram succeeds, the cached binary—not the device—was the problem. There is no portable command to list or clear an ICD cache directory.

Missing diagnostic detail

Do you own the binary cache files, or are you relying on the ICD vendor cache directory? If you do not own the files, there is no safe portable way to invalidate a single entry, and the recommendation changes to always compiling from source or accepting vendor-specific behavior.

Assumes OpenCL 1.2 or later with an ICD loader. Driver version string parsing is heuristic because formats vary by vendor.