1 /* SPDX-License-Identifier: GPL-2.0 */ 2 /* 3 * ChromeOS Wilco Embedded Controller 4 * 5 * Copyright 2018 Google LLC 6 */ 7 8 #ifndef WILCO_EC_H 9 #define WILCO_EC_H 10 11 #include <linux/device.h> 12 #include <linux/kernel.h> 13 14 /* Message flags for using the mailbox() interface */ 15 #define WILCO_EC_FLAG_NO_RESPONSE BIT(0) /* EC does not respond */ 16 17 /* Normal commands have a maximum 32 bytes of data */ 18 #define EC_MAILBOX_DATA_SIZE 32 19 20 /** 21 * struct wilco_ec_device - Wilco Embedded Controller handle. 22 * @dev: Device handle. 23 * @mailbox_lock: Mutex to ensure one mailbox command at a time. 24 * @io_command: I/O port for mailbox command. Provided by ACPI. 25 * @io_data: I/O port for mailbox data. Provided by ACPI. 26 * @io_packet: I/O port for mailbox packet data. Provided by ACPI. 27 * @data_buffer: Buffer used for EC communication. The same buffer 28 * is used to hold the request and the response. 29 * @data_size: Size of the data buffer used for EC communication. 30 * @debugfs_pdev: The child platform_device used by the debugfs sub-driver. 31 * @rtc_pdev: The child platform_device used by the RTC sub-driver. 32 * @charger_pdev: Child platform_device used by the charger config sub-driver. 33 * @telem_pdev: The child platform_device used by the telemetry sub-driver. 34 */ 35 struct wilco_ec_device { 36 struct device *dev; 37 struct mutex mailbox_lock; 38 struct resource *io_command; 39 struct resource *io_data; 40 struct resource *io_packet; 41 void *data_buffer; 42 size_t data_size; 43 struct platform_device *debugfs_pdev; 44 struct platform_device *rtc_pdev; 45 struct platform_device *charger_pdev; 46 struct platform_device *telem_pdev; 47 }; 48 49 /** 50 * struct wilco_ec_request - Mailbox request message format. 51 * @struct_version: Should be %EC_MAILBOX_PROTO_VERSION 52 * @checksum: Sum of all bytes must be 0. 53 * @mailbox_id: Mailbox identifier, specifies the command set. 54 * @mailbox_version: Mailbox interface version %EC_MAILBOX_VERSION 55 * @reserved: Set to zero. 56 * @data_size: Length of following data. 57 */ 58 struct wilco_ec_request { 59 u8 struct_version; 60 u8 checksum; 61 u16 mailbox_id; 62 u8 mailbox_version; 63 u8 reserved; 64 u16 data_size; 65 } __packed; 66 67 /** 68 * struct wilco_ec_response - Mailbox response message format. 69 * @struct_version: Should be %EC_MAILBOX_PROTO_VERSION 70 * @checksum: Sum of all bytes must be 0. 71 * @result: Result code from the EC. Non-zero indicates an error. 72 * @data_size: Length of the response data buffer. 73 * @reserved: Set to zero. 74 * @data: Response data buffer. Max size is %EC_MAILBOX_DATA_SIZE_EXTENDED. 75 */ 76 struct wilco_ec_response { 77 u8 struct_version; 78 u8 checksum; 79 u16 result; 80 u16 data_size; 81 u8 reserved[2]; 82 u8 data[0]; 83 } __packed; 84 85 /** 86 * enum wilco_ec_msg_type - Message type to select a set of command codes. 87 * @WILCO_EC_MSG_LEGACY: Legacy EC messages for standard EC behavior. 88 * @WILCO_EC_MSG_PROPERTY: Get/Set/Sync EC controlled NVRAM property. 89 * @WILCO_EC_MSG_TELEMETRY: Request telemetry data from the EC. 90 */ 91 enum wilco_ec_msg_type { 92 WILCO_EC_MSG_LEGACY = 0x00f0, 93 WILCO_EC_MSG_PROPERTY = 0x00f2, 94 WILCO_EC_MSG_TELEMETRY = 0x00f5, 95 }; 96 97 /** 98 * struct wilco_ec_message - Request and response message. 99 * @type: Mailbox message type. 100 * @flags: Message flags, e.g. %WILCO_EC_FLAG_NO_RESPONSE. 101 * @request_size: Number of bytes to send to the EC. 102 * @request_data: Buffer containing the request data. 103 * @response_size: Number of bytes to read from EC. 104 * @response_data: Buffer containing the response data, should be 105 * response_size bytes and allocated by caller. 106 */ 107 struct wilco_ec_message { 108 enum wilco_ec_msg_type type; 109 u8 flags; 110 size_t request_size; 111 void *request_data; 112 size_t response_size; 113 void *response_data; 114 }; 115 116 /** 117 * wilco_ec_mailbox() - Send request to the EC and receive the response. 118 * @ec: Wilco EC device. 119 * @msg: Wilco EC message. 120 * 121 * Return: Number of bytes received or negative error code on failure. 122 */ 123 int wilco_ec_mailbox(struct wilco_ec_device *ec, struct wilco_ec_message *msg); 124 125 /** 126 * wilco_keyboard_leds_init() - Set up the keyboard backlight LEDs. 127 * @ec: EC device to query. 128 * 129 * After this call, the keyboard backlight will be exposed through a an LED 130 * device at /sys/class/leds. 131 * 132 * This may sleep because it uses wilco_ec_mailbox(). 133 * 134 * Return: 0 on success, negative error code on failure. 135 */ 136 int wilco_keyboard_leds_init(struct wilco_ec_device *ec); 137 138 /* 139 * A Property is typically a data item that is stored to NVRAM 140 * by the EC. Each of these data items has an index associated 141 * with it, known as the Property ID (PID). Properties may have 142 * variable lengths, up to a max of WILCO_EC_PROPERTY_MAX_SIZE 143 * bytes. Properties can be simple integers, or they may be more 144 * complex binary data. 145 */ 146 147 #define WILCO_EC_PROPERTY_MAX_SIZE 4 148 149 /** 150 * struct ec_property_set_msg - Message to get or set a property. 151 * @property_id: Which property to get or set. 152 * @length: Number of bytes of |data| that are used. 153 * @data: Actual property data. 154 */ 155 struct wilco_ec_property_msg { 156 u32 property_id; 157 int length; 158 u8 data[WILCO_EC_PROPERTY_MAX_SIZE]; 159 }; 160 161 /** 162 * wilco_ec_get_property() - Retrieve a property from the EC. 163 * @ec: Embedded Controller device. 164 * @prop_msg: Message for request and response. 165 * 166 * The property_id field of |prop_msg| should be filled before calling this 167 * function. The result will be stored in the data and length fields. 168 * 169 * Return: 0 on success, negative error code on failure. 170 */ 171 int wilco_ec_get_property(struct wilco_ec_device *ec, 172 struct wilco_ec_property_msg *prop_msg); 173 174 /** 175 * wilco_ec_set_property() - Store a property on the EC. 176 * @ec: Embedded Controller device. 177 * @prop_msg: Message for request and response. 178 * 179 * The property_id, length, and data fields of |prop_msg| should be 180 * filled before calling this function. 181 * 182 * Return: 0 on success, negative error code on failure. 183 */ 184 int wilco_ec_set_property(struct wilco_ec_device *ec, 185 struct wilco_ec_property_msg *prop_msg); 186 187 /** 188 * wilco_ec_get_byte_property() - Retrieve a byte-size property from the EC. 189 * @ec: Embedded Controller device. 190 * @property_id: Which property to retrieve. 191 * @val: The result value, will be filled by this function. 192 * 193 * Return: 0 on success, negative error code on failure. 194 */ 195 int wilco_ec_get_byte_property(struct wilco_ec_device *ec, u32 property_id, 196 u8 *val); 197 198 /** 199 * wilco_ec_get_byte_property() - Store a byte-size property on the EC. 200 * @ec: Embedded Controller device. 201 * @property_id: Which property to store. 202 * @val: Value to store. 203 * 204 * Return: 0 on success, negative error code on failure. 205 */ 206 int wilco_ec_set_byte_property(struct wilco_ec_device *ec, u32 property_id, 207 u8 val); 208 209 /** 210 * wilco_ec_add_sysfs() - Create sysfs entries 211 * @ec: Wilco EC device 212 * 213 * wilco_ec_remove_sysfs() needs to be called afterwards 214 * to perform the necessary cleanup. 215 * 216 * Return: 0 on success or negative error code on failure. 217 */ 218 int wilco_ec_add_sysfs(struct wilco_ec_device *ec); 219 void wilco_ec_remove_sysfs(struct wilco_ec_device *ec); 220 221 #endif /* WILCO_EC_H */ 222