Re: [PATCH v3 7/9] drm/xe/hwmon: Add kernel-doc for fan control

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

Hi Karthik,

On 16-10-2026 00:37, Karthik Poosa wrote:
> Add kernel-doc for xe hwmon fan control and describe the fan control
> model built around firmware stock tables and driver-managed user tables.
>
> Document the exposed sysfs files for fan speed, maximum speed, pwm
> control, pwm mode selection, and per-point fan curve temperature/PWM
> programming.
>
> This makes the hwmon fan control userspace interface easier to discover
> and understand.
>
> Signed-off-by: Karthik Poosa <karthik.poosa@intel.com>
> Assisted-by: LLM
> ---
>   drivers/gpu/drm/xe/xe_hwmon.c | 43 +++++++++++++++++++++++++++++++++++
>   1 file changed, 43 insertions(+)
>
> diff --git a/drivers/gpu/drm/xe/xe_hwmon.c b/drivers/gpu/drm/xe/xe_hwmon.c
> index de2adb56d15b..aa3c921407b5 100644
> --- a/drivers/gpu/drm/xe/xe_hwmon.c
> +++ b/drivers/gpu/drm/xe/xe_hwmon.c
> @@ -139,6 +139,49 @@ struct xe_hwmon_energy_info {
>   	long accum_energy;
>   };
>   
> +/**
> + * DOC: Xe fan control
> + *
> + * Xe fan control is exposed through the hwmon pwm and fan interfaces when the
> + * platform advertises PCODE-backed fan management support.
> + *
> + * The implementation tracks two fan tables per fan:
> + *
> + * - A stock table read from firmware through PCODE.
> + * - A user table cached in the driver and programmed back through PCODE.
> + *
> + * The pwmN_enable sysfs mode selects how those tables are used:
> + *
> + * - ``XE_FAN_PWM_AUTO_STOCK_TABLE`` restores automatic control using the stock
> + *   firmware table.
> + * - ``XE_FAN_PWM_MANUAL_USER_TABLE`` enables the user table for manual control.
> + * - ``XE_FAN_PWM_FULL_SPEED`` reuses the user table path but programs every
> + *   point to 100 percent duty cycle as a full-speed override.
> + *
> + * The fan-control sysfs files are:
> + *
> + * - ``fanN_input`` reports the measured fan speed in RPM.
> + * - ``fanN_max`` reports the maximum supported fan speed in RPM.
> + * - ``pwmN`` reads or sets the manual PWM duty cycle in the hwmon 0..255
> + *   range. Manual writes are accepted only while ``pwmN_enable`` is set to
> + *   ``XE_FAN_PWM_MANUAL_USER_TABLE``.
> + * - ``pwmN_enable`` selects stock automatic mode, manual user-table mode, or
> + *   full-speed override.
Should the ABI values be noted (0 = full speed, 1 = manual, 2 = 
automatic), since users write the number?
> + * - ``pwmN_auto_pointM_temp`` exposes the temperature threshold for user-table
> + *   point ``M`` in millidegrees Celsius.
> + * - ``pwmN_auto_pointM_pwm`` exposes the PWM value for user-table point ``M``
> + *   in the hwmon 0..255 range.
Is it required to mention that point writes also require pwmN_enable = 
manual, else they return invalid?
> + *
> + * Writes to pwmN_auto_pointM_temp and pwmN_auto_pointM_pwm update the cached
> + * user table entries. The driver commits the full user table once the last
> + * point has both temperature and PWM values, which keeps intermediate sysfs
> + * writes from pushing partially updated curves to firmware.
Could the (0, 0) end-marker be documented, since writing such a point 
terminates a shorter curve rather than requiring all points?
and also at least 2 points, non-decreasing temp and pwm, else invalid.

Regards,
Soham
> + *
> + * Writes to pwmN provide a constant manual duty cycle by rewriting every point
> + * in the active user table to the same PWM value, clamped against the minimum
> + * duty cycle reported by firmware for that fan.
> + */
> +
>   enum xe_fan_pwm_enable_mode {
>   	/** @XE_FAN_PWM_FULL_SPEED: force all user table points to full speed */
>   	XE_FAN_PWM_FULL_SPEED = 0,