On 7/14/26 10:10, Srinivasan Shanmugam wrote:
> Add the UAPI definitions for a render-node WAIT_EVENT ioctl.
>
> WAIT_EVENT lets userspace wait for a kernel-defined event type and
> receive metadata describing the event. This provides the
> metadata-carrying half of the event interface and is kept separate from
> EVENTFD, which is used only for lightweight readiness notification.
>
> The new UAPI supports:
>
> - event type selection
> - queue-scoped or GPU-scoped event selection
> - timeout-based waiting
> - metadata copy to userspace
> - single-consumer delivery of the first matching event
>
> queue_id is the userspace USERQ queue handle identifying a queue created
> through DRM_IOCTL_AMDGPU_USERQ. It is used at the WAIT_EVENT ioctl
> boundary and returned in metadata for queue-scoped events.
>
> Changes since v8:
> - Clarified that queue_id identifies a USERQ created through
> DRM_IOCTL_AMDGPU_USERQ, as suggested by Alex.
>
> Cc: Alex Deucher <[email protected]>
> Cc: Christian König <[email protected]>
> Signed-off-by: Srinivasan Shanmugam <[email protected]>
> ---
> include/uapi/drm/amdgpu_drm.h | 109 ++++++++++++++++++++++++++++++++++
> 1 file changed, 109 insertions(+)
>
> diff --git a/include/uapi/drm/amdgpu_drm.h b/include/uapi/drm/amdgpu_drm.h
> index bbda6ffc498b..2ec57f4975cb 100644
> --- a/include/uapi/drm/amdgpu_drm.h
> +++ b/include/uapi/drm/amdgpu_drm.h
> @@ -61,6 +61,7 @@ extern "C" {
> #define DRM_AMDGPU_PROC_OPTIONS 0x1A
> #define DRM_AMDGPU_CWSR 0x1B
> #define DRM_AMDGPU_EVENTFD 0x1C
> +#define DRM_AMDGPU_WAIT_EVENT 0x1D
>
> #define DRM_IOCTL_AMDGPU_GEM_CREATE DRM_IOWR(DRM_COMMAND_BASE +
> DRM_AMDGPU_GEM_CREATE, union drm_amdgpu_gem_create)
> #define DRM_IOCTL_AMDGPU_GEM_MMAP DRM_IOWR(DRM_COMMAND_BASE +
> DRM_AMDGPU_GEM_MMAP, union drm_amdgpu_gem_mmap)
> @@ -86,6 +87,8 @@ extern "C" {
> #define DRM_IOCTL_AMDGPU_CWSR DRM_IOWR(DRM_COMMAND_BASE +
> DRM_AMDGPU_CWSR, union drm_amdgpu_cwsr)
> #define DRM_IOCTL_AMDGPU_EVENTFD \
> DRM_IOW(DRM_COMMAND_BASE + DRM_AMDGPU_EVENTFD, struct
> drm_amdgpu_eventfd)
> +#define DRM_IOCTL_AMDGPU_WAIT_EVENT \
> + DRM_IOWR(DRM_COMMAND_BASE + DRM_AMDGPU_WAIT_EVENT, struct
> drm_amdgpu_wait_event)
>
> /**
> * DOC: memory domains
> @@ -251,6 +254,112 @@ struct drm_amdgpu_eventfd {
> __u32 flags;
> };
>
> +/**
> + * struct drm_amdgpu_wait_event_queue - queue-scoped event metadata
> + * @queue_id: userspace USERQ queue handle identifying a queue created
> + * through DRM_IOCTL_AMDGPU_USERQ
> + * @status: event-specific status or error code
> + * @data0: event-specific payload
> + * @data1: event-specific payload
> + */
> +struct drm_amdgpu_wait_event_queue {
> + __u32 queue_id;
> + __u32 status;
> + __u64 data0;
> + __u64 data1;
> +};
> +
> +/**
> + * struct drm_amdgpu_wait_event_memory - memory exception metadata
> + * @queue_id: userspace USERQ queue handle identifying a queue created
> + * through DRM_IOCTL_AMDGPU_USERQ, if applicable; otherwise 0
> + * @fault_status: device-specific fault or exception status
> + * @va: faulting virtual address if applicable
> + * @data0: event-specific payload
> + */
> +struct drm_amdgpu_wait_event_memory {
> + __u32 queue_id;
> + __u32 fault_status;
> + __u64 va;
> + __u64 data0;
> +};
> +
> +/**
> + * struct drm_amdgpu_wait_event_reset - reset metadata
> + * @queue_id: userspace USERQ queue handle identifying a queue created
> + * through DRM_IOCTL_AMDGPU_USERQ, if queue-scoped; otherwise 0
> + * @reset_cause: reset cause or reason code
> + * @data0: event-specific payload
> + * @data1: event-specific payload
> + */
> +struct drm_amdgpu_wait_event_reset {
> + __u32 queue_id;
> + __u32 reset_cause;
> + __u64 data0;
> + __u64 data1;
> +};
> +
> +/**
> + * struct drm_amdgpu_wait_event_scratch - scratch event metadata
> + * @queue_id: userspace USERQ queue handle identifying a queue created
> + * through DRM_IOCTL_AMDGPU_USERQ
> + * @error_code: scratch-related error code
> + * @requested_bytes: requested scratch size
> + * @available_bytes: available scratch size if known
> + */
> +struct drm_amdgpu_wait_event_scratch {
> + __u32 queue_id;
> + __u32 error_code;
> + __u64 requested_bytes;
> + __u64 available_bytes;
> +};
> +
> +/**
> + * struct drm_amdgpu_wait_event_data - returned event record
> + * @event_type: kernel-defined event type
> + * @queue_id: userspace USERQ queue handle identifying a queue created
> + * through DRM_IOCTL_AMDGPU_USERQ, or 0 for GPU-scoped events
> + * @flags: reserved, must be 0
> + * @reserved: reserved, must be 0
> + * @seqno: per-file event sequence number
> + * @u: event-specific metadata
> + */
> +struct drm_amdgpu_wait_event_data {
> + __u32 event_type;
> + __u32 queue_id;
> + __u32 flags;
> + __u32 reserved;
> + __u64 seqno;
> + union {
> + struct drm_amdgpu_wait_event_queue queue;
> + struct drm_amdgpu_wait_event_memory memory;
> + struct drm_amdgpu_wait_event_reset reset;
> + struct drm_amdgpu_wait_event_scratch scratch;
> + } u;
> +};
> +
> +/**
> + * struct drm_amdgpu_wait_event - wait for a render-node event
> + * @event_type: kernel-defined event type
> + * @queue_id: userspace USERQ queue handle identifying a queue created
> + * through DRM_IOCTL_AMDGPU_USERQ, or 0 for GPU-scoped events
> + * @timeout_ns: relative timeout in nanoseconds; negative means wait forever
Please never ever use relative timeouts in IOCTLs!
Only absolute CLOCK_MONOTONIC based timeouts, preferable as nanoseconds cause
that is the same as ktime_get() returns and easy to work with.
Apart from that looks good to me,
Christian.
> + * @out_ptr: userspace pointer to struct drm_amdgpu_wait_event_data
> + * @out_size: size of userspace output buffer
> + * @flags: must be 0
> + *
> + * Wait for the selected event and copy the first matching event record to
> + * userspace. Matching records are consumed by a single waiter.
> + */
> +struct drm_amdgpu_wait_event {
> + __u32 event_type;
> + __u32 queue_id;
> + __s64 timeout_ns;
> + __u64 out_ptr;
> + __u32 out_size;
> + __u32 flags;
> +};
> +
> /** Opcode to create new residency list. */
> #define AMDGPU_BO_LIST_OP_CREATE 0
> /** Opcode to destroy previously created residency list */
