diff mbox series

[8/9] hwmon: (dell-smm) Document the WMI SMM interface

Message ID 20231103185716.11007-9-W_Armin@gmx.de (mailing list archive)
State Superseded
Headers show
Series hwmon: (dell-smm) Add support for WMI SMM interface | expand

Commit Message

Armin Wolf Nov. 3, 2023, 6:57 p.m. UTC
Document the WMI SMM interface so that future developers
can better understand how it works.

Signed-off-by: Armin Wolf <W_Armin@gmx.de>
---
 Documentation/hwmon/dell-smm-hwmon.rst | 33 +++++++++++++++++++++++---
 1 file changed, 30 insertions(+), 3 deletions(-)

--
2.39.2

Comments

Guenter Roeck Nov. 4, 2023, 2:58 p.m. UTC | #1
On Fri, Nov 03, 2023 at 07:57:15PM +0100, Armin Wolf wrote:
> Document the WMI SMM interface so that future developers
> can better understand how it works.
> 
> Signed-off-by: Armin Wolf <W_Armin@gmx.de>
> ---
>  Documentation/hwmon/dell-smm-hwmon.rst | 33 +++++++++++++++++++++++---
>  1 file changed, 30 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/hwmon/dell-smm-hwmon.rst b/Documentation/hwmon/dell-smm-hwmon.rst
> index d8f1d6859b96..fea8cf76088e 100644
> --- a/Documentation/hwmon/dell-smm-hwmon.rst
> +++ b/Documentation/hwmon/dell-smm-hwmon.rst
> @@ -186,8 +186,7 @@ SMM Interface
>  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
> +The SMM 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
> @@ -210,7 +209,35 @@ 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
> +- setting the carry flag (legacy SMM interface only)
> +
> +Legacy SMM Interface
> +--------------------
> +
> +When using the legacy SMM interface, a SMM is triggered by writing the least significant byte
> +of the command code to the special ioports ``0xb2`` and ``0x84``. This interface is not
> +described inside the ACPI tables and can thus only be detected by issuing a test SMM call.
> +
> +WMI SMM Interface
> +-----------------
> +
> +On modern Dell machines, the SMM calls are done over ACPI WMI:
> +
> +::
> +
> + #pragma namespace("\\\\.\\root\\dcim\\sysman\\diagnostics")
> + [WMI, Provider("Provider_DiagnosticsServices"), Dynamic, Locale("MS\\0x409"), Description("RunDellDiag"), guid("{F1DDEE52-063C-4784-A11E-8A06684B9B01}")]
> + class LegacyDiags {
> +  [key, read] string InstanceName;
> +  [read] boolean Active;
> +
> +  [WmiMethodId(1), Implemented, read, write, Description("Legacy Method ")] void Execute([in, out] uint32 EaxLen, [in, out, WmiSizeIs("EaxLen") : ToInstance] uint8 EaxVal[], [in, out] uint32 EbxLen, [in, out, WmiSizeIs("EbxLen") : ToInstance] uint8 EbxVal[], [in, out] uint32 EcxLen, [in, out, WmiSizeIs("EcxLen") : ToInstance] uint8 EcxVal[], [in, out] uint32 EdxLen, [in, out, WmiSizeIs("EdxLen") : ToInstance] uint8 EdxVal[]);

I don't think this has to violate formatting rules.

Guenter

> + };
> +
> +Some machines support only the WMI SMM interface, while some machines support both interfaces.
> +The driver automatically detects which interfaces are present and will use the WMI SMM interface
> +if the legacy SMM interface is not present. The WMI SMM interface is usually slower than the
> +legacy SMM interface since ACPI methods need to be called in order to trigger a SMM.
> 
>  SMM command codes
>  -----------------
> --
> 2.39.2
>
diff mbox series

Patch

diff --git a/Documentation/hwmon/dell-smm-hwmon.rst b/Documentation/hwmon/dell-smm-hwmon.rst
index d8f1d6859b96..fea8cf76088e 100644
--- a/Documentation/hwmon/dell-smm-hwmon.rst
+++ b/Documentation/hwmon/dell-smm-hwmon.rst
@@ -186,8 +186,7 @@  SMM Interface
 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
+The SMM 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
@@ -210,7 +209,35 @@  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
+- setting the carry flag (legacy SMM interface only)
+
+Legacy SMM Interface
+--------------------
+
+When using the legacy SMM interface, a SMM is triggered by writing the least significant byte
+of the command code to the special ioports ``0xb2`` and ``0x84``. This interface is not
+described inside the ACPI tables and can thus only be detected by issuing a test SMM call.
+
+WMI SMM Interface
+-----------------
+
+On modern Dell machines, the SMM calls are done over ACPI WMI:
+
+::
+
+ #pragma namespace("\\\\.\\root\\dcim\\sysman\\diagnostics")
+ [WMI, Provider("Provider_DiagnosticsServices"), Dynamic, Locale("MS\\0x409"), Description("RunDellDiag"), guid("{F1DDEE52-063C-4784-A11E-8A06684B9B01}")]
+ class LegacyDiags {
+  [key, read] string InstanceName;
+  [read] boolean Active;
+
+  [WmiMethodId(1), Implemented, read, write, Description("Legacy Method ")] void Execute([in, out] uint32 EaxLen, [in, out, WmiSizeIs("EaxLen") : ToInstance] uint8 EaxVal[], [in, out] uint32 EbxLen, [in, out, WmiSizeIs("EbxLen") : ToInstance] uint8 EbxVal[], [in, out] uint32 EcxLen, [in, out, WmiSizeIs("EcxLen") : ToInstance] uint8 EcxVal[], [in, out] uint32 EdxLen, [in, out, WmiSizeIs("EdxLen") : ToInstance] uint8 EdxVal[]);
+ };
+
+Some machines support only the WMI SMM interface, while some machines support both interfaces.
+The driver automatically detects which interfaces are present and will use the WMI SMM interface
+if the legacy SMM interface is not present. The WMI SMM interface is usually slower than the
+legacy SMM interface since ACPI methods need to be called in order to trigger a SMM.

 SMM command codes
 -----------------