drm_xe_vm_bind_op Struct Reference

#include <xe_drm.h>

Public Attributes
__u64	extensions
__u32	obj
__u16	pat_index
__u16	pad
union {
__u64   obj_offset
__u64   userptr
__s64   cpu_addr_mirror_offset
};
__u64	range
__u64	addr
__u32	op
__u32	flags
__u32	prefetch_mem_region_instance
__u32	pad2
__u64	reserved [3]

Detailed Description

struct drm_xe_vm_bind_op - run bind operations

The @op can be:

• DRM_XE_VM_BIND_OP_MAP
• DRM_XE_VM_BIND_OP_UNMAP
• DRM_XE_VM_BIND_OP_MAP_USERPTR
• DRM_XE_VM_BIND_OP_UNMAP_ALL
• DRM_XE_VM_BIND_OP_PREFETCH

and the @flags can be:

• DRM_XE_VM_BIND_FLAG_READONLY - Setup the page tables as read-only to ensure write protection
• DRM_XE_VM_BIND_FLAG_IMMEDIATE - On a faulting VM, do the MAP operation immediately rather than deferring the MAP to the page fault handler. This is implied on a non-faulting VM as there is no fault handler to defer to.
• DRM_XE_VM_BIND_FLAG_NULL - When the NULL flag is set, the page tables are setup with a special bit which indicates writes are dropped and all reads return zero. In the future, the NULL flags will only be valid for DRM_XE_VM_BIND_OP_MAP operations, the BO handle MBZ, and the BO offset MBZ. This flag is intended to implement VK sparse bindings.
• DRM_XE_VM_BIND_FLAG_CHECK_PXP - If the object is encrypted via PXP, reject the binding if the encryption key is no longer valid. This flag has no effect on BOs that are not marked as using PXP.
• DRM_XE_VM_BIND_FLAG_CPU_ADDR_MIRROR - When the CPU address mirror flag is set, no mappings are created rather the range is reserved for CPU address mirroring which will be populated on GPU page faults or prefetches. Only valid on VMs with DRM_XE_VM_CREATE_FLAG_FAULT_MODE set. The CPU address mirror flag is only valid for DRM_XE_VM_BIND_OP_MAP operations, the BO handle MBZ, and the BO offset MBZ.
• DRM_XE_VM_BIND_FLAG_MADVISE_AUTORESET - Can be used in combination with DRM_XE_VM_BIND_FLAG_CPU_ADDR_MIRROR to reset madvises when the underlying CPU address space range is unmapped (typically with munmap(2) or brk(2)). The madvise values set with &DRM_IOCTL_XE_MADVISE are reset to the values that were present immediately after the &DRM_IOCTL_XE_VM_BIND. The reset GPU virtual address range is the intersection of the range bound using &DRM_IOCTL_XE_VM_BIND and the virtual CPU address space range unmapped. This functionality is present to mimic the behaviour of CPU address space madvises set using madvise(2), which are typically reset on unmap. Note: free(3) may or may not call munmap(2) and/or brk(2), and may thus not invoke autoreset. Neither will stack variables going out of scope. Therefore it's recommended to always explicitly reset the madvises when freeing the memory backing a region used in a &DRM_IOCTL_XE_MADVISE call.
• DRM_XE_VM_BIND_FLAG_DECOMPRESS - Request on-device decompression for a MAP. When set on a MAP bind operation, request the driver schedule an on-device in-place decompression (via the migrate/resolve path) for the GPU mapping created by this bind. Only valid for DRM_XE_VM_BIND_OP_MAP; usage on other ops is rejected. The bind's pat_index must select the device's "no-compression" PAT. Only meaningful for VRAM-backed BOs on devices that support Flat CCS and the required HW generation XE2+.

The @prefetch_mem_region_instance for DRM_XE_VM_BIND_OP_PREFETCH can also be:

• DRM_XE_CONSULT_MEM_ADVISE_PREF_LOC, which ensures prefetching occurs in the memory region advised by madvise.

Member Data Documentation

[union]

union { ... } drm_xe_vm_bind_op

addr

__u64 drm_xe_vm_bind_op::addr

@addr: Address to operate on, MBZ for UNMAP_ALL

cpu_addr_mirror_offset

__s64 drm_xe_vm_bind_op::cpu_addr_mirror_offset

@cpu_addr_mirror_offset: Offset from GPU @addr to create CPU address mirror mappings. MBZ with current level of support (e.g. 1 to 1 mapping between GPU and CPU mappings only supported).

extensions

__u64 drm_xe_vm_bind_op::extensions

@extensions: Pointer to the first extension struct, if any

flags

__u32 drm_xe_vm_bind_op::flags

@flags: Bind flags

obj

__u32 drm_xe_vm_bind_op::obj

@obj: GEM object to operate on, MBZ for MAP_USERPTR, MBZ for UNMAP

obj_offset

__u64 drm_xe_vm_bind_op::obj_offset

@obj_offset: Offset into the object, MBZ for CLEAR_RANGE, ignored for unbind

op

__u32 drm_xe_vm_bind_op::op

@op: Bind operation to perform

pad

__u16 drm_xe_vm_bind_op::pad

@pad: MBZ

pad2

__u32 drm_xe_vm_bind_op::pad2

@pad2: MBZ

pat_index

__u16 drm_xe_vm_bind_op::pat_index

@pat_index: The platform defined @pat_index to use for this mapping. The index basically maps to some predefined memory attributes, including things like caching, coherency, compression etc. The exact meaning of the pat_index is platform specific and defined in the Bspec and PRMs. When the KMD sets up the binding the index here is encoded into the ppGTT PTE.

For coherency the @pat_index needs to be at least 1way coherent when drm_xe_gem_create.cpu_caching is DRM_XE_GEM_CPU_CACHING_WB. The KMD will extract the coherency mode from the @pat_index and reject if there is a mismatch (see note below for pre-MTL platforms).

Note: On pre-MTL platforms there is only a caching mode and no explicit coherency mode, but on such hardware there is always a shared-LLC (or is dgpu) so all GT memory accesses are coherent with CPU caches even with the caching mode set as uncached. It's only the display engine that is incoherent (on dgpu it must be in VRAM which is always mapped as WC on the CPU). However to keep the uapi somewhat consistent with newer platforms the KMD groups the different cache levels into the following coherency buckets on all pre-MTL platforms:

ppGTT UC -> COH_NONE ppGTT WC -> COH_NONE ppGTT WT -> COH_NONE ppGTT WB -> COH_AT_LEAST_1WAY

In practice UC/WC/WT should only ever be used for scanout surfaces on such platforms (or perhaps in general for dma-buf if shared with another device) since it is only the display engine that is actually incoherent. Everything else should typically use WB given that we have a shared-LLC. On MTL+ this completely changes and the HW defines the coherency mode as part of the @pat_index, where incoherent GT access is possible.

Note: For userptr and externally imported dma-buf the kernel expects either 1WAY or 2WAY for the @pat_index. Starting from NVL-P, for userptr, svm, madvise and externally imported dma-buf the kernel expects either 2WAY or 1WAY and XA @pat_index.

For DRM_XE_VM_BIND_FLAG_NULL bindings there are no KMD restrictions on the @pat_index. For such mappings there is no actual memory being mapped (the address in the PTE is invalid), so the various PAT memory attributes likely do not apply. Simply leaving as zero is one option (still a valid pat_index). Same applies to DRM_XE_VM_BIND_FLAG_CPU_ADDR_MIRROR bindings as for such mapping there is no actual memory being mapped.

prefetch_mem_region_instance

__u32 drm_xe_vm_bind_op::prefetch_mem_region_instance

@prefetch_mem_region_instance: Memory region to prefetch VMA to. It is a region instance, not a mask. To be used only with DRM_XE_VM_BIND_OP_PREFETCH operation.

range

__u64 drm_xe_vm_bind_op::range

@range: Number of bytes from the object to bind to addr, MBZ for UNMAP_ALL

reserved

__u64 drm_xe_vm_bind_op::reserved[3]

@reserved: Reserved

userptr

__u64 drm_xe_vm_bind_op::userptr

@userptr: user pointer to bind on

---

The documentation for this struct was generated from the following file:

• XenevaOS/BaseHdr/uapi/drm/xe_drm.h