Re: [PATCH v7 1/1] drm/xe/xe_ras: Add RAS GPU health indicator

["Tauro, Riana" <riana.tauro@intel.com>]

On 08-07-2026 13:27, Purkait, Soham wrote:
> Hi Riana,
>
> On 08-07-2026 13:10, Tauro, Riana wrote:
>>
>> On 08-07-2026 11:42, Soham Purkait wrote:
>>> Add a sysfs interface that reports the current GPU health state and
>>> lets admin users and management tools update it but is readable by all
>>> users. Requests are routed through the sysctrl mailbox. The interface
>>> is present only on platforms that support the GPU health indicator.
>>>
>>> The interface is a single read/write file at the device level:
>>>
>>>    $ cat /sys/.../device/gpu_health
>>>    ok
>>>
>>>    $ echo critical > /sys/.../device/gpu_health
>>>
>>>    $ cat /sys/.../device/gpu_health
>>>    critical
>>>
>>> v1:
>>>   - Add enum for health status. (Andi, Rodrigo)
>>>   - Return error number instead of error message in _show/_store. 
>>> (Andi)
>>>   - Move GPU health sysfs init error logging to xe_ras_init. (Andi)
>>>   - Return only the current health state for sysfs read. (Andi, 
>>> Rodrigo)
>>>   - Add documentation for sysfs interface. (Andi, Rodrigo)
>>>
>>> v2:
>>>   - Make logs and structures consistent with their counterparts. 
>>> (Riana)
>>>   - Drop unnecessary variables. (Andi, Riana)
>>>   - Add correct KernelVersion. (Raag)
>>>
>>> v3:
>>>   - Add missing blank line before #endif. (Badal)
>>>
>>> v4:
>>>   - Add consistent "gpu" nomenclature to the gpu health indicator
>>>     DOC blocks. (Riana)
>>>   - Add Kdoc for gpu health indicator. (Anshuman)
>>>
>>> v5:
>>>   - Rename struct fields to response.health, request.health. (Riana, 
>>> Raag)
>>>   - Use devm_device_add_group instead of custom sysfs init/fini. (Raag)
>>>   - Rename health enum to shorter XE_RAS_HEALTH_*, drop redundant
>>>     invalid-input log, and minor log/format cleanups. (Raag)
>>>
>>> Signed-off-by: Soham Purkait <soham.purkait@intel.com>
>>> Acked-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
>>> Reviewed-by: Andi Shyti <andi.shyti@linux.intel.com>
>>> Reviewed-by: Badal Nilawar <badal.nilawar@intel.com>
>>> ---
>>>   .../ABI/testing/sysfs-driver-intel-xe-ras     |  30 ++++
>>>   Documentation/gpu/xe/xe_device.rst            |   9 ++
>>>   drivers/gpu/drm/xe/xe_ras.c                   | 139 
>>> ++++++++++++++++++
>>>   drivers/gpu/drm/xe/xe_ras_types.h             |  57 +++++++
>>>   drivers/gpu/drm/xe/xe_sysctrl_mailbox_types.h |   4 +
>>>   5 files changed, 239 insertions(+)
>>>   create mode 100644 
>>> Documentation/ABI/testing/sysfs-driver-intel-xe-ras
>>>
>>> diff --git a/Documentation/ABI/testing/sysfs-driver-intel-xe-ras 
>>> b/Documentation/ABI/testing/sysfs-driver-intel-xe-ras
>>> new file mode 100644
>>> index 000000000000..9612b97b0f88
>>> --- /dev/null
>>> +++ b/Documentation/ABI/testing/sysfs-driver-intel-xe-ras
>>> @@ -0,0 +1,30 @@
>>> +What:        /sys/bus/pci/drivers/xe/.../gpu_health
>>> +Date:        April 2026
>>> +KernelVersion:    7.2
>>> +Contact:    intel-xe@lists.freedesktop.org
>>> +Description:
>>> +        This file exposes the current gpu health state and allows 
>>> the gpu
>>> +        health state to be updated.
>>> +
>>> +        This sysfs file is present only on Intel Xe platforms that 
>>> support
>>> +        the gpu health indicator interface for RAS. Reading the 
>>> current
>>> +        health state is available to all users, while updating the 
>>> health
>>> +        state is restricted to administrative users only.
>>> +
>>> +        Read returns a single line containing one of the valid 
>>> values for
>>> +        the current gpu health state. Writing one of the valid values
>>> +        updates the current gpu health state.
>>> +
>>> +        The valid values for the gpu health state are:
>>> +
>>> +            ok
>>> +                The gpu is healthy and operating within normal
>>> +                parameters.
>>> +
>>> +            warning
>>> +                The gpu is experiencing minor issues but remains
>>> +                operational.
>>> +
>>> +            critical
>>> +                The gpu is in a critical state and may not be
>>> +                operational.
>>> diff --git a/Documentation/gpu/xe/xe_device.rst 
>>> b/Documentation/gpu/xe/xe_device.rst
>>> index 39a937b97cd3..6fdba960c2d9 100644
>>> --- a/Documentation/gpu/xe/xe_device.rst
>>> +++ b/Documentation/gpu/xe/xe_device.rst
>>> @@ -8,3 +8,12 @@ Xe Device Wedging
>>>     .. kernel-doc:: drivers/gpu/drm/xe/xe_device.c
>>>      :doc: Xe Device Wedging
>>> +
>>> +.. _xe-gpu-health-indicator:
>>
>> Where is this used?
>>
>>> +
>>> +====================
>>> +GPU Health Indicator
>>> +====================
>>> +
>>> +.. kernel-doc:: drivers/gpu/drm/xe/xe_ras.c
>>> +   :doc: GPU Health Indicator
>>> diff --git a/drivers/gpu/drm/xe/xe_ras.c b/drivers/gpu/drm/xe/xe_ras.c
>>> index 74d5016d9ffe..d1214a213d6e 100644
>>> --- a/drivers/gpu/drm/xe/xe_ras.c
>>> +++ b/drivers/gpu/drm/xe/xe_ras.c
>>> @@ -65,6 +65,13 @@ static const char *const xe_ras_components[] = {
>>>   };
>>>   static_assert(ARRAY_SIZE(xe_ras_components) == XE_RAS_COMP_MAX);
>>>   +static const char * const gpu_health_states[] = {
>>
>> status or states. Use any one consistently.
>>
>>> +    [XE_RAS_HEALTH_OK]        = "ok",
>>> +    [XE_RAS_HEALTH_WARNING]        = "warning",
>>> +    [XE_RAS_HEALTH_CRITICAL]    = "critical",
>>> +};
>>> +static_assert(ARRAY_SIZE(gpu_health_states) == XE_RAS_HEALTH_MAX);
>>> +
>>>   static u8 drm_to_xe_ras_severity(u8 severity)
>>>   {
>>>       switch (severity) {
>>> @@ -332,6 +339,132 @@ int xe_ras_clear_counter(struct xe_device *xe, 
>>> u8 severity, u8 component)
>>>       return 0;
>>>   }
>>>   +static ssize_t gpu_health_show(struct device *dev, struct 
>>> device_attribute *attr, char *buf)
>>> +{
>>> +    struct xe_ras_get_health_response response = {0};
>>> +    struct xe_sysctrl_mailbox_command command = {0};
>>> +    struct xe_ras_get_health_request request = {0};
>>> +    struct xe_device *xe = kdev_to_xe_device(dev);
>>> +    const char *health;
>>> +    size_t rlen;
>>> +    int ret;
>>> +
>>> +    xe_sysctrl_create_command(&command, XE_SYSCTRL_GROUP_GFSP, 
>>> XE_SYSCTRL_CMD_GET_HEALTH,
>>> +                  &request, sizeof(request), &response, 
>>> sizeof(response));
>>> +    guard(xe_pm_runtime)(xe);
>>> +    ret = xe_sysctrl_send_command(&xe->sc, &command, &rlen);
>>> +    if (ret) {
>>> +        xe_err(xe, "sysctrl: failed to get health %d\n", ret);
>>> +        return ret;
>>> +    }
>>> +
>>> +    if (rlen != sizeof(response)) {
>>> +        xe_err(xe, "sysctrl: unexpected get health response length 
>>> %zu (expected %zu)\n",
>>> +               rlen, sizeof(response));
>>> +        return -EIO;
>>> +    }
>>> +    if (response.health >= XE_RAS_HEALTH_MAX) {
>>> +        xe_err(xe, "sysctrl: invalid health state %u\n",
>>> +               response.health);
>>> +        return -EIO;
>>> +    }
>>> +
>>> +    health = gpu_health_states[response.health];
>>> +
>>> +    xe_dbg(xe, "[RAS]: get health: %s\n", health);
>>> +
>>> +    return sysfs_emit(buf, "%s\n", health);
>>> +}
>>> +
>>> +static ssize_t gpu_health_store(struct device *dev, struct 
>>> device_attribute *attr,
>>> +                const char *buf, size_t count)
>>> +{
>>> +    struct xe_ras_set_health_response response = {0};
>>> +    struct xe_sysctrl_mailbox_command command = {0};
>>> +    struct xe_ras_set_health_request request = {0};
>>> +    struct xe_device *xe = kdev_to_xe_device(dev);
>>> +    const char *health;
>>> +    size_t rlen;
>>> +    int state;
>>> +    int ret;
>>> +
>>> +    state = sysfs_match_string(gpu_health_states, buf);
>>> +    if (state < 0)
>>> +        return -EINVAL;
>>> +
>>> +    request.health = state;
>>> +
>>> +    xe_sysctrl_create_command(&command, XE_SYSCTRL_GROUP_GFSP, 
>>> XE_SYSCTRL_CMD_SET_HEALTH,
>>> +                  &request, sizeof(request), &response, 
>>> sizeof(response));
>>> +    guard(xe_pm_runtime)(xe);
>>> +    ret = xe_sysctrl_send_command(&xe->sc, &command, &rlen);
>>> +    if (ret) {
>>> +        xe_err(xe, "sysctrl: failed to set health %d\n", ret);
>>> +        return ret;
>>> +    }
>>> +
>>> +    if (rlen != sizeof(response)) {
>>> +        xe_err(xe, "sysctrl: unexpected set health response length 
>>> %zu (expected %zu)\n",
>>> +               rlen, sizeof(response));
>>> +        return -EIO;
>>> +    }
>>> +
>>> +    ret = ras_status_to_errno(response.status);
>>> +    if (ret) {
>>> +        xe_err(xe, "sysctrl: set health command failed with status 
>>> %#x\n",
>>> +               response.status);
>>> +        return ret;
>>> +    }
>>> +
>>> +    if (response.health >= XE_RAS_HEALTH_MAX) {
>>> +        xe_err(xe, "sysctrl: invalid health state %u\n",
>>> +               response.health);
>>> +        return -EIO;
>>> +    }
>>> +
>>> +    health = gpu_health_states[response.health];
>>> +
>>> +    xe_dbg(xe, "[RAS]: set health: %s\n", health);
>>> +
>>> +    return count;
>>> +}
>>> +
>>> +static DEVICE_ATTR_RW(gpu_health);
>>> +
>>> +static struct attribute *gpu_health_attrs[] = {
>>> +    &dev_attr_gpu_health.attr,
>>> +    NULL,
>>> +};
>>> +
>>> +/**
>>> + * DOC: GPU Health Indicator
>>> + *
>>> + * On Intel Xe platforms that support the GPU health indicator 
>>> interface,
>>> + * the driver exposes a sysfs attribute at the device level as:
>>> + *
>> code block would be appropriate
>>
>>> + * ``/sys/bus/pci/drivers/xe/<BDF>/gpu_health``
>>> + *
>>> + * Reading the attribute returns a single line containing the 
>>> current GPU
>>> + * health state. Writing one of the valid values updates the same. 
>>> Reads
>>> + * are available to all users; writes are restricted to administrative
>>> + * users only (attribute permissions ``0644``).
>>
>> Can these be set by firmware too? Worth mentioning incase an admin 
>> had never set
> Does this  falls under the scope of this doc ? 


I am asking.  Do you know if firmware is allowed to set it too? Or is it 
only admin.
If as a admin i am reading this document i see that only i am allowed to 
set.

>> the value and sees a warning.
>>
>> Do we need to mention when user needs to use this?
>>
>>
>>> + *
>>> + * The valid values for the GPU health state are:
>>> + *
>>> + * - ``ok``:
>>> + *    The GPU is healthy and operating within normal parameters.
>>
>> Have you generated the document?
> yes.

Any reason for having the description and the status in different lines?

Thanks
Riana

>
> Thanks,
> Soham.
>>
>>> + * - ``warning``:
>>> + *    The GPU is experiencing minor issues but remains operational.
>>> + * - ``critical``:
>>> + *    The GPU is in a critical state and may not be operational.
>>> + *
>>> + * See Documentation/ABI/testing/sysfs-driver-intel-xe-ras for the ABI
>>> + * specification.
>>> + */
>>> +static const struct attribute_group gpu_health_group = {
>>> +    .attrs = gpu_health_attrs,
>>> +};
>>> +
>>>   /**
>>>    * xe_ras_init - Initialize Xe RAS
>>>    * @xe: xe device instance
>>> @@ -340,6 +473,8 @@ int xe_ras_clear_counter(struct xe_device *xe, 
>>> u8 severity, u8 component)
>>>    */
>>>   void xe_ras_init(struct xe_device *xe)
>>>   {
>>> +    int ret;
>>> +
>>>       if (!xe->info.has_drm_ras)
>>>           return;
>>>   @@ -350,4 +485,8 @@ void xe_ras_init(struct xe_device *xe)
>>>         if (IS_ENABLED(CONFIG_PCIEAER))
>>>           ras_usp_aer_init(xe);
>>> +
>>> +    ret = devm_device_add_group(xe->drm.dev, &gpu_health_group);
>>> +    if (ret)
>>> +        xe_err(xe, "Failed to initialize GPU health sysfs, 
>>> err=%d\n", ret);
>>>   }
>>> diff --git a/drivers/gpu/drm/xe/xe_ras_types.h 
>>> b/drivers/gpu/drm/xe/xe_ras_types.h
>>> index 6688e11f57a8..4c4fbc42c956 100644
>>> --- a/drivers/gpu/drm/xe/xe_ras_types.h
>>> +++ b/drivers/gpu/drm/xe/xe_ras_types.h
>>> @@ -10,6 +10,21 @@
>>>     #define XE_RAS_NUM_COUNTERS            16
>>>   +/**
>>> + * enum xe_ras_health_status - gpu health status values
>>> + *
>>> + * @XE_RAS_HEALTH_OK: gpu is healthy and operating normally.
>>> + * @XE_RAS_HEALTH_WARNING: gpu has minor issues but is still 
>>> operational.
>>> + * @XE_RAS_HEALTH_CRITICAL: gpu is in a critical state and may not 
>>> be operational.
>>> + * @XE_RAS_HEALTH_MAX: Sentinel value for validation
>>> + */
>>> +enum xe_ras_health_status {
>>
>> If you removed status from enum, remove from name as well.
>>
>>> +    XE_RAS_HEALTH_OK = 0,
>>> +    XE_RAS_HEALTH_WARNING,
>>> +    XE_RAS_HEALTH_CRITICAL,
>>> +    XE_RAS_HEALTH_MAX
>>> +};
>>> +
>>>   /**
>>>    * struct xe_ras_error_common - Error fields that are common 
>>> across all products
>>>    */
>>> @@ -121,4 +136,46 @@ struct xe_ras_clear_counter_response {
>>>       /** @reserved1: Reserved for future use */
>>>       u32 reserved1[3];
>>>   } __packed;
>>> +
>>> +/**
>>> + * struct xe_ras_get_health_request - Request structure for 
>>> obtaining gpu health
>>> + */
>>> +struct xe_ras_get_health_request {
>>> +    /** @reserved: Reserved for future use. */
>>> +    u32 reserved[2];
>>> +} __packed;
>>> +
>>> +/**
>>> + * struct xe_ras_get_health_response - Response structure for 
>>> obtaining gpu health
>>> + */
>>> +struct xe_ras_get_health_response {
>>> +    /** @health: Current gpu health, see &enum xe_ras_health_status */
>>> +    u8 health;
>>> +    /** @reserved: Reserved for future use */
>>> +    u8 reserved[3];
>>> +} __packed;
>>> +
>>> +/**
>>> + * struct xe_ras_set_health_request - Request structure for setting 
>>> gpu health
>>> + */
>>> +struct xe_ras_set_health_request {
>>> +    /** @health: New gpu health to set, see &enum 
>>> xe_ras_health_status */
>>
>>
>> Let's use short description . "gpu health to be set" or just gpu health
>>
>>> +    u8 health;
>>> +    /** @reserved: Reserved for future use */
>>> +    u8 reserved[3];
>>> +} __packed;
>>> +
>>> +/**
>>> + * struct xe_ras_set_health_response - Response structure for 
>>> setting gpu health
>>> + */
>>> +struct xe_ras_set_health_response {
>>> +    /** @status: Status of set health operation, see &enum 
>>> xe_ras_response_status */
>>> +    u32 status;
>>> +    /** @health: Resulting current gpu health, see &enum 
>>> xe_ras_health_status */
>> Let's use short description . "current gpu health" or just gpu health
>>> +    u8 health;
>>> +    /** @reserved: Reserved for future use */
>>> +    u8 reserved[3];
>>> +    /** @reserved1: Reserved for future use */
>>> +    u32 reserved1[2];
>>> +} __packed;
>>>   #endif
>>> diff --git a/drivers/gpu/drm/xe/xe_sysctrl_mailbox_types.h 
>>> b/drivers/gpu/drm/xe/xe_sysctrl_mailbox_types.h
>>> index 6e3753554510..d4da6e9ef774 100644
>>> --- a/drivers/gpu/drm/xe/xe_sysctrl_mailbox_types.h
>>> +++ b/drivers/gpu/drm/xe/xe_sysctrl_mailbox_types.h
>>> @@ -25,11 +25,15 @@ enum xe_sysctrl_group {
>>>    * @XE_SYSCTRL_CMD_GET_COUNTER: Get error counter value
>>>    * @XE_SYSCTRL_CMD_CLEAR_COUNTER: Clear error counter value
>>>    * @XE_SYSCTRL_CMD_GET_PENDING_EVENT: Retrieve pending event
>>> + * @XE_SYSCTRL_CMD_GET_HEALTH: Retrieve current health status
>>
>> gpu health
>>
>> Thanks
>> Riana
>>
>>> + * @XE_SYSCTRL_CMD_SET_HEALTH: Set new health status
>>>    */
>>>   enum xe_sysctrl_gfsp_cmd {
>>>       XE_SYSCTRL_CMD_GET_COUNTER        = 0x03,
>>>       XE_SYSCTRL_CMD_CLEAR_COUNTER        = 0x04,
>>>       XE_SYSCTRL_CMD_GET_PENDING_EVENT    = 0x07,
>>> +    XE_SYSCTRL_CMD_GET_HEALTH        = 0x0B,
>>> +    XE_SYSCTRL_CMD_SET_HEALTH        = 0x0C,
>>>   };
>>>     /**