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

[Natalie Vock <nat@pixelcluster.dev>]

Hi,

first of all: Thanks for working on this! It's great seeing trap handler 
support come together.

On 8/20/26 09:01, Srinivasan Shanmugam wrote:
> 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).

This should be a BO handle and offset+size, instead. The BOs associated
with the TBA/TMA must be tracked as used by every submission from the VM
that has this trap handler installed, otherwise you introduce a ton of
race conditions. Off the top of my head, here are a few:
1. The GEM VA ioctl can spuriously fail to actually update page tables.
    This is okay and intentional, and BOs with outdated page tables will
    be updated on the next submit if they're used by the submission. If
    the TBA/TMA BOs aren't marked in the set of used buffers, the PTs may
    end up never being updated and subsequent accesses will fault.
2. The TBA/TMA may be evicted/moved around concurrently with executing
    submissions if these submissions didn't add their fences to the
    TBA/TMA resv, which would likely randomly corrupt things or hang.

A simpler solution could be requiring the TBA/TMA buffers to be
VM_ALWAYS_VALID, in which case synchronization to all submissions in the
VM is taken care of automagically. This prevents exporting the TBA/TMA
to an fd, but I don't expect anyone would want to do this.

Regards,
Natalie

> 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 <christian.koenig@amd.com>
> Cc: Alex Deucher <alexander.deucher@amd.com>
> Cc: Felix Kuehling <felix.kuehling@amd.com>
> Cc: James Zhu <james.zhu@amd.com>
> Cc: Lijo Lazar <lijo.lazar@amd.com>
> Cc: Lancelot Six <lancelot.six@amd.com>
> Cc: Pierre-Eric Pelloux-Prayer <pierre-eric.pelloux-prayer@amd.com>
> Cc: Timur Kristóf <timur.kristof@gmail.com>
> Cc: Samuel Pitoiset <hakzsam@gmail.com>
> Cc: Natalie Vock <natalie.vock@gmx.de>
> Signed-off-by: Srinivasan Shanmugam <srinivasan.shanmugam@amd.com>
> 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 {