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