2022-02-15 23:12:12

by Armin Wolf

[permalink] [raw]
Subject: [PATCH 6/7] hwmon: (dell-smm) Add SMM interface documentation

Document the SMM interface as requested by Pali Rohar.
Since Dell does not offer any offical documentation
regarding the SMM interface, the necessary information
was extracted from the dell_smm_hwmon driver and other
sources.

Suggested-by: Pali Rohár <[email protected]>
Signed-off-by: Armin Wolf <[email protected]>
---
Documentation/hwmon/dell-smm-hwmon.rst | 180 +++++++++++++++++++++++++
1 file changed, 180 insertions(+)

diff --git a/Documentation/hwmon/dell-smm-hwmon.rst b/Documentation/hwmon/dell-smm-hwmon.rst
index cfaee682a245..12bba5fd1447 100644
--- a/Documentation/hwmon/dell-smm-hwmon.rst
+++ b/Documentation/hwmon/dell-smm-hwmon.rst
@@ -173,3 +173,183 @@ obtain the same information and to control the fan status. The ioctl
interface can be accessed from C programs or from shell using the
i8kctl utility. See the source file of ``i8kutils`` for more
information on how to use the ioctl interface.
+
+SMM Interface
+-------------
+
+.. warning:: The SMM interface was reverse-engineered by trial-and-error
+ since Dell did not provide any Documentation,
+ please keep that in mind.
+
+The driver uses the SMM interface to send commands to the system BIOS.
+This interface is normally used by Dell's 32-bit diagnostic program or
+on newer notebook models by the buildin BIOS diagnostics.
+The SMM is triggered by writing to the special ioports ``0xb2`` and ``0x84``,
+and may cause short hangs when the BIOS code is taking too long to
+execute.
+
+The SMM handler inside the system BIOS looks at the contents of the
+``eax``, ``ebx``, ``ecx``, ``edx``, ``esi`` and ``edi`` registers.
+Each register has a special purpose:
+
+=============== ==================================
+Register Purpose
+=============== ==================================
+eax Holds the command code before SMM,
+ holds the first result after SMM.
+ebx Holds the arguments.
+ecx Unknown, set to 0.
+edx Holds the second result after SMM.
+esi Unknown, set to 0.
+edi Unknown, set to 0.
+=============== ==================================
+
+The SMM handler can signal a failure by either:
+
+- setting the lower sixteen bits of ``eax`` to ``0xffff``
+- not modifying ``eax`` at all
+- setting the carry flag
+
+SMM command codes
+-----------------
+
+=============== ======================= ================================================
+Command Code Command Name Description
+=============== ======================= ================================================
+``0x0025`` Get Fn key status Returns the Fn key pressed after SMM:
+
+ - 9th bit in ``eax`` indicates Volume up
+ - 10th bit in ``eax`` indicates Volume down
+ - both bits indicate Volume mute
+
+``0xa069`` Get power status Returns current power status after SMM:
+
+ - 1st bit in ``eax`` indicates Battery connected
+ - 3th bit in ``eax`` indicates AC connected
+
+``0x00a3`` Get fan state Returns current fan state after SMM:
+
+ - 1st byte in ``eax`` holds the current
+ fan state (0 - 2 or 3)
+
+``0x01a3`` Set fan state Sets the fan speed:
+
+ - 1st byte in ``ebx`` holds the fan number
+ - 2nd byte in ``ebx`` holds the desired
+ fan state (0 - 2 or 3)
+
+``0x02a3`` Get fan speed Returns the current fan speed in RPM:
+
+ - 1st byte in ``ebx`` holds the fan number
+ - 1st word in ``eax`` holds the current
+ fan speed in RPM (after SMM)
+
+``0x03a3`` Get fan type Returns the fan type:
+
+ - 1st byte in ``ebx`` holds the fan number
+ - 1st byte in ``eax`` holds the
+ fan type (after SMM):
+
+ - 5th bit indicates docking fan
+ - 1 indicates Processor fan
+ - 2 indicates Motherboard fan
+ - 3 indicates Video fan
+ - 4 indicates Power supply fan
+ - 5 indicates Chipset fan
+ - 6 indicates other fan type
+
+``0x04a3`` Get nominal fan speed Returns the nominal RPM in each fan state:
+
+ - 1st byte in ``ebx`` holds the fan number
+ - 2nd byte in ``ebx`` holds the fan state
+ in question (0 - 2 or 3)
+ - 1st word in ``eax`` holds the nominal
+ fan speed in RPM (after SMM)
+
+``0x05a3`` Get fan speed tolerance Returns the speed tolerance for each fan state:
+
+ - 1st byte in ``ebx`` holds the fan number
+ - 2nd byte in ``ebx`` holds the fan state
+ in question (0 - 2 or 3)
+ - 1st byte in ``eax`` returns the speed
+ tolerance
+
+``0x10a3`` Get sensor temperature Returns the measured temperature:
+
+ - 1st byte in ``ebx`` holds the sensor number
+ - 1st byte in ``eax`` holds the measured
+ temperature (after SMM)
+
+``0x11a3`` Get sensor type Returns the sensor type:
+
+ - 1st byte in ``ebx`` holds the sensor number
+ - 1st byte in ``eax`` holds the
+ temperature type (after SMM):
+
+ - 1 indicates CPU sensor
+ - 2 indicates GPU sensor
+ - 3 indicates SODIMM sensor
+ - 4 indicates other sensor type
+ - 5 indicates Ambient sensor
+ - 6 indicates other sensor type
+
+``0xfea3`` Get SMM signature Returns Dell signature if interface
+ is supported (after SMM):
+
+ - ``eax`` holds 1145651527
+ (0x44494147 or "DIAG")
+ - ``edx`` holds 1145392204
+ (0x44454c4c or "DELL")
+
+``0xffa3`` Get SMM signature Same as ``0xfea3``, check both.
+=============== ======================= ================================================
+
+There are additional commands for enabling (``0x31a3`` or ``0x35a3``) and
+disabling (``0x30a3`` or ``0x34a3``) automatic fan speed control.
+The commands are however causing severe sideeffects on many machines, so
+they are not used by default.
+
+On several machines (Inspiron 3505, Precision 490, Vostro 1720, ...), the
+fans supports a 4th "magic" state, which signals the BIOS that automatic
+fan control should be enabled for a specific fan.
+However there are also some machines who do support a 4th regular fan state too,
+but in case of the "magic" state, the nominal RPM reported for this state is a
+placeholder value, which however is not always detectable.
+
+Firmware Bugs
+-------------
+
+The SMM calls can behave erratic on some machines:
+
+======================================================= =================
+Firmware Bug Affected Machines
+======================================================= =================
+Reading of fan states return spurious errors. Precision 490
+
+Reading of fan types causes erratic fan behaviour. Studio XPS 8000
+
+ Studio XPS 8100
+
+ Inspiron 580
+
+Fan-related SMM calls take too long (about 500ms). Inspiron 7720
+
+ Vostro 3360
+
+ XPS 13 9333
+
+ XPS 15 L502X
+======================================================= =================
+
+In case you experience similar issues on your Dell machine, please
+submit a bugreport on bugzilla to we can apply workarounds.
+
+Limitations
+-----------
+
+The SMM calls can take too long to execute on some machines, causing
+short hangs and/or audio glitches.
+Also the fan state needs to be restored after suspend, as well as
+the automatic mode settings.
+When reading a temperature sensor, values above 127 degrees indicate
+a BIOS read error or a deactivated sensor.
--
2.30.2


2022-02-16 06:47:20

by Pali Rohár

[permalink] [raw]
Subject: Re: [PATCH 6/7] hwmon: (dell-smm) Add SMM interface documentation

On Tuesday 15 February 2022 20:11:12 Armin Wolf wrote:
> Document the SMM interface as requested by Pali Rohar.
> Since Dell does not offer any offical documentation
> regarding the SMM interface, the necessary information
> was extracted from the dell_smm_hwmon driver and other
> sources.
>
> Suggested-by: Pali Rohár <[email protected]>
> Signed-off-by: Armin Wolf <[email protected]>

Perfect!

Reviewed-by: Pali Rohár <[email protected]>

I have info about some more commands but I'm not sure if they are
implement on new machines:

0x00a6 get SMBIOS version
0x22a3 get charger info (1 arg)
0x24a3 get adaptor info status (1 arg oder 0x03)
0x32a3 restore normal Fn key mode (no args)
0x33a3 put the Fn key in "raw" mode (sends the scancode e009 instead of activating the Fn- functions) (no args)
0x36a3 get hotkey scancode list (args see diags; returns number of hotkeys)
0x40a3 get docking state (no args)

> ---
> Documentation/hwmon/dell-smm-hwmon.rst | 180 +++++++++++++++++++++++++
> 1 file changed, 180 insertions(+)
>
> diff --git a/Documentation/hwmon/dell-smm-hwmon.rst b/Documentation/hwmon/dell-smm-hwmon.rst
> index cfaee682a245..12bba5fd1447 100644
> --- a/Documentation/hwmon/dell-smm-hwmon.rst
> +++ b/Documentation/hwmon/dell-smm-hwmon.rst
> @@ -173,3 +173,183 @@ obtain the same information and to control the fan status. The ioctl
> interface can be accessed from C programs or from shell using the
> i8kctl utility. See the source file of ``i8kutils`` for more
> information on how to use the ioctl interface.
> +
> +SMM Interface
> +-------------
> +
> +.. warning:: The SMM interface was reverse-engineered by trial-and-error
> + since Dell did not provide any Documentation,
> + please keep that in mind.
> +
> +The driver uses the SMM interface to send commands to the system BIOS.
> +This interface is normally used by Dell's 32-bit diagnostic program or
> +on newer notebook models by the buildin BIOS diagnostics.
> +The SMM is triggered by writing to the special ioports ``0xb2`` and ``0x84``,
> +and may cause short hangs when the BIOS code is taking too long to
> +execute.
> +
> +The SMM handler inside the system BIOS looks at the contents of the
> +``eax``, ``ebx``, ``ecx``, ``edx``, ``esi`` and ``edi`` registers.
> +Each register has a special purpose:
> +
> +=============== ==================================
> +Register Purpose
> +=============== ==================================
> +eax Holds the command code before SMM,
> + holds the first result after SMM.
> +ebx Holds the arguments.
> +ecx Unknown, set to 0.
> +edx Holds the second result after SMM.
> +esi Unknown, set to 0.
> +edi Unknown, set to 0.
> +=============== ==================================
> +
> +The SMM handler can signal a failure by either:
> +
> +- setting the lower sixteen bits of ``eax`` to ``0xffff``
> +- not modifying ``eax`` at all
> +- setting the carry flag
> +
> +SMM command codes
> +-----------------
> +
> +=============== ======================= ================================================
> +Command Code Command Name Description
> +=============== ======================= ================================================
> +``0x0025`` Get Fn key status Returns the Fn key pressed after SMM:
> +
> + - 9th bit in ``eax`` indicates Volume up
> + - 10th bit in ``eax`` indicates Volume down
> + - both bits indicate Volume mute
> +
> +``0xa069`` Get power status Returns current power status after SMM:
> +
> + - 1st bit in ``eax`` indicates Battery connected
> + - 3th bit in ``eax`` indicates AC connected
> +
> +``0x00a3`` Get fan state Returns current fan state after SMM:
> +
> + - 1st byte in ``eax`` holds the current
> + fan state (0 - 2 or 3)
> +
> +``0x01a3`` Set fan state Sets the fan speed:
> +
> + - 1st byte in ``ebx`` holds the fan number
> + - 2nd byte in ``ebx`` holds the desired
> + fan state (0 - 2 or 3)
> +
> +``0x02a3`` Get fan speed Returns the current fan speed in RPM:
> +
> + - 1st byte in ``ebx`` holds the fan number
> + - 1st word in ``eax`` holds the current
> + fan speed in RPM (after SMM)
> +
> +``0x03a3`` Get fan type Returns the fan type:
> +
> + - 1st byte in ``ebx`` holds the fan number
> + - 1st byte in ``eax`` holds the
> + fan type (after SMM):
> +
> + - 5th bit indicates docking fan
> + - 1 indicates Processor fan
> + - 2 indicates Motherboard fan
> + - 3 indicates Video fan
> + - 4 indicates Power supply fan
> + - 5 indicates Chipset fan
> + - 6 indicates other fan type
> +
> +``0x04a3`` Get nominal fan speed Returns the nominal RPM in each fan state:
> +
> + - 1st byte in ``ebx`` holds the fan number
> + - 2nd byte in ``ebx`` holds the fan state
> + in question (0 - 2 or 3)
> + - 1st word in ``eax`` holds the nominal
> + fan speed in RPM (after SMM)
> +
> +``0x05a3`` Get fan speed tolerance Returns the speed tolerance for each fan state:
> +
> + - 1st byte in ``ebx`` holds the fan number
> + - 2nd byte in ``ebx`` holds the fan state
> + in question (0 - 2 or 3)
> + - 1st byte in ``eax`` returns the speed
> + tolerance
> +
> +``0x10a3`` Get sensor temperature Returns the measured temperature:
> +
> + - 1st byte in ``ebx`` holds the sensor number
> + - 1st byte in ``eax`` holds the measured
> + temperature (after SMM)
> +
> +``0x11a3`` Get sensor type Returns the sensor type:
> +
> + - 1st byte in ``ebx`` holds the sensor number
> + - 1st byte in ``eax`` holds the
> + temperature type (after SMM):
> +
> + - 1 indicates CPU sensor
> + - 2 indicates GPU sensor
> + - 3 indicates SODIMM sensor
> + - 4 indicates other sensor type
> + - 5 indicates Ambient sensor
> + - 6 indicates other sensor type
> +
> +``0xfea3`` Get SMM signature Returns Dell signature if interface
> + is supported (after SMM):
> +
> + - ``eax`` holds 1145651527
> + (0x44494147 or "DIAG")
> + - ``edx`` holds 1145392204
> + (0x44454c4c or "DELL")
> +
> +``0xffa3`` Get SMM signature Same as ``0xfea3``, check both.
> +=============== ======================= ================================================
> +
> +There are additional commands for enabling (``0x31a3`` or ``0x35a3``) and
> +disabling (``0x30a3`` or ``0x34a3``) automatic fan speed control.
> +The commands are however causing severe sideeffects on many machines, so
> +they are not used by default.
> +
> +On several machines (Inspiron 3505, Precision 490, Vostro 1720, ...), the
> +fans supports a 4th "magic" state, which signals the BIOS that automatic
> +fan control should be enabled for a specific fan.
> +However there are also some machines who do support a 4th regular fan state too,
> +but in case of the "magic" state, the nominal RPM reported for this state is a
> +placeholder value, which however is not always detectable.
> +
> +Firmware Bugs
> +-------------
> +
> +The SMM calls can behave erratic on some machines:
> +
> +======================================================= =================
> +Firmware Bug Affected Machines
> +======================================================= =================
> +Reading of fan states return spurious errors. Precision 490
> +
> +Reading of fan types causes erratic fan behaviour. Studio XPS 8000
> +
> + Studio XPS 8100
> +
> + Inspiron 580
> +
> +Fan-related SMM calls take too long (about 500ms). Inspiron 7720
> +
> + Vostro 3360
> +
> + XPS 13 9333
> +
> + XPS 15 L502X
> +======================================================= =================
> +
> +In case you experience similar issues on your Dell machine, please
> +submit a bugreport on bugzilla to we can apply workarounds.
> +
> +Limitations
> +-----------
> +
> +The SMM calls can take too long to execute on some machines, causing
> +short hangs and/or audio glitches.
> +Also the fan state needs to be restored after suspend, as well as
> +the automatic mode settings.
> +When reading a temperature sensor, values above 127 degrees indicate
> +a BIOS read error or a deactivated sensor.
> --
> 2.30.2
>

2022-02-20 14:46:43

by Guenter Roeck

[permalink] [raw]
Subject: Re: [PATCH 6/7] hwmon: (dell-smm) Add SMM interface documentation

On Tue, Feb 15, 2022 at 08:11:12PM +0100, Armin Wolf wrote:
> Document the SMM interface as requested by Pali Rohar.
> Since Dell does not offer any offical documentation
> regarding the SMM interface, the necessary information
> was extracted from the dell_smm_hwmon driver and other
> sources.
>
> Suggested-by: Pali Roh?r <[email protected]>
> Signed-off-by: Armin Wolf <[email protected]>
> Reviewed-by: Pali Roh?r <[email protected]>

Applied to hwmon-next.

Thanks,
Guenter

> ---
> Documentation/hwmon/dell-smm-hwmon.rst | 180 +++++++++++++++++++++++++
> 1 file changed, 180 insertions(+)
>
> --
> 2.30.2
>
> diff --git a/Documentation/hwmon/dell-smm-hwmon.rst b/Documentation/hwmon/dell-smm-hwmon.rst
> index cfaee682a245..12bba5fd1447 100644
> --- a/Documentation/hwmon/dell-smm-hwmon.rst
> +++ b/Documentation/hwmon/dell-smm-hwmon.rst
> @@ -173,3 +173,183 @@ obtain the same information and to control the fan status. The ioctl
> interface can be accessed from C programs or from shell using the
> i8kctl utility. See the source file of ``i8kutils`` for more
> information on how to use the ioctl interface.
> +
> +SMM Interface
> +-------------
> +
> +.. warning:: The SMM interface was reverse-engineered by trial-and-error
> + since Dell did not provide any Documentation,
> + please keep that in mind.
> +
> +The driver uses the SMM interface to send commands to the system BIOS.
> +This interface is normally used by Dell's 32-bit diagnostic program or
> +on newer notebook models by the buildin BIOS diagnostics.
> +The SMM is triggered by writing to the special ioports ``0xb2`` and ``0x84``,
> +and may cause short hangs when the BIOS code is taking too long to
> +execute.
> +
> +The SMM handler inside the system BIOS looks at the contents of the
> +``eax``, ``ebx``, ``ecx``, ``edx``, ``esi`` and ``edi`` registers.
> +Each register has a special purpose:
> +
> +=============== ==================================
> +Register Purpose
> +=============== ==================================
> +eax Holds the command code before SMM,
> + holds the first result after SMM.
> +ebx Holds the arguments.
> +ecx Unknown, set to 0.
> +edx Holds the second result after SMM.
> +esi Unknown, set to 0.
> +edi Unknown, set to 0.
> +=============== ==================================
> +
> +The SMM handler can signal a failure by either:
> +
> +- setting the lower sixteen bits of ``eax`` to ``0xffff``
> +- not modifying ``eax`` at all
> +- setting the carry flag
> +
> +SMM command codes
> +-----------------
> +
> +=============== ======================= ================================================
> +Command Code Command Name Description
> +=============== ======================= ================================================
> +``0x0025`` Get Fn key status Returns the Fn key pressed after SMM:
> +
> + - 9th bit in ``eax`` indicates Volume up
> + - 10th bit in ``eax`` indicates Volume down
> + - both bits indicate Volume mute
> +
> +``0xa069`` Get power status Returns current power status after SMM:
> +
> + - 1st bit in ``eax`` indicates Battery connected
> + - 3th bit in ``eax`` indicates AC connected
> +
> +``0x00a3`` Get fan state Returns current fan state after SMM:
> +
> + - 1st byte in ``eax`` holds the current
> + fan state (0 - 2 or 3)
> +
> +``0x01a3`` Set fan state Sets the fan speed:
> +
> + - 1st byte in ``ebx`` holds the fan number
> + - 2nd byte in ``ebx`` holds the desired
> + fan state (0 - 2 or 3)
> +
> +``0x02a3`` Get fan speed Returns the current fan speed in RPM:
> +
> + - 1st byte in ``ebx`` holds the fan number
> + - 1st word in ``eax`` holds the current
> + fan speed in RPM (after SMM)
> +
> +``0x03a3`` Get fan type Returns the fan type:
> +
> + - 1st byte in ``ebx`` holds the fan number
> + - 1st byte in ``eax`` holds the
> + fan type (after SMM):
> +
> + - 5th bit indicates docking fan
> + - 1 indicates Processor fan
> + - 2 indicates Motherboard fan
> + - 3 indicates Video fan
> + - 4 indicates Power supply fan
> + - 5 indicates Chipset fan
> + - 6 indicates other fan type
> +
> +``0x04a3`` Get nominal fan speed Returns the nominal RPM in each fan state:
> +
> + - 1st byte in ``ebx`` holds the fan number
> + - 2nd byte in ``ebx`` holds the fan state
> + in question (0 - 2 or 3)
> + - 1st word in ``eax`` holds the nominal
> + fan speed in RPM (after SMM)
> +
> +``0x05a3`` Get fan speed tolerance Returns the speed tolerance for each fan state:
> +
> + - 1st byte in ``ebx`` holds the fan number
> + - 2nd byte in ``ebx`` holds the fan state
> + in question (0 - 2 or 3)
> + - 1st byte in ``eax`` returns the speed
> + tolerance
> +
> +``0x10a3`` Get sensor temperature Returns the measured temperature:
> +
> + - 1st byte in ``ebx`` holds the sensor number
> + - 1st byte in ``eax`` holds the measured
> + temperature (after SMM)
> +
> +``0x11a3`` Get sensor type Returns the sensor type:
> +
> + - 1st byte in ``ebx`` holds the sensor number
> + - 1st byte in ``eax`` holds the
> + temperature type (after SMM):
> +
> + - 1 indicates CPU sensor
> + - 2 indicates GPU sensor
> + - 3 indicates SODIMM sensor
> + - 4 indicates other sensor type
> + - 5 indicates Ambient sensor
> + - 6 indicates other sensor type
> +
> +``0xfea3`` Get SMM signature Returns Dell signature if interface
> + is supported (after SMM):
> +
> + - ``eax`` holds 1145651527
> + (0x44494147 or "DIAG")
> + - ``edx`` holds 1145392204
> + (0x44454c4c or "DELL")
> +
> +``0xffa3`` Get SMM signature Same as ``0xfea3``, check both.
> +=============== ======================= ================================================
> +
> +There are additional commands for enabling (``0x31a3`` or ``0x35a3``) and
> +disabling (``0x30a3`` or ``0x34a3``) automatic fan speed control.
> +The commands are however causing severe sideeffects on many machines, so
> +they are not used by default.
> +
> +On several machines (Inspiron 3505, Precision 490, Vostro 1720, ...), the
> +fans supports a 4th "magic" state, which signals the BIOS that automatic
> +fan control should be enabled for a specific fan.
> +However there are also some machines who do support a 4th regular fan state too,
> +but in case of the "magic" state, the nominal RPM reported for this state is a
> +placeholder value, which however is not always detectable.
> +
> +Firmware Bugs
> +-------------
> +
> +The SMM calls can behave erratic on some machines:
> +
> +======================================================= =================
> +Firmware Bug Affected Machines
> +======================================================= =================
> +Reading of fan states return spurious errors. Precision 490
> +
> +Reading of fan types causes erratic fan behaviour. Studio XPS 8000
> +
> + Studio XPS 8100
> +
> + Inspiron 580
> +
> +Fan-related SMM calls take too long (about 500ms). Inspiron 7720
> +
> + Vostro 3360
> +
> + XPS 13 9333
> +
> + XPS 15 L502X
> +======================================================= =================
> +
> +In case you experience similar issues on your Dell machine, please
> +submit a bugreport on bugzilla to we can apply workarounds.
> +
> +Limitations
> +-----------
> +
> +The SMM calls can take too long to execute on some machines, causing
> +short hangs and/or audio glitches.
> +Also the fan state needs to be restored after suspend, as well as
> +the automatic mode settings.
> +When reading a temperature sensor, values above 127 degrees indicate
> +a BIOS read error or a deactivated sensor.