]>
Commit | Line | Data |
---|---|---|
88364387 HT |
1 | /* |
2 | * Chromium OS cros_ec driver | |
3 | * | |
4 | * Copyright (c) 2012 The Chromium OS Authors. | |
88364387 | 5 | * |
1a459660 | 6 | * SPDX-License-Identifier: GPL-2.0+ |
88364387 HT |
7 | */ |
8 | ||
9 | #ifndef _CROS_EC_H | |
10 | #define _CROS_EC_H | |
11 | ||
12 | #include <linux/compiler.h> | |
13 | #include <ec_commands.h> | |
14 | #include <fdtdec.h> | |
15 | #include <cros_ec_message.h> | |
16 | ||
17 | /* Which interface is the device on? */ | |
18 | enum cros_ec_interface_t { | |
19 | CROS_EC_IF_NONE, | |
20 | CROS_EC_IF_SPI, | |
21 | CROS_EC_IF_I2C, | |
22 | CROS_EC_IF_LPC, /* Intel Low Pin Count interface */ | |
23 | }; | |
24 | ||
25 | /* Our configuration information */ | |
26 | struct cros_ec_dev { | |
27 | enum cros_ec_interface_t interface; | |
28 | struct spi_slave *spi; /* Our SPI slave, if using SPI */ | |
29 | int node; /* Our node */ | |
30 | int parent_node; /* Our parent node (interface) */ | |
31 | unsigned int cs; /* Our chip select */ | |
32 | unsigned int addr; /* Device address (for I2C) */ | |
33 | unsigned int bus_num; /* Bus number (for I2C) */ | |
34 | unsigned int max_frequency; /* Maximum interface frequency */ | |
35 | struct fdt_gpio_state ec_int; /* GPIO used as EC interrupt line */ | |
36 | int cmd_version_is_supported; /* Device supports command versions */ | |
37 | int optimise_flash_write; /* Don't write erased flash blocks */ | |
38 | ||
39 | /* | |
40 | * These two buffers will always be dword-aligned and include enough | |
41 | * space for up to 7 word-alignment bytes also, so we can ensure that | |
42 | * the body of the message is always dword-aligned (64-bit). | |
43 | * | |
44 | * We use this alignment to keep ARM and x86 happy. Probably word | |
45 | * alignment would be OK, there might be a small performance advantage | |
46 | * to using dword. | |
47 | */ | |
48 | uint8_t din[ALIGN(MSG_BYTES + sizeof(int64_t), sizeof(int64_t))] | |
49 | __aligned(sizeof(int64_t)); | |
50 | uint8_t dout[ALIGN(MSG_BYTES + sizeof(int64_t), sizeof(int64_t))] | |
51 | __aligned(sizeof(int64_t)); | |
52 | }; | |
53 | ||
54 | /* | |
55 | * Hard-code the number of columns we happen to know we have right now. It | |
56 | * would be more correct to call cros_ec_info() at startup and determine the | |
57 | * actual number of keyboard cols from there. | |
58 | */ | |
59 | #define CROS_EC_KEYSCAN_COLS 13 | |
60 | ||
61 | /* Information returned by a key scan */ | |
62 | struct mbkp_keyscan { | |
63 | uint8_t data[CROS_EC_KEYSCAN_COLS]; | |
64 | }; | |
65 | ||
66 | /** | |
67 | * Read the ID of the CROS-EC device | |
68 | * | |
69 | * The ID is a string identifying the CROS-EC device. | |
70 | * | |
71 | * @param dev CROS-EC device | |
72 | * @param id Place to put the ID | |
73 | * @param maxlen Maximum length of the ID field | |
74 | * @return 0 if ok, -1 on error | |
75 | */ | |
76 | int cros_ec_read_id(struct cros_ec_dev *dev, char *id, int maxlen); | |
77 | ||
78 | /** | |
79 | * Read a keyboard scan from the CROS-EC device | |
80 | * | |
81 | * Send a message requesting a keyboard scan and return the result | |
82 | * | |
83 | * @param dev CROS-EC device | |
84 | * @param scan Place to put the scan results | |
85 | * @return 0 if ok, -1 on error | |
86 | */ | |
87 | int cros_ec_scan_keyboard(struct cros_ec_dev *dev, struct mbkp_keyscan *scan); | |
88 | ||
89 | /** | |
90 | * Read which image is currently running on the CROS-EC device. | |
91 | * | |
92 | * @param dev CROS-EC device | |
93 | * @param image Destination for image identifier | |
94 | * @return 0 if ok, <0 on error | |
95 | */ | |
96 | int cros_ec_read_current_image(struct cros_ec_dev *dev, | |
97 | enum ec_current_image *image); | |
98 | ||
99 | /** | |
100 | * Read the hash of the CROS-EC device firmware. | |
101 | * | |
102 | * @param dev CROS-EC device | |
103 | * @param hash Destination for hash information | |
104 | * @return 0 if ok, <0 on error | |
105 | */ | |
106 | int cros_ec_read_hash(struct cros_ec_dev *dev, | |
107 | struct ec_response_vboot_hash *hash); | |
108 | ||
109 | /** | |
110 | * Send a reboot command to the CROS-EC device. | |
111 | * | |
112 | * Note that some reboot commands (such as EC_REBOOT_COLD) also reboot the AP. | |
113 | * | |
114 | * @param dev CROS-EC device | |
115 | * @param cmd Reboot command | |
116 | * @param flags Flags for reboot command (EC_REBOOT_FLAG_*) | |
117 | * @return 0 if ok, <0 on error | |
118 | */ | |
119 | int cros_ec_reboot(struct cros_ec_dev *dev, enum ec_reboot_cmd cmd, | |
120 | uint8_t flags); | |
121 | ||
122 | /** | |
123 | * Check if the CROS-EC device has an interrupt pending. | |
124 | * | |
125 | * Read the status of the external interrupt connected to the CROS-EC device. | |
126 | * If no external interrupt is configured, this always returns 1. | |
127 | * | |
128 | * @param dev CROS-EC device | |
129 | * @return 0 if no interrupt is pending | |
130 | */ | |
131 | int cros_ec_interrupt_pending(struct cros_ec_dev *dev); | |
132 | ||
133 | enum { | |
134 | CROS_EC_OK, | |
135 | CROS_EC_ERR = 1, | |
136 | CROS_EC_ERR_FDT_DECODE, | |
137 | CROS_EC_ERR_CHECK_VERSION, | |
138 | CROS_EC_ERR_READ_ID, | |
139 | CROS_EC_ERR_DEV_INIT, | |
140 | }; | |
141 | ||
142 | /** | |
143 | * Set up the Chromium OS matrix keyboard protocol | |
144 | * | |
145 | * @param blob Device tree blob containing setup information | |
146 | * @param cros_ecp Returns pointer to the cros_ec device, or NULL if none | |
147 | * @return 0 if we got an cros_ec device and all is well (or no cros_ec is | |
148 | * expected), -ve if we should have an cros_ec device but failed to find | |
149 | * one, or init failed (-CROS_EC_ERR_...). | |
150 | */ | |
151 | int cros_ec_init(const void *blob, struct cros_ec_dev **cros_ecp); | |
152 | ||
153 | /** | |
154 | * Read information about the keyboard matrix | |
155 | * | |
156 | * @param dev CROS-EC device | |
157 | * @param info Place to put the info structure | |
158 | */ | |
159 | int cros_ec_info(struct cros_ec_dev *dev, | |
160 | struct ec_response_cros_ec_info *info); | |
161 | ||
162 | /** | |
163 | * Read the host event flags | |
164 | * | |
165 | * @param dev CROS-EC device | |
166 | * @param events_ptr Destination for event flags. Not changed on error. | |
167 | * @return 0 if ok, <0 on error | |
168 | */ | |
169 | int cros_ec_get_host_events(struct cros_ec_dev *dev, uint32_t *events_ptr); | |
170 | ||
171 | /** | |
172 | * Clear the specified host event flags | |
173 | * | |
174 | * @param dev CROS-EC device | |
175 | * @param events Event flags to clear | |
176 | * @return 0 if ok, <0 on error | |
177 | */ | |
178 | int cros_ec_clear_host_events(struct cros_ec_dev *dev, uint32_t events); | |
179 | ||
180 | /** | |
181 | * Get/set flash protection | |
182 | * | |
183 | * @param dev CROS-EC device | |
184 | * @param set_mask Mask of flags to set; if 0, just retrieves existing | |
185 | * protection state without changing it. | |
186 | * @param set_flags New flag values; only bits in set_mask are applied; | |
187 | * ignored if set_mask=0. | |
188 | * @param prot Destination for updated protection state from EC. | |
189 | * @return 0 if ok, <0 on error | |
190 | */ | |
191 | int cros_ec_flash_protect(struct cros_ec_dev *dev, | |
192 | uint32_t set_mask, uint32_t set_flags, | |
193 | struct ec_response_flash_protect *resp); | |
194 | ||
195 | ||
196 | /** | |
197 | * Run internal tests on the cros_ec interface. | |
198 | * | |
199 | * @param dev CROS-EC device | |
200 | * @return 0 if ok, <0 if the test failed | |
201 | */ | |
202 | int cros_ec_test(struct cros_ec_dev *dev); | |
203 | ||
204 | /** | |
205 | * Update the EC RW copy. | |
206 | * | |
207 | * @param dev CROS-EC device | |
208 | * @param image the content to write | |
209 | * @param imafge_size content length | |
210 | * @return 0 if ok, <0 if the test failed | |
211 | */ | |
212 | int cros_ec_flash_update_rw(struct cros_ec_dev *dev, | |
213 | const uint8_t *image, int image_size); | |
214 | ||
215 | /** | |
216 | * Return a pointer to the board's CROS-EC device | |
217 | * | |
218 | * This should be implemented by board files. | |
219 | * | |
220 | * @return pointer to CROS-EC device, or NULL if none is available | |
221 | */ | |
222 | struct cros_ec_dev *board_get_cros_ec_dev(void); | |
223 | ||
224 | ||
225 | /* Internal interfaces */ | |
226 | int cros_ec_i2c_init(struct cros_ec_dev *dev, const void *blob); | |
227 | int cros_ec_spi_init(struct cros_ec_dev *dev, const void *blob); | |
228 | int cros_ec_lpc_init(struct cros_ec_dev *dev, const void *blob); | |
229 | ||
230 | /** | |
231 | * Read information from the fdt for the i2c cros_ec interface | |
232 | * | |
233 | * @param dev CROS-EC device | |
234 | * @param blob Device tree blob | |
235 | * @return 0 if ok, -1 if we failed to read all required information | |
236 | */ | |
237 | int cros_ec_i2c_decode_fdt(struct cros_ec_dev *dev, const void *blob); | |
238 | ||
239 | /** | |
240 | * Read information from the fdt for the spi cros_ec interface | |
241 | * | |
242 | * @param dev CROS-EC device | |
243 | * @param blob Device tree blob | |
244 | * @return 0 if ok, -1 if we failed to read all required information | |
245 | */ | |
246 | int cros_ec_spi_decode_fdt(struct cros_ec_dev *dev, const void *blob); | |
247 | ||
248 | /** | |
249 | * Check whether the LPC interface supports new-style commands. | |
250 | * | |
251 | * LPC has its own way of doing this, which involves checking LPC values | |
252 | * visible to the host. Do this, and update dev->cmd_version_is_supported | |
253 | * accordingly. | |
254 | * | |
255 | * @param dev CROS-EC device to check | |
256 | */ | |
257 | int cros_ec_lpc_check_version(struct cros_ec_dev *dev); | |
258 | ||
259 | /** | |
260 | * Send a command to an I2C CROS-EC device and return the reply. | |
261 | * | |
262 | * This rather complicated function deals with sending both old-style and | |
263 | * new-style commands. The old ones have just a command byte and arguments. | |
264 | * The new ones have version, command, arg-len, [args], chksum so are 3 bytes | |
265 | * longer. | |
266 | * | |
267 | * The device's internal input/output buffers are used. | |
268 | * | |
269 | * @param dev CROS-EC device | |
270 | * @param cmd Command to send (EC_CMD_...) | |
271 | * @param cmd_version Version of command to send (EC_VER_...) | |
272 | * @param dout Output data (may be NULL If dout_len=0) | |
273 | * @param dout_len Size of output data in bytes | |
274 | * @param dinp Returns pointer to response data | |
275 | * @param din_len Maximum size of response in bytes | |
276 | * @return number of bytes in response, or -1 on error | |
277 | */ | |
278 | int cros_ec_i2c_command(struct cros_ec_dev *dev, uint8_t cmd, int cmd_version, | |
279 | const uint8_t *dout, int dout_len, | |
280 | uint8_t **dinp, int din_len); | |
281 | ||
282 | /** | |
283 | * Send a command to a LPC CROS-EC device and return the reply. | |
284 | * | |
285 | * The device's internal input/output buffers are used. | |
286 | * | |
287 | * @param dev CROS-EC device | |
288 | * @param cmd Command to send (EC_CMD_...) | |
289 | * @param cmd_version Version of command to send (EC_VER_...) | |
290 | * @param dout Output data (may be NULL If dout_len=0) | |
291 | * @param dout_len Size of output data in bytes | |
292 | * @param dinp Returns pointer to response data | |
293 | * @param din_len Maximum size of response in bytes | |
294 | * @return number of bytes in response, or -1 on error | |
295 | */ | |
296 | int cros_ec_lpc_command(struct cros_ec_dev *dev, uint8_t cmd, int cmd_version, | |
297 | const uint8_t *dout, int dout_len, | |
298 | uint8_t **dinp, int din_len); | |
299 | ||
300 | int cros_ec_spi_command(struct cros_ec_dev *dev, uint8_t cmd, int cmd_version, | |
301 | const uint8_t *dout, int dout_len, | |
302 | uint8_t **dinp, int din_len); | |
303 | ||
304 | /** | |
305 | * Dump a block of data for a command. | |
306 | * | |
307 | * @param name Name for data (e.g. 'in', 'out') | |
308 | * @param cmd Command number associated with data, or -1 for none | |
309 | * @param data Data block to dump | |
310 | * @param len Length of data block to dump | |
311 | */ | |
312 | void cros_ec_dump_data(const char *name, int cmd, const uint8_t *data, int len); | |
313 | ||
314 | /** | |
315 | * Calculate a simple 8-bit checksum of a data block | |
316 | * | |
317 | * @param data Data block to checksum | |
318 | * @param size Size of data block in bytes | |
319 | * @return checksum value (0 to 255) | |
320 | */ | |
321 | int cros_ec_calc_checksum(const uint8_t *data, int size); | |
322 | ||
323 | /** | |
324 | * Decode a flash region parameter | |
325 | * | |
326 | * @param argc Number of params remaining | |
327 | * @param argv List of remaining parameters | |
328 | * @return flash region (EC_FLASH_REGION_...) or -1 on error | |
329 | */ | |
330 | int cros_ec_decode_region(int argc, char * const argv[]); | |
331 | ||
332 | int cros_ec_flash_erase(struct cros_ec_dev *dev, uint32_t offset, | |
333 | uint32_t size); | |
334 | ||
335 | /** | |
336 | * Read data from the flash | |
337 | * | |
338 | * Read an arbitrary amount of data from the EC flash, by repeatedly reading | |
339 | * small blocks. | |
340 | * | |
341 | * The offset starts at 0. You can obtain the region information from | |
342 | * cros_ec_flash_offset() to find out where to read for a particular region. | |
343 | * | |
344 | * @param dev CROS-EC device | |
345 | * @param data Pointer to data buffer to read into | |
346 | * @param offset Offset within flash to read from | |
347 | * @param size Number of bytes to read | |
348 | * @return 0 if ok, -1 on error | |
349 | */ | |
350 | int cros_ec_flash_read(struct cros_ec_dev *dev, uint8_t *data, uint32_t offset, | |
351 | uint32_t size); | |
352 | ||
353 | /** | |
354 | * Write data to the flash | |
355 | * | |
356 | * Write an arbitrary amount of data to the EC flash, by repeatedly writing | |
357 | * small blocks. | |
358 | * | |
359 | * The offset starts at 0. You can obtain the region information from | |
360 | * cros_ec_flash_offset() to find out where to write for a particular region. | |
361 | * | |
362 | * Attempting to write to the region where the EC is currently running from | |
363 | * will result in an error. | |
364 | * | |
365 | * @param dev CROS-EC device | |
366 | * @param data Pointer to data buffer to write | |
367 | * @param offset Offset within flash to write to. | |
368 | * @param size Number of bytes to write | |
369 | * @return 0 if ok, -1 on error | |
370 | */ | |
371 | int cros_ec_flash_write(struct cros_ec_dev *dev, const uint8_t *data, | |
372 | uint32_t offset, uint32_t size); | |
373 | ||
374 | /** | |
375 | * Obtain position and size of a flash region | |
376 | * | |
377 | * @param dev CROS-EC device | |
378 | * @param region Flash region to query | |
379 | * @param offset Returns offset of flash region in EC flash | |
380 | * @param size Returns size of flash region | |
381 | * @return 0 if ok, -1 on error | |
382 | */ | |
383 | int cros_ec_flash_offset(struct cros_ec_dev *dev, enum ec_flash_region region, | |
384 | uint32_t *offset, uint32_t *size); | |
385 | ||
386 | /** | |
387 | * Read/write VbNvContext from/to a CROS-EC device. | |
388 | * | |
389 | * @param dev CROS-EC device | |
390 | * @param block Buffer of VbNvContext to be read/write | |
391 | * @return 0 if ok, -1 on error | |
392 | */ | |
393 | int cros_ec_read_vbnvcontext(struct cros_ec_dev *dev, uint8_t *block); | |
394 | int cros_ec_write_vbnvcontext(struct cros_ec_dev *dev, const uint8_t *block); | |
395 | ||
396 | /** | |
397 | * Read the version information for the EC images | |
398 | * | |
399 | * @param dev CROS-EC device | |
400 | * @param versionp This is set to point to the version information | |
401 | * @return 0 if ok, -1 on error | |
402 | */ | |
403 | int cros_ec_read_version(struct cros_ec_dev *dev, | |
404 | struct ec_response_get_version **versionp); | |
405 | ||
406 | /** | |
407 | * Read the build information for the EC | |
408 | * | |
409 | * @param dev CROS-EC device | |
410 | * @param versionp This is set to point to the build string | |
411 | * @return 0 if ok, -1 on error | |
412 | */ | |
413 | int cros_ec_read_build_info(struct cros_ec_dev *dev, char **strp); | |
414 | ||
415 | /** | |
416 | * Switch on/off a LDO / FET. | |
417 | * | |
418 | * @param dev CROS-EC device | |
419 | * @param index index of the LDO/FET to switch | |
420 | * @param state new state of the LDO/FET : EC_LDO_STATE_ON|OFF | |
421 | * @return 0 if ok, -1 on error | |
422 | */ | |
423 | int cros_ec_set_ldo(struct cros_ec_dev *dev, uint8_t index, uint8_t state); | |
424 | ||
425 | /** | |
426 | * Read back a LDO / FET current state. | |
427 | * | |
428 | * @param dev CROS-EC device | |
429 | * @param index index of the LDO/FET to switch | |
430 | * @param state current state of the LDO/FET : EC_LDO_STATE_ON|OFF | |
431 | * @return 0 if ok, -1 on error | |
432 | */ | |
433 | int cros_ec_get_ldo(struct cros_ec_dev *dev, uint8_t index, uint8_t *state); | |
434 | #endif |