1 /* SPDX-License-Identifier: GPL-2.0-only */ 2 /* 3 * wmi.h - ACPI WMI interface 4 * 5 * Copyright (c) 2015 Andrew Lutomirski 6 */ 7 8 #ifndef _LINUX_WMI_H 9 #define _LINUX_WMI_H 10 11 #include <linux/compiler_attributes.h> 12 #include <linux/device.h> 13 #include <linux/acpi.h> 14 #include <linux/mod_devicetable.h> 15 #include <linux/types.h> 16 17 /** 18 * struct wmi_device - WMI device structure 19 * @dev: Device associated with this WMI device 20 * @setable: True for devices implementing the Set Control Method 21 * 22 * This represents WMI devices discovered by the WMI driver core. 23 */ 24 struct wmi_device { 25 struct device dev; 26 bool setable; 27 }; 28 29 /** 30 * to_wmi_device() - Helper macro to cast a device to a wmi_device 31 * @device: device struct 32 * 33 * Cast a struct device to a struct wmi_device. 34 */ 35 #define to_wmi_device(device) container_of_const(device, struct wmi_device, dev) 36 37 /** 38 * struct wmi_buffer - WMI data buffer 39 * @length: Buffer length in bytes 40 * @data: Pointer to the buffer content 41 * 42 * This structure is used to exchange data with the WMI driver core. 43 */ 44 struct wmi_buffer { 45 size_t length; 46 void *data; 47 }; 48 49 /** 50 * struct wmi_string - WMI string representation 51 * @length: Size of @chars in bytes 52 * @chars: UTF16-LE characters with optional nul termination and padding 53 * 54 * This structure is used when exchanging string data over the WMI interface. 55 */ 56 struct wmi_string { 57 __le16 length; 58 __le16 chars[]; 59 } __packed; 60 61 ssize_t wmi_string_to_utf8s(const struct wmi_string *str, u8 *dst, size_t length); 62 63 ssize_t wmi_string_from_utf8s(struct wmi_string *str, size_t max_chars, const u8 *src, 64 size_t src_length); 65 66 int wmidev_invoke_method(struct wmi_device *wdev, u8 instance, u32 method_id, 67 const struct wmi_buffer *in, struct wmi_buffer *out, size_t min_size); 68 69 int wmidev_invoke_procedure(struct wmi_device *wdev, u8 instance, u32 method_id, 70 const struct wmi_buffer *in); 71 72 int wmidev_query_block(struct wmi_device *wdev, u8 instance, struct wmi_buffer *out, 73 size_t min_size); 74 75 int wmidev_set_block(struct wmi_device *wdev, u8 instance, const struct wmi_buffer *in); 76 77 acpi_status wmidev_evaluate_method(struct wmi_device *wdev, u8 instance, u32 method_id, 78 const struct acpi_buffer *in, struct acpi_buffer *out); 79 80 union acpi_object *wmidev_block_query(struct wmi_device *wdev, u8 instance); 81 82 acpi_status wmidev_block_set(struct wmi_device *wdev, u8 instance, const struct acpi_buffer *in); 83 84 u8 wmidev_instance_count(struct wmi_device *wdev); 85 86 /** 87 * struct wmi_driver - WMI driver structure 88 * @driver: Driver model structure 89 * @id_table: List of WMI GUIDs supported by this driver 90 * @min_event_size: Minimum event payload size supported by this driver 91 * @no_singleton: Driver can be instantiated multiple times 92 * @probe: Callback for device binding 93 * @remove: Callback for device unbinding 94 * @shutdown: Callback for device shutdown 95 * @notify: Callback for receiving WMI events (deprecated) 96 * @notify_new: Callback for receiving WMI events 97 * 98 * This represents WMI drivers which handle WMI devices. The data inside the buffer 99 * passed to the @notify_new callback is guaranteed to be aligned on a 8-byte boundary. 100 * The minimum supported size for said buffer can be specified using @min_event_size. 101 * WMI drivers that still use the deprecated @notify callback can still set @min_event_size 102 * to 0 in order to signal that they support WMI events which provide no event data. 103 */ 104 struct wmi_driver { 105 struct device_driver driver; 106 const struct wmi_device_id *id_table; 107 size_t min_event_size; 108 bool no_singleton; 109 110 int (*probe)(struct wmi_device *wdev, const void *context); 111 void (*remove)(struct wmi_device *wdev); 112 void (*shutdown)(struct wmi_device *wdev); 113 void (*notify)(struct wmi_device *device, union acpi_object *data); 114 void (*notify_new)(struct wmi_device *device, const struct wmi_buffer *data); 115 }; 116 117 /** 118 * to_wmi_driver() - Helper macro to cast a driver to a wmi_driver 119 * @drv: driver struct 120 * 121 * Cast a struct device_driver to a struct wmi_driver. 122 */ 123 #define to_wmi_driver(drv) container_of_const(drv, struct wmi_driver, driver) 124 125 int __must_check __wmi_driver_register(struct wmi_driver *driver, struct module *owner); 126 127 void wmi_driver_unregister(struct wmi_driver *driver); 128 129 /** 130 * wmi_driver_register() - Helper macro to register a WMI driver 131 * @driver: wmi_driver struct 132 * 133 * Helper macro for registering a WMI driver. It automatically passes 134 * THIS_MODULE to the underlying function. 135 */ 136 #define wmi_driver_register(driver) __wmi_driver_register((driver), THIS_MODULE) 137 138 /** 139 * module_wmi_driver() - Helper macro to register/unregister a WMI driver 140 * @__wmi_driver: wmi_driver struct 141 * 142 * Helper macro for WMI drivers which do not do anything special in module 143 * init/exit. This eliminates a lot of boilerplate. Each module may only 144 * use this macro once, and calling it replaces module_init() and module_exit(). 145 */ 146 #define module_wmi_driver(__wmi_driver) \ 147 module_driver(__wmi_driver, wmi_driver_register, \ 148 wmi_driver_unregister) 149 150 #endif 151