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

["Purkait, Soham" <soham.purkait@intel.com>]

On 08-07-2026 13:31, Tauro, Riana wrote:
>
> 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. 
Then It could be explicitly mentioned that :  for only inbound cases.
As reset of the part is out of the scope of this doc.
>>> 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?
Just for the aesthetics nothing else.

Thanks,
Soham
>
> 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,
>>>>   };
>>>>     /**