---
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.

![A tier ladder resolving to simd_fp16 on a live probe, with the device facts and an execution self-test](https://huggingface.co/kernels/phanerozoic/xpu-caps/resolve/main/media/hero.gif)

*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.