Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.37 as permitted sender) client-ip=23.128.96.37;
From:   Armin Wolf <W_Armin@gmx.de>
To:     pali@kernel.org
Cc:     hdegoede@redhat.com, markgross@kernel.org,
        ilpo.jarvinen@linux.intel.com, jdelvare@suse.com,
        linux@roeck-us.net, platform-driver-x86@vger.kernel.org,
        linux-hwmon@vger.kernel.org, linux-kernel@vger.kernel.org
Subject: [PATCH v2 8/9] hwmon: (dell-smm) Document the WMI SMM interface
Date:   Sat,  4 Nov 2023 16:55:58 +0100
Message-Id: <20231104155559.11842-9-W_Armin@gmx.de>
In-Reply-To: <20231104155559.11842-1-W_Armin@gmx.de>
References: <20231104155559.11842-1-W_Armin@gmx.de>
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable
UI-OutboundReport: notjunk:1;M01:P0:Zfn4TXe2Lkg=;EqBE00tFK915qpptKI8QT50k7WE
 9oV4ViRnTUGwu+yz0gvbN6yrXvF57jFNu+ch7xq7bbCjFG6W+z+jRRjx0hg8RmbKFtBcJ0KYr
 w+DLwvEYq02A0YcKMNXPb1npKADXz//4xnKyErJcCkDMa+Us5NKh5SPG0KGlyQ1cdmV+JVfGl
 V6ubQT6/yYuAkeP6v3yBm1QxkgoLfMtbI3vqd+bZ5OZ1muwNfLXyguFnkL2Z22DpMnRpOwRqL
 FuZvTcPGJT0jwuHTqEbsYJJy8bG20yYBvCHmmXLpnEm3KOWKPs3gwqlBgVwoSDH4HYkTu5IMF
 3v/gBQxXKeUshOvwM5EFH/SGSJZ2dDQEhUcpOaOs1ff/GqKUQDfukAO0MfhG4Ug6D9WKHiqfr
 Cg+xkSGrq4WLssUIw24w07VgIs9vE/Cc6ARb8bf9Kwz31m5j4ySTynCV9k0KOUsNRZgqm9RHQ
 tuf+yk2WmTJ/Zku/JKMdizYbrsqwln2UK/xwdv7FzmJOGRw2HjUEUthTzO6RlXoc2afOuyXHm
 MX9FfE7i9VzLhJ08nSY6P5MaDlSGEt4Q1gabJ0owxSJ24IJA8FbDv9rNa9xGjTf5M/AQIKemE
 UQUb/+f0PZTe/ktHCR1ueDnj64hIdsvd71K5vrY2V7ETUPBk3ccJC05ha7fIN/en524AapxHt
 Y3/krSlc9NFNvEEsXnP3ZRiWyWnCZGAqlRbZVCs2t/KC8dDO6YbVYhjErOhs2HeW7fr6xH7v3
 lJwogwaByOrM50auhIeVpuP+gjkxDPIdbt8Udiij7BCVCfJHiGefKgXYgEG3/1sWvqg06IaLI
 yYkRc/v8SY+UWCUPgIDVpdF5+BISKAFCBOYAFt9GZhiJHxk4Yy6Td79nlJAH2bhE9JxZPHsCf
 W+DjUnmkvpwGD9xEB0Vv3bF8wPuEGwkQIiqetFhAfpJh9uXjWxcx0SXpDLLLZtkNOrSEXZfFU
 Vm7JLcaj1egCx2RYFfmXk0lnJno=
Precedence: bulk

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

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