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