Module Sarek_opencl.Opencl_warp_probe

Sub-group probe of an OpenCL device (docs/plans/warp-shuffle-intake-2026-10-17.md, section 6.5).

OpenCL does not tie the sub-group lane to the linear local id. The warp shuffles are specified over the lane (lane = linear thread id mod W), so a device may run them only if that equality is MEASURED. The probe compiles one tiny kernel and runs it for two block shapes, 64x1 and 8x8; each work-item reports get_sub_group_size() and get_sub_group_local_id(). The device is accepted when every work-item reports the same size W and its lane equals its linear id modulo W in both shapes. W also replaces the constant 32 the plugin used to report as warp_size.

The probe is made once per device and cached by the caller. It uses its own context and queue, released before returning, so it never perturbs the plugin's per-device state. Any failure is "no sub-group support": the feature is not claimed.

type t = {
  1. width : int;
    (*

    the sub-group size reported by the device

    *)
  2. lane_mapping_ok : bool;
    (*

    lane = linear thread id mod width in every probed shape

    *)
  3. failing_shape : (int * int) option;
    (*

    the first block shape (x, y) that broke the mapping

    *)
}
val probe_source : string
val shapes : (int * int) list
val shape_fits : Opencl_api.Device.t -> (int * int) -> bool
val run_shape : Opencl_api.CommandQueue.t -> Opencl_api.Kernel.t -> 'a Opencl_api.Memory.buffer -> (int * int) -> (int * int) array
val evaluate_shape : int -> (int * int) array -> bool
val measure : Opencl_api.Device.t -> t
val probe : Opencl_api.Device.t -> t option

probe d measures d, or None when the device cannot run the probe (no sub-group support, a compile or launch failure). Never raises.

val features_of_probe : t option -> Sarek_ir_analysis.feature list

The capability a probe result earns: Warp_shuffle only when the lane mapping was measured, in every probed shape, on a device that reported a sub-group size. The extension strings alone never grant it.

val warp_size_of_probe : t option -> int

The warp_size a device reports: the measured sub-group size, or 1 when the device has no sub-group support (no warp structure is known). It used to be the constant 32.