From b4cc979588ee94b179e28c6f3f5c2d6197ea6461 Mon Sep 17 00:00:00 2001 From: Armin Wolf Date: Tue, 25 Apr 2023 00:29:36 +0200 Subject: platform/x86: wmi: Add kernel doc comments 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 Link: https://lore.kernel.org/r/20230424222939.208137-2-W_Armin@gmx.de Signed-off-by: Hans de Goede --- include/linux/wmi.h | 41 ++++++++++++++++++++++++++++++++++++++--- 1 file changed, 38 insertions(+), 3 deletions(-) (limited to 'include/linux/wmi.h') 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) -- cgit v1.2.3 From 2a2b13ae50cf70e07b471301ff50299f31d81c1d Mon Sep 17 00:00:00 2001 From: Armin Wolf Date: Sun, 30 Apr 2023 22:31:52 +0200 Subject: platform/x86: wmi: Allow retrieving the number of WMI object instances Currently, the WMI driver core knows how many instances of a given WMI object exist, but WMI drivers cannot access this information. At the same time, some current and upcoming WMI drivers want to have access to this information. Add wmi_instance_count() and wmidev_instance_count() to allow WMI drivers to get the number of WMI object instances. Signed-off-by: Armin Wolf Link: https://lore.kernel.org/r/20230430203153.5587-2-W_Armin@gmx.de Reviewed-by: Hans de Goede Signed-off-by: Hans de Goede --- drivers/platform/x86/wmi.c | 41 +++++++++++++++++++++++++++++++++++++++++ include/linux/acpi.h | 2 ++ include/linux/wmi.h | 2 ++ 3 files changed, 45 insertions(+) (limited to 'include/linux/wmi.h') diff --git a/drivers/platform/x86/wmi.c b/drivers/platform/x86/wmi.c index c226dd4163a1..5b95d7aa5c2f 100644 --- a/drivers/platform/x86/wmi.c +++ b/drivers/platform/x86/wmi.c @@ -263,6 +263,47 @@ int set_required_buffer_size(struct wmi_device *wdev, u64 length) } EXPORT_SYMBOL_GPL(set_required_buffer_size); +/** + * wmi_instance_count - Get number of WMI object instances + * @guid_string: 36 char string of the form fa50ff2b-f2e8-45de-83fa-65417f2f49ba + * + * Get the number of WMI object instances. + * + * Returns: Number of WMI object instances or negative error code. + */ +int wmi_instance_count(const char *guid_string) +{ + struct wmi_block *wblock; + acpi_status status; + + status = find_guid(guid_string, &wblock); + if (ACPI_FAILURE(status)) { + if (status == AE_BAD_PARAMETER) + return -EINVAL; + + return -ENODEV; + } + + return wmidev_instance_count(&wblock->dev); +} +EXPORT_SYMBOL_GPL(wmi_instance_count); + +/** + * wmidev_instance_count - Get number of WMI object instances + * @wdev: A wmi bus device from a driver + * + * Get the number of WMI object instances. + * + * Returns: Number of WMI object instances. + */ +u8 wmidev_instance_count(struct wmi_device *wdev) +{ + struct wmi_block *wblock = container_of(wdev, struct wmi_block, dev); + + return wblock->gblock.instance_count; +} +EXPORT_SYMBOL_GPL(wmidev_instance_count); + /** * wmi_evaluate_method - Evaluate a WMI method (deprecated) * @guid_string: 36 char string of the form fa50ff2b-f2e8-45de-83fa-65417f2f49ba diff --git a/include/linux/acpi.h b/include/linux/acpi.h index 7b71dd74baeb..5b9353f56928 100644 --- a/include/linux/acpi.h +++ b/include/linux/acpi.h @@ -414,6 +414,8 @@ extern bool acpi_is_pnp_device(struct acpi_device *); typedef void (*wmi_notify_handler) (u32 value, void *context); +int wmi_instance_count(const char *guid); + extern acpi_status wmi_evaluate_method(const char *guid, u8 instance, u32 method_id, const struct acpi_buffer *in, diff --git a/include/linux/wmi.h b/include/linux/wmi.h index c1a3bd4e4838..763bd382cf2d 100644 --- a/include/linux/wmi.h +++ b/include/linux/wmi.h @@ -35,6 +35,8 @@ extern acpi_status wmidev_evaluate_method(struct wmi_device *wdev, extern union acpi_object *wmidev_block_query(struct wmi_device *wdev, u8 instance); +u8 wmidev_instance_count(struct wmi_device *wdev); + extern int set_required_buffer_size(struct wmi_device *wdev, u64 length); /** -- cgit v1.2.3