From patchwork Mon Apr 24 22:29:36 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Armin Wolf X-Patchwork-Id: 87195 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a59:b0ea:0:b0:3b6:4342:cba0 with SMTP id b10csp3048105vqo; Mon, 24 Apr 2023 15:55:15 -0700 (PDT) X-Google-Smtp-Source: AKy350ZIXXfKerBwlQoZyeEC2BJo52y0QP67OrNmUi82djGp0i49xW6VAx3rn774R24UB2D+vqiF X-Received: by 2002:a17:90a:ca81:b0:247:a272:71be with SMTP id y1-20020a17090aca8100b00247a27271bemr15607959pjt.46.1682376915454; Mon, 24 Apr 2023 15:55:15 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1682376915; cv=none; d=google.com; s=arc-20160816; b=tCnhpXUIhXQo/p4LvaHMpXtDLEMYREwPXVCxBlKUmmdmpY4MXW/DKsThacv3sj50Ex gyV6HVxT+6ryq7QKQM4eMSI0iaPfJVgMUnSC7uaIAmgX+uDOOHNI/7B9PlXhSyEfghFC Br2zvbUzIykRjdZH0r7H3qpLBhWmZPPQgOTllvel34SjzY3t6Avfc/A85qwScHy1+x8A +VycvDwnh969T25jZ+3Wb+XhOpSRYbHmLR+IzdIAjJtiXPUbxB3KXd/3LmDbTcAPHz1z ucOAvHln7V0ISCaTbOh7IRoQRPt3z10QvPKf/fCW2OP5OHbM+1cqe5Gey9A3GG/Ch3Iq z6vQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:ui-outboundreport:content-transfer-encoding :mime-version:references:in-reply-to:message-id:date:subject:cc:to :from:dkim-signature; bh=1/v5Q3BRF5I4PhLTlab+7BQuA4KtsPIutxfLfg//HTQ=; b=haSaU5Jga91Qj5aLVceGpTgq94LTKj/rz0/lKJauoAtcWXgk3Vhn2Nq+TcHppgQuEY nv29cISe6vI67jBNh+7TRuffl6nZAI0D2iSzYZj2cA+MP9bRGJtJ4lbb/qTDvmE4Ntem 1nxhhn7eVAnHExcGXd0YedEfMpu8KBIWlCKbxKW6WzMbsvJD+1oP5HuHvSgCgAyTC2Fa rvz5ACQDvO9RYtKv9zXLQb2TptUMOB1lMME1t4hS/h5w45EcEN1x+ihQ/0hvFD1fPuF5 YMRP2iC4hMQVTleYBVI/RerPjOCDptjGgzMZFE6T2fu8jOvrRRWsESgg+W+DUJe7QWYv UYww== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@gmx.de header.s=s31663417 header.b=EPBT1DsZ; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=gmx.de Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id jx8-20020a17090b46c800b002474c31b885si7970887pjb.78.2023.04.24.15.55.01; Mon, 24 Apr 2023 15:55:15 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@gmx.de header.s=s31663417 header.b=EPBT1DsZ; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=gmx.de Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S232396AbjDXWai (ORCPT + 99 others); Mon, 24 Apr 2023 18:30:38 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:47176 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232847AbjDXWaO (ORCPT ); Mon, 24 Apr 2023 18:30:14 -0400 Received: from mout.gmx.net (mout.gmx.net [212.227.15.15]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 7F028658A; Mon, 24 Apr 2023 15:30:12 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=gmx.de; s=s31663417; t=1682375394; i=w_armin@gmx.de; bh=iVqdph6X+GipV6ZKWRoPrN5VwYjb+Cuw0LlqITIXC8g=; h=X-UI-Sender-Class:From:To:Cc:Subject:Date:In-Reply-To:References; b=EPBT1DsZlnuFQnYXiODEXNX6V/vApieESYS6Bvn+kzrf3oq8pb2ZuMaVG0jjlc7M3 cnYgZef38ilsyf6WAsn6qXYa4/IX5bZDydINoJxLhkHHVmH2MXZLVOoSv9M1Jk0wiF j+PxGrbt1xbQOOeaXKM/MznyNpg06vAb72uYvkEMPOfumSgpWtPa4/1gm0E761dni8 vKIbG48bumaIyIru6qgnwMuvIQKLMa91L7ZeO7WMKK5IN+ktwsZjJ6O/2JGYnbdL6+ V7F8SC9VaRUPo4LYIOgdPIdczspCcjwhdMIbhVrcBMgeUH6gIc8K3aK3WGtAqbCbFD 16ZqP/oGuJv2g== X-UI-Sender-Class: 724b4f7f-cbec-4199-ad4e-598c01a50d3a Received: from esprimo-mx.users.agdsn.de ([141.30.226.129]) by mail.gmx.net (mrgmx004 [212.227.17.190]) with ESMTPSA (Nemesis) id 1MfpSl-1qWlEu37px-00gH6M; Tue, 25 Apr 2023 00:29:53 +0200 From: Armin Wolf To: hdegoede@redhat.com, markgross@kernel.org, rdunlap@infradead.org Cc: corbet@lwn.net, linux-doc@vger.kernel.org, platform-driver-x86@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH v2 1/4] platform/x86: wmi: Add kernel doc comments Date: Tue, 25 Apr 2023 00:29:36 +0200 Message-Id: <20230424222939.208137-2-W_Armin@gmx.de> X-Mailer: git-send-email 2.30.2 In-Reply-To: <20230424222939.208137-1-W_Armin@gmx.de> References: <20230424222939.208137-1-W_Armin@gmx.de> MIME-Version: 1.0 X-Provags-ID: V03:K1:vRCVVwbDWD+ZJ87iIsOkjEBi0bfwLpBmzAC78h858sft/66f5Ec z7kUdMGQ1VOCGx4Dqts+r38gSCuFfi/XFazYZAJGfyVzRpKG+rkbp8Ds3c3F+DOnqyK+iDi GBQtvuqmOVViN69BIxD04KLTCnS+8HU9WLGlFJx8unnjS6aMOctzL0KftEtq/wfSBXw707F y+Yszbh7OtadYnny8TNnQ== UI-OutboundReport: notjunk:1;M01:P0:gOsB93qS9hI=;SkHAswjJY9NmoO4Uf27QmE4aze5 P4rLLQRpWzSuWfbyK6ChIvxJCfg5sAl6YEvipZb60kf31fx/QlFxILOraQ8uaIbaEG2+Y8JEL hrGsNzLPgOLGAeHAmuM1ZGa4uB2Ol9eAcTtv6+5RV7GZHYZU09CMO2YryJC8hNqqxbBiwurY0 cxhP8JnIcdDswNITNog0zCrAxqAs/usQtUXIMLHRA/zAiIEKS5LAWVE7We9MnCU43MA4Vt0eI lUnPRuKZVZ6VswQnqRPgWgV604QLDYlpgwmFddbJ9VFeh89AdxUDWdX3ORd+ObQqj/lbvCSHZ WSXEnEXiB8bSJPDPeTx++WaMMK+LiB4ptVG1smKq/MwrN0KE/4QMdLx3sHLTphaRDsztQ/h6z uRX05Xv5oG3hSj98reux2tYk9+yCQUd2MPQ6qWZVbG0kH4AYMaOvAf8Cos4iZt4x0F0Yb8tPP lboqMUFp8D/rD0KbCJOTpgy6vYtNJn6WWNyHXw5HwxNnF3Var0IH3mgbyrwsq0tjxcTIPdiG/ kL10nfpajrH/Elv9kKr8tlCuSPB1KQEHFIzjn1lE38JH0iWBNsWInkmQu8CqhcRlM1UrcYdgV EwiuE7U0KcMUATfeIgEYfAUtcYZ8YeXF/g9hN+4EvsXXgzYFGTUKrA0FUKxw1Mc59LZrvFFTB Q2Yd85GqrSxKvMARCguMU6Y2bJC/etSW9UaEaQaKbeYQVYt/bBiB715urV69hZq2ryCowawtx RUPSMiDYd9Xkq65hojWCMj5fNyotk8kTE9TIeHnjo+LXU8zwnbOXf1TgWm9bH2LfCENFACmhV FjxvT+1PI4IZkoR7VtdC2OzXE42q29FTwASgwIOWyJaCeLlEIJAwT3DCxhSAzr1p067xvxzMl ClTshkEMU2MhmNEDbkh+I2/6XBhCUInmMszOGDP/MkVD5DyXqBYJPj4YrJoACQ5oaUilV6IZu UbijtJ4GWOlkp4Ki1iyj1T7AI6Q= X-Spam-Status: No, score=-2.8 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,FREEMAIL_FROM,RCVD_IN_DNSWL_LOW, RCVD_IN_MSPIKE_H2,SPF_HELO_NONE,SPF_PASS,T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1764100056126888687?= X-GMAIL-MSGID: =?utf-8?q?1764100056126888687?= Add kernel doc comments useful for documenting the functions/structs used to interact with the WMI driver core. Signed-off-by: Armin Wolf Tested-by: Randy Dunlap Acked-by: Randy Dunlap --- drivers/platform/x86/wmi.c | 51 +++++++++++++++++++++++++++++++------- include/linux/wmi.h | 41 +++++++++++++++++++++++++++--- 2 files changed, 80 insertions(+), 12 deletions(-) -- 2.30.2 diff --git a/drivers/platform/x86/wmi.c b/drivers/platform/x86/wmi.c index d81319a502ef..99af2cc03b0f 100644 --- a/drivers/platform/x86/wmi.c +++ b/drivers/platform/x86/wmi.c @@ -248,7 +248,9 @@ static acpi_status get_event_data(const struct wmi_block *wblock, struct acpi_bu * @wdev: A wmi bus device from a driver * @length: Required buffer size * - * Allocates memory needed for buffer, stores the buffer size in that memory + * Allocates memory needed for buffer, stores the buffer size in that memory. + * + * Return: 0 on success or a negative error code for failure. */ int set_required_buffer_size(struct wmi_device *wdev, u64 length) { @@ -269,7 +271,9 @@ EXPORT_SYMBOL_GPL(set_required_buffer_size); * @in: Buffer containing input for the method call * @out: Empty buffer to return the method results * - * Call an ACPI-WMI method + * Call an ACPI-WMI method, the caller must free @out. + * + * Return: acpi_status signaling success or error. */ acpi_status wmi_evaluate_method(const char *guid_string, u8 instance, u32 method_id, const struct acpi_buffer *in, struct acpi_buffer *out) @@ -294,7 +298,9 @@ EXPORT_SYMBOL_GPL(wmi_evaluate_method); * @in: Buffer containing input for the method call * @out: Empty buffer to return the method results * - * Call an ACPI-WMI method + * Call an ACPI-WMI method, the caller must free @out. + * + * Return: acpi_status signaling success or error. */ acpi_status wmidev_evaluate_method(struct wmi_device *wdev, u8 instance, u32 method_id, const struct acpi_buffer *in, struct acpi_buffer *out) @@ -411,7 +417,9 @@ static acpi_status __query_block(struct wmi_block *wblock, u8 instance, * @instance: Instance index * @out: Empty buffer to return the contents of the data block to * - * Return the contents of an ACPI-WMI data block to a buffer + * Query a ACPI-WMI block, the caller must free @out. + * + * Return: ACPI object containing the content of the WMI block. */ acpi_status wmi_query_block(const char *guid_string, u8 instance, struct acpi_buffer *out) @@ -427,6 +435,15 @@ acpi_status wmi_query_block(const char *guid_string, u8 instance, } EXPORT_SYMBOL_GPL(wmi_query_block); +/** + * wmidev_block_query - Return contents of a WMI block + * @wdev: A wmi bus device from a driver + * @instance: Instance index + * + * Query an ACPI-WMI block, the caller must free the result. + * + * Return: ACPI object containing the content of the WMI block. + */ union acpi_object *wmidev_block_query(struct wmi_device *wdev, u8 instance) { struct acpi_buffer out = { ACPI_ALLOCATE_BUFFER, NULL }; @@ -445,7 +462,9 @@ EXPORT_SYMBOL_GPL(wmidev_block_query); * @instance: Instance index * @in: Buffer containing new values for the data block * - * Write the contents of the input buffer to an ACPI-WMI data block + * Write the contents of the input buffer to an ACPI-WMI data block. + * + * Return: acpi_status signaling success or error. */ acpi_status wmi_set_block(const char *guid_string, u8 instance, const struct acpi_buffer *in) @@ -555,6 +574,8 @@ static void wmi_notify_debug(u32 value, void *context) * @data: Data to be returned to handler when event is fired * * Register a handler for events sent to the ACPI-WMI mapper device. + * + * Return: acpi_status signaling success or error. */ acpi_status wmi_install_notify_handler(const char *guid, wmi_notify_handler handler, @@ -597,6 +618,8 @@ EXPORT_SYMBOL_GPL(wmi_install_notify_handler); * @guid: 36 char string of the form fa50ff2b-f2e8-45de-83fa-65417f2f49ba * * Unregister handler for events sent to the ACPI-WMI mapper device. + * + * Return: acpi_status signaling success or error. */ acpi_status wmi_remove_notify_handler(const char *guid) { @@ -641,9 +664,11 @@ EXPORT_SYMBOL_GPL(wmi_remove_notify_handler); * wmi_get_event_data - Get WMI data associated with an event * * @event: Event to find - * @out: Buffer to hold event data. out->pointer should be freed with kfree() + * @out: Buffer to hold event data + * + * Get extra data associated with an WMI event, the caller needs to free @out. * - * Returns extra data associated with an event in WMI. + * Return: acpi_status signaling success or error. */ acpi_status wmi_get_event_data(u32 event, struct acpi_buffer *out) { @@ -664,7 +689,9 @@ EXPORT_SYMBOL_GPL(wmi_get_event_data); * wmi_has_guid - Check if a GUID is available * @guid_string: 36 char string of the form fa50ff2b-f2e8-45de-83fa-65417f2f49ba * - * Check if a given GUID is defined by _WDG + * Check if a given GUID is defined by _WDG. + * + * Return: True if GUID is available, false otherwise. */ bool wmi_has_guid(const char *guid_string) { @@ -678,7 +705,7 @@ EXPORT_SYMBOL_GPL(wmi_has_guid); * * Find the _UID of ACPI device associated with this WMI GUID. * - * Return: The ACPI _UID field value or NULL if the WMI GUID was not found + * Return: The ACPI _UID field value or NULL if the WMI GUID was not found. */ char *wmi_get_acpi_device_uid(const char *guid_string) { @@ -1454,6 +1481,12 @@ int __must_check __wmi_driver_register(struct wmi_driver *driver, } EXPORT_SYMBOL(__wmi_driver_register); +/** + * wmi_driver_unregister() - Unregister a WMI driver + * @driver: WMI driver to unregister + * + * Unregisters a WMI driver from the WMI bus. + */ void wmi_driver_unregister(struct wmi_driver *driver) { driver_unregister(&driver->driver); diff --git a/include/linux/wmi.h b/include/linux/wmi.h index b88d7b58e61e..c1a3bd4e4838 100644 --- a/include/linux/wmi.h +++ b/include/linux/wmi.h @@ -13,25 +13,44 @@ #include #include +/** + * struct wmi_device - WMI device structure + * @dev: Device associated with this WMI device + * @setable: True for devices implementing the Set Control Method + * + * This represents WMI devices discovered by the WMI driver core. + */ struct wmi_device { struct device dev; - /* True for data blocks implementing the Set Control Method */ + /* private: used by the WMI driver core */ bool setable; }; -/* evaluate the ACPI method associated with this device */ extern acpi_status wmidev_evaluate_method(struct wmi_device *wdev, u8 instance, u32 method_id, const struct acpi_buffer *in, struct acpi_buffer *out); -/* Caller must kfree the result. */ extern union acpi_object *wmidev_block_query(struct wmi_device *wdev, u8 instance); extern int set_required_buffer_size(struct wmi_device *wdev, u64 length); +/** + * struct wmi_driver - WMI driver structure + * @driver: Driver model structure + * @id_table: List of WMI GUIDs supported by this driver + * @no_notify_data: WMI events provide no event data + * @probe: Callback for device binding + * @remove: Callback for device unbinding + * @notify: Callback for receiving WMI events + * @filter_callback: Callback for filtering device IOCTLs + * + * This represents WMI drivers which handle WMI devices. + * @filter_callback is only necessary for drivers which + * want to set up a WMI IOCTL interface. + */ struct wmi_driver { struct device_driver driver; const struct wmi_device_id *id_table; @@ -47,8 +66,24 @@ struct wmi_driver { extern int __must_check __wmi_driver_register(struct wmi_driver *driver, struct module *owner); extern void wmi_driver_unregister(struct wmi_driver *driver); + +/** + * wmi_driver_register() - Helper macro to register a WMI driver + * @driver: wmi_driver struct + * + * Helper macro for registering a WMI driver. It automatically passes + * THIS_MODULE to the underlying function. + */ #define wmi_driver_register(driver) __wmi_driver_register((driver), THIS_MODULE) +/** + * module_wmi_driver() - Helper macro to register/unregister a WMI driver + * @__wmi_driver: wmi_driver struct + * + * Helper macro for WMI drivers which do not do anything special in module + * init/exit. This eliminates a lot of boilerplate. Each module may only + * use this macro once, and calling it replaces module_init() and module_exit(). + */ #define module_wmi_driver(__wmi_driver) \ module_driver(__wmi_driver, wmi_driver_register, \ wmi_driver_unregister) From patchwork Mon Apr 24 22:29:37 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Armin Wolf X-Patchwork-Id: 87194 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a59:b0ea:0:b0:3b6:4342:cba0 with SMTP id b10csp3041670vqo; Mon, 24 Apr 2023 15:35:22 -0700 (PDT) X-Google-Smtp-Source: AKy350Y7m+Sx51jnU4dZ8MzGn5p0ON/kNHTMOwzKgtXRP9SWd+76fSJ9FeSsMGSab30QmGmnwr4Z X-Received: by 2002:a17:90a:d703:b0:247:601c:20fa with SMTP id y3-20020a17090ad70300b00247601c20famr14325065pju.5.1682375722557; Mon, 24 Apr 2023 15:35:22 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1682375722; cv=none; d=google.com; s=arc-20160816; b=Z45xHYbltcMgYkKhttQ4Vze6DCtGRO8mRlCUctX4ZDAYDyTm7j5zbx4ASrNiqcUc7S K/z7AcPUq002x4Kzqv83Ob9DmoI70ycFRt50bQQUjKhwueh6OgG5LHxcMXLTEhBa3I3b DFDxFIU5i0TVLfZumhz0xl7pxnbnJnjTV7rXF9zGiSWQWVtR0X6fgK8duEy7DhE1iPd1 3VRgRLa5QqbUiua2QXaNxAGMhAZnDueUJpRKkwsY+PI6xV6wPM0195RmDkOTDwnOFXxh Sa3dqX3dplz6mLnhWSBp4n4jK35Z2UqZN2Osm//i8+v5k/CUP57jnndprsDiLdbpnx4K I3fg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:ui-outboundreport:content-transfer-encoding :mime-version:references:in-reply-to:message-id:date:subject:cc:to :from:dkim-signature; bh=chHzSUgPofgd7WlqeRMA+kAutEpgozfQsUj5xMmttgo=; b=ef+2h+q/CA0jyb4zEKBg075ylIP0Zx4UIHzNY2PhNPthCpH5g/JPTqthBVR+21jhVB rLdc6lAFeOYihdTM4BXXhi4dCDpEvL0WlFJ3XeszRWWRmV5qdFDtUrvnyl1qc1TXfbJe jiUvjvNhCC6WcVTxD1WuL6rNNQ8M+C2rQW1444W4M8grE0+rokNTNvsTe8O4YrUUuGsp Uvqy5prN0gKktjISONs97DnwBj7/VQxdq7446tUyzuGfgX2tYcyzZqcnhBh+0cTlLrTi PFVqLBfaOyQFvTCGltItygp1pawo4IVRQPVA7Ng2S82JN6Y8jPt8nCUvWAcdkA5nx57k qfvA== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@gmx.de header.s=s31663417 header.b=Y8MLpEy6; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=gmx.de Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id fy20-20020a17090b021400b002400d82df5asi11948943pjb.57.2023.04.24.15.35.07; Mon, 24 Apr 2023 15:35:22 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@gmx.de header.s=s31663417 header.b=Y8MLpEy6; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=gmx.de Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S232953AbjDXWal (ORCPT + 99 others); Mon, 24 Apr 2023 18:30:41 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:47178 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232852AbjDXWaO (ORCPT ); Mon, 24 Apr 2023 18:30:14 -0400 Received: from mout.gmx.net (mout.gmx.net [212.227.17.22]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 6D65E658F; Mon, 24 Apr 2023 15:30:13 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=gmx.de; s=s31663417; t=1682375395; i=w_armin@gmx.de; bh=2YrIKDNZDkQHrEt9bRGYeH12nvZWn7b5Z+NCxkBIups=; h=X-UI-Sender-Class:From:To:Cc:Subject:Date:In-Reply-To:References; b=Y8MLpEy65VYfq7tJD26XILAj2ooR+iEf6vms8AcH7yCanT/BGqeYrAEhDnCgbObCQ BQ/w6Zv8kwWocqM/PNPezHO0MVTsKuOfhizGWIqeS53hEMuO4YZEDFbDlsO1bZ8ftc Q3cecka58FaUz3BaKSayItE1g+oTs2rPDPgWUv4CJVCh/Td8GgT0VUV/G1DCoVn/92 lrqKnSm75QMp79WxfbP4jizs6wJO1MftCF49g5JIg800gACnMDHew6caNqAwfNSEuR FqE/lP245pPbItK/933lshLUSRsrcOIgg26KfZJGqKoTAX7ZgaO1t1sTChGcShZFON 4O5A1Rua1EFcQ== X-UI-Sender-Class: 724b4f7f-cbec-4199-ad4e-598c01a50d3a Received: from esprimo-mx.users.agdsn.de ([141.30.226.129]) by mail.gmx.net (mrgmx105 [212.227.17.168]) with ESMTPSA (Nemesis) id 1MmUHp-1qYy9K2sK1-00iRsO; Tue, 25 Apr 2023 00:29:55 +0200 From: Armin Wolf To: hdegoede@redhat.com, markgross@kernel.org, rdunlap@infradead.org Cc: corbet@lwn.net, linux-doc@vger.kernel.org, platform-driver-x86@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH v2 2/4] platform/x86: wmi: Mark GUID-based WMI interface as deprecated Date: Tue, 25 Apr 2023 00:29:37 +0200 Message-Id: <20230424222939.208137-3-W_Armin@gmx.de> X-Mailer: git-send-email 2.30.2 In-Reply-To: <20230424222939.208137-1-W_Armin@gmx.de> References: <20230424222939.208137-1-W_Armin@gmx.de> MIME-Version: 1.0 X-Provags-ID: V03:K1:Jv/gn/iU8iEbpWse970NO/spdEVRZL10JicOLpQBqcvKIijc9Dx uv0uQRB9fGbgisoAzqPYb/CCkEN1jbD1i0jIRfndxARu1dSC9zKrgZXc6Ev8B8h965h4A7u ZPTAJgiRXn/qwfMR4EKJuEQ22zcjF6QwIHyKQEYzIgSFWmi/ejwFlT1i1QHJlXsHte++0bA KvWQQ/miINcZhreBQznbQ== UI-OutboundReport: notjunk:1;M01:P0:V+2ge/4u46E=;ChSDFo4TkbFqe38HJ5v/yOKkux1 /d69AaXtveGKrxfO1XtVnmjNlyDeQgNyGMyjhtDHkakhR1Fio1JR6ZHS70KI4xcUNGsGv40rq S0Y9jzzyXXRrnbZAN5utwIrQPW/JJ73AsYrLYAXRuxv6gKLRx56cDWyXiulmBeRUDikC5I+Mn yoiJs1dt0P0xwlZSuLCKCi8LUHMHeyuJcZx8Xc2WA4oknsqCC4axW9uECqCSjh19ajezg2JmW GhIbN7SepvwFLkgs3LLc59awj50/b883Q5G2TggWhJB49O69N//cKXfO4zyedzUROthIzsGVv +ycP32O98E5qBUw/1EOswVWhkAw1FhXE4YIqJVbDUCn026W5yX6dhuWt3mYK5tCmeATAIlVRR A26XS8WJuc7mSM7VRHnDiRaCw/qMjamSXO2mhVNU56GtNEzNnWWn+2TkEAlivN4zdoqnpo713 9y5oejNXcodPmiSOICTG4Vldfok4P324mi5WduTWFtOh/FYC7y+olCboDujWzkr/4QreLWmyH 9S1nxJVieaQppjo1focMMRUOO/eJ2B8ZoRGXc6iirAWtXArDwRTAKk8EVYAVpLODqhDVAYijd hHPmUJ+cA8CeIlbLDGqgUPgbcOWYc88RhUN1MN1WnuyHDHQXzhaziHDRQM+Cwu40qxMxoayoD rIfaaLgp5v8x82CxOyfTp8LPGyO0aCR/Gt5/itF6ahVs+WPtP+U9g8LjH0Achgt6dx+xdtWDt 9qTWcCN5ZPgw/1Nb4bFQd2XPtAjG2/V6zThGRlRCabrJg6v4leIbQFXuWXyAbU85GGkqrYs+N r7kCFA0IuoxjMNjt0FaDwz2gw5M/Gb2hYTWD8gZWq/1jAYW1INdyIJObK16JnPpUVv7iaseNc pmaBiCyhGwUX1t5vurzViUhyAn2XVwFte2qXjij9uVHsZIV3AUoxwW8e19Mv0Rs6bdcaxu6h2 H60NdsB1G5C2tuShg0SRSg42uig= X-Spam-Status: No, score=-2.8 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,FREEMAIL_FROM,RCVD_IN_DNSWL_LOW, RCVD_IN_MSPIKE_H2,SPF_HELO_NONE,SPF_PASS,T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1764098805634366952?= X-GMAIL-MSGID: =?utf-8?q?1764098805634366952?= The WMI driver core supports a more mordern bus-based interface for interacting with WMI devices. The older GUID-based interface depends on each WMI GUID and notification id being unique on a given system, which turned out is not the case. Mark the older interface as deprecated since new WMI drivers should use the bus-based interface to avoid this issues. Signed-off-by: Armin Wolf Tested-by: Randy Dunlap Acked-by: Randy Dunlap --- drivers/platform/x86/wmi.c | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) -- 2.30.2 diff --git a/drivers/platform/x86/wmi.c b/drivers/platform/x86/wmi.c index 99af2cc03b0f..c226dd4163a1 100644 --- a/drivers/platform/x86/wmi.c +++ b/drivers/platform/x86/wmi.c @@ -264,7 +264,7 @@ int set_required_buffer_size(struct wmi_device *wdev, u64 length) EXPORT_SYMBOL_GPL(set_required_buffer_size); /** - * wmi_evaluate_method - Evaluate a WMI method + * wmi_evaluate_method - Evaluate a WMI method (deprecated) * @guid_string: 36 char string of the form fa50ff2b-f2e8-45de-83fa-65417f2f49ba * @instance: Instance index * @method_id: Method ID to call @@ -457,7 +457,7 @@ union acpi_object *wmidev_block_query(struct wmi_device *wdev, u8 instance) EXPORT_SYMBOL_GPL(wmidev_block_query); /** - * wmi_set_block - Write to a WMI block + * wmi_set_block - Write to a WMI block (deprecated) * @guid_string: 36 char string of the form fa50ff2b-f2e8-45de-83fa-65417f2f49ba * @instance: Instance index * @in: Buffer containing new values for the data block @@ -568,7 +568,7 @@ static void wmi_notify_debug(u32 value, void *context) } /** - * wmi_install_notify_handler - Register handler for WMI events + * wmi_install_notify_handler - Register handler for WMI events (deprecated) * @guid: 36 char string of the form fa50ff2b-f2e8-45de-83fa-65417f2f49ba * @handler: Function to handle notifications * @data: Data to be returned to handler when event is fired @@ -614,7 +614,7 @@ acpi_status wmi_install_notify_handler(const char *guid, EXPORT_SYMBOL_GPL(wmi_install_notify_handler); /** - * wmi_remove_notify_handler - Unregister handler for WMI events + * wmi_remove_notify_handler - Unregister handler for WMI events (deprecated) * @guid: 36 char string of the form fa50ff2b-f2e8-45de-83fa-65417f2f49ba * * Unregister handler for events sent to the ACPI-WMI mapper device. @@ -661,7 +661,7 @@ acpi_status wmi_remove_notify_handler(const char *guid) EXPORT_SYMBOL_GPL(wmi_remove_notify_handler); /** - * wmi_get_event_data - Get WMI data associated with an event + * wmi_get_event_data - Get WMI data associated with an event (deprecated) * * @event: Event to find * @out: Buffer to hold event data @@ -700,7 +700,7 @@ bool wmi_has_guid(const char *guid_string) EXPORT_SYMBOL_GPL(wmi_has_guid); /** - * wmi_get_acpi_device_uid() - Get _UID name of ACPI device that defines GUID + * wmi_get_acpi_device_uid() - Get _UID name of ACPI device that defines GUID (deprecated) * @guid_string: 36 char string of the form fa50ff2b-f2e8-45de-83fa-65417f2f49ba * * Find the _UID of ACPI device associated with this WMI GUID. From patchwork Mon Apr 24 22:29:38 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Armin Wolf X-Patchwork-Id: 87197 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a59:b0ea:0:b0:3b6:4342:cba0 with SMTP id b10csp3050431vqo; Mon, 24 Apr 2023 16:01:28 -0700 (PDT) X-Google-Smtp-Source: AKy350aTQ1eN20NV2aXThOPfeuaDpoN0ODrwvHXSw6OBATvU3MlZJzommtp0yeLkN7HY7f96VayH X-Received: by 2002:a17:90b:4f41:b0:23d:16d6:2f05 with SMTP id pj1-20020a17090b4f4100b0023d16d62f05mr15544927pjb.22.1682377288663; Mon, 24 Apr 2023 16:01:28 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1682377288; cv=none; d=google.com; s=arc-20160816; b=slGWCccXddiLCX/M4PhVgCEups1cpqQrlR3TrUsqZcoJ3mOlAjGuz/Si9IfyUr+5SB oaUPWMqpsTC/+qzqwZ6iwX8xi+giNWJMTWY+nI1hD1Nm1o9oH/nQ/EkwYK87JVbFzCs7 JP7RFnBjfOvIikihAj/+0MpKzsJwy8wpXp/BpHcIiTSDdKdtnxklDyBOBqea6/IdgHGr GalCi8Gj+y9PYr8OxSU8/iYKCWBaqpwQ4mUHE7bfcHMJF2JdkCz8mYXZhqylz8ol6uma oReV36NVjsWwIuXv50KipKjnyo0xGLAvPeLtQkxTOnDx2tZ41A2GUyxVLhNf70iUjHEK DRKQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:ui-outboundreport:content-transfer-encoding :mime-version:references:in-reply-to:message-id:date:subject:cc:to :from:dkim-signature; bh=OtndVJP4TBfgel4uBSSNEz5HNS7ctOBnckBnJlMxQyo=; b=TXkl4mKyuAFB3dntYCoksCe59m495oajuILYBXE1RYYf2jDKaG9FnnyQPfoP0fIYtg IOILJnm5CFgFZX5xjA291eAtHJDY+gB4vJ/YL5MZjwTFYsfJ+5ClEJPbLpJXgB7xYPSW X1vf6aZ/92HyuJYCbGQH/BJnQdcC9aIhz97YTRuiBhLAZGEyfjh/wH2Sl4k8qzg4wW9m Kw9/iavzlbRXHM1m7wcK9RePafjOXn8gQDB0AsBc0BV10qOt8q+IoONoth2F0k5xPjPZ ccziRGHZahVWZeoGIZPzJe9/gaQhHUOdQLJIRO0KmaZOd9eD+CRPt5syESio8vtRea+H uIuA== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@gmx.de header.s=s31663417 header.b=DtchKjHS; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=gmx.de Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id i16-20020a170902cf1000b001a6bda7f476si8516740plg.468.2023.04.24.16.01.13; Mon, 24 Apr 2023 16:01:28 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@gmx.de header.s=s31663417 header.b=DtchKjHS; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=gmx.de Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S232845AbjDXWap (ORCPT + 99 others); Mon, 24 Apr 2023 18:30:45 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:47180 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232854AbjDXWaP (ORCPT ); Mon, 24 Apr 2023 18:30:15 -0400 Received: from mout.gmx.net (mout.gmx.net [212.227.15.15]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 8852265BD; Mon, 24 Apr 2023 15:30:13 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=gmx.de; s=s31663417; t=1682375397; i=w_armin@gmx.de; bh=7xRY30R6PXSQyDMierFQ8JoyNLMxxmzzr3zVRFswPG8=; h=X-UI-Sender-Class:From:To:Cc:Subject:Date:In-Reply-To:References; b=DtchKjHSsUoNxbg56fdo584LnTsOc1BLexEoPato1YybQiBwPRXB3+WBWuixk2m+E U6gUFofBT0lFh7XFtfDMy10yGoH0afW61xJkgWzHza/zaMvkXFIxNf79TeVNQsxoie 12fF9fInvUrQUZW6wCUma7N3D/RqcURuP0qgSKIfPoYJ5OD/9M40fMkhIQHAND0l9B pJ46f6iqWYIenn2JvlGMwG1ejPeioAx0Fd02H0fXwIOhaDfWk4Xv+sNHKcocXTvE/I WIkGaUSgkHmZOXF5rYKo7s+RaM5+yqRBJV3nikLM5IN4aB6Gv8X/AVDdQp90yrJFHK qhNs0qYQqyybw== X-UI-Sender-Class: 724b4f7f-cbec-4199-ad4e-598c01a50d3a Received: from esprimo-mx.users.agdsn.de ([141.30.226.129]) by mail.gmx.net (mrgmx004 [212.227.17.190]) with ESMTPSA (Nemesis) id 1M5fIW-1px9F1270E-007DPB; Tue, 25 Apr 2023 00:29:57 +0200 From: Armin Wolf To: hdegoede@redhat.com, markgross@kernel.org, rdunlap@infradead.org Cc: corbet@lwn.net, linux-doc@vger.kernel.org, platform-driver-x86@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH v2 3/4] platform/x86: wmi: Add documentation Date: Tue, 25 Apr 2023 00:29:38 +0200 Message-Id: <20230424222939.208137-4-W_Armin@gmx.de> X-Mailer: git-send-email 2.30.2 In-Reply-To: <20230424222939.208137-1-W_Armin@gmx.de> References: <20230424222939.208137-1-W_Armin@gmx.de> MIME-Version: 1.0 X-Provags-ID: V03:K1:G7wfzvf0b2FmNc7WgLDZkgubw083T6DgfoLFo5jse07WvsvhvmR cN6ZCIT0oZcV/LCGFVYbmGTp77EnSfiAzQ5n6LsV0+V9QiXMTF1gehbwA3cSJbLHsxSR2dB LoDpcqMe0Cu4F/udWr0K5+YubzJbBixK3n4+swc5efRUU7f5Hw2A15jru/ieHj6n50Wc8lY HVUgNPZaMFS8j0Sm30Zcw== UI-OutboundReport: notjunk:1;M01:P0:JRf1laSJV5c=;bviMjp8nreVz+dyAfaLvNsh6Vyo dGX40jI7cC9O8bDXvSaFN4no5U+PJySI3dC8YmdGq5U0Eai5+6JdCpSxXGqOx+4wxtj5rd2RO WFOBoasrxrQCsl3SYdhoRO8urrFr6giR+WP49dilY/0D3bGMe0jIoequi4euXnWbH/XgW8YJa baFs0gblpd6KrZmpMCkFk6qVkNneA4qvco2D6teCNXIFxjH/L+7sTJm4o9sRFAqQyGwbCXkk6 T1PS3hkFzcdyu1zRQEzj0t0F2Ea3twiGp6blV2fo9c5ym7BrhqbGWfV3mdlj9jnKTLL93lpNb 1P5ieyep3xlhuurdx1khag2Sg2gTwe1dYk2sAMwjA/JZ0EtLCJnuGgC/pXINRY03Nmnh0t9Hz UhpUTGcNu+t3fAVh8NTL6Ny6xTXdDZrDqQM34uF2gLu3ZKnNT1NBVuDlwBJdKMN2G+ZzMBkO8 Q7OR0lsTIC8uLK0tWP8/SySfQ8oy9Ugp7TY2TDj+6tXBJyK+Mn0sPVmbeOn32TtZ4JVTewTtA l5n9uLni15gGYnMy66OrsugCQ3Z/fDngSUCqSndsdcH2IG9qyG/wdoBWG5z3epo8iNaJGiTkV /Mz1D9qRF91Y5DkV12MpLtMVuolZEBh0A1jiecqLA0lRQsh+KfB454cZwsaesXNEK+mad+EHG Ha6A5CvO795JfnRS+p96PKIp/0NyxK94Sc2CRait7Gjgs6GanCc2H4UxlZZZb6LdjpPrFpcQk HGNQqZ4hvUk6E9wrShZjRuyCIJlCAONMHt7VT1wtVMKzqS3Rwm9JG+8f9Fyl/3s3+2zAHqYOz u7Z97exC10seMuxrFBIfLvITkCjuxiH5G7me2qdzptRc+nKaHsZ41f4iqWbkOFCakA/YoDwYU Cj7QxwWiu1T9rgeT17JzkHjEgAQrbc7JqH9W+6+QETFJQslZPE1gG6q/LTrJNSwyt/NXnFPkP 5883RnKUvLezI0T+UTTBpjzgUus= X-Spam-Status: No, score=-2.8 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,FREEMAIL_FROM,RCVD_IN_DNSWL_LOW, RCVD_IN_MSPIKE_H2,SPF_HELO_NONE,SPF_PASS,T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1764100447876904569?= X-GMAIL-MSGID: =?utf-8?q?1764100447876904569?= Add documentation for the WMI subsystem. The documentation describes both the ACPI WMI interface and the driver API for interacting with the WMI driver core. The information regarding the ACPI interface was retrieved from the Ubuntu kernel references and the Windows driver samples available on GitHub. The documentation is supposed to help driver developers writing WMI drivers, as many modern machines designed to run Windows provide an ACPI WMI interface. Signed-off-by: Armin Wolf Tested-by: Randy Dunlap Acked-by: Randy Dunlap --- Documentation/driver-api/index.rst | 1 + Documentation/driver-api/wmi.rst | 21 ++++++ Documentation/subsystem-apis.rst | 1 + Documentation/wmi/acpi-interface.rst | 96 ++++++++++++++++++++++++++++ Documentation/wmi/index.rst | 18 ++++++ MAINTAINERS | 2 + 6 files changed, 139 insertions(+) create mode 100644 Documentation/driver-api/wmi.rst create mode 100644 Documentation/wmi/acpi-interface.rst create mode 100644 Documentation/wmi/index.rst -- 2.30.2 diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index ff9aa1afdc62..1e16a40da3ba 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -113,6 +113,7 @@ available subsections can be seen below. xillybus zorro hte/index + wmi .. only:: subproject and html diff --git a/Documentation/driver-api/wmi.rst b/Documentation/driver-api/wmi.rst new file mode 100644 index 000000000000..6ca58c8249e5 --- /dev/null +++ b/Documentation/driver-api/wmi.rst @@ -0,0 +1,21 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +============== +WMI Driver API +============== + +The WMI driver core supports a more modern bus-based interface for interacting +with WMI devices, and an older GUID-based interface. The latter interface is +considered to be deprecated, so new WMI drivers should generally avoid it since +it has some issues with multiple WMI devices and events sharing the same GUIDs +and/or notification IDs. The modern bus-based interface instead maps each +WMI device to a :c:type:`struct wmi_device `, so it supports +WMI devices sharing GUIDs and/or notification IDs. Drivers can then register +a :c:type:`struct wmi_driver `, which will be bound to compatible +WMI devices by the driver core. + +.. kernel-doc:: include/linux/wmi.h + :internal: + +.. kernel-doc:: drivers/platform/x86/wmi.c + :export: diff --git a/Documentation/subsystem-apis.rst b/Documentation/subsystem-apis.rst index b51f38527e14..69f5e4d53bad 100644 --- a/Documentation/subsystem-apis.rst +++ b/Documentation/subsystem-apis.rst @@ -57,3 +57,4 @@ needed). scheduler/index mhi/index peci/index + wmi/index diff --git a/Documentation/wmi/acpi-interface.rst b/Documentation/wmi/acpi-interface.rst new file mode 100644 index 000000000000..d31af0ed9c08 --- /dev/null +++ b/Documentation/wmi/acpi-interface.rst @@ -0,0 +1,96 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +================== +ACPI WMI interface +================== + +The ACPI WMI interface is a proprietary extension of the ACPI specification made +by Microsoft to allow hardware vendors to embed WMI (Windows Management Instrumentation) +objects inside their ACPI firmware. Typical functions implemented over ACPI WMI +are hotkey events on modern notebooks and configuration of BIOS options. + +PNP0C14 ACPI device +------------------- + +Discovery of WMI objects is handled by defining ACPI devices with a PNP ID +of ``PNP0C14``. These devices will contain a set of ACPI buffers and methods +used for mapping and execution of WMI methods and/or queries. If there exist +multiple of such devices, then each device is required to have a +unique ACPI UID. + +_WDG buffer +----------- + +The ``_WDG`` buffer is used to discover WMI objects and is required to be +static. Its internal structure consists of data blocks with a size of 20 bytes, +containing the following data: + +======= =============== ===================================================== +Offset Size (in bytes) Content +======= =============== ===================================================== +0x00 16 128 bit Variant 2 object GUID. +0x10 2 2 character method ID or single byte notification ID. +0x12 1 Object instance count. +0x13 1 Object flags. +======= =============== ===================================================== + +The WMI object flags control whether the method or notification ID is used: + +- 0x1: Data block usage is expensive and must be explicitly enabled/disabled. +- 0x2: Data block contains WMI methods. +- 0x4: Data block contains ASCIZ string. +- 0x8: Data block describes a WMI event, use notification ID instead + of method ID. + +Each WMI object GUID can appear multiple times inside a system. +The method/notification ID is used to construct the ACPI method names used for +interacting with the WMI object. + +WQxx ACPI methods +----------------- + +If a data block does not contain WMI methods, then its content can be retrieved +by this required ACPI method. The last two characters of the ACPI method name +are the method ID of the data block to query. Their single parameter is an +integer describing the instance which should be queried. This parameter can be +omitted if the data block contains only a single instance. + +WSxx ACPI methods +----------------- + +Similar to the ``WQxx`` ACPI methods, except that it is optional and takes an +additional buffer as its second argument. The instance argument also cannot +be omitted. + +WMxx ACPI methods +----------------- + +Used for executing WMI methods associated with a data block. The last two +characters of the ACPI method name are the method ID of the data block +containing the WMI methods. Their first parameter is a integer describing the +instance which methods should be executed. The second parameter is an integer +describing the WMI method ID to execute, and the third parameter is a buffer +containing the WMI method parameters. If the data block is marked as containing +an ASCIZ string, then this buffer should contain an ASCIZ string. The ACPI +method will return the result of the executed WMI method. + +WExx ACPI methods +----------------- + +Used for optionally enabling/disabling WMI events, the last two characters of +the ACPI method are the notification ID of the data block describing the WMI +event as hexadecimal value. Their first parameter is an integer with a value +of 0 if the WMI event should be disabled, other values will enable +the WMI event. + +WCxx ACPI methods +----------------- +Similar to the ``WExx`` ACPI methods, except that it controls data collection +instead of events and thus the last two characters of the ACPI method name are +the method ID of the data block to enable/disable. + +_WED ACPI method +---------------- + +Used to retrieve additional WMI event data, its single parameter is a integer +holding the notification ID of the event. diff --git a/Documentation/wmi/index.rst b/Documentation/wmi/index.rst new file mode 100644 index 000000000000..b29933a86380 --- /dev/null +++ b/Documentation/wmi/index.rst @@ -0,0 +1,18 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +============= +WMI Subsystem +============= + +.. toctree:: + :maxdepth: 1 + + acpi-interface + +.. only:: subproject and html + + + Indices + ======= + + * :ref:`genindex` diff --git a/MAINTAINERS b/MAINTAINERS index 0c9011f5fc17..979d37176429 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -449,6 +449,8 @@ F: include/linux/acpi_viot.h ACPI WMI DRIVER L: platform-driver-x86@vger.kernel.org S: Orphan +F: Documentation/driver-api/wmi.rst +F: Documentation/wmi/ F: drivers/platform/x86/wmi.c F: include/uapi/linux/wmi.h From patchwork Mon Apr 24 22:29:39 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Armin Wolf X-Patchwork-Id: 87196 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a59:b0ea:0:b0:3b6:4342:cba0 with SMTP id b10csp3050300vqo; Mon, 24 Apr 2023 16:01:16 -0700 (PDT) X-Google-Smtp-Source: AKy350Zd29C6k589ZUAXRYkrg3p/46D6V5i5LxbXViAR2g3TtJGQqO8Bvhv6cdNYi2bjAjij5CsK X-Received: by 2002:a17:902:ec81:b0:19d:20a:a219 with SMTP id x1-20020a170902ec8100b0019d020aa219mr18855851plg.66.1682377275965; Mon, 24 Apr 2023 16:01:15 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1682377275; cv=none; d=google.com; s=arc-20160816; b=jc2JAoWRGLvlo6ro6t97scYUAN2YXB3dl0Dk8fWbvTAs/BMeYkkNF3ROyyYNnH4Ts3 hSbrZwcNSK/ZBd7WKDgrRBdS7eysofXl+zqYnLVLGN4iesYXrrKUxfEkSPHC+JxmucsX ocEsdxMm6KbbrsudU095HLAdnOy+PwNvaWyNshTB4zanvwtqw5Y5f7LDIrQJxQA0t9sf VvclC35TG8YJuAIOXnWzbFP6RonSfcDMEeH9XnOJNz6UqM6rMEmz+TcJHotx1fr5d4md +p2wC3AXSbCw9Lt85T4dSvw+KIkBG0LqLEamHaKbEYtaZqg2Qknd5SG65WfX4LgTuvfc gTbQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:ui-outboundreport:content-transfer-encoding :mime-version:references:in-reply-to:message-id:date:subject:cc:to :from:dkim-signature; bh=4N6fsF58IRuAm/rQrZ7qWCvVkGY029nzpBGXP6NPSGU=; b=jVDg8nrvaH9QEwBg6gCQBgZCL0UXxhY4l0DeQ2EOPiNSCGOGmVUPQ2l+gL4vTjhTIS 5VdGrMqpXNwXHwVxCnSU0AqVn+CbBZRRFMUJh7eG0oqga5wB1TdWM4KK3bwMIbSuPbIh wn5uJ2ybfKRORB4oCPG3ADLAz8FxeyqrVHJ4Ycpq9C46ZVDEvwqTZrCD+2D4rKJLfOmW /U0SFE7aYeIt7icFdwO1rOf9pC3gTkrNMramGbO1dTmhAzQUQgbirR7dMF9bssPpVbQD iJGWtRLq/Dm8eH2aDwmIgEhX+LMaj13iXs4IS00+UeLUpLT+380mURoBioUr4ADgWFdp ELFQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@gmx.de header.s=s31663417 header.b=FC5JywkA; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=gmx.de Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id p8-20020a170902ebc800b001a59439dbfesi11563715plg.529.2023.04.24.16.01.00; Mon, 24 Apr 2023 16:01:15 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@gmx.de header.s=s31663417 header.b=FC5JywkA; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=gmx.de Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S233025AbjDXWas (ORCPT + 99 others); Mon, 24 Apr 2023 18:30:48 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:47188 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232797AbjDXWaS (ORCPT ); Mon, 24 Apr 2023 18:30:18 -0400 Received: from mout.gmx.net (mout.gmx.net [212.227.15.18]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id AA47719BA; Mon, 24 Apr 2023 15:30:16 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=gmx.de; s=s31663417; t=1682375399; i=w_armin@gmx.de; bh=5sBozmCf1BEgGSGkQpQ5TyvhvOpqQjnfZg8RI7c13lk=; h=X-UI-Sender-Class:From:To:Cc:Subject:Date:In-Reply-To:References; b=FC5JywkA/v5UxGhp8hi3nxL80rlZlTGfNrFD1a2FKtJ60+MKzi+d8Nksv97tNglu3 q0FxY8612TUoitJkt5zEsZfGEAEb4IjitLlzI+W/4WKVYzt2DCKJV+08bCocRqqsKD bPV3B91ffGYh8tiIllxEUkTg2mIPS53a9DdF4QhbeQxLKYVIO4r4BsJuGZ7jULr3YG MTzZRjaARA5OISsRwcYaCuMqM7iF30ycjcmUDOP7fJpr6Wu8Hhfxg8LkElRhbXC83s fyPau81CN/0Yi9fPHcigm0vqAD7nNlKuZkUeLzZWm+h0u18G6s664m3VvgRkEPuXqo kODP61Oxy7r/Q== X-UI-Sender-Class: 724b4f7f-cbec-4199-ad4e-598c01a50d3a Received: from esprimo-mx.users.agdsn.de ([141.30.226.129]) by mail.gmx.net (mrgmx005 [212.227.17.190]) with ESMTPSA (Nemesis) id 1MTzf6-1phpGX1oVW-00R1oW; Tue, 25 Apr 2023 00:29:59 +0200 From: Armin Wolf To: hdegoede@redhat.com, markgross@kernel.org, rdunlap@infradead.org Cc: corbet@lwn.net, linux-doc@vger.kernel.org, platform-driver-x86@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH v2 4/4] platform/x86: wmi: Add device specific documentation Date: Tue, 25 Apr 2023 00:29:39 +0200 Message-Id: <20230424222939.208137-5-W_Armin@gmx.de> X-Mailer: git-send-email 2.30.2 In-Reply-To: <20230424222939.208137-1-W_Armin@gmx.de> References: <20230424222939.208137-1-W_Armin@gmx.de> MIME-Version: 1.0 X-Provags-ID: V03:K1:7+O4enu/7tBLqmAzdJ19x3VYC6p81wTc2Dcvcw2qlO/LUffLERb u/8VvAuNUSQdNEyYsgw173I+QYxGCtgRrTSlFW0B2mnnlheRktdqrtbe+H0+98750UXoEbR 1lVD2oERS6EteadvPBY7xLdyMsoPgDJLJMcMf7jqXuml9sfaPx4vVNddA5rfv1TVck9gZ5U DoqIhLHzmUWm8rEECS16Q== UI-OutboundReport: notjunk:1;M01:P0:loTMlzO8HN0=;r3JaavTxwMUfj/S5WPf6y8yap4K DOI7NZPNEEh//RJrvbktQw1wA9+YApoiVOiMFpu7IS3mvbmPrIW3nOITznzKa36ZUKTO6SH// Pfi4Bf+XTVkmdZZyZ2+yfs6X6wdIn/feM77tNyK1wtyCEuUO3fyKzEWvJLjUm/YFWmmlJMGgP osZX2ZETorSIhCV0AK9eQhy0P8p1PI/RVsFa2dnjoztplSOK90UJVW0QGEpgcm2bc7rGxC8Od U60Xoh9lHrIR660ZPopVmItpU8Iy3QafykhD2A1VhNXwKPgky8Tt7556O2xvCh8mOz3GyQRnY wtsQkya+PtLUBqqzdfhQ4QUtYxRnwsLa44ofx+GrzyU/X2JXlXDi7C2cNRSrKnEKOGyBFz5mO oRRRjaL+V7d+eSPvFyLyyZXPQTewAoMU2tnz+8nHHd8qCeu/Dfioyonrb8Z6Wdf04Zl4Yd/kw AgMdEYk8vsCiWeMRkRVvoiv826on997cRUbgK+fW+66K6y7hHLcAPF4QT1FTl212kOPIoa9Kw JkLgdMyuLEQSwgX0vLv8S2Nc7GVX9lGK16CCuD/Swpz5wuyJ10fy/Lzzt4Tglb29ugpsoUMwR 7pud+fjZ8gu3zw2N2JJJNCL6nY7gvqIlsMmzI71+WEW+InH4kVqEQSB/iQzDMA1YiYm5WZQjP TmiMTmgPyX/RaSqRNxPVsu56qxrkJeuVCdHMbKKpJnOsgpAx8isvoiXwddvYi6EI29Ks6D5Do DpEtCudvkNOHR9J5dZAVhqfda2LN57IJibeWxWgKhu2ow38uSBslz/DVm3Y+vf6k8ulCPT2Mb +WJCnOSeY8e/eqkrU+zB/9Akqr2JQRvhSzxIIJvmKMwIf59RBle2hMafNwU1DOmbVlzSZcfma PqE7e3U653MZZiSvOcqCcFGRxVuKlF2Aw018o/Z8unf2E+cSwcqZTHbg3RDfY8NhFXSPb5tTp k4EGVb81m4NMelmNJrGI+qjoG/s= X-Spam-Status: No, score=-2.8 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,FREEMAIL_FROM,RCVD_IN_DNSWL_LOW, RCVD_IN_MSPIKE_H2,SPF_HELO_NONE,SPF_PASS,T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1764100434669009465?= X-GMAIL-MSGID: =?utf-8?q?1764100434669009465?= Add a place for device-specific documentation of WMI drivers. The first entry is documentation for the wmi-bmof driver, with additional documentation being expected to follow. Signed-off-by: Armin Wolf Tested-by: Randy Dunlap Acked-by: Randy Dunlap --- .../ABI/stable/sysfs-platform-wmi-bmof | 7 ++++++ Documentation/wmi/devices/index.rst | 22 ++++++++++++++++ Documentation/wmi/devices/wmi-bmof.rst | 25 +++++++++++++++++++ Documentation/wmi/index.rst | 1 + MAINTAINERS | 7 ++++++ drivers/platform/x86/Kconfig | 4 +-- 6 files changed, 64 insertions(+), 2 deletions(-) create mode 100644 Documentation/ABI/stable/sysfs-platform-wmi-bmof create mode 100644 Documentation/wmi/devices/index.rst create mode 100644 Documentation/wmi/devices/wmi-bmof.rst -- 2.30.2 diff --git a/Documentation/ABI/stable/sysfs-platform-wmi-bmof b/Documentation/ABI/stable/sysfs-platform-wmi-bmof new file mode 100644 index 000000000000..a786504b6027 --- /dev/null +++ b/Documentation/ABI/stable/sysfs-platform-wmi-bmof @@ -0,0 +1,7 @@ +What: /sys/bus/wmi/devices/05901221-D566-11D1-B2F0-00A0C9062910[-X]/bmof +Date: Jun 2017 +KernelVersion: 4.13 +Description: + Binary MOF metadata used to decribe the details of available ACPI WMI interfaces. + + See Documentation/wmi/devices/wmi-bmof.rst for details. diff --git a/Documentation/wmi/devices/index.rst b/Documentation/wmi/devices/index.rst new file mode 100644 index 000000000000..c08735a9d7df --- /dev/null +++ b/Documentation/wmi/devices/index.rst @@ -0,0 +1,22 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +============================= +Driver-specific Documentation +============================= + +This section provides information about various devices supported by +the Linux kernel, their protocols and driver details. + +.. toctree:: + :maxdepth: 1 + :numbered: + :glob: + + * + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/wmi/devices/wmi-bmof.rst b/Documentation/wmi/devices/wmi-bmof.rst new file mode 100644 index 000000000000..ca1ee9a29be3 --- /dev/null +++ b/Documentation/wmi/devices/wmi-bmof.rst @@ -0,0 +1,25 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +============================== +WMI embedded Binary MOF driver +============================== + +Introduction +============ + +Many machines embed WMI Binary MOF (Managed Object Format) metadata used to +describe the details of their ACPI WMI interfaces. The data can be decoded +with tools like `bmfdec `_ to obtain a +human readable WMI interface description, which is useful for developing +new WMI drivers. + +The Binary MOF data can be retrieved from the ``bmof`` sysfs attribute of the +associated WMI device. Please note that multiple WMI devices containing Binary +MOF data can exist on a given system. + +WMI interface +============= + +The Binary MOF WMI device is identified by the WMI GUID ``05901221-D566-11D1-B2F0-00A0C9062910``. +The Binary MOF can be obtained by doing a WMI data block query. The result is +then returned as an ACPI buffer with a variable size. diff --git a/Documentation/wmi/index.rst b/Documentation/wmi/index.rst index b29933a86380..537cff188e14 100644 --- a/Documentation/wmi/index.rst +++ b/Documentation/wmi/index.rst @@ -8,6 +8,7 @@ WMI Subsystem :maxdepth: 1 acpi-interface + devices/index .. only:: subproject and html diff --git a/MAINTAINERS b/MAINTAINERS index 979d37176429..4d5b1f6d77f6 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -22556,6 +22556,13 @@ L: linux-wireless@vger.kernel.org S: Odd fixes F: drivers/net/wireless/wl3501* +WMI BINARY MOF DRIVER +L: platform-drivers-x86@vger.kernel.org +S: Orphan +F: Documentation/ABI/stable/sysfs-platform-wmi-bmof +F: Documentation/wmi/devices/wmi-bmof.rst +F: drivers/platform/x86/wmi-bmof.c + WOLFSON MICROELECTRONICS DRIVERS L: patches@opensource.cirrus.com S: Supported diff --git a/drivers/platform/x86/Kconfig b/drivers/platform/x86/Kconfig index 22052031c719..3d5dd9e997a6 100644 --- a/drivers/platform/x86/Kconfig +++ b/drivers/platform/x86/Kconfig @@ -43,8 +43,8 @@ config WMI_BMOF default ACPI_WMI help Say Y here if you want to be able to read a firmware-embedded - WMI Binary MOF data. Using this requires userspace tools and may be - rather tedious. + WMI Binary MOF (Managed Object Format) data. Using this requires + userspace tools and may be rather tedious. To compile this driver as a module, choose M here: the module will be called wmi-bmof.