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>
This commit is contained in:
Armin Wolf
Hans de Goede
parent
3d43f9f639
commit
b4cc979588
@ -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
|
||||
*
|
||||
* Returns extra data associated with an event in WMI.
|
||||
* Get extra data associated with an WMI event, the caller needs to free @out.
|
||||
*
|
||||
* 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);
|
||||
|
||||
@ -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)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user