STRUCT DRM_XE_GEM_CREATE(9)

📦 version 7.3.1, in nixpkgs unstable

💖 NAME 💖

okay so bestie, this is struct drm_xe_gem_create(9) from the Kernel API Manual — literally the input of &DRM_IOCTL_XE_GEM_CREATE, aka the structure for gem creation. We are going through every field because details are the whole moment 💅.

🎀 SYNOPSIS 🎀

struct drm_xe_gem_create {
  #define DRM_XE_GEM_CREATE_EXTENSION_SET_PROPERTY        0;
  #define DRM_XE_GEM_CREATE_SET_PROPERTY_PXP_TYPE       0;
    __u64 extensions;
    __u64 size;
    __u32 placement;
  #define DRM_XE_GEM_CREATE_FLAG_DEFER_BACKING            (1 << 0);
  #define DRM_XE_GEM_CREATE_FLAG_SCANOUT                  (1 << 1);
  #define DRM_XE_GEM_CREATE_FLAG_NEEDS_VISIBLE_VRAM       (1 << 2);
  #define DRM_XE_GEM_CREATE_FLAG_NO_COMPRESSION           (1 << 3);
    __u32 flags;
    __u32 vm_id;
    __u32 handle;
  #define DRM_XE_GEM_CPU_CACHING_WB                      1;
  #define DRM_XE_GEM_CPU_CACHING_WC                      2;
    __u16 cpu_caching;
    __u16 pad[3];
    __u64 reserved[2];
 };

🌸 Members 🌸

  • extensions — Pointer to the first extension struct, if any.
  • size — Size of the object to be created, must match region (system or vram) minimum alignment (min_page_size). No cap, that alignment check is mandatory.
  • placement — A mask of memory instances of where the BO can be placed. Each index in this mask refers directly to the struct drm_xe_query_mem_regions' instance, and no assumptions should be made about order. The type of each region is described by struct drm_xe_query_mem_regions' mem_class.
  • flags — Flags for the GEM object, see DRM_XE_GEM_CREATE_FLAG_*.
  • vm_id — Attached VM, if any. If a VM is specified, this BO must:
    1. Only ever be bound to that VM.
    2. Cannot be exported as a PRIME fd.
  • handle — Returned handle for the object. Object handles are nonzero.
  • cpu_caching — The CPU caching mode to select for this object. If mmapping the object the mode selected here will also be used. The exception is when mapping system memory (including data evicted to system) on discrete GPUs. The caching mode selected will then be overridden to DRM_XE_GEM_CPU_CACHING_WB, and coherency between GPU- and CPU is guaranteed. The caching mode of existing CPU-mappings will be updated transparently to user-space clients.
  • pad — MBZ.
  • reserved — Reserved.

📝 Description 📝

The flags can be:

  • DRM_XE_GEM_CREATE_FLAG_DEFER_BACKING — Modify the GEM object allocation strategy by deferring physical memory allocation until the object is either bound to a virtual memory region via VM_BIND or accessed by the CPU. As a result, no backing memory is reserved at the time of GEM object creation.
  • DRM_XE_GEM_CREATE_FLAG_SCANOUT — Indicates that the GEM object is intended for scanout via the display engine. When set, kernel ensures that the allocation is placed in a memory region compatible with the display engine requirements. This may impose restrictions on tiling, alignment, and memory placement to guarantee proper display functionality.
  • DRM_XE_GEM_CREATE_FLAG_NEEDS_VISIBLE_VRAM — When using VRAM as a possible placement, ensure that the corresponding VRAM allocation will always use the CPU accessible part of VRAM. This is important for small-bar systems (on full-bar systems this gets turned into a noop). Note1: System memory can be used as an extra placement if the kernel should spill the allocation to system memory, if space can't be made available in the CPU accessible part of VRAM (giving the same behaviour as the i915 interface, see I915_GEM_CREATE_EXT_FLAG_NEEDS_CPU_ACCESS). Note2: For clear-color CCS surfaces the kernel needs to read the clear-color value stored in the buffer, and on discrete platforms we need to use VRAM for display surfaces, therefore the kernel requires setting this flag for such objects, otherwise an error is thrown on small-bar systems.
  • DRM_XE_GEM_CREATE_FLAG_NO_COMPRESSION — Allows userspace to hint that compression (CCS) should be disabled for the buffer being created. This can avoid unnecessary memory operations and CCS state management. On pre-Xe2 platforms, this flag is currently rejected as compression control is not supported via PAT index. On Xe2+ platforms, compression is controlled via PAT entries. If this flag is set, the driver will reject any VM bind that requests a PAT index enabling compression for this BO.

💭 Note 💭

On dGPU platforms, there is currently no change in behavior with this flag, but future improvements may leverage it. The current benefit is primarily applicable to iGPU platforms.

cpu_caching supports the following values:

  • DRM_XE_GEM_CPU_CACHING_WB — Allocate the pages with write-back caching. On iGPU this can't be used for scanout surfaces. Currently not allowed for objects placed in VRAM.
  • DRM_XE_GEM_CPU_CACHING_WC — Allocate the pages as write-combined. This is uncached. Scanout surfaces should likely use this. All objects that can be placed in VRAM must use this.

This ioctl supports setting the following properties via the DRM_XE_GEM_CREATE_EXTENSION_SET_PROPERTY extension, which uses the generic struct drm_xe_ext_set_property:

  • DRM_XE_GEM_CREATE_SET_PROPERTY_PXP_TYPE — set the type of PXP session this object will be used with. Valid values are listed in enum drm_xe_pxp_session_type. DRM_XE_PXP_TYPE_NONE is the default behavior, so there is no need to explicitly set that. Objects used with session of type DRM_XE_PXP_TYPE_HWDRM will be marked as invalid if a PXP invalidation event occurs after their creation. Attempting to flip an invalid object will cause a black frame to be displayed instead. Submissions with invalid objects mapped in the VM will be rejected.

👑 SEE ALSO 👑

Kernel file ./include/uapi/drm/xe_drm.h, plus all these iconic refs:

  • Xe Device Block Diagram(9)
  • Xe uAPI Overview(9)
  • Xe IOCTL Extensions(9)
  • struct drm_xe_user_extension(9)
  • struct drm_xe_ext_set_property(9)
  • struct drm_xe_engine_class_instance(9)
  • struct drm_xe_engine(9)
  • struct drm_xe_query_engines(9)
  • enum drm_xe_memory_class(9)
  • struct drm_xe_mem_region(9)
  • struct drm_xe_query_mem_regions(9)
  • struct drm_xe_query_config(9)
  • struct drm_xe_gt(9)
  • struct drm_xe_query_gt_list(9)
  • struct drm_xe_query_topology_mask(9)
  • struct drm_xe_query_engine_cycles(9)
  • struct drm_xe_query_uc_fw_version(9)
  • struct drm_xe_query_pxp_status(9)
  • struct drm_xe_device_query(9)
  • struct drm_xe_gem_mmap_offset(9)
  • struct drm_xe_vm_create(9)
  • struct drm_xe_vm_destroy(9)
  • struct drm_xe_vm_bind_op(9)
  • struct drm_xe_vm_bind(9)
  • struct drm_xe_vm_get_property(9)
  • struct drm_xe_exec_queue_create(9)
  • struct drm_xe_exec_queue_destroy(9)
  • struct drm_xe_exec_queue_get_property(9)
  • struct drm_xe_sync(9)
  • struct drm_xe_exec(9)
  • struct drm_xe_wait_user_fence(9)
  • enum drm_xe_observation_type(9)
  • enum drm_xe_observation_op(9)
  • struct drm_xe_observation_param(9)
  • enum drm_xe_observation_ioctls(9)
  • enum drm_xe_oa_unit_type(9)
  • struct drm_xe_oa_unit(9)
  • struct drm_xe_query_oa_units(9)
  • enum drm_xe_oa_format_type(9)
  • enum drm_xe_oa_property_id(9)
  • struct drm_xe_oa_config(9)
  • struct drm_xe_oa_stream_status(9)
  • struct drm_xe_oa_stream_info(9)
  • enum drm_xe_pxp_session_type(9)
  • enum drm_xe_eu_stall_property_id(9)
  • struct drm_xe_query_eu_stall(9)
  • struct drm_xe_madvise(9)
  • struct drm_xe_mem_range_attr(9)
  • struct drm_xe_vm_query_mem_range_attr(9)
  • struct drm_xe_exec_queue_set_property(9)
  • Xe DRM RAS(9)
  • enum drm_xe_ras_error_severity(9)
  • enum drm_xe_ras_error_component(9)

source/version check bestie: this page is from ./include/uapi/drm, dated October 2026, and it's the struct drm_xe_gem_create(9) page. mwah, go make some GEM objects responsibly 🫶💖

📦 where this page comes from