| --- |
| license: apache-2.0 |
| library_name: kernels |
| tags: |
| - kernel |
| - xpu |
| - sycl |
| - intel |
| - dispatch |
| --- |
| |
| # xpu-caps |
|
|
| Runtime capability tiering for Intel GPUs, loadable through `kernels`. It |
| reports what the active device supports and resolves a dispatch tier other |
| kernels select paths on, the way an aarch64 kernel picks between SDOT, base |
| NEON, and scalar. Every field with an independent source is cross-checked |
| against `torch.xpu.get_device_capability`. |
|
|
| Intel GPUs span parts with and without XMX, bf16, and fp64, and there is no |
| shared way to ask which one you are on, so kernels either assume recent |
| discrete hardware and do nothing useful elsewhere, or hard-code a fallback |
| and leave the matrix engine idle. This kernel answers the question once, and |
| it answers a second one nothing else does: whether the backend actually |
| executes. A capability query cannot detect a backend that compiles, |
| launches, synchronizes, and returns success while writing nothing; only |
| running a kernel and checking its output can. |
|
|
|  |
|
|
| *Probed live on an Intel Iris Xe: the ladder resolves to `simd_fp16` (fp16 arithmetic, no matrix engine) on a 96-EU integrated part with no XMX and no fp64, and `self_test()` runs a real kernel and verifies its output, which a capability query cannot do.* |
|
|
| ## Usage |
|
|
| ```python |
| from kernels import get_kernel |
| |
| caps_mod = get_kernel("phanerozoic/xpu-caps", version=1, trust_remote_code=True) |
| |
| caps = caps_mod.capabilities() |
| print(caps.tier) # 'simd_fp16' |
| print(caps.has_xmx, caps.has_bf16, caps.is_integrated) |
| |
| assert caps_mod.self_test() # the backend actually executes |
| ``` |
|
|
| `version` selects the release branch; `trust_remote_code` is required by |
| `kernels` for publishers without the trusted-publisher mark. |
|
|
| ## API |
|
|
| | Symbol | Purpose | |
| |---|---| |
| | `capabilities()` | device capability record and resolved dispatch tier | |
| | `self_test()` | run a real kernel and verify its output on the host | |
|
|
| Reported fields: `has_fp16`, `has_fp64`, `has_bf16`, `has_atomic64`, |
| `has_xmx`, `is_integrated`, `max_work_group_size`, `local_mem_size`, |
| `max_compute_units`, `global_mem_mib`, `eu_count`, `eu_simd_width`, |
| `subslices_per_slice`, `max_mem_bandwidth`, `sub_group_sizes`, |
| `max_sub_group_size`. |
|
|
| ## Method |
|
|
| Tiers, ordered by capability: |
|
|
| | tier | condition | |
| |---|---| |
| | `xmx_bf16` | matrix engine with bf16 operands | |
| | `xmx_fp16` | matrix engine, fp16 operands | |
| | `simd_fp16` | fp16 arithmetic, no matrix engine | |
| | `simd_fp32` | fp32 only | |
| | `scalar` | fallback | |
|
|
| `XPU_CAPS_TIER` demotes the reported tier for exercising a fallback path. It |
| may only lower it; requesting a tier the device does not support raises. |
|
|
| `self_test()` runs a kernel whose output depends on both the global index |
| and a group reduction, then verifies the result on the host. This exists |
| because Triton on Gen12LP does exactly the failure it catches: kernels |
| return exit code 0 with the output buffer untouched. |
|
|
| `has_bf16` comes from torch's device query; oneAPI 2026.0 exposes no bf16 |
| SYCL aspect. |
|
|
| ## Validation |
|
|
| Sixteen checks on Intel Iris Xe (Gen12LP, 96 EUs), torch 2.13.0+xpu. Every |
| field with an independent source is cross-checked against |
| `torch.xpu.get_device_capability`: `has_fp16`, `has_fp64`, `has_atomic64`, |
| `has_xmx`, `max_work_group_size`, `max_compute_units`, and `eu_count` all |
| agree exactly. The execution probe is verified element-exact at n = 1, 255, |
| 256, 1000, and 65536, covering the partial-work-group tail. |
|
|
| ## Requirements and limits |
|
|
| - Intel GPU with a working Level Zero driver and a torch XPU build. |
| - The tier is a capability statement, not a performance model: a device may |
| report `xmx_fp16` and still be slower than a larger `simd_fp16` part. |
|
|
| ## References |
|
|
| SYCL device aspects and the Level Zero device query; `torch.xpu` device |
| capability reporting. |
|
|
| ## License |
|
|
| Apache-2.0. |
|
|
|
|
|
|
