drm_xe_madvise Struct Reference

#include <xe_drm.h>

Public Attributes
__u64	extensions
__u64	start
__u64	range
__u32	vm_id
__u32	type
union {
struct {
__u32   devmem_fd
__u16   migration_policy
__u16   region_instance
__u64   reserved
}   preferred_mem_loc
struct {
__u32   val
__u32   pad
__u64   reserved
}   atomic
struct {
__u32   val
__u32   pad
__u64   reserved
}   pat_index
struct {
__u32   val
__u32   pad
__u64   retained_ptr
}   purge_state_val
};

Detailed Description

struct drm_xe_madvise - Input of &DRM_IOCTL_XE_MADVISE

This structure is used to set memory attributes for a virtual address range in a VM. The type of attribute is specified by @type, and the corresponding union member is used to provide additional parameters for @type.

Supported attribute types:

• DRM_XE_MEM_RANGE_ATTR_PREFERRED_LOC: Set preferred memory location.
• DRM_XE_MEM_RANGE_ATTR_ATOMIC: Set atomic access policy.
• DRM_XE_MEM_RANGE_ATTR_PAT: Set page attribute table index.
• DRM_XE_VMA_ATTR_PURGEABLE_STATE: Set purgeable state for BOs.

Example:

.. code-block:: C

struct drm_xe_madvise madvise = { .vm_id = vm_id, .start = 0x100000, .range = 0x2000, .type = DRM_XE_MEM_RANGE_ATTR_ATOMIC, .atomic.val = DRM_XE_ATOMIC_DEVICE, };

ioctl(fd, DRM_IOCTL_XE_MADVISE, &madvise);

Member Data Documentation

[union]

union { ... } drm_xe_madvise

[struct]

struct { ... } drm_xe_madvise::atomic

@atomic: Atomic access policy

Used when @type == DRM_XE_MEM_RANGE_ATTR_ATOMIC.

Supported values for @atomic.val:

• DRM_XE_ATOMIC_UNDEFINED: Undefined or default behaviour. Support both GPU and CPU atomic operations for system allocator. Support GPU atomic operations for normal(bo) allocator.
• DRM_XE_ATOMIC_DEVICE: Support GPU atomic operations.
• DRM_XE_ATOMIC_GLOBAL: Support both GPU and CPU atomic operations.
• DRM_XE_ATOMIC_CPU: Support CPU atomic only, no GPU atomics supported.

devmem_fd

__u32 drm_xe_madvise::devmem_fd

@preferred_mem_loc.devmem_fd: Device file-descriptor of the device where the preferred memory is located, or one of the above special values. Please also see @preferred_mem_loc.region_instance below.

extensions

__u64 drm_xe_madvise::extensions

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

migration_policy

__u16 drm_xe_madvise::migration_policy

@preferred_mem_loc.migration_policy: Page migration policy

pad

__u32 drm_xe_madvise::pad

@atomic.pad: MBZ

@pat_index.pad: MBZ

@purge_state_val.pad: MBZ

[struct]

struct { ... } drm_xe_madvise::pat_index

@pat_index: Page attribute table index

Used when @type == DRM_XE_MEM_RANGE_ATTR_PAT.

[struct]

struct { ... } drm_xe_madvise::preferred_mem_loc

@preferred_mem_loc: preferred memory location

Used when @type == DRM_XE_MEM_RANGE_ATTR_PREFERRED_LOC

Supported values for @preferred_mem_loc.devmem_fd:

• DRM_XE_PREFERRED_LOC_DEFAULT_DEVICE: set vram of fault tile as preferred loc
• DRM_XE_PREFERRED_LOC_DEFAULT_SYSTEM: set smem as preferred loc

Supported values for @preferred_mem_loc.migration_policy:

• DRM_XE_MIGRATE_ALL_PAGES
• DRM_XE_MIGRATE_ONLY_SYSTEM_PAGES

[struct]

struct { ... } drm_xe_madvise::purge_state_val

@purge_state_val: Purgeable state configuration

Used when @type == DRM_XE_VMA_ATTR_PURGEABLE_STATE.

Configures the purgeable state of buffer objects in the specified virtual address range. This allows applications to hint to the kernel about bo's usage patterns for better memory management.

By default all VMAs are in WILLNEED state.

Supported values for @purge_state_val.val:

• DRM_XE_VMA_PURGEABLE_STATE_WILLNEED (0): Marks BO as needed. If the BO was previously purged, the kernel sets the __u32 at @retained_ptr to 0 (backing store lost) so the application knows it must recreate the BO.

• DRM_XE_VMA_PURGEABLE_STATE_DONTNEED (1): Marks BO as not currently needed. Kernel may purge it under memory pressure to reclaim memory. Only applies to non-shared BOs. The kernel sets the __u32 at @retained_ptr to 1 if the backing store still exists (not yet purged), or 0 if it was already purged.

  Important: Once marked as DONTNEED, touching the BO's memory is undefined behavior. It may succeed temporarily (before the kernel purges the backing store) but will suddenly fail once the BO transitions to PURGED state.

  To transition back: use WILLNEED and check @retained_ptr — if 0, backing store was lost and the BO must be recreated.

  The following operations are blocked in DONTNEED state to prevent the BO from being re-mapped after madvise:

  • New mmap() calls: Fail with -EBUSY
  • VM_BIND operations: Fail with -EBUSY
  • New dma-buf exports: Fail with -EBUSY
  • CPU page faults (existing mmap): Fail with SIGBUS
  • GPU page faults (fault-mode VMs): Fail with -EACCES

range

__u64 drm_xe_madvise::range

@range: size of the virtual address range

region_instance

__u16 drm_xe_madvise::region_instance

@preferred_mem_loc.region_instance : Region instance. MBZ if @devmem_fd <= DRM_XE_PREFERRED_LOC_DEFAULT_DEVICE. Otherwise should point to the desired device VRAM instance of the device indicated by @preferred_mem_loc.devmem_fd.

reserved

__u64 drm_xe_madvise::reserved

@preferred_mem_loc.reserved : Reserved

@atomic.reserved: Reserved

@pat_index.reserved: Reserved

@reserved: Reserved

retained_ptr

__u64 drm_xe_madvise::retained_ptr

@purge_state_val.retained_ptr: Pointer to a __u32 output field for backing store status.

Userspace must initialize the __u32 value at this address to 0 before the ioctl. Kernel writes a __u32 after the operation:

• 1 if backing store exists (not purged)
• 0 if backing store was purged

If userspace fails to initialize to 0, ioctl returns -EINVAL. This ensures a safe default (0 = assume purged) if kernel cannot write the result.

Similar to i915's drm_i915_gem_madvise.retained field.

start

__u64 drm_xe_madvise::start

@start: start of the virtual address range

type

__u32 drm_xe_madvise::type

@type: type of attribute

val

__u32 drm_xe_madvise::val

@atomic.val: value of atomic operation

@pat_index.val: PAT index value

@purge_state_val.val: value for DRM_XE_VMA_ATTR_PURGEABLE_STATE

vm_id

__u32 drm_xe_madvise::vm_id

@vm_id: vm_id of the virtual range

---

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

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