diff options
| author | Armin Wolf <W_Armin@gmx.de> | 2023-04-25 00:29:36 +0200 |
|---|---|---|
| committer | Hans de Goede <hdegoede@redhat.com> | 2023-05-09 11:54:42 +0200 |
| commit | b4cc979588ee94b179e28c6f3f5c2d6197ea6461 (patch) | |
| tree | 8f9f52a0a27c7b89f1940ded5dd17c5f06a40bbf /include/linux/wmi.h | |
| parent | 3d43f9f639542fadfb28f40b509bf147a6624d48 (diff) | |
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 <W_Armin@gmx.de>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Link: https://lore.kernel.org/r/20230424222939.208137-2-W_Armin@gmx.de
Signed-off-by: Hans de Goede <hdegoede@redhat.com>
Diffstat (limited to 'include/linux/wmi.h')
| -rw-r--r-- | include/linux/wmi.h | 41 |
1 files changed, 38 insertions, 3 deletions
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 <linux/mod_devicetable.h> #include <uapi/linux/wmi.h> +/** + * 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) |