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