#23576 added `query_capabilities` to the device vtable but left the
Vulkan implementation as a bare `UNIMPLEMENTED` return. Every other
driver (local_task, local_sync, HIP, CUDA, Metal, null, AMDGPU) got
the correct `memset + ok_status` stub. The Vulkan driver was the sole
holdout, which meant device group creation — now required by the HAL
module — failed immediately for any Vulkan device.

This broke every Vulkan CI job, but I didn't notice because the AMD
GPU runners have been flaky for months and I'd stopped reading those
failures carefully. Lesson learned.

Co-Authored-By: Claude <[email protected]>

)

#23576 added `query_capabilities` to the device vtable but left the
Vulkan implementation as a bare `UNIMPLEMENTED` return. Every other
driver (local_task, local_sync, HIP, CUDA, Metal, null, AMDGPU) got the
correct `memset + ok_status` stub. The Vulkan driver was the sole
holdout, which meant device group creation — now required by the HAL
module — failed immediately for any Vulkan device.

This broke every Vulkan CI job, but I didn't notice because the AMD GPU
runners have been flaky for months and I'd stopped reading those
failures carefully. Lesson learned.

Co-authored-by: Claude <[email protected]>

…ange

This commit updates shortfin to work with IREE PR #23576 (commit eacda0d,
Feb 25, 2026), which introduced iree_hal_device_group_t to own device
topology lifecycle.

Background:
-----------
IREE PR #23576 refactored the HAL module API to fix a lifetime ownership
problem. Previously, devices received raw pointers to topology data with
no guarantees that those pointers remained valid. The new device_group
abstraction owns the device lifecycle and ensures topology pointer
validity.

API Changes:
------------
The iree_hal_module_create() signature changed from 8 to 7 parameters:

Before:
  iree_hal_module_create(instance, policy, device_count, devices[],
                        flags, debug_sink, allocator, out_module)

After:
  iree_hal_module_create(instance, policy, device_group,
                        flags, debug_sink, allocator, out_module)

Implementation:
---------------
1. Added hal_device_group_ptr smart pointer wrapper in iree_helpers.h
   using the SHORTFIN_IREE_DEF_PTR macro

2. Updated program.cc to create device groups before module creation:
   - Single device: Uses iree_hal_device_group_create_from_device()
   - Multiple devices: Uses builder pattern with
     iree_hal_device_group_builder_* APIs

Benefits:
---------
- Clear lifetime semantics (module retains group; group retains devices)
- Topology safety (pointers guaranteed valid for device lifetime)
- Simplified allocation (no flexible array members)

References:
-----------
- IREE PR: iree-org/iree#23576
- Commit: eacda0d84b0a357d5ea701fec9137346fc724f59

Co-Authored-By: Claude Opus 4.6 <[email protected]>

…org#23576)

The topology matrix from iree-org#23573 needs an owner with a clear lifetime
contract. Today devices are passed to the HAL module as a flat array —
there is no object that retains the devices, owns the topology, and
guarantees the topology pointer remains valid for the duration of
execution. Every device holds a raw pointer to the topology it was
assigned, so if the topology is freed while devices are still alive,
those pointers dangle.

`iree_hal_device_group_t` is that owner. It takes already-created
devices, builds the immutable topology matrix from their capabilities,
pushes topology info into each device, and retains all of them. The
group's lifetime brackets the devices': whoever holds the devices
long-term (the HAL module, the CTS harness, a Python session) retains
the group, and the group retains the devices, so the topology pointer in
each device is guaranteed valid.

### Creation API

The builder pattern matches the topology builder it wraps:
stack-allocate, add devices, finalize. Finalize is a consuming operation
— it queries capabilities from all devices, computes edge descriptors,
calls driver-specific refinement for same-driver pairs, builds the
topology matrix, assigns topology info into each device via the new
vtable method, and produces the immutable group. The builder is zeroed
after finalize (whether it succeeds or fails) and cannot be reused.

For the common single-device case (7 of 9 callers),
`iree_hal_device_group_create_from_device` wraps the builder sequence
into a one-liner.

### `assign_topology_info` vtable method

Devices need to receive their topology info after the matrix is built —
the topology doesn't exist yet when the device is created, and the
device's index in the matrix isn't known until group creation. This is a
new vtable method on `iree_hal_device_t` that the group calls during
finalize. All existing driver implementations (local-sync, local-task,
CUDA, HIP, Vulkan, Metal, AMDGPU, null) store the info into their device
struct. The method is called exactly once per device, during group
creation.

### HAL module integration

`iree_hal_module_create` now takes a `iree_hal_device_group_t*` instead
of `(device_count, devices[])`. The module retains the group and
delegates all device access through `iree_hal_device_group_device_count`
/ `iree_hal_device_group_device_at`. This eliminates the flexible array
member from `iree_hal_module_t`, simplifies allocation (fixed-size
struct instead of variable-size), and makes the lifetime contract
explicit: the module holds the group, the group holds the devices and
topology.

All callers are updated — CLI tooling, the high-level runtime session,
TFLite bindings, Python bindings, PJRT, ConstEval, simple_embedding
samples, check_test, and the CTS test harness.

### Testing

A mock device (`hal/testing/mock_device`) provides controllable
capabilities for testing topology construction without requiring real
hardware. The device group tests exercise builder validation (empty
builds, duplicate devices, capacity limits), single-device and
multi-device group creation, topology correctness (self-edges,
cross-device edges with expected interop modes), the convenience
function, and lifetime ordering (group outlives devices). The CTS test
harness creates a device group in `SetUpTestSuite` so every CTS test
runs with topology info assigned.

### Where this is going

The device group is the scheduling domain for the causal execution
system. When the AMDGPU driver gets its frontier-integrated semaphores
and queue operations, the device group's topology matrix is what tells
the scheduler whether a semaphore can be waited on natively or needs
handle import, whether a buffer can be read directly or needs DMA
transfer, and what the relative cost is. The group also becomes the
natural attachment point for collective channel creation and
multi-device resource pools.

---------

Co-authored-by: Claude <[email protected]>

…e-org#23582)

iree-org#23576 added `query_capabilities` to the device vtable but left the
Vulkan implementation as a bare `UNIMPLEMENTED` return. Every other
driver (local_task, local_sync, HIP, CUDA, Metal, null, AMDGPU) got the
correct `memset + ok_status` stub. The Vulkan driver was the sole
holdout, which meant device group creation — now required by the HAL
module — failed immediately for any Vulkan device.

This broke every Vulkan CI job, but I didn't notice because the AMD GPU
runners have been flaky for months and I'd stopped reading those
failures carefully. Lesson learned.

Co-authored-by: Claude <[email protected]>