Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.31 as permitted sender) client-ip=23.128.96.31;
From:   Armin Wolf <W_Armin@gmx.de>
To:     pali@kernel.org
Cc:     jdelvare@suse.com, linux@roeck-us.net, hdegoede@redhat.com,
        markgross@kernel.org, ilpo.jarvinen@linux.intel.com,
        platform-driver-x86@vger.kernel.org, linux-hwmon@vger.kernel.org,
        linux-kernel@vger.kernel.org
Subject: [PATCH v4 8/9] hwmon: (dell-smm) Document the WMI SMM interface
Date:   Thu, 23 Nov 2023 01:48:19 +0100
Message-Id: <20231123004820.50635-9-W_Armin@gmx.de>
In-Reply-To: <20231123004820.50635-1-W_Armin@gmx.de>
References: <20231123004820.50635-1-W_Armin@gmx.de>
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable
UI-OutboundReport: notjunk:1;M01:P0:8JXhW/qO+Zs=;h+T4cUIgBQMOQdKZEU/teBj3t4n
 i7AQl3qZyclJo4S+GOIwYibtiZdooOORDmwWgbUXX9Mx27iuc50to6wffpCJSZviCvMjE0BPt
 YR4NkCbI6szgJgc5p89HcRVyM+eShAdI9J/cQcm6e8AToRkvdzxqvcJsBErpqbJfaSX8/kbGE
 StFPuQXDIf5yaclpnbrFGK8lNrPX6iTKgpaNRSLLJfIniI+Z/7XLT4lh6UDi7My+xSQFE2hXs
 T+BT4REcOn5vuyhe2tk78hEtGKIdaWsh8pjrXjFfm/dTJSz+8pEwRunbFqTllfl7t8vPXjBkc
 zUOFS0jM7dSVI5C/sg9+RI6udbe3vDt+kv5w6Lk1EKXybghY2TBReHqxtRhWgeVOkh8uQfeCk
 skigdNF26DvAHS5UDj/pxcQJmF/dRXQYeWJjtA0kCarYsmqnl2pm8gLEjjj7wrYQkU0vt0/MU
 nL1wkqXO72ZDtz8v9Pcdr6Su0WSDCGADOWUYULuOZFaNeCfRCiuCl1fk0RozeKCdTd0E3DTCE
 RdA89SnXNAVaN0PVMiXzRIXqaMZUBau/ONxEEQ3cBoHDjqQL/N0ypYcuq140DNh2EXcCvpITB
 kGMDOJkF6PWvE9EqyIMhXRs+DTNmMJF7IcR/a/Xp6czr0XMvpGTTKVs/aVL692C7mS0fu1TeC
 d57+HARJOEvXr4p7fVUtGtQIH8GoXnvHj1aLsyrtWIT82kJxqi2NvPdEuP729QRXn1g+aUxF4
 m4qT8H7mPgmLYsgiwAGurL2LAD/KiUtdba1K9wHZ4p/qu33wiReUBEjz69Jsv+DhLHqEpRifu
 f3AohTK+0RN7lIfjIFNY6jvN8zrLc6dXDtepZqQ5Rf0/sSfiAZSOWL6KvBEW8d3TWpyrDKOJc
 usV0DFgtzutjNz7FZsSwqA5IgnJV+ke370JTrGls6z/UhOV4ZjOvZgsGcCmb9R6uVK1Ye9Nvo
 3im6R+Q1GYDYuQC6dLw9f9jOO7U=
Precedence: bulk

Document the WMI SMM interface so that future developers
can better understand how it works.

Reviewed-by: Hans de Goede <hdegoede@redhat.com>
Signed-off-by: Armin Wolf <W_Armin@gmx.de>
=2D--
 Documentation/hwmon/dell-smm-hwmon.rst | 38 ++++++++++++++++++++++++--
 1 file changed, 35 insertions(+), 3 deletions(-)

diff --git a/Documentation/hwmon/dell-smm-hwmon.rst b/Documentation/hwmon/=
dell-smm-hwmon.rst
index d8f1d6859b96..977263cb57a8 100644
=2D-- 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 ``0x8=
4``,
-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,40 @@ The SMM handler can signal a failure by either:

 - setting the lower sixteen bits of ``eax`` to ``0xffff``
 - not modifying ``eax`` at all
=2D- 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 le=
ast significant byte
+of the command code to the special ioports ``0xb2`` and ``0x84``. This in=
terface 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\\0x4=
09"),
+  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") : T=
oInstance] uint8 EaxVal[],
+               [in, out] uint32 EbxLen, [in, out, WmiSizeIs("EbxLen") : T=
oInstance] uint8 EbxVal[],
+               [in, out] uint32 EcxLen, [in, out, WmiSizeIs("EcxLen") : T=
oInstance] uint8 EcxVal[],
+               [in, out] uint32 EdxLen, [in, out, WmiSizeIs("EdxLen") : T=
oInstance] uint8 EdxVal[]);
+ };
+
+Some machines support only the WMI SMM interface, while some machines sup=
port both interfaces.
+The driver automatically detects which interfaces are present and will us=
e the WMI SMM interface
+if the legacy SMM interface is not present. The WMI SMM interface is usua=
lly slower than the
+legacy SMM interface since ACPI methods need to be called in order to tri=
gger a SMM.

 SMM command codes
 -----------------
=2D-
2.39.2