[PATCH v2] drm/xe/hwmon: document DG2 fan speed reporting quirk

[PATCH v2] drm/xe/hwmon: document DG2 fan speed reporting quirk

[Zhan Wei]

The number of fanN_input attributes on DG2 is hardcoded to two because
FSC_READ_NUM_FANS returns an incorrect value on some boards. How the
physical fans map onto the tach channels is left to the board vendor:
some OEMs route multiple physical fans through a single shared tach
line, in which case the unwired channel's pulse counter never
accumulates and fanN_input reads a constant 0 RPM.

This is expected behaviour for such boards rather than a driver fault,
and the driver has no reliable way to distinguish a shared-tach layout
from a genuinely silent fan. Document this so the flat DG2 fan count is
not mistaken for a bug and "fixed" by lowering it, which would hide a
working fan2 on boards that do wire two tach lines.

Signed-off-by: Zhan Wei <zhanwei919@gmail.com>
---
v1 -> v2: Drop the code change. As pointed out in review, the same PCI
  device ID ships with both shared-tach (multiple physical fans on one
  channel) and 1:1 fan wiring, and FSC_READ_NUM_FANS is unreliable on
  some boards, so the DG2 fan count cannot be lowered without hiding a
  working fan2 on boards that do wire two tach lines. Document the
  behaviour instead of changing the reported fan count.

v1: https://lore.kernel.org/intel-xe/20260527115311.13398-1-zhanwei919@gmail.com/

 Documentation/gpu/xe/index.rst    |  1 +
 Documentation/gpu/xe/xe_hwmon.rst | 48 +++++++++++++++++++++++++++++++
 2 files changed, 49 insertions(+)
 create mode 100644 Documentation/gpu/xe/xe_hwmon.rst

diff --git a/Documentation/gpu/xe/index.rst b/Documentation/gpu/xe/index.rst
index 874ffcb6da3a..3c14cdcaa8a6 100644
--- a/Documentation/gpu/xe/index.rst
+++ b/Documentation/gpu/xe/index.rst
@@ -30,3 +30,4 @@ DG2, etc is provided to prototype the driver.
    xe-drm-usage-stats.rst
    xe_configfs
    xe_gt_stats
+   xe_hwmon
diff --git a/Documentation/gpu/xe/xe_hwmon.rst b/Documentation/gpu/xe/xe_hwmon.rst
new file mode 100644
index 000000000000..8cd48df59386
--- /dev/null
+++ b/Documentation/gpu/xe/xe_hwmon.rst
@@ -0,0 +1,48 @@
+.. SPDX-License-Identifier: (GPL-2.0+ OR MIT)
+
+=================
+Xe HWMON support
+=================
+
+The xe driver exposes hardware monitoring sensors (power, energy,
+temperature, voltage and fan speed) through the kernel hwmon subsystem,
+typically consumed via ``/sys/class/hwmon/hwmonX/`` or tools such as
+``sensors``.
+
+Fan speed reporting
+===================
+
+Fan speed (``fanN_input``) is reported in RPM and computed from a tach
+pulse counter: the driver reads an accumulating pulse register, divides
+the delta between two subsequent readings by two pulses per rotation,
+and time-averages the result.
+
+Number of fan channels
+-----------------------
+
+The number of ``fanN_input`` attributes exposed in sysfs is the fan
+count returned by the ``FSC_READ_NUM_FANS`` pcode command. On DG2 this
+command has been found to return an incorrect value on some boards, so
+the driver hardcodes a fan count of two there. As a result up to
+``fan1_input`` and ``fan2_input`` are always exposed on DG2 regardless
+of how many tach lines are actually wired.
+
+Zero RPM on DG2 is not necessarily a bug
+----------------------------------------
+
+How physical fans map onto the tach channels is left to the board
+vendor. Some OEMs route several physical fans through a single shared
+tach line, while others wire each fan to its own channel 1:1. The
+driver has no reliable way to tell these layouts apart, and the same PCI
+device ID can ship in either configuration.
+
+When a channel has no tach line driving it, its pulse counter never
+accumulates, so the corresponding ``fanN_input`` reads a constant 0 RPM.
+On DG2 this is most often seen on ``fan2_input`` for boards that drive
+both physical fans from a single tach line. This is expected behaviour
+for such boards, not a driver fault, and reflects the board wiring
+rather than a missing or stalled fan.
+
+For this reason the fan count on DG2 is intentionally left at a flat
+value rather than tracked per board: there is no driver-visible signal
+that distinguishes a shared-tach layout from a genuinely silent fan.
-- 
2.43.0

Re: [PATCH v2] drm/xe/hwmon: document DG2 fan speed reporting quirk

[占wei]

+Cc Raag, who authored the fan support and reviewed v1.

Thanks for your help, this v2 drops the code change and documents the
DG2 shared-tach behaviour instead, per your feedback on v1.

Zhan Wei <zhanwei919@gmail.com> 于2026年5月29日周五 21:50写道：
>
> The number of fanN_input attributes on DG2 is hardcoded to two because
> FSC_READ_NUM_FANS returns an incorrect value on some boards. How the
> physical fans map onto the tach channels is left to the board vendor:
> some OEMs route multiple physical fans through a single shared tach
> line, in which case the unwired channel's pulse counter never
> accumulates and fanN_input reads a constant 0 RPM.
>
> This is expected behaviour for such boards rather than a driver fault,
> and the driver has no reliable way to distinguish a shared-tach layout
> from a genuinely silent fan. Document this so the flat DG2 fan count is
> not mistaken for a bug and "fixed" by lowering it, which would hide a
> working fan2 on boards that do wire two tach lines.
>
> Signed-off-by: Zhan Wei <zhanwei919@gmail.com>
> ---
> v1 -> v2: Drop the code change. As pointed out in review, the same PCI
>   device ID ships with both shared-tach (multiple physical fans on one
>   channel) and 1:1 fan wiring, and FSC_READ_NUM_FANS is unreliable on
>   some boards, so the DG2 fan count cannot be lowered without hiding a
>   working fan2 on boards that do wire two tach lines. Document the
>   behaviour instead of changing the reported fan count.
>
> v1: https://lore.kernel.org/intel-xe/20260527115311.13398-1-zhanwei919@gmail.com/
>
>  Documentation/gpu/xe/index.rst    |  1 +
>  Documentation/gpu/xe/xe_hwmon.rst | 48 +++++++++++++++++++++++++++++++
>  2 files changed, 49 insertions(+)
>  create mode 100644 Documentation/gpu/xe/xe_hwmon.rst
>
> diff --git a/Documentation/gpu/xe/index.rst b/Documentation/gpu/xe/index.rst
> index 874ffcb6da3a..3c14cdcaa8a6 100644
> --- a/Documentation/gpu/xe/index.rst
> +++ b/Documentation/gpu/xe/index.rst
> @@ -30,3 +30,4 @@ DG2, etc is provided to prototype the driver.
>     xe-drm-usage-stats.rst
>     xe_configfs
>     xe_gt_stats
> +   xe_hwmon
> diff --git a/Documentation/gpu/xe/xe_hwmon.rst b/Documentation/gpu/xe/xe_hwmon.rst
> new file mode 100644
> index 000000000000..8cd48df59386
> --- /dev/null
> +++ b/Documentation/gpu/xe/xe_hwmon.rst
> @@ -0,0 +1,48 @@
> +.. SPDX-License-Identifier: (GPL-2.0+ OR MIT)
> +
> +=================
> +Xe HWMON support
> +=================
> +
> +The xe driver exposes hardware monitoring sensors (power, energy,
> +temperature, voltage and fan speed) through the kernel hwmon subsystem,
> +typically consumed via ``/sys/class/hwmon/hwmonX/`` or tools such as
> +``sensors``.
> +
> +Fan speed reporting
> +===================
> +
> +Fan speed (``fanN_input``) is reported in RPM and computed from a tach
> +pulse counter: the driver reads an accumulating pulse register, divides
> +the delta between two subsequent readings by two pulses per rotation,
> +and time-averages the result.
> +
> +Number of fan channels
> +-----------------------
> +
> +The number of ``fanN_input`` attributes exposed in sysfs is the fan
> +count returned by the ``FSC_READ_NUM_FANS`` pcode command. On DG2 this
> +command has been found to return an incorrect value on some boards, so
> +the driver hardcodes a fan count of two there. As a result up to
> +``fan1_input`` and ``fan2_input`` are always exposed on DG2 regardless
> +of how many tach lines are actually wired.
> +
> +Zero RPM on DG2 is not necessarily a bug
> +----------------------------------------
> +
> +How physical fans map onto the tach channels is left to the board
> +vendor. Some OEMs route several physical fans through a single shared
> +tach line, while others wire each fan to its own channel 1:1. The
> +driver has no reliable way to tell these layouts apart, and the same PCI
> +device ID can ship in either configuration.
> +
> +When a channel has no tach line driving it, its pulse counter never
> +accumulates, so the corresponding ``fanN_input`` reads a constant 0 RPM.
> +On DG2 this is most often seen on ``fan2_input`` for boards that drive
> +both physical fans from a single tach line. This is expected behaviour
> +for such boards, not a driver fault, and reflects the board wiring
> +rather than a missing or stalled fan.
> +
> +For this reason the fan count on DG2 is intentionally left at a flat
> +value rather than tracked per board: there is no driver-visible signal
> +that distinguishes a shared-tach layout from a genuinely silent fan.
> --
> 2.43.0
>

Re: [PATCH v2] drm/xe/hwmon: document DG2 fan speed reporting quirk

[Raag Jadav]

On Fri, May 29, 2026 at 10:05:58PM +0800, 占wei wrote:
> +Cc Raag, who authored the fan support and reviewed v1.
> 
> Thanks for your help, this v2 drops the code change and documents the
> DG2 shared-tach behaviour instead, per your feedback on v1.

IMO it's a bit verbose to have a dedicated doc for this. Just add a small
comment in the existing ABI doc[1] under fan channel description.

[1] Documentation/ABI/testing/sysfs-driver-intel-xe-hwmon

Raag

> Zhan Wei <zhanwei919@gmail.com> 于2026年5月29日周五 21:50写道：
> >
> > The number of fanN_input attributes on DG2 is hardcoded to two because
> > FSC_READ_NUM_FANS returns an incorrect value on some boards. How the
> > physical fans map onto the tach channels is left to the board vendor:
> > some OEMs route multiple physical fans through a single shared tach
> > line, in which case the unwired channel's pulse counter never
> > accumulates and fanN_input reads a constant 0 RPM.
> >
> > This is expected behaviour for such boards rather than a driver fault,
> > and the driver has no reliable way to distinguish a shared-tach layout
> > from a genuinely silent fan. Document this so the flat DG2 fan count is
> > not mistaken for a bug and "fixed" by lowering it, which would hide a
> > working fan2 on boards that do wire two tach lines.
> >
> > Signed-off-by: Zhan Wei <zhanwei919@gmail.com>
> > ---
> > v1 -> v2: Drop the code change. As pointed out in review, the same PCI
> >   device ID ships with both shared-tach (multiple physical fans on one
> >   channel) and 1:1 fan wiring, and FSC_READ_NUM_FANS is unreliable on
> >   some boards, so the DG2 fan count cannot be lowered without hiding a
> >   working fan2 on boards that do wire two tach lines. Document the
> >   behaviour instead of changing the reported fan count.
> >
> > v1: https://lore.kernel.org/intel-xe/20260527115311.13398-1-zhanwei919@gmail.com/
> >
> >  Documentation/gpu/xe/index.rst    |  1 +
> >  Documentation/gpu/xe/xe_hwmon.rst | 48 +++++++++++++++++++++++++++++++
> >  2 files changed, 49 insertions(+)
> >  create mode 100644 Documentation/gpu/xe/xe_hwmon.rst
> >
> > diff --git a/Documentation/gpu/xe/index.rst b/Documentation/gpu/xe/index.rst
> > index 874ffcb6da3a..3c14cdcaa8a6 100644
> > --- a/Documentation/gpu/xe/index.rst
> > +++ b/Documentation/gpu/xe/index.rst
> > @@ -30,3 +30,4 @@ DG2, etc is provided to prototype the driver.
> >     xe-drm-usage-stats.rst
> >     xe_configfs
> >     xe_gt_stats
> > +   xe_hwmon
> > diff --git a/Documentation/gpu/xe/xe_hwmon.rst b/Documentation/gpu/xe/xe_hwmon.rst
> > new file mode 100644
> > index 000000000000..8cd48df59386
> > --- /dev/null
> > +++ b/Documentation/gpu/xe/xe_hwmon.rst
> > @@ -0,0 +1,48 @@
> > +.. SPDX-License-Identifier: (GPL-2.0+ OR MIT)
> > +
> > +=================
> > +Xe HWMON support
> > +=================
> > +
> > +The xe driver exposes hardware monitoring sensors (power, energy,
> > +temperature, voltage and fan speed) through the kernel hwmon subsystem,
> > +typically consumed via ``/sys/class/hwmon/hwmonX/`` or tools such as
> > +``sensors``.
> > +
> > +Fan speed reporting
> > +===================
> > +
> > +Fan speed (``fanN_input``) is reported in RPM and computed from a tach
> > +pulse counter: the driver reads an accumulating pulse register, divides
> > +the delta between two subsequent readings by two pulses per rotation,
> > +and time-averages the result.
> > +
> > +Number of fan channels
> > +-----------------------
> > +
> > +The number of ``fanN_input`` attributes exposed in sysfs is the fan
> > +count returned by the ``FSC_READ_NUM_FANS`` pcode command. On DG2 this
> > +command has been found to return an incorrect value on some boards, so
> > +the driver hardcodes a fan count of two there. As a result up to
> > +``fan1_input`` and ``fan2_input`` are always exposed on DG2 regardless
> > +of how many tach lines are actually wired.
> > +
> > +Zero RPM on DG2 is not necessarily a bug
> > +----------------------------------------
> > +
> > +How physical fans map onto the tach channels is left to the board
> > +vendor. Some OEMs route several physical fans through a single shared
> > +tach line, while others wire each fan to its own channel 1:1. The
> > +driver has no reliable way to tell these layouts apart, and the same PCI
> > +device ID can ship in either configuration.
> > +
> > +When a channel has no tach line driving it, its pulse counter never
> > +accumulates, so the corresponding ``fanN_input`` reads a constant 0 RPM.
> > +On DG2 this is most often seen on ``fan2_input`` for boards that drive
> > +both physical fans from a single tach line. This is expected behaviour
> > +for such boards, not a driver fault, and reflects the board wiring
> > +rather than a missing or stalled fan.
> > +
> > +For this reason the fan count on DG2 is intentionally left at a flat
> > +value rather than tracked per board: there is no driver-visible signal
> > +that distinguishes a shared-tach layout from a genuinely silent fan.
> > --
> > 2.43.0
> >

[PATCH v3] drm/xe/hwmon: document DG2 fan speed reporting quirk

[Zhan Wei]

On DG2 the driver always shows two fan channels, because the
FSC_READ_NUM_FANS command does not work on some cards. OEMs decide how
the fans map to tach channels, so two fans can share one tach line.
When that happens, the second channel reads 0 RPM even though the fan
is spinning.

Note this on the fan2_input ABI entry so the steady 0 RPM is not
mistaken for a driver bug.

Signed-off-by: Zhan Wei <zhanwei919@gmail.com>
---
v3:
- Drop the dedicated Documentation/gpu/xe/xe_hwmon.rst doc and the
  index.rst hunk; add a short note under the fan2_input entry in the
  existing ABI doc instead, per Raag's feedback.
v2: https://lore.kernel.org/intel-xe/20260529135028.20763-1-zhanwei919@gmail.com/
- Drop the code change that reported a single fan on DG2; document the
  shared-tach behaviour instead, per review feedback on v1.
v1: https://lore.kernel.org/intel-xe/20260527115311.13398-1-zhanwei919@gmail.com/

 Documentation/ABI/testing/sysfs-driver-intel-xe-hwmon | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Documentation/ABI/testing/sysfs-driver-intel-xe-hwmon b/Documentation/ABI/testing/sysfs-driver-intel-xe-hwmon
index 55ab45f669ac..0da739d9a816 100644
--- a/Documentation/ABI/testing/sysfs-driver-intel-xe-hwmon
+++ b/Documentation/ABI/testing/sysfs-driver-intel-xe-hwmon
@@ -251,6 +251,13 @@ Description:	RO. Fan 2 speed in RPM.
 
 		Only supported for particular Intel Xe graphics platforms.
 
+		On DG2 the driver always shows two fan channels, because the
+		FSC_READ_NUM_FANS command does not work on some cards. OEMs
+		decide how the fans map to tach channels, so two fans can share
+		one tach line. When that happens, the second channel
+		reads 0 RPM even though the fan is spinning. This is normal, not
+		a bug.
+
 What:		/sys/bus/pci/drivers/xe/.../hwmon/hwmon<i>/fan3_input
 Date:		March 2025
 KernelVersion:	6.16
-- 
2.43.0