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