Xe Configfs¶

Overview¶

Configfs is a filesystem-based manager of kernel objects. XE KMD registers a configfs subsystem called xe that creates a directory in the mounted configfs directory. The user can create devices under this directory and configure them as necessary. See Configfs - Userspace-driven Kernel Object Configuration for more information about how configfs works.

Create devices¶

To create a device, the xe module should already be loaded, but some attributes can only be set before binding the device. It can be accomplished by blocking the driver autoprobe:

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

In order to create a device, the user has to create a directory inside xe:

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

Every device created is populated by the driver with entries that can be used 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

After configuring the attributes as per next section, the device can be probed 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. This setting only takes effect when probing the device. Example to enable it:

# 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:¶

Allow only specific types of GTs to be detected and initialized by the driver. Any combination of GT types can be enabled/disabled, although 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. 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:¶

Allow only a set of engine(s) to be available, disabling the other engines even if they are available in hardware. This is applied after HW fuses are considered on each tile. Examples:

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

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

Allow only compute engines and first copy engine:

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

Note that 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.

The requested configuration may not be supported by the platform and 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.

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 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¶

Allow to execute a batch buffer during any context switches. When the GPU is restoring the context, it executes additional commands. It’s useful for testing additional workarounds and validating certain HW behaviors: it’s not intended for normal execution and will taint the kernel with TAINT_TEST when used.

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

Generic instruction:

<engine-class> cmd <instr> [[dword0] [dword1] [...]]

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.

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

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

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 to limit number of the Virtual Functions (VFs) that can be managed by the Physical Function (PF) driver, where value 0 disables the PF mode (no VFs).

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

How to enable PF with support with 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.

Remove devices¶

The created device directories can be removed using rmdir:

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

Internal API¶

void xe_configfs_check_device(struct pci_dev *pdev)¶: Test if device was configured by configfs

Parameters

struct pci_dev *pdev: the pci_dev device to test

Description

Try to find the configfs group that belongs to the specified pci device and print a diagnostic message if different than the default value.

bool xe_configfs_get_survivability_mode(struct pci_dev *pdev)¶: get configfs survivability mode attribute

Parameters

struct pci_dev *pdev: pci device

Return

survivability_mode attribute in configfs

bool xe_configfs_primary_gt_allowed(struct pci_dev *pdev)¶: determine whether primary GTs are supported

Parameters

struct pci_dev *pdev: pci device

Return

True if primary GTs are enabled, false if they have been disabled via configfs.

bool xe_configfs_media_gt_allowed(struct pci_dev *pdev)¶: determine whether media GTs are supported

Parameters

struct pci_dev *pdev: pci device

Return

True if the media GTs are enabled, false if they have been disabled via configfs.

u64 xe_configfs_get_engines_allowed(struct pci_dev *pdev)¶: get engine allowed mask from configfs

Parameters

struct pci_dev *pdev: pci device

Return

engine mask with allowed engines set in configfs

bool xe_configfs_get_psmi_enabled(struct pci_dev *pdev)¶: get configfs enable_psmi setting

Parameters

struct pci_dev *pdev: pci device

Return

enable_psmi setting in configfs

u32 xe_configfs_get_ctx_restore_mid_bb(struct pci_dev *pdev, enum xe_engine_class class, const u32 **cs)¶: get configfs ctx_restore_mid_bb setting

Parameters

struct pci_dev *pdev: pci device
enum xe_engine_class class: hw engine class
const u32 **cs: pointer to the bb to use - only valid during probe

Return

Number of dwords used in the mid_ctx_restore setting in configfs

u32 xe_configfs_get_ctx_restore_post_bb(struct pci_dev *pdev, enum xe_engine_class class, const u32 **cs)¶: get configfs ctx_restore_post_bb setting

Parameters

struct pci_dev *pdev: pci device
enum xe_engine_class class: hw engine class
const u32 **cs: pointer to the bb to use - only valid during probe

Return

Number of dwords used in the post_ctx_restore setting in configfs

unsigned int xe_configfs_get_max_vfs(struct pci_dev *pdev)¶: Get number of VFs that could be managed

Parameters

struct pci_dev *pdev: the pci_dev device

Description

Find the configfs group that belongs to the PCI device and return maximum number of Virtual Functions (VFs) that could be managed by this device. If configfs group is not present, use value of max_vfs module parameter.

Return

maximum number of VFs that could be managed.