feat(api): import HIP device frames, dma-bufs and GL textures with event and sync_file fences (RC4 WP3, ADR-2092)

.config/clang-tidy/measured-sources.txt

@@ -291,6 +291,12 @@ core/src/framesync.c
 core/src/gpu_dispatch_env.cpp
 core/src/gpu_picture_pool.cpp
 core/src/hip/common.c
+core/src/hip/import_convert.hip
+core/src/hip/import_device.c
+core/src/hip/import_dmabuf.c
+core/src/hip/import_fence.c
+core/src/hip/import_frame.c
+core/src/hip/import_gl.c
 core/src/hip/kernel_template.c
 core/src/hip/picture_hip.c
 core/src/hip/shared_frame.c
@@ -352,6 +358,7 @@ core/src/vmafx/frame_import.c
 core/src/vmafx/frame_import_admit.c
 core/src/vmafx/frame_import_hooks.c
 core/src/vmafx/frame_pool.c
+core/src/vmafx/gl_sync.c
 core/src/vmafx/mcp_server.c
 core/src/vmafx/model.c
 core/src/vmafx/options.c
@@ -360,13 +367,15 @@ core/src/vmafx/provenance_build.c
 core/src/vmafx/provenance_json.c
 core/src/vmafx/provenance_render.c
 core/src/vmafx/register.c
+core/src/vmafx/release_events.c
 core/src/vmafx/report.c
 core/src/vmafx/report_verify.c
 core/src/vmafx/score.c
 core/src/vmafx/sha256.c
 core/src/vmafx/sized.c
 core/src/vmafx/status_gen.c
 core/src/vmafx/submit.c
+core/src/vmafx/sync_file.c
 core/src/vmafx/tiny_model.c
 core/src/vmafx/window.c
 core/src/vmafx/window_clock.c
@@ -812,6 +821,7 @@ core/test/test_vmafx_api_slice.c
 core/test/test_vmafx_bitexact.c
 core/test/test_vmafx_context.c
 core/test/test_vmafx_exactness.c
+core/test/test_vmafx_fence_kinds.c
 core/test/test_vmafx_frame.c
 core/test/test_vmafx_frame_input.c
 core/test/test_vmafx_host_fence_wait.c
@@ -822,6 +832,10 @@ core/test/test_vmafx_import_cuda_bitexact.c
 core/test/test_vmafx_import_cuda_fence.c
 core/test/test_vmafx_import_cuda_gl.c
 core/test/test_vmafx_import_fence.c
+core/test/test_vmafx_import_hip.c
+core/test/test_vmafx_import_hip_bitexact.c
+core/test/test_vmafx_import_hip_fence.c
+core/test/test_vmafx_import_hip_gl.c
 core/test/test_vmafx_lifetime.c
 core/test/test_vmafx_live_pacing.c
 core/test/test_vmafx_log_routing.c

changelog.d/added/api-hip-device-frames.md

@@ -0,0 +1,22 @@
+- **VMAFx device frames on HIP (RC4, ADR-2092).** In a build with the HIP
+  backend the VMAFx API creates HIP devices by index or from your stream
+  (`vmafx_device_create` with `VMAFX_BACKEND_HIP`), scores a context on one
+  (`vmafx_context_use_device`; features registered afterwards run on their
+  HIP twins) and imports frames without a copy through the host
+  (`vmafx_frame_import`): HIP device pointers at any offset and pitch,
+  dma-bufs (`VMAFX_MEMORY_DMABUF`, imported as external memory), HIP arrays
+  and OpenGL textures from a GLX context on the device's GPU; NV12, P010 and
+  P016 are planarised on the device. Acquire fences of kind
+  `VMAFX_FENCE_HIP_EVENT` are waited on by the device's stream;
+  `VMAFX_FENCE_SYNC_FILE` (for example a dma-buf's exported sync_file) and
+  `VMAFX_FENCE_GL_SYNC` are checked on the host and waited for by
+  `vmafx_context_import_frame`. Release fences (`VMAFX_FENCE_HOST`,
+  `VMAFX_FENCE_HIP_EVENT`) are signalled after the last reader in every
+  context, and the release callback runs after them. `vmafx_fence_wait`
+  waits on `VMAFX_FENCE_SYNC_FILE` and `VMAFX_FENCE_GL_SYNC` fences in every
+  build. Imported frames score bit for bit as the same frames uploaded from
+  the host. A HIP device has no frame pools, and a `VMAFX_FENCE_SYNC_FILE`
+  release fence is refused (the ROCm runtime cannot signal one). With ROCm
+  10.1, whose runtime maps a GL texture but cannot read it, GL imports are
+  refused with `VMAFX_E_NOTSUP` naming the runtime. See
+  [HIP devices](docs/api/vmafx/index.md#hip-devices).

changelog.d/changed/float-vif-hip-autodispatch-default.md

@@ -0,0 +1,8 @@
+- **`float_vif_hip` runs for `float_vif` under `--backend hip` by default
+  (ADR-2092).** The build option `enable_float_vif_hip_autodispatch` now
+  defaults to `true`, so `--backend hip --feature float_vif`, models that
+  read `float_vif` and a VMAFx context on a HIP device run the HIP twin, which
+  returns the CPU's scores bit for bit (ADR-1444), instead of the CPU
+  extractor. Build with `-Denable_float_vif_hip_autodispatch=false` for the
+  old behaviour, where the twin runs only as `--feature float_vif_hip`. See
+  [`enable_float_vif_hip_autodispatch`](docs/development/build-flags.md#enable_float_vif_hip_autodispatch).

changelog.d/changed/hip-twins-device-level0.md

@@ -0,0 +1,5 @@
+- **`psnr_hvs_hip`, `ssimulacra2_hip` and `float_ms_ssim_hip` read device
+  frames on the device (ADR-2092).** Given a frame in HIP device memory, the
+  three twins that staged planes on the host copy or convert them on the
+  device (`float_ms_ssim_hip` builds level 0 with a kernel of the same
+  arithmetic as `picture_copy()`); host frames are read as before.

core/api/vmafx.toml

@@ -345,12 +345,12 @@ values = [
   { name = "VMAFX_MEMORY_NONE", value = 0, doc = "Not set; refused by vmafx_frame_import()." },
   { name = "VMAFX_MEMORY_HOST", value = 1, doc = "Host memory the CPU reads: `handle` is the address of the plane's allocation, `offset` the bytes to its first sample." },
   { name = "VMAFX_MEMORY_DEVICE_POINTER", value = 2, doc = "A device pointer (CUDA or HIP device pointer, SYCL USM pointer) in the device's context." },
-  { name = "VMAFX_MEMORY_DEVICE_ARRAY", value = 3, doc = "A device array (CUDA array) in the device's context." },
+  { name = "VMAFX_MEMORY_DEVICE_ARRAY", value = 3, doc = "A device array (CUDA or HIP array) in the device's context." },
   { name = "VMAFX_MEMORY_DMABUF", value = 4, doc = "A Linux dma-buf: `fd`, `offset`, `pitch`, `modifier` and `size` of the object the plane lives in." },
   { name = "VMAFX_MEMORY_METAL_SURFACE", value = 5, doc = "A shared surface: `handle` is the surface, `plane_index` its plane." },
   { name = "VMAFX_MEMORY_METAL_TEXTURE", value = 6, doc = "A Metal texture per plane: `handle` is the texture." },
   { name = "VMAFX_MEMORY_WIN32_SHARED", value = 7, doc = "A Windows shared texture: `handle` is the shared NT handle, `plane_index` its plane." },
-  { name = "VMAFX_MEMORY_GL_TEXTURE", value = 8, doc = "An OpenGL 2D texture (`GL_TEXTURE_2D`) of the GL context current on the calling thread: `handle` is the texture name, one texture per plane (NV12: an R8 luma and an RG8 chroma texture). Imported on a device of a backend with GL interop (CUDA). Added in ABI 0.1.7." },
+  { name = "VMAFX_MEMORY_GL_TEXTURE", value = 8, doc = "An OpenGL 2D texture (`GL_TEXTURE_2D`) of the GL context current on the calling thread: `handle` is the texture name, one texture per plane (NV12: an R8 luma and an RG8 chroma texture). Imported on a device of a backend with GL interop (CUDA; HIP from a GLX context of the device's GPU). Added in ABI 0.1.7." },
 ]
 
 [[enums]]
@@ -364,7 +364,7 @@ values = [
   { name = "VMAFX_FENCE_CUDA_EVENT", value = 2, doc = "A CUDA event (`handle`) of the device's context." },
   { name = "VMAFX_FENCE_HIP_EVENT", value = 3, doc = "A HIP event (`handle`) of the device." },
   { name = "VMAFX_FENCE_SYCL_EVENT", value = 4, doc = "A pointer to a SYCL event (`handle`) of the device's context." },
-  { name = "VMAFX_FENCE_SYNC_FILE", value = 5, doc = "A Linux sync_file descriptor (`fd`)." },
+  { name = "VMAFX_FENCE_SYNC_FILE", value = 5, doc = "A Linux sync_file descriptor (`fd`), borrowed: an acquire fence a device without a kernel-scheduled queue checks on the host (HIP)." },
   { name = "VMAFX_FENCE_METAL_SHARED_EVENT", value = 6, doc = "A Metal shared event (`handle`) and the value it reaches when signalled (`value`)." },
   { name = "VMAFX_FENCE_WIN32_SHARED", value = 7, doc = "A Windows shared fence (`handle`, an NT handle) and the value it reaches when signalled (`value`)." },
   { name = "VMAFX_FENCE_GL_SYNC", value = 8, doc = "An OpenGL sync object (`handle`, a `GLsync`) of the GL context current on the calling thread, or of a context sharing objects with it; an acquire fence of VMAFX_MEMORY_GL_TEXTURE imports. Added in ABI 0.1.7." },
@@ -691,10 +691,10 @@ since = "0.1"
 sized = true
 doc = "Which device to create. Initialise with VMAFX_DEVICE_DESC_INIT."
 fields = [
-  { name = "backend", type = "u32", enum = "VmafxBackend", doc = "Backend of the device: CPU in every build, CUDA in a build with the CUDA backend; another backend is VMAFX_E_NOTSUP naming it." },
+  { name = "backend", type = "u32", enum = "VmafxBackend", doc = "Backend of the device: CPU in every build, CUDA or HIP in a build with that backend; another backend is VMAFX_E_NOTSUP naming it." },
   { name = "index", type = "i32", doc = "Device index within the backend (see vmafx_device_count()); -1: any device of the backend. Ignored when `external[0]` is set." },
   { name = "flags", type = "u32", flags = "VmafxDeviceFlags", doc = "How to create the device. Added in ABI 0.1.2." },
-  { name = "external", type = "uptr", count = 2, doc = "The caller's runtime objects, which stay the caller's and must outlive the device: CUDA context and stream, SYCL queue and 0, HIP device and stream, Metal device and command queue. 0: the library creates its own. The CPU takes none. Added in ABI 0.1.2." },
+  { name = "external", type = "uptr", count = 2, doc = "The caller's runtime objects, which stay the caller's and must outlive the device: CUDA context and stream, SYCL queue and 0, HIP stream and 0 (the device is the stream's), Metal device and command queue. 0: the library creates its own. The CPU takes none. Added in ABI 0.1.2." },
 ]
 
 [[structs]]
@@ -759,7 +759,7 @@ fields = [
   { name = "plane", type = "VmafxImportPlane", count = 3, doc = "Each plane; entries past `n_planes` are ignored." },
   { name = "acquire", type = "VmafxFence", doc = "Signalled when the producer has written the planes. Borrowed for the call: the library takes what it needs (a reference, a duplicated descriptor, a device-side wait). NONE: the planes are written." },
   { name = "flags", type = "u32", flags = "VmafxImportFlags", doc = "0: zero copy only." },
-  { name = "release", type = "VmafxFrameReleaseCallback", doc = "Called once, on the thread that drops the frame's last reference, after its release fences were signalled or recorded: a CUDA_EVENT release fence can be waited on from here (a producer makes its stream wait on it before it reuses the planes, with no host wait); NULL: none. Added in ABI 0.1.7." },
+  { name = "release", type = "VmafxFrameReleaseCallback", doc = "Called once, on the thread that drops the frame's last reference, after its release fences were signalled or recorded: a CUDA_EVENT or HIP_EVENT release fence can be waited on from here (a producer makes its stream wait on it before it reuses the planes, with no host wait); NULL: none. Added in ABI 0.1.7." },
   { name = "user", type = "ptr", doc = "Passed to `release`. Added in ABI 0.1.7." },
 ]
 
@@ -1365,7 +1365,7 @@ name = "vmafx_frame_release_fence"
 header = "vmafx/frame.h"
 since = "0.1"
 returns = "status"
-doc = "A fence of `kind` signalled once the last reference of the frame is gone, in every context it was submitted to: from then on the library reads none of its memory and the producer may reuse it. Call it while holding a reference, before the frame is submitted; each call returns a new fence the caller destroys. HOST: signalled when the device has run the frame's last reader. CUDA_EVENT: an event the library records on its stream behind the last reader where the last reference is dropped; vmafx_fence_wait() waits for the recording too, while a stream wait on it means something only from the frame's release callback (VmafxFrameImport.release) or after a host wait returned. A kind the frame's device cannot signal is VMAFX_E_NOTSUP naming it."
+doc = "A fence of `kind` signalled once the last reference of the frame is gone, in every context it was submitted to: from then on the library reads none of its memory and the producer may reuse it. Call it while holding a reference, before the frame is submitted; each call returns a new fence the caller destroys. HOST: signalled when the device has run the frame's last reader. CUDA_EVENT, HIP_EVENT: an event the library records on its stream behind the last reader where the last reference is dropped; vmafx_fence_wait() waits for the recording too, while a stream wait on it means something only from the frame's release callback (VmafxFrameImport.release) or after a host wait returned. A kind the frame's device cannot signal is VMAFX_E_NOTSUP naming it."
 params = [
   { name = "frame", type = "VmafxFrame", pass = "in" },
   { name = "kind", type = "u32", pass = "in" },

core/include/vmafx/device.h

@@ -51,7 +51,7 @@ struct VmafxDeviceDesc {
     /** Size of this struct as the caller compiled it; set by the _INIT macro. */
     uint32_t struct_size;
     /**
-     * Backend of the device: CPU in every build, CUDA in a build with the CUDA backend; another
+     * Backend of the device: CPU in every build, CUDA or HIP in a build with that backend; another
      * backend is VMAFX_E_NOTSUP naming it. Values: VmafxBackend.
      */
     uint32_t backend;
@@ -64,8 +64,9 @@ struct VmafxDeviceDesc {
     uint32_t flags;
     /**
      * The caller's runtime objects, which stay the caller's and must outlive the device: CUDA
-     * context and stream, SYCL queue and 0, HIP device and stream, Metal device and command queue.
-     * 0: the library creates its own. The CPU takes none. Added in ABI 0.1.2.
+     * context and stream, SYCL queue and 0, HIP stream and 0 (the device is the stream's), Metal
+     * device and command queue. 0: the library creates its own. The CPU takes none. Added in ABI
+     * 0.1.2.
      */
     uintptr_t external[2];
 };

core/include/vmafx/frame.h

@@ -39,7 +39,7 @@ typedef enum VmafxMemoryKind {
     VMAFX_MEMORY_HOST = 1,
     /** A device pointer (CUDA or HIP device pointer, SYCL USM pointer) in the device's context. */
     VMAFX_MEMORY_DEVICE_POINTER = 2,
-    /** A device array (CUDA array) in the device's context. */
+    /** A device array (CUDA or HIP array) in the device's context. */
     VMAFX_MEMORY_DEVICE_ARRAY = 3,
     /**
      * A Linux dma-buf: `fd`, `offset`, `pitch`, `modifier` and `size` of the object the plane lives
@@ -55,7 +55,8 @@ typedef enum VmafxMemoryKind {
     /**
      * An OpenGL 2D texture (`GL_TEXTURE_2D`) of the GL context current on the calling thread:
      * `handle` is the texture name, one texture per plane (NV12: an R8 luma and an RG8 chroma
-     * texture). Imported on a device of a backend with GL interop (CUDA). Added in ABI 0.1.7.
+     * texture). Imported on a device of a backend with GL interop (CUDA; HIP from a GLX context of
+     * the device's GPU). Added in ABI 0.1.7.
      */
     VMAFX_MEMORY_GL_TEXTURE = 8,
 } VmafxMemoryKind;
@@ -75,7 +76,10 @@ typedef enum VmafxFenceKind {
     VMAFX_FENCE_HIP_EVENT = 3,
     /** A pointer to a SYCL event (`handle`) of the device's context. */
     VMAFX_FENCE_SYCL_EVENT = 4,
-    /** A Linux sync_file descriptor (`fd`). */
+    /**
+     * A Linux sync_file descriptor (`fd`), borrowed: an acquire fence a device without a kernel-
+     * scheduled queue checks on the host (HIP).
+     */
     VMAFX_FENCE_SYNC_FILE = 5,
     /** A Metal shared event (`handle`) and the value it reaches when signalled (`value`). */
     VMAFX_FENCE_METAL_SHARED_EVENT = 6,
@@ -307,9 +311,9 @@ struct VmafxFrameImport {
     uint32_t flags;
     /**
      * Called once, on the thread that drops the frame's last reference, after its release fences
-     * were signalled or recorded: a CUDA_EVENT release fence can be waited on from here (a producer
-     * makes its stream wait on it before it reuses the planes, with no host wait); NULL: none.
-     * Added in ABI 0.1.7.
+     * were signalled or recorded: a CUDA_EVENT or HIP_EVENT release fence can be waited on from
+     * here (a producer makes its stream wait on it before it reuses the planes, with no host wait);
+     * NULL: none. Added in ABI 0.1.7.
      */
     VmafxFrameReleaseCallback release;
     /** Passed to `release`. Added in ABI 0.1.7. */
@@ -507,11 +511,11 @@ VMAFX_EXPORT VmafxStatus vmafx_frame_import(VmafxDevice *device, const VmafxFram
  * A fence of `kind` signalled once the last reference of the frame is gone, in every context it was
  * submitted to: from then on the library reads none of its memory and the producer may reuse it.
  * Call it while holding a reference, before the frame is submitted; each call returns a new fence
- * the caller destroys. HOST: signalled when the device has run the frame's last reader. CUDA_EVENT:
- * an event the library records on its stream behind the last reader where the last reference is
- * dropped; vmafx_fence_wait() waits for the recording too, while a stream wait on it means
- * something only from the frame's release callback (VmafxFrameImport.release) or after a host wait
- * returned. A kind the frame's device cannot signal is VMAFX_E_NOTSUP naming it.
+ * the caller destroys. HOST: signalled when the device has run the frame's last reader. CUDA_EVENT,
+ * HIP_EVENT: an event the library records on its stream behind the last reader where the last
+ * reference is dropped; vmafx_fence_wait() waits for the recording too, while a stream wait on it
+ * means something only from the frame's release callback (VmafxFrameImport.release) or after a host
+ * wait returned. A kind the frame's device cannot signal is VMAFX_E_NOTSUP naming it.
  * @since 0.1
  */
 VMAFX_EXPORT VmafxStatus vmafx_frame_release_fence(VmafxFrame *frame, uint32_t kind,

core/meson_options.txt

@@ -119,8 +119,8 @@ option('enable_hipcc',
 
 option('enable_float_vif_hip_autodispatch',
     type: 'boolean',
-    value: false,
-    description: 'Enable automatic model-driven dispatch of float_vif_hip by setting VMAF_FEATURE_EXTRACTOR_HIP on its descriptor (ADR-0623). Default OFF pending T7-10c picture-pool plumbing: without the pool, pictures arrive as CPU VmafPictures and the extractor performs explicit HtoD copies rather than zero-copy from the HIP picture pool. Enable only after T7-10c lands.')
+    value: true,
+    description: 'Set VMAF_FEATURE_EXTRACTOR_HIP on float_vif_hip, so --backend hip and a VMAFx context on a HIP device pick it for float_vif (ADR-0623, ADR-2092). Default ON since the HIP lane of the VMAFx API reads device frames on the device, the condition ADR-0623 waited for (T7-10c). OFF: the twin runs only when named, and imported HIP frames are refused for float_vif.')
 
 option('nvcc_threads',
     type: 'integer',