From nobody Wed Nov 27 09:39:18 2024 Received: from mail-pf1-f175.google.com (mail-pf1-f175.google.com [209.85.210.175]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id DFB8BCA6B; Sat, 12 Oct 2024 02:04:02 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.210.175 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1728698644; cv=none; b=GBNGbblazyLuP598ZcV5PthDvM6F8iZr9CYGTS+W+3u1uRxWtyM8hOin5hW+sc/3sID9g4yNgIb63/D1Qlum/dXwVgpHZBI3TlnS/K2NaN5VsJuz9/rnmz0vpVWedUBV/q4jxxhvutRDb7GphlHxDHDWl4RCu4lit/ZB4oCHI+g= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1728698644; c=relaxed/simple; bh=uHTVNDHNzMdHEszGkpOtgg8HfLd1Ay6FO1JIqardStQ=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=tA5bwNHTtiHRNCx9ci6Rs46b9sKDgc1MHpVapB26JUP6I1fnTO1vGl+dvzoJ+/ObBolSBkCMsN5bUOB6BoywMoEcuwQSJM/ICSYZMg+DQ7Pa492L7Y7c62AcZe2I1cRnObHO593Q/XJjCG5XWdXP/Urqt/csU8jyejaP46gEaIE= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=ixfNIvSM; arc=none smtp.client-ip=209.85.210.175 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="ixfNIvSM" Received: by mail-pf1-f175.google.com with SMTP id d2e1a72fcca58-71df04d3cd1so2245325b3a.2; Fri, 11 Oct 2024 19:04:02 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1728698642; x=1729303442; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=gWU58bMH8D3m63RV4wVHw9YRua6XCRL3HRZAWvufV1A=; b=ixfNIvSMn9AjbONtl+DA/a8y49JzfXzyZP/APyNP2blOnzbk3dgAf7rXxklBTE7QYl TEw2ducaNGIrtcSLpwZT82YRmPxukdFFkmRP2pci9AL0uL+8+/42ijmgox2yMmcYhkQq S86uj35QPac7gvtlO6bVGJQDfuxJGO+DMorV49pSDghnG7d6e5JgqR5A7z5z5l8WpPyW oACPPddsYu/vErOW6H6SBUHiPXTuo84xDSkpX3u0SG7iEaDkbgGtcyATZ/biqRv3XDLo fItqA55696O+BbvzBKR5/1joGrHbF2xGe1BPL/Mof0kbnjqEEPU15QNVcsz4iI2efL2O nXBQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1728698642; x=1729303442; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=gWU58bMH8D3m63RV4wVHw9YRua6XCRL3HRZAWvufV1A=; b=M46dWzfOm+N9AcjTanA43bYC7mSwZESsH/KCU4ySrtcREy0PoNTsqxsIJdzPF3IXYg VJIP9PGYELpt/4Mw3OUBlEE2qa9dOwZalzAWRxWjSZRZSB0YZpsOFacAQGc1oNIMo3j8 e5zjXjBeaDEPZtrSheE/Kt0RziAGXgb2rePNYYWrjBEg8Syr8ZGrGno5GnkElVWYhTOL S7fET7F0fDVvifjXd3l+FUMKN9Ll9nvnlwGqnh6nFgG/926N2pF7tSDo3Yn0c08E2COu Oaq08tZuMfv/cPMuMSoyw2ENNcAoHEBOwC151ZB/drnWPC4454Z5wegKpZOYWkDqv1K7 73jw== X-Forwarded-Encrypted: i=1; AJvYcCUBDamJ1/0VbpDWp+RtPGNLNwaE8U0YV1rWFwjFZXcvuYYxpKipTPv0C2bHaz3UE9JxhgJ6SICOOwRQy/gbVzx1uZBaCQ==@vger.kernel.org, AJvYcCUbOdVTVj1aHo2QQahvCCgd8lM7rgx6vynhu1gZJv81UMnaW3+BtFY4TuxytOq7FVUfQxOfL/V4YKMOazM=@vger.kernel.org X-Gm-Message-State: AOJu0YzkHB3MpTMiHSC+ybVo2dHbxU3qPsefx4Ko5UolWJymQd9ogyrs weeFF+DfRpRSYYtO/M6hTNimkZpXtEjJTW1ubgpeMjs405w3gkez/sxfGfta X-Google-Smtp-Source: AGHT+IHCRTRn/D4B9dbrCS7rOOPcPT9EdqvUfRgWiaSC7nI8av82kcl2Irbt5yHSMR4BC49Dwja9AQ== X-Received: by 2002:a05:6a21:38c:b0:1d7:76d:7ff with SMTP id adf61e73a8af0-1d8c96bbcd1mr1819207637.45.1728698642070; Fri, 11 Oct 2024 19:04:02 -0700 (PDT) Received: from localhost.localdomain (host95.181-12-202.telecom.net.ar. [181.12.202.95]) by smtp.gmail.com with ESMTPSA id 41be03b00d2f7-7ea65fae62fsm1101646a12.39.2024.10.11.19.03.59 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 11 Oct 2024 19:04:01 -0700 (PDT) From: Kurt Borja To: kuurtb@gmail.com Cc: hdegoede@redhat.com, ilpo.jarvinen@linux.intel.com, linux-kernel@vger.kernel.org, platform-driver-x86@vger.kernel.org Subject: [PATCH v5 4/4] alienware-wmi: WMAX interface documentation Date: Fri, 11 Oct 2024 23:03:31 -0300 Message-ID: <20241012020330.20278-2-kuurtb@gmail.com> X-Mailer: git-send-email 2.47.0 In-Reply-To: <20241012015849.19036-3-kuurtb@gmail.com> References: <20241012015849.19036-3-kuurtb@gmail.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Added documentation for new WMAX interface, present on some Alienware X-Series, Alienware M-Series and Dell's G-Series laptops. Signed-off-by: Kurt Borja --- Documentation/wmi/devices/alienware-wmi.rst | 366 ++++++++++++++++++++ 1 file changed, 366 insertions(+) create mode 100644 Documentation/wmi/devices/alienware-wmi.rst diff --git a/Documentation/wmi/devices/alienware-wmi.rst b/Documentation/wm= i/devices/alienware-wmi.rst new file mode 100644 index 000000000..77460b91c --- /dev/null +++ b/Documentation/wmi/devices/alienware-wmi.rst @@ -0,0 +1,366 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Dell AWCC WMI interface driver (alienware-wmi) +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Introduction +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The WMI device WMAX has been implemented for many Alienware and Dell's G-S= eries +models. Throughout these models, two implementations have been identified.= The +first one, used by older systems, deals with HDMI, brightness, RGB, amplif= ier +and deep sleep control. The second one used by newer systems deals primari= ly +with thermal, overclocking, and GPIO control. + +It is suspected that the latter is used by Alienware Command Center (AWCC)= to +manage manufacturer predefined thermal profiles. The alienware-wmi driver +exposes Thermal_Information and Thermal_Control methods through the Platfo= rm +Profile API to mimic AWCC's behavior. + +This newer interface, named AWCCMethodFunction has been reverse engineered= , as +Dell has not provided any official documentation. We will try to describe = to the +best of our ability its discovered inner workings. + +.. note:: + The following method description may vary between models. + +WMI interface description +------------------------- + +The WMI interface description can be decoded from the embedded binary MOF = (bmof) +data using the `bmfdec `_ utility: + +:: + + [WMI, Dynamic, Provider("WmiProv"), Locale("MS\\0x409"), Description("WMI= Function"), guid("{A70591CE-A997-11DA-B012-B622A1EF5492}")] + class AWCCWmiMethodFunction { + [key, read] string InstanceName; + [read] boolean Active; + + [WmiMethodId(13), Implemented, read, write, Description("Return Overclo= cking Report.")] void Return_OverclockingReport([out] uint32 argr); + [WmiMethodId(14), Implemented, read, write, Description("Set OCUIBIOS C= ontrol.")] void Set_OCUIBIOSControl([in] uint32 arg2, [out] uint32 argr); + [WmiMethodId(15), Implemented, read, write, Description("Clear OC FailS= afe Flag.")] void Clear_OCFailSafeFlag([out] uint32 argr); + [WmiMethodId(19), Implemented, read, write, Description("Get Fan Sensor= s.")] void GetFanSensors([in] uint32 arg2, [out] uint32 argr); + [WmiMethodId(20), Implemented, read, write, Description("Thermal Inform= ation.")] void Thermal_Information([in] uint32 arg2, [out] uint32 argr); + [WmiMethodId(21), Implemented, read, write, Description("Thermal Contro= l.")] void Thermal_Control([in] uint32 arg2, [out] uint32 argr); + [WmiMethodId(23), Implemented, read, write, Description("MemoryOCContro= l.")] void MemoryOCControl([in] uint32 arg2, [out] uint32 argr); + [WmiMethodId(26), Implemented, read, write, Description("System Informa= tion.")] void SystemInformation([in] uint32 arg2, [out] uint32 argr); + [WmiMethodId(28), Implemented, read, write, Description("Power Informat= ion.")] void PowerInformation([in] uint32 arg2, [out] uint32 argr); + [WmiMethodId(32), Implemented, read, write, Description("FW Update GPIO= toggle.")] void FWUpdateGPIOtoggle([in] uint32 arg2, [out] uint32 argr); + [WmiMethodId(33), Implemented, read, write, Description("Read Total of = GPIOs.")] void ReadTotalofGPIOs([out] uint32 argr); + [WmiMethodId(34), Implemented, read, write, Description("Read GPIO pin = Status.")] void ReadGPIOpPinStatus([in] uint32 arg2, [out] uint32 argr); + [WmiMethodId(35), Implemented, read, write, Description("Read Chassis C= olor.")] void ReadChassisColor([out] uint32 argr); + [WmiMethodId(36), Implemented, read, write, Description("Read Platform = Properties.")] void ReadPlatformProperties([out] uint32 argr); + [WmiMethodId(128), Implemented, read, write, Description("Caldera SW in= stallation.")] void CalderaSWInstallation([out] uint32 argr); + [WmiMethodId(129), Implemented, read, write, Description("Caldera SW is= released.")] void CalderaSWReleased([out] uint32 argr); + [WmiMethodId(130), Implemented, read, write, Description("Caldera Conne= ction Status.")] void CalderaConnectionStatus([in] uint32 arg2, [out] uint3= 2 argr); + [WmiMethodId(131), Implemented, read, write, Description("Surprise Unpl= ugged Flag Status.")] void SurpriseUnpluggedFlagStatus([out] uint32 argr); + [WmiMethodId(132), Implemented, read, write, Description("Clear Surpris= e Unplugged Flag.")] void ClearSurpriseUnpluggedFlag([out] uint32 argr); + [WmiMethodId(133), Implemented, read, write, Description("Cancel Undock= Request.")] void CancelUndockRequest([out] uint32 argr); + [WmiMethodId(135), Implemented, read, write, Description("Devices in Ca= ldera.")] void DevicesInCaldera([in] uint32 arg2, [out] uint32 argr); + [WmiMethodId(136), Implemented, read, write, Description("Notify BIOS f= or SW ready to disconnect Caldera.")] void NotifyBIOSForSWReadyToDisconnect= Caldera([out] uint32 argr); + [WmiMethodId(160), Implemented, read, write, Description("Tobii SW inst= allation.")] void TobiiSWinstallation([out] uint32 argr); + [WmiMethodId(161), Implemented, read, write, Description("Tobii SW Rele= ased.")] void TobiiSWReleased([out] uint32 argr); + [WmiMethodId(162), Implemented, read, write, Description("Tobii Camera = Power Reset.")] void TobiiCameraPowerReset([out] uint32 argr); + [WmiMethodId(163), Implemented, read, write, Description("Tobii Camera = Power On.")] void TobiiCameraPowerOn([out] uint32 argr); + [WmiMethodId(164), Implemented, read, write, Description("Tobii Camera = Power Off.")] void TobiiCameraPowerOff([out] uint32 argr); + }; + +Some of these methods get quite intricate so we will describe them using +pseudo-code that vaguely resembles the original ASL code. + +Argument Structure +------------------ + +All input arguments have type **uint32** and their structure is very simil= ar +between methods. Usually, the first byte corresponds to a specific *operat= ion* +the method performs, and the subsequent bytes correspond to *arguments* pa= ssed +to this *operation*. For example, if an operation has code 0x01 and requir= es an +ID 0xA0, the argument you would pass to the method is 0xA001. + + +Thermal Methods +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +WMI method Thermal_Information([in] uint32 arg2, [out] uint32 argr) +------------------------------------------------------------------- + +:: + + if BYTE_0(arg2) =3D=3D 0x01: + argr =3D 1 + + if BYTE_0(arg2) =3D=3D 0x02: + argr =3D UNKNOWN_CONSTANT + + if BYTE_0(arg2) =3D=3D 0x03: + if BYTE_1(arg2) =3D=3D 0x00: + argr =3D FAN_ID_0 + + if BYTE_1(arg2) =3D=3D 0x01: + argr =3D FAN_ID_1 + + if BYTE_1(arg2) =3D=3D 0x02: + argr =3D FAN_ID_2 + + if BYTE_1(arg2) =3D=3D 0x03: + argr =3D FAN_ID_3 + + if BYTE_1(arg2) =3D=3D 0x04: + argr =3D SENSOR_ID_CPU | 0x0100 + + if BYTE_1(arg2) =3D=3D 0x05: + argr =3D SENSOR_ID_GPU | 0x0100 + + if BYTE_1(arg2) =3D=3D 0x06: + argr =3D THERMAL_MODE_QUIET_ID + + if BYTE_1(arg2) =3D=3D 0x07: + argr =3D THERMAL_MODE_BALANCED_ID + + if BYTE_1(arg2) =3D=3D 0x08: + argr =3D THERMAL_MODE_BALANCED_PERFORMANCE_ID + + if BYTE_1(arg2) =3D=3D 0x09: + argr =3D THERMAL_MODE_PERFORMANCE_ID + + if BYTE_1(arg2) =3D=3D 0x0A: + argr =3D THERMAL_MODE_LOW_POWER_ID + + if BYTE_1(arg2) =3D=3D 0x0B: + argr =3D THERMAL_MODE_GMODE_ID + + else: + argr =3D 0xFFFFFFFF + + if BYTE_0(arg2) =3D=3D 0x04: + if is_valid_sensor(BYTE_1(arg2)): + argr =3D SENSOR_TEMP_C + else: + argr =3D 0xFFFFFFFF + + if BYTE_0(arg2) =3D=3D 0x05: + if is_valid_fan(BYTE_1(arg2)): + argr =3D FAN_RPM() + + if BYTE_0(arg2) =3D=3D 0x06: + skip + + if BYTE_0(arg2) =3D=3D 0x07: + argr =3D 0 + + If BYTE_0(arg2) =3D=3D 0x08: + if is_valid_fan(BYTE_1(arg2)): + argr =3D 0 + else: + argr =3D 0xFFFFFFFF + + if BYTE_0(arg2) =3D=3D 0x09: + if is_valid_fan(BYTE_1(arg2)): + argr =3D FAN_UNKNOWN_STAT_0() + + else: + argr =3D 0xFFFFFFFF + + if BYTE_0(arg2) =3D=3D 0x0A: + argr =3D THERMAL_MODE_BALANCED_ID + + if BYTE_0(arg2) =3D=3D 0x0B: + argr =3D CURRENT_THERMAL_MODE() + + if BYTE_0(arg2) =3D=3D 0x0C: + if is_valid_fan(BYTE_1(arg2)): + argr =3D FAN_UNKNOWN_STAT_1() + else: + argr =3D 0xFFFFFFFF + +WMI method Thermal_Control([in] uint32 arg2, [out] uint32 argr) +--------------------------------------------------------------- + +:: + + if BYTE_0(arg2) =3D=3D 0x01: + if is_valid_thermal_profile(BYTE_1(arg2)): + SET_THERMAL_PROFILE(BYTE_1(arg2)) + argr =3D 0 + + if BYTE_0(arg2) =3D=3D 0x02: + if is_valid_fan(BYTE_1(arg2)): + SET_FAN_SPEED_MULTIPLIER(BYTE_2(arg2)) + argr =3D 0 + else: + argr =3D 0xFFFFFFFF + +.. note:: + While you can manually change the fan speed multiplier with this method, + Dell's BIOS tends to overwrite this changes anyway. + +These are the known thermal profile codes: + +:: + + CUSTOM 0x00 + + QUIET 0x96 + BALANCED 0x97 + BALANCED_PERFORMANCE 0x98 + PERFORMANCE 0x99 + + QUIET_USTT 0xA3 + BALANCED_USTT 0xA0 + BALANCED_PERFORMANCE_USTT 0xA1 + PERFORMANCE_USTT 0xA4 + LOW_POWER_USTT 0xA5 + + GMODE 0xAB + +Usually if a model doesn't support the first four profiles they will suppo= rt +the User Selectable Thermal Tables (USTT) profiles and vice-versa. + +GMODE replaces PERFORMANCE in G-Series laptops. + +WMI method GetFanSensors([in] uint32 arg2, [out] uint32 argr) +------------------------------------------------------------- + +:: + + if BYTE_0(arg2) =3D=3D 1: + if is_valid_fan(BYTE_1(arg2)): + argr =3D 1 + else: + argr =3D 0 + + if BYTE_0(arg2) =3D=3D 2: + if is_valid_fan(BYTE_1(arg2)): + if BYTE_2(arg2) =3D=3D 0: + argr =3D=3D SENSOR_ID + else + argr =3D=3D 0xFFFFFFFF + else: + argr =3D 0 + +Overclocking Methods +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. warning:: + These methods have not been tested and are only partially reverse + engineered. + +WMI method Return_OverclockingReport([out] uint32 argr) +------------------------------------------------------- + +:: + + CSMI (0xE3, 0x99) + argr =3D 0 + +CSMI is an unknown operation. + +WMI method Set_OCUIBIOSControl([in] uint32 arg2, [out] uint32 argr) +------------------------------------------------------------------- + +:: + + CSMI (0xE3, 0x99) + argr =3D 0 + +CSMI is an unknown operation + +WMI method Clear_OCFailSafeFlag([out] uint32 argr) +-------------------------------------------------- + +:: + + CSMI (0xE3, 0x99) + argr =3D 0 + +CSMI is an unknown operation + + +WMI method MemoryOCControl([in] uint32 arg2, [out] uint32 argr) +--------------------------------------------------------------- + +AWCC supports memory overclocking, but this method is very intricate and h= as +not been deciphered yet. + +GPIO methods +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +These methods are probably related to some kind of firmware update system, +through a GPIO device. + +.. warning:: + These methods have not been tested and are only partially reverse + engineered. + +WMI method FWUpdateGPIOtoggle([in] uint32 arg2, [out] uint32 argr) +------------------------------------------------------------------ + +:: + + if BYTE_0(arg2) =3D=3D 0: + if BYTE_1(arg2) =3D=3D 1: + SET_PIN_A_HIGH() + else: + SET_PIN_A_LOW() + + if BYTE_0(arg2) =3D=3D 1: + if BYTE_1(arg2) =3D=3D 1: + SET_PIN_B_HIGH() + + else: + SET_PIN_B_LOW() + + else: + argr =3D 1 + +WMI method ReadTotalofGPIOs([out] uint32 argr) +---------------------------------------------- + +:: + + argr =3D 0x02 + +WMI method ReadGPIOpPinStatus([in] uint32 arg2, [out] uint32 argr) +------------------------------------------------------------------ + +:: + + if BYTE_0(arg2) =3D=3D 0: + argr =3D PIN_A_STATUS + + if BYTE_0(arg2) =3D=3D 1: + argr =3D PIN_B_STATUS + +Other information Methods +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D + +WMI method SystemInformation([in] uint32 arg2, [out] uint32 argr) +----------------------------------------------------------------- + +Returns unknown information. + +WMI method PowerInformation([in] uint32 arg2, [out] uint32 argr) +---------------------------------------------------------------- + +Returns unknown information. + +WMI method ReadChassisColor([out] uint32 argr) +---------------------------------------------- + +:: + + argr =3D CHASSIS_COLOR_ID + +WMI method ReadPlatformProperties([out] uint32 argr) +---------------------------------------------------- + +Returns unknown information. + +Acknowledgements +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Kudos to `AlexIII `_ for documenting +and testing avaliable thermal profile codes. + --=20 2.47.0