[RFC PATCH 1/3] drm/amdgpu/uapi: Add second-level trap handler ops to VM ioctl

When a GPU shader hits an exception, memory fault, or debug breakpoint,
the hardware jumps to the first-level trap handler. The first-level
handler (managed by the kernel via CWSR) checks the TMA buffer for a
second-level handler address. If one is installed, it forwards the trap
to that userspace handler, allowing the runtime or debugger to handle
shader exceptions without modifying the kernel trap handler.

KFD already supports this for compute workloads. Render-node user queues
had no equivalent mechanism. Add it.

The second-level handler is a per-VM setting — it applies to all shader
waves executing under that VMID regardless of queue type. GFX and
compute queues from the same process share the same VMID, so one
SET_L2_TRAP call covers all queue types for that process. This
configuration is not CWSR-specific; CWSR is only the first-level handler
mechanism. The correct home for this setting is the VM ioctl
(DRM_AMDGPU_VM), following the same pattern as
AMDGPU_VM_OP_RESERVE_VMID.

Add two new VM ioctl operations:
  AMDGPU_VM_OP_SET_L2_TRAP   (op = 3) — install second-level handler
  AMDGPU_VM_OP_CLEAR_L2_TRAP (op = 4) — remove second-level handler

Extend drm_amdgpu_vm_in with a 32-byte union for op-specific data. The
l2trap member carries the GPU virtual addresses and sizes of the TBA
(handler code) and TMA (handler scratch memory). Existing ops only use
the first 8 bytes (op + flags); the union is zero-initialized for those
ops. The DRM framework zero-extends when userspace passes a smaller
struct, so existing userspace is unaffected.

Explicit padding is used at every natural alignment boundary so the
layout is identical for native and 32-bit compat userspace.

If the TBA or TMA mapping is removed via GEM_VA UNMAP/CLEAR while the
handler is active, the kernel waits for the VM to be idle, evicts all
user queues, flushes the GPU TLB, clears the handler, and allows the
unmap to proceed. UNMAP never returns an error for this condition.
Queues whose trap handler VA was removed are not restarted.

Cc: Christian König <[email protected]>
Cc: Alex Deucher <[email protected]>
Cc: Felix Kuehling <[email protected]>
Cc: James Zhu <[email protected]>
Cc: Lijo Lazar <[email protected]>
Cc: Lancelot Six <[email protected]>
Cc: Pierre-Eric Pelloux-Prayer <[email protected]>
Cc: Timur Kristóf <[email protected]>
Cc: Samuel Pitoiset <[email protected]>
Cc: Natalie Vock <[email protected]>
Signed-off-by: Srinivasan Shanmugam <[email protected]>
Change-Id: Ie039e496c75092c91c13719a16d541c5f06c3257
---
 include/uapi/drm/amdgpu_drm.h | 67 +++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)

diff --git a/include/uapi/drm/amdgpu_drm.h b/include/uapi/drm/amdgpu_drm.h
index 9222be9a6d2a..872ff9d1d1ff 100644
--- a/include/uapi/drm/amdgpu_drm.h
+++ b/include/uapi/drm/amdgpu_drm.h
@@ -634,10 +634,77 @@ struct drm_amdgpu_userq_wait {
 #define AMDGPU_VM_OP_RESERVE_VMID	1
 #define AMDGPU_VM_OP_UNRESERVE_VMID	2
 
+/**
+ * AMDGPU_VM_OP_SET_L2_TRAP - install or replace the second-level trap
+ *   handler for all GFX and compute user queues belonging to this VM.
+ *
+ * The second-level trap handler is a per-VM setting. All shader waves
+ * executing under this VMID share the same handler regardless of queue
+ * type. GFX and compute queues from the same process share the same VMID
+ * so one SET_L2_TRAP covers all queue types for this DRM file.
+ *
+ * The TBA range must contain the handler executable code.
+ * The TMA range is the handler scratch memory buffer.
+ * Both ranges must be non-empty and fully mapped in the GPU virtual
+ * address space of this DRM file descriptor.
+ *
+ * Userspace should keep both mappings alive until
+ * AMDGPU_VM_OP_CLEAR_L2_TRAP succeeds. If either mapping is removed
+ * while the handler is active, the kernel waits for the VM to be idle,
+ * evicts all user queues, flushes the GPU TLB, clears the handler, and
+ * allows the unmap to proceed. UNMAP never returns an error for this
+ * condition. Queues whose trap handler VA was removed are not restarted.
+ *
+ * Returns:
+ *  0             on success;
+ *  -EOPNOTSUPP   if the first-level CWSR handler is unavailable;
+ *  -EINVAL       for an invalid or incompletely mapped range;
+ *  negative errno if the VM reservation fails.
+ */
+#define AMDGPU_VM_OP_SET_L2_TRAP	3
+/**
+ * AMDGPU_VM_OP_CLEAR_L2_TRAP - disable the second-level trap handler.
+ *
+ * All active user queues are evicted and the GPU TLB is flushed before
+ * TBA is zeroed to ensure no wave is executing inside the handler at the
+ * time of the clear and no stale TBA/TMA values remain cached.
+ * The l2trap input members are ignored.
+ *
+ * After this operation succeeds userspace may safely remove the TBA
+ * and TMA mappings.
+ *
+ * Returns:
+ *  0             on success;
+ *  -EOPNOTSUPP   if the first-level CWSR handler is unavailable;
+ *  negative errno if the VM reservation fails.
+ */
+#define AMDGPU_VM_OP_CLEAR_L2_TRAP	4
+
 struct drm_amdgpu_vm_in {
 	/** AMDGPU_VM_OP_* */
 	__u32	op;
 	__u32	flags;
+	union {
+		struct {
+			/** Second-level trap handler code base address (GPU VA) */
+			__u64 tba_va;
+			/** TBA buffer size in bytes */
+			__u32 tba_sz;
+			/** Explicit padding; tma_va starts at offset 24 */
+			__u32 _pad;
+			/** Second-level trap handler scratch memory address (GPU VA) */
+			__u64 tma_va;
+			/** TMA buffer size in bytes */
+			__u32 tma_sz;
+			/** Padding to fix total union size at 32 bytes */
+			__u32 _pad2;
+		} l2trap;
+		/**
+		 * Padding — keeps the union at a fixed 32-byte size for
+		 * future ops. Zero-initialise for RESERVE/UNRESERVE_VMID.
+		 */
+		__u64 _pad[4];
+	};
 };
 
 struct drm_amdgpu_vm_out {
-- 
2.34.1