xref: /openbmc/u-boot/include/cros_ec.h (revision 522e4fbb)
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  #include <asm/gpio.h>
17  
18  /* Our configuration information */
19  struct cros_ec_dev {
20  	struct udevice *dev;		/* Transport device */
21  	struct gpio_desc ec_int;	/* GPIO used as EC interrupt line */
22  	int protocol_version;           /* Protocol version to use */
23  	int optimise_flash_write;	/* Don't write erased flash blocks */
24  
25  	/*
26  	 * These two buffers will always be dword-aligned and include enough
27  	 * space for up to 7 word-alignment bytes also, so we can ensure that
28  	 * the body of the message is always dword-aligned (64-bit).
29  	 *
30  	 * We use this alignment to keep ARM and x86 happy. Probably word
31  	 * alignment would be OK, there might be a small performance advantage
32  	 * to using dword.
33  	 */
34  	uint8_t din[ALIGN(MSG_BYTES + sizeof(int64_t), sizeof(int64_t))]
35  		__aligned(sizeof(int64_t));
36  	uint8_t dout[ALIGN(MSG_BYTES + sizeof(int64_t), sizeof(int64_t))]
37  		__aligned(sizeof(int64_t));
38  };
39  
40  /*
41   * Hard-code the number of columns we happen to know we have right now.  It
42   * would be more correct to call cros_ec_info() at startup and determine the
43   * actual number of keyboard cols from there.
44   */
45  #define CROS_EC_KEYSCAN_COLS 13
46  
47  /* Information returned by a key scan */
48  struct mbkp_keyscan {
49  	uint8_t data[CROS_EC_KEYSCAN_COLS];
50  };
51  
52  /* Holds information about the Chrome EC */
53  struct fdt_cros_ec {
54  	struct fmap_entry flash;	/* Address and size of EC flash */
55  	/*
56  	 * Byte value of erased flash, or -1 if not known. It is normally
57  	 * 0xff but some flash devices use 0 (e.g. STM32Lxxx)
58  	 */
59  	int flash_erase_value;
60  	struct fmap_entry region[EC_FLASH_REGION_COUNT];
61  };
62  
63  /**
64   * Read the ID of the CROS-EC device
65   *
66   * The ID is a string identifying the CROS-EC device.
67   *
68   * @param dev		CROS-EC device
69   * @param id		Place to put the ID
70   * @param maxlen	Maximum length of the ID field
71   * @return 0 if ok, -1 on error
72   */
73  int cros_ec_read_id(struct cros_ec_dev *dev, char *id, int maxlen);
74  
75  /**
76   * Read a keyboard scan from the CROS-EC device
77   *
78   * Send a message requesting a keyboard scan and return the result
79   *
80   * @param dev		CROS-EC device
81   * @param scan		Place to put the scan results
82   * @return 0 if ok, -1 on error
83   */
84  int cros_ec_scan_keyboard(struct udevice *dev, struct mbkp_keyscan *scan);
85  
86  /**
87   * Read which image is currently running on the CROS-EC device.
88   *
89   * @param dev		CROS-EC device
90   * @param image		Destination for image identifier
91   * @return 0 if ok, <0 on error
92   */
93  int cros_ec_read_current_image(struct cros_ec_dev *dev,
94  		enum ec_current_image *image);
95  
96  /**
97   * Read the hash of the CROS-EC device firmware.
98   *
99   * @param dev		CROS-EC device
100   * @param hash		Destination for hash information
101   * @return 0 if ok, <0 on error
102   */
103  int cros_ec_read_hash(struct cros_ec_dev *dev,
104  		struct ec_response_vboot_hash *hash);
105  
106  /**
107   * Send a reboot command to the CROS-EC device.
108   *
109   * Note that some reboot commands (such as EC_REBOOT_COLD) also reboot the AP.
110   *
111   * @param dev		CROS-EC device
112   * @param cmd		Reboot command
113   * @param flags         Flags for reboot command (EC_REBOOT_FLAG_*)
114   * @return 0 if ok, <0 on error
115   */
116  int cros_ec_reboot(struct cros_ec_dev *dev, enum ec_reboot_cmd cmd,
117  		uint8_t flags);
118  
119  /**
120   * Check if the CROS-EC device has an interrupt pending.
121   *
122   * Read the status of the external interrupt connected to the CROS-EC device.
123   * If no external interrupt is configured, this always returns 1.
124   *
125   * @param dev		CROS-EC device
126   * @return 0 if no interrupt is pending
127   */
128  int cros_ec_interrupt_pending(struct udevice *dev);
129  
130  enum {
131  	CROS_EC_OK,
132  	CROS_EC_ERR = 1,
133  	CROS_EC_ERR_FDT_DECODE,
134  	CROS_EC_ERR_CHECK_VERSION,
135  	CROS_EC_ERR_READ_ID,
136  	CROS_EC_ERR_DEV_INIT,
137  };
138  
139  /**
140   * Initialise the Chromium OS EC driver
141   *
142   * @param blob		Device tree blob containing setup information
143   * @param cros_ecp        Returns pointer to the cros_ec device, or NULL if none
144   * @return 0 if we got an cros_ec device and all is well (or no cros_ec is
145   *	expected), -ve if we should have an cros_ec device but failed to find
146   *	one, or init failed (-CROS_EC_ERR_...).
147   */
148  int cros_ec_init(const void *blob, struct cros_ec_dev **cros_ecp);
149  
150  /**
151   * Read information about the keyboard matrix
152   *
153   * @param dev		CROS-EC device
154   * @param info		Place to put the info structure
155   */
156  int cros_ec_info(struct cros_ec_dev *dev,
157  		struct ec_response_mkbp_info *info);
158  
159  /**
160   * Read the host event flags
161   *
162   * @param dev		CROS-EC device
163   * @param events_ptr	Destination for event flags.  Not changed on error.
164   * @return 0 if ok, <0 on error
165   */
166  int cros_ec_get_host_events(struct cros_ec_dev *dev, uint32_t *events_ptr);
167  
168  /**
169   * Clear the specified host event flags
170   *
171   * @param dev		CROS-EC device
172   * @param events	Event flags to clear
173   * @return 0 if ok, <0 on error
174   */
175  int cros_ec_clear_host_events(struct cros_ec_dev *dev, uint32_t events);
176  
177  /**
178   * Get/set flash protection
179   *
180   * @param dev		CROS-EC device
181   * @param set_mask	Mask of flags to set; if 0, just retrieves existing
182   *                      protection state without changing it.
183   * @param set_flags	New flag values; only bits in set_mask are applied;
184   *                      ignored if set_mask=0.
185   * @param prot          Destination for updated protection state from EC.
186   * @return 0 if ok, <0 on error
187   */
188  int cros_ec_flash_protect(struct cros_ec_dev *dev,
189  		       uint32_t set_mask, uint32_t set_flags,
190  		       struct ec_response_flash_protect *resp);
191  
192  
193  /**
194   * Run internal tests on the cros_ec interface.
195   *
196   * @param dev		CROS-EC device
197   * @return 0 if ok, <0 if the test failed
198   */
199  int cros_ec_test(struct cros_ec_dev *dev);
200  
201  /**
202   * Update the EC RW copy.
203   *
204   * @param dev		CROS-EC device
205   * @param image		the content to write
206   * @param imafge_size	content length
207   * @return 0 if ok, <0 if the test failed
208   */
209  int cros_ec_flash_update_rw(struct cros_ec_dev *dev,
210  			 const uint8_t  *image, int image_size);
211  
212  /**
213   * Return a pointer to the board's CROS-EC device
214   *
215   * This should be implemented by board files.
216   *
217   * @return pointer to CROS-EC device, or NULL if none is available
218   */
219  struct cros_ec_dev *board_get_cros_ec_dev(void);
220  
221  struct dm_cros_ec_ops {
222  	int (*check_version)(struct udevice *dev);
223  	int (*command)(struct udevice *dev, uint8_t cmd, int cmd_version,
224  		       const uint8_t *dout, int dout_len,
225  		       uint8_t **dinp, int din_len);
226  	int (*packet)(struct udevice *dev, int out_bytes, int in_bytes);
227  };
228  
229  #define dm_cros_ec_get_ops(dev) \
230  		((struct dm_cros_ec_ops *)(dev)->driver->ops)
231  
232  int cros_ec_register(struct udevice *dev);
233  
234  /**
235   * Dump a block of data for a command.
236   *
237   * @param name	Name for data (e.g. 'in', 'out')
238   * @param cmd	Command number associated with data, or -1 for none
239   * @param data	Data block to dump
240   * @param len	Length of data block to dump
241   */
242  void cros_ec_dump_data(const char *name, int cmd, const uint8_t *data, int len);
243  
244  /**
245   * Calculate a simple 8-bit checksum of a data block
246   *
247   * @param data	Data block to checksum
248   * @param size	Size of data block in bytes
249   * @return checksum value (0 to 255)
250   */
251  int cros_ec_calc_checksum(const uint8_t *data, int size);
252  
253  /**
254   * Decode a flash region parameter
255   *
256   * @param argc	Number of params remaining
257   * @param argv	List of remaining parameters
258   * @return flash region (EC_FLASH_REGION_...) or -1 on error
259   */
260  int cros_ec_decode_region(int argc, char * const argv[]);
261  
262  int cros_ec_flash_erase(struct cros_ec_dev *dev, uint32_t offset,
263  		uint32_t size);
264  
265  /**
266   * Read data from the flash
267   *
268   * Read an arbitrary amount of data from the EC flash, by repeatedly reading
269   * small blocks.
270   *
271   * The offset starts at 0. You can obtain the region information from
272   * cros_ec_flash_offset() to find out where to read for a particular region.
273   *
274   * @param dev		CROS-EC device
275   * @param data		Pointer to data buffer to read into
276   * @param offset	Offset within flash to read from
277   * @param size		Number of bytes to read
278   * @return 0 if ok, -1 on error
279   */
280  int cros_ec_flash_read(struct cros_ec_dev *dev, uint8_t *data, uint32_t offset,
281  		    uint32_t size);
282  
283  /**
284   * Write data to the flash
285   *
286   * Write an arbitrary amount of data to the EC flash, by repeatedly writing
287   * small blocks.
288   *
289   * The offset starts at 0. You can obtain the region information from
290   * cros_ec_flash_offset() to find out where to write for a particular region.
291   *
292   * Attempting to write to the region where the EC is currently running from
293   * will result in an error.
294   *
295   * @param dev		CROS-EC device
296   * @param data		Pointer to data buffer to write
297   * @param offset	Offset within flash to write to.
298   * @param size		Number of bytes to write
299   * @return 0 if ok, -1 on error
300   */
301  int cros_ec_flash_write(struct cros_ec_dev *dev, const uint8_t *data,
302  		     uint32_t offset, uint32_t size);
303  
304  /**
305   * Obtain position and size of a flash region
306   *
307   * @param dev		CROS-EC device
308   * @param region	Flash region to query
309   * @param offset	Returns offset of flash region in EC flash
310   * @param size		Returns size of flash region
311   * @return 0 if ok, -1 on error
312   */
313  int cros_ec_flash_offset(struct cros_ec_dev *dev, enum ec_flash_region region,
314  		      uint32_t *offset, uint32_t *size);
315  
316  /**
317   * Read/write VbNvContext from/to a CROS-EC device.
318   *
319   * @param dev		CROS-EC device
320   * @param block		Buffer of VbNvContext to be read/write
321   * @return 0 if ok, -1 on error
322   */
323  int cros_ec_read_vbnvcontext(struct cros_ec_dev *dev, uint8_t *block);
324  int cros_ec_write_vbnvcontext(struct cros_ec_dev *dev, const uint8_t *block);
325  
326  /**
327   * Read the version information for the EC images
328   *
329   * @param dev		CROS-EC device
330   * @param versionp	This is set to point to the version information
331   * @return 0 if ok, -1 on error
332   */
333  int cros_ec_read_version(struct cros_ec_dev *dev,
334  		       struct ec_response_get_version **versionp);
335  
336  /**
337   * Read the build information for the EC
338   *
339   * @param dev		CROS-EC device
340   * @param versionp	This is set to point to the build string
341   * @return 0 if ok, -1 on error
342   */
343  int cros_ec_read_build_info(struct cros_ec_dev *dev, char **strp);
344  
345  /**
346   * Switch on/off a LDO / FET.
347   *
348   * @param dev		CROS-EC device
349   * @param index		index of the LDO/FET to switch
350   * @param state		new state of the LDO/FET : EC_LDO_STATE_ON|OFF
351   * @return 0 if ok, -1 on error
352   */
353  int cros_ec_set_ldo(struct udevice *dev, uint8_t index, uint8_t state);
354  
355  /**
356   * Read back a LDO / FET current state.
357   *
358   * @param dev		CROS-EC device
359   * @param index		index of the LDO/FET to switch
360   * @param state		current state of the LDO/FET : EC_LDO_STATE_ON|OFF
361   * @return 0 if ok, -1 on error
362   */
363  int cros_ec_get_ldo(struct udevice *dev, uint8_t index, uint8_t *state);
364  
365  /**
366   * Get access to the error reported when cros_ec_board_init() was called
367   *
368   * This permits delayed reporting of the EC error if it failed during
369   * early init.
370   *
371   * @return error (0 if there was no error, -ve if there was an error)
372   */
373  int cros_ec_get_error(void);
374  
375  /**
376   * Returns information from the FDT about the Chrome EC flash
377   *
378   * @param blob		FDT blob to use
379   * @param node		Node offset to read from
380   * @param config	Structure to use to return information
381   */
382  int cros_ec_decode_ec_flash(const void *blob, int node,
383  			    struct fdt_cros_ec *config);
384  
385  /**
386   * Check the current keyboard state, in case recovery mode is requested.
387   * This function is for sandbox only.
388   *
389   * @param ec		CROS-EC device
390   */
391  void cros_ec_check_keyboard(struct cros_ec_dev *dev);
392  
393  struct i2c_msg;
394  /*
395   * Tunnel an I2C transfer to the EC
396   *
397   * @param dev		CROS-EC device
398   * @param msg		List of messages to transfer
399   * @param nmsgs		Number of messages to transfer
400   */
401  int cros_ec_i2c_tunnel(struct udevice *dev, struct i2c_msg *msg, int nmsgs);
402  
403  #endif
404