blob: 1e4d8db96b7889e32586c665e001513523357b48 [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>
16
17/* Which interface is the device on? */
18enum 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 */
Simon Glassdf93d902014-02-27 13:26:12 -070023 CROS_EC_IF_SANDBOX,
Hung-ying Tyan88364382013-05-15 18:27:28 +080024};
25
26/* Our configuration information */
27struct 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 */
Randall Spanglere8c12662014-02-27 13:26:08 -070037 int protocol_version; /* Protocol version to use */
Hung-ying Tyan88364382013-05-15 18:27:28 +080038 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 */
63struct mbkp_keyscan {
64 uint8_t data[CROS_EC_KEYSCAN_COLS];
65};
66
Simon Glassd7f25f32014-02-27 13:26:03 -070067/* Holds information about the Chrome EC */
68struct 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
Hung-ying Tyan88364382013-05-15 18:27:28 +080078/**
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 */
88int 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 */
99int 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 */
108int 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 */
118int 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 */
131int 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 */
143int cros_ec_interrupt_pending(struct cros_ec_dev *dev);
144
145enum {
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/**
Simon Glass836bb6e2014-02-27 13:26:07 -0700155 * Initialise the Chromium OS EC driver
Hung-ying Tyan88364382013-05-15 18:27:28 +0800156 *
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 */
163int 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 */
171int cros_ec_info(struct cros_ec_dev *dev,
Simon Glass836bb6e2014-02-27 13:26:07 -0700172 struct ec_response_mkbp_info *info);
Hung-ying Tyan88364382013-05-15 18:27:28 +0800173
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 */
181int 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 */
190int 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 */
203int 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 */
214int 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 */
224int 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 */
234struct cros_ec_dev *board_get_cros_ec_dev(void);
235
236
237/* Internal interfaces */
238int cros_ec_i2c_init(struct cros_ec_dev *dev, const void *blob);
239int cros_ec_spi_init(struct cros_ec_dev *dev, const void *blob);
240int cros_ec_lpc_init(struct cros_ec_dev *dev, const void *blob);
Simon Glassdf93d902014-02-27 13:26:12 -0700241int cros_ec_sandbox_init(struct cros_ec_dev *dev, const void *blob);
Hung-ying Tyan88364382013-05-15 18:27:28 +0800242
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 */
250int 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 */
259int cros_ec_spi_decode_fdt(struct cros_ec_dev *dev, const void *blob);
260
261/**
Simon Glassdf93d902014-02-27 13:26:12 -0700262 * 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 */
268int cros_ec_sandbox_decode_fdt(struct cros_ec_dev *dev, const void *blob);
269
270/**
Hung-ying Tyan88364382013-05-15 18:27:28 +0800271 * Check whether the LPC interface supports new-style commands.
272 *
273 * LPC has its own way of doing this, which involves checking LPC values
Randall Spanglere8c12662014-02-27 13:26:08 -0700274 * visible to the host. Do this, and update dev->protocol_version accordingly.
Hung-ying Tyan88364382013-05-15 18:27:28 +0800275 *
276 * @param dev CROS-EC device to check
277 */
278int 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 */
299int 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 */
317int 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
321int 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
325/**
Randall Spanglera6070282014-02-27 13:26:10 -0700326 * 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 */
336int cros_ec_spi_packet(struct cros_ec_dev *dev, int out_bytes, int in_bytes);
Simon Glassdf93d902014-02-27 13:26:12 -0700337int cros_ec_sandbox_packet(struct cros_ec_dev *dev, int out_bytes,
338 int in_bytes);
Randall Spanglera6070282014-02-27 13:26:10 -0700339
340/**
Hung-ying Tyan88364382013-05-15 18:27:28 +0800341 * 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 */
348void 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 */
357int 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 */
366int cros_ec_decode_region(int argc, char * const argv[]);
367
368int 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 */
386int 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 */
407int 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 */
419int 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 */
429int cros_ec_read_vbnvcontext(struct cros_ec_dev *dev, uint8_t *block);
430int 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 */
439int 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 */
449int 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 */
459int 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 */
469int cros_ec_get_ldo(struct cros_ec_dev *dev, uint8_t index, uint8_t *state);
Vadim Bendebury41364f02014-02-27 13:26:02 -0700470
471/**
472 * Initialize the Chrome OS EC at board initialization time.
473 *
474 * @return 0 if ok, -ve on error
475 */
476int 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 */
486int cros_ec_get_error(void);
487
Simon Glassd7f25f32014-02-27 13:26:03 -0700488/**
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 */
494int cros_ec_decode_ec_flash(const void *blob, struct fdt_cros_ec *config);
495
Simon Glassdf93d902014-02-27 13:26:12 -0700496/**
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 */
502void cros_ec_check_keyboard(struct cros_ec_dev *dev);
503
Simon Glassb2a668b2014-02-27 13:26:14 -0700504/*
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 */
515int cros_ec_i2c_xfer(struct cros_ec_dev *dev, uchar chip, uint addr,
516 int alen, uchar *buffer, int len, int is_read);
517
Hung-ying Tyan88364382013-05-15 18:27:28 +0800518#endif