XE CONFIGFS(9)

📦 version 7.3.1, in nixpkgs unstable

💅 Xe Configfs(9)

Okay so welcome to the Xe Configfs page of the Kernel API Manual — grab a snack, we're gonna learn how to hand-build GPU devices in a filesystem, and honestly? It's giving main character energy. 🎀

✨ Overview ✨

So like, configfs is a filesystem-based manager of kernel objects — think of it as a little directory tree where you sculpt kernel stuff into existence instead of poking at modules. Xe KMD registers a configfs subsystem called xe that creates a directory inside the mounted configfs directory. Then you (yes, YOU, bestie 🫶) can create devices under that directory and configure them however you need. If you wanna know how configfs actually works under the hood, go read Documentation/filesystems/configfs.rst — it's all in there.

🌸 Create devices 🌸

To create a device, the xe module should already be loaded — but heads up, some attributes can only be set before binding the device. So you block the driver autoprobe first, like this:

# echo 0 > /sys/bus/pci/drivers_autoprobe
# modprobe xe

Then to actually make a device, you just create a directory inside xe. Yes, mkdir. That's the whole vibe:

# mkdir /sys/kernel/config/xe/0000:03:00.0/

Every device you create gets populated by the driver with a bunch of entries you can use to configure it 💖:

/sys/kernel/config/xe/
├── 0000:00:02.0
│   └── ...
├── 0000:00:02.1
│   └── ...
:
└── 0000:03:00.0
    ├── survivability_mode
    ├── gt_types_allowed
    ├── engines_allowed
    └── enable_psmi

Once you've configured the attributes (next section, keep scrolling 💅), you probe the device with:

# echo 0000:03:00.0 > /sys/bus/pci/drivers/xe/bind
# # or
# echo 0000:03:00.0 > /sys/bus/pci/drivers_probe

🦋 Configure Attributes 🦋

Survivability mode:

Enable survivability mode on supported cards. Iconic. This setting only takes effect when probing the device. Example to flip it on:

# echo 1 > /sys/kernel/config/xe/0000:03:00.0/survivability_mode
⚠️ This attribute can only be set before binding to the device.

Allowed GT types:

This one lets you allow only specific types of GTs to be detected and initialized by the driver. Any combination of GT types can be enabled/disabled — although ngl, some settings will cause the device to fail to probe 😭.

Writes support both comma- and newline-separated input format. Reads will always return one GT type per line. "primary" and "media" are the GT type names supported by this interface.

⚠️ This attribute can only be set before binding to the device.

Examples:

Allow both primary and media GTs to be initialized and used — this matches the driver's default behavior:

# echo 'primary,media' > /sys/kernel/config/xe/0000:03:00.0/gt_types_allowed

Allow only the primary GT of each tile to be initialized and used, effectively disabling the media GT if it exists on the platform:

# echo 'primary' > /sys/kernel/config/xe/0000:03:00.0/gt_types_allowed

Allow only the media GT of each tile to be initialized and used, effectively disabling the primary GT. This configuration will cause device probe failure on all current platforms, but may be allowed on igpu platforms in the future:

# echo 'media' > /sys/kernel/config/xe/0000:03:00.0/gt_types_allowed

Disable all GTs — then only other GPU IP (such as display) is potentially usable. This configuration will cause device probe failure on all current platforms, but may be allowed on igpu platforms in the future:

# echo '' > /sys/kernel/config/xe/0000:03:00.0/gt_types_allowed

Allowed engines:

Let only a set of engine(s) be available, disabling all the other engines even if they're literally right there in the hardware. This gets applied after HW fuses are considered on each tile. Examples, bestie:

Allow only one render and one copy engine, nothing else:

# echo 'rcs0,bcs0' > /sys/kernel/config/xe/0000:03:00.0/engines_allowed

Allow only compute engines and the first copy engine:

# echo 'ccs*,bcs0' > /sys/kernel/config/xe/0000:03:00.0/engines_allowed

Lowkey important: the engine names are the per-GT hardware names. On multi-tile platforms, writing rcs0,bcs0 to this file would allow the first render and copy engines on each tile.

Also the requested configuration may not be supported by the platform and the driver may fail to probe. For example: if at least one copy engine is expected to be available for migrations, but it's disabled. This is intended for debugging purposes only — fr fr, don't ship this.

⚠️ This attribute can only be set before binding to the device.

PSMI

Enable extra debugging capabilities to trace engine execution 👀. Only useful during early platform enabling, and it requires additional hardware connected. Once it's enabled, additionals WAs are added and runtime configuration is done via debugfs. Example to enable it:

# echo 1 > /sys/kernel/config/xe/0000:03:00.0/enable_psmi
⚠️ This attribute can only be set before binding to the device.

Context restore BB

This lets you execute a batch buffer during any context switches. When the GPU is restoring the context, it executes additional commands. Super useful for testing additional workarounds and validating certain HW behaviors — but it is not intended for normal execution and will taint the kernel with TAINT_TEST when used 💀.

The syntax lets you pass straight instructions to be executed by the engine in a batch buffer, or set specific registers.

  1. Generic instruction:
<engine-class> cmd <instr> [[dword0] [dword1] [...]]
  1. Simple register setting:
<engine-class> reg <address> <value>

Commands are saved per engine class: all instances of that class will execute those commands during context switch. The instruction, dword arguments, addresses and values are in hex format, like in the examples below.

  1. Execute a LRI command to write 0xDEADBEEF to register 0x4f10 after the normal context restore:
# echo 'rcs cmd 11000001 4F100 DEADBEEF'              > /sys/kernel/config/xe/0000:03:00.0/ctx_restore_post_bb
  1. Execute a LRI command to write 0xDEADBEEF to register 0x4f10 at the beginning of the context restore:
# echo 'rcs cmd 11000001 4F100 DEADBEEF'              > /sys/kernel/config/xe/0000:03:00.0/ctx_restore_mid_bb
  1. Load certain values in a couple of registers (it can be used as a simpler alternative to the cmd action):
# cat > /sys/kernel/config/xe/0000:03:00.0/ctx_restore_post_bb <<EOF
rcs reg 4F100 DEADBEEF
rcs reg 4F104 FFFFFFFF
EOF
📝 note: When using multiple lines, make sure to use a command that is implemented with a single write syscall, like HEREDOC.

Currently this is implemented only for post and mid context restore, and these attributes can only be set before binding to the device.

Max SR-IOV Virtual Functions

This config allows you to limit the number of the Virtual Functions (VFs) that can be managed by the Physical Function (PF) driver — and a value of 0 disables the PF mode entirely (no VFs).

The default max_vfs config value is taken from the max_vfs modparam.

How to enable PF with support for an unlimited (up to HW limit) number of VFs:

# echo unlimited > /sys/kernel/config/xe/0000:00:02.0/sriov/max_vfs
# echo 0000:00:02.0 > /sys/bus/pci/drivers/xe/bind

How to enable PF with support up to 3 VFs:

# echo 3 > /sys/kernel/config/xe/0000:00:02.0/sriov/max_vfs
# echo 0000:00:02.0 > /sys/bus/pci/drivers/xe/bind

How to disable PF mode and always run as native:

# echo 0 > /sys/kernel/config/xe/0000:00:02.0/sriov/max_vfs
# echo 0000:00:02.0 > /sys/bus/pci/drivers/xe/bind

This setting only takes effect when probing the device.

Enable multi-queue

Multi-queue support on the device is enabled by default where the hardware supports it ✨. Writing 0 force-disables multi-queue support: multi-queue exec-queue group creation via ioctl is refused, and the GuC feature is disabled:

# echo 0 > /sys/kernel/config/xe/0000:03:00.0/enable_multi_queue
⚠️ This attribute can only be set before binding to the device.

🌈 Remove devices 🌈

Cleanup era! The created device directories can be removed using rmdir:

# rmdir /sys/kernel/config/xe/0000:03:00.0/

👑 SEE ALSO

And that's the whole page, bestie 🧚💜 — brought to you from ./drivers/gpu/drm/xe, dated October 2026. Slay, go configure some GPUs responsibly 💅✨

📦 where this page comes from