Skip to contentSkip to conversation

Xe driver watch-queue implementation and example

RFC PATCH New Thomas Hellström 1 participant 3 messages Mar 4

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

cover Xe driver watch-queue implementation and example

This series aims to provide an example how to use the xe driver watch-queue interface. The interface provides a means for user-space render clients to get asynchronous notifications with metadata attached.

The primary use-case would be the LR mode rebind worker running out of memory. Currently the VM gets killed, but it should be possible to recover, unbind buffer objects and restart.

Thomas Hellström (2):
lib/xe: add xe_watch listener for watch queue events tests/intel/xe_exec_compute_mode: Add a listener for file events

 include/drm-uapi/xe_drm.h          |  46 ++++++
 include/drm-uapi/xe_drm_events.h   |  65 +++++++++
 lib/meson.build                    |   1 +
 lib/xe/xe_watch.c                  | 221 +++++++++++++++++++++++++++++
 lib/xe/xe_watch.h                  |  80 +++++++++++
 tests/intel/xe_exec_compute_mode.c |  59 +++++++-
 6 files changed, 470 insertions(+), 2 deletions(-)
 create mode 100644 include/drm-uapi/xe_drm_events.h
 create mode 100644 lib/xe/xe_watch.c
 create mode 100644 lib/xe/xe_watch.h
Signature · 1 line
2.53.0
#1 lore raw

RFC PATCH 1/2 lib/xe: add xe_watch listener for watch queue events

Add a new xe_watch library module that subscribes an Xe device file descriptor to kernel watch queue notifications and dispatches them to a caller-supplied handler from a background pthread.

The public API consists of two functions and three types:

xe_watch_listener_create(xe_fd, event)
Opens an O_NOTIFICATION_PIPE, sizes it, filters it to WATCH_TYPE_DRM_NOTIFY events, registers it with the Xe device via DRM_IOCTL_XE_WATCH_QUEUE, and starts a worker pthread.

xe_watch_listener_destroy(listener)
Signals the worker to exit via an internal stop-pipe, joins the thread, and frees all resources.

struct xe_watch_event / xe_watch_event_ops / xe_watch_event_fn
Caller embeds struct xe_watch_event in its own private state and points ops->event_deliver at its handler. The worker sets event->notif (a struct watch_notification *) before each call, and the handler uses container_of() to recover its private context.

The implementation relies on the userspace-safe guard added to <linux/watch_queue.h> so it can be included from xe_drm.h directly. A WATCH_TYPE_DRM_XE_NOTIFY fallback define is provided for build environments whose system header predates that define.

xe_drm.h is updated to match the upstream watch_queue branch:
- Add DRM_XE_WATCH_QUEUE ioctl number (0x0f) and DRM_IOCTL_XE_WATCH_QUEUE macro.
- Add struct drm_xe_watch_queue, enum drm_xe_watch_event

    (DRM_XE_WATCH_EVENT_VM_ERR = 0), and
    struct drm_xe_watch_notification_vm_oom.
Assisted-by GitHub Copilot:claude-sonnet-4.6
---
 include/drm-uapi/xe_drm.h        |  46 +++++++
 include/drm-uapi/xe_drm_events.h |  65 +++++++++
 lib/meson.build                  |   1 +
 lib/xe/xe_watch.c                | 221 +++++++++++++++++++++++++++++++
 lib/xe/xe_watch.h                |  80 +++++++++++
 5 files changed, 413 insertions(+)
 create mode 100644 include/drm-uapi/xe_drm_events.h
 create mode 100644 lib/xe/xe_watch.c
 create mode 100644 lib/xe/xe_watch.h
include/drm-uapi/xe_drm.h +46 -0
index f7abd9b37..934d92634 100644
@@ -83,6 +83,7 @@ extern "C" {
  *  - &DRM_IOCTL_XE_OBSERVATION
  *  - &DRM_IOCTL_XE_MADVISE
  *  - &DRM_IOCTL_XE_VM_QUERY_MEM_RANGE_ATTRS
+ *  - &DRM_IOCTL_XE_WATCH_QUEUE
  */
 
 /*
@@ -107,6 +108,7 @@ extern "C" {
 #define DRM_XE_MADVISE			0x0c
 #define DRM_XE_VM_QUERY_MEM_RANGE_ATTRS	0x0d
 #define DRM_XE_EXEC_QUEUE_SET_PROPERTY	0x0e
+#define DRM_XE_WATCH_QUEUE		0x0f
 
 /* Must be kept compact -- no holes */
 
@@ -125,6 +127,7 @@ extern "C" {
 #define DRM_IOCTL_XE_MADVISE			DRM_IOW(DRM_COMMAND_BASE + DRM_XE_MADVISE, struct drm_xe_madvise)
 #define DRM_IOCTL_XE_VM_QUERY_MEM_RANGE_ATTRS	DRM_IOWR(DRM_COMMAND_BASE + DRM_XE_VM_QUERY_MEM_RANGE_ATTRS, struct drm_xe_vm_query_mem_range_attr)
 #define DRM_IOCTL_XE_EXEC_QUEUE_SET_PROPERTY	DRM_IOW(DRM_COMMAND_BASE + DRM_XE_EXEC_QUEUE_SET_PROPERTY, struct drm_xe_exec_queue_set_property)
+#define DRM_IOCTL_XE_WATCH_QUEUE		DRM_IOW(DRM_COMMAND_BASE + DRM_XE_WATCH_QUEUE, struct drm_xe_watch_queue)
 
 /**
  * DOC: Xe IOCTL Extensions
@@ -2363,6 +2366,49 @@ struct drm_xe_exec_queue_set_property {
 	__u64 reserved[2];
 };
 
+/**
+ * DOC: DRM_XE_WATCH_QUEUE
+ *
+ * Subscribe a notification pipe to receive device events for the calling
+ * process's DRM file handle.  Events are scoped to the subscribing file:
+ * only events that belong to that file (for example, VM error on a VM created
+ * through the same file) are delivered, preventing information leaks between
+ * processes sharing the same GPU device.
+ *
+ * The pipe must first be opened with O_NOTIFICATION_PIPE (i.e. O_EXCL passed
+ * to pipe2()) and sized via %IOC_WATCH_QUEUE_SET_SIZE before subscribing.
+ *
+ * Events are delivered as notification records read from the pipe.  The
+ * @watch_id field is embedded in the notification info field and can be used
+ * to distinguish multiple watches sharing a pipe.
+ *
+ * Currently defined event subtypes:
+ *  - %DRM_XE_WATCH_EVENT_VM_ERR - a VM owned by this file has encountered an error
+ */
+
+/**
+ * struct drm_xe_watch_queue - subscribe to device event notifications
+ *
+ * Used with %DRM_IOCTL_XE_WATCH_QUEUE.  Notifications are scoped to the
+ * DRM file handle used to issue this IOCTL.
+ */
+struct drm_xe_watch_queue {
+	/** @fd: file descriptor of pipe opened with O_NOTIFICATION_PIPE */
+	__u32 fd;
+
+	/**
+	 * @watch_id: identifier (0–255) embedded in the watch notification
+	 * info field; allows multiplexing several watches on one pipe
+	 */
+	__u32 watch_id;
+
+	/** @flags: must be zero */
+	__u32 flags;
+
+	/** @pad: reserved, must be zero */
+	__u32 pad;
+};
+
 #if defined(__cplusplus)
 }
 #endif
include/drm-uapi/xe_drm_events.h new file +65 -0

65 lines not on this page · raw message

lib/meson.build +1 -0
index ea721ecf7..1fa2cac0b 100644
@@ -132,6 +132,7 @@ lib_sources = [
 	'xe/xe_sriov_debugfs.c',
 	'xe/xe_sriov_provisioning.c',
 	'xe/xe_util.c',
+	'xe/xe_watch.c',
 ]
 
 lib_deps = [
lib/xe/xe_watch.c new file +221 -0

221 lines not on this page · raw message

lib/xe/xe_watch.h new file +80 -0

80 lines not on this page · raw message

Signature · 1 line
2.53.0
#2 lore raw

RFC PATCH 2/2 tests/intel/xe_exec_compute_mode: Add a listener for file events

In reply to Thomas Hellström

Using the new xe_watch library functionality, add a listener for file events. The listener gets notified on

* File close,
* Lost event,
* Rebind worker error.

But doesn't take any action.

Assisted-by GitHub Copilot:claude-sonnet-4.6
---
 tests/intel/xe_exec_compute_mode.c | 59 +++++++++++++++++++++++++++++-
 1 file changed, 57 insertions(+), 2 deletions(-)
tests/intel/xe_exec_compute_mode.c +57 -2
index 438ea163f..0784f3a31 100644
@@ -22,6 +22,7 @@
 #include "xe/xe_ioctl.h"
 #include "xe/xe_query.h"
 #include "xe/xe_spin.h"
+#include "xe/xe_watch.h"
 #include <string.h>
 
 #define MAX_N_EXECQUEUES 	16
@@ -35,6 +36,52 @@
 #define FREE_MAPPPING			(0x1 << 7)
 #define UNMAP_MAPPPING			(0x1 << 8)
 
+static void xe_event_fn(struct xe_watch_event *event)
+{
+	const struct watch_notification *notif = event->notif;
+	const struct drm_xe_watch_notification_vm_err *err_event =
+		igt_container_of(notif, err_event, base);
+
+	switch (notif->type) {
+	case WATCH_TYPE_META:
+		switch (notif->subtype) {
+		case WATCH_META_REMOVAL_NOTIFICATION:
+			igt_info("The device file was closed.\n");
+			break;
+		case WATCH_META_LOSS_NOTIFICATION:
+			igt_warn("The listener lost a message.\n");
+			break;
+		default:
+			igt_warn("Unknown META subtype.\n");
+			break;
+		}
+		break;
+
+	case WATCH_TYPE_DRM_XE_NOTIFY:
+		switch (notif->subtype) {
+		case DRM_XE_WATCH_EVENT_VM_ERR:
+			igt_info("VM with id %u saw an error: %d\n",
+				 (unsigned int) err_event->vm_id,
+				 (int) err_event->error_code);
+			break;
+		default:
+			igt_warn("Unknown XE watch subtype %u\n",
+				 (unsigned int) notif->subtype);
+			break;
+		}
+
+		break;
+
+	default:
+		igt_warn("Unknown watch type %u.\n", notif->type);
+		break;
+	}
+}
+
+const struct xe_watch_event_ops event_ops = {
+	.event_deliver = xe_event_fn,
+};
+
 /**
  * SUBTEST: twice-%s
  * Description: Run %arg[1] compute machine test twice
@@ -430,9 +477,15 @@ int igt_main()
 		{ NULL },
 	};
 	int fd;
+	struct xe_watch_event watch_event = {
+		.ops = &event_ops,
+	};
+	struct xe_watch_listener *listener;
 
-	igt_fixture()
+	igt_fixture() {
 		fd = drm_open_driver(DRIVER_XE);
+		listener = xe_watch_listener_create(fd, &watch_event);
+	}
 
 	for (const struct section *s = sections; s->name; s++) {
 		igt_subtest_f("once-%s", s->name)
@@ -465,6 +518,8 @@ int igt_main()
 		lr_mode_workload(fd);
 
 
-	igt_fixture()
+	igt_fixture() {
 		drm_close_driver(fd);
+		xe_watch_listener_destroy(listener);
+	}
 }
Signature · 1 line
2.53.0