blob: 335d5b4e639dfaae75a842a7724981e31d635efe [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.
5 * See file CREDITS for list of people who contributed to this
6 * project.
7 *
8 * This program is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU General Public License as
10 * published by the Free Software Foundation; either version 2 of
11 * the License, or (at your option) any later version.
12 *
13 * This program is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 * GNU General Public License for more details.
17 *
18 * You should have received a copy of the GNU General Public License
19 * along with this program; if not, write to the Free Software
20 * Foundation, Inc., 59 Temple Place, Suite 330, Boston,
21 * MA 02111-1307 USA
22 */
23
24#ifndef _CROS_EC_H
25#define _CROS_EC_H
26
27#include <linux/compiler.h>
28#include <ec_commands.h>
29#include <fdtdec.h>
30#include <cros_ec_message.h>
31
32/* Which interface is the device on? */
33enum cros_ec_interface_t {
34 CROS_EC_IF_NONE,
35 CROS_EC_IF_SPI,
36 CROS_EC_IF_I2C,
37 CROS_EC_IF_LPC, /* Intel Low Pin Count interface */
38};
39
40/* Our configuration information */
41struct cros_ec_dev {
42 enum cros_ec_interface_t interface;
43 struct spi_slave *spi; /* Our SPI slave, if using SPI */
44 int node; /* Our node */
45 int parent_node; /* Our parent node (interface) */
46 unsigned int cs; /* Our chip select */
47 unsigned int addr; /* Device address (for I2C) */
48 unsigned int bus_num; /* Bus number (for I2C) */
49 unsigned int max_frequency; /* Maximum interface frequency */
50 struct fdt_gpio_state ec_int; /* GPIO used as EC interrupt line */
51 int cmd_version_is_supported; /* Device supports command versions */
52 int optimise_flash_write; /* Don't write erased flash blocks */
53
54 /*
55 * These two buffers will always be dword-aligned and include enough
56 * space for up to 7 word-alignment bytes also, so we can ensure that
57 * the body of the message is always dword-aligned (64-bit).
58 *
59 * We use this alignment to keep ARM and x86 happy. Probably word
60 * alignment would be OK, there might be a small performance advantage
61 * to using dword.
62 */
63 uint8_t din[ALIGN(MSG_BYTES + sizeof(int64_t), sizeof(int64_t))]
64 __aligned(sizeof(int64_t));
65 uint8_t dout[ALIGN(MSG_BYTES + sizeof(int64_t), sizeof(int64_t))]
66 __aligned(sizeof(int64_t));
67};
68
69/*
70 * Hard-code the number of columns we happen to know we have right now. It
71 * would be more correct to call cros_ec_info() at startup and determine the
72 * actual number of keyboard cols from there.
73 */
74#define CROS_EC_KEYSCAN_COLS 13
75
76/* Information returned by a key scan */
77struct mbkp_keyscan {
78 uint8_t data[CROS_EC_KEYSCAN_COLS];
79};
80
81/**
82 * Read the ID of the CROS-EC device
83 *
84 * The ID is a string identifying the CROS-EC device.
85 *
86 * @param dev CROS-EC device
87 * @param id Place to put the ID
88 * @param maxlen Maximum length of the ID field
89 * @return 0 if ok, -1 on error
90 */
91int cros_ec_read_id(struct cros_ec_dev *dev, char *id, int maxlen);
92
93/**
94 * Read a keyboard scan from the CROS-EC device
95 *
96 * Send a message requesting a keyboard scan and return the result
97 *
98 * @param dev CROS-EC device
99 * @param scan Place to put the scan results
100 * @return 0 if ok, -1 on error
101 */
102int cros_ec_scan_keyboard(struct cros_ec_dev *dev, struct mbkp_keyscan *scan);
103
104/**
105 * Read which image is currently running on the CROS-EC device.
106 *
107 * @param dev CROS-EC device
108 * @param image Destination for image identifier
109 * @return 0 if ok, <0 on error
110 */
111int cros_ec_read_current_image(struct cros_ec_dev *dev,
112 enum ec_current_image *image);
113
114/**
115 * Read the hash of the CROS-EC device firmware.
116 *
117 * @param dev CROS-EC device
118 * @param hash Destination for hash information
119 * @return 0 if ok, <0 on error
120 */
121int cros_ec_read_hash(struct cros_ec_dev *dev,
122 struct ec_response_vboot_hash *hash);
123
124/**
125 * Send a reboot command to the CROS-EC device.
126 *
127 * Note that some reboot commands (such as EC_REBOOT_COLD) also reboot the AP.
128 *
129 * @param dev CROS-EC device
130 * @param cmd Reboot command
131 * @param flags Flags for reboot command (EC_REBOOT_FLAG_*)
132 * @return 0 if ok, <0 on error
133 */
134int cros_ec_reboot(struct cros_ec_dev *dev, enum ec_reboot_cmd cmd,
135 uint8_t flags);
136
137/**
138 * Check if the CROS-EC device has an interrupt pending.
139 *
140 * Read the status of the external interrupt connected to the CROS-EC device.
141 * If no external interrupt is configured, this always returns 1.
142 *
143 * @param dev CROS-EC device
144 * @return 0 if no interrupt is pending
145 */
146int cros_ec_interrupt_pending(struct cros_ec_dev *dev);
147
148enum {
149 CROS_EC_OK,
150 CROS_EC_ERR = 1,
151 CROS_EC_ERR_FDT_DECODE,
152 CROS_EC_ERR_CHECK_VERSION,
153 CROS_EC_ERR_READ_ID,
154 CROS_EC_ERR_DEV_INIT,
155};
156
157/**
158 * Set up the Chromium OS matrix keyboard protocol
159 *
160 * @param blob Device tree blob containing setup information
161 * @param cros_ecp Returns pointer to the cros_ec device, or NULL if none
162 * @return 0 if we got an cros_ec device and all is well (or no cros_ec is
163 * expected), -ve if we should have an cros_ec device but failed to find
164 * one, or init failed (-CROS_EC_ERR_...).
165 */
166int cros_ec_init(const void *blob, struct cros_ec_dev **cros_ecp);
167
168/**
169 * Read information about the keyboard matrix
170 *
171 * @param dev CROS-EC device
172 * @param info Place to put the info structure
173 */
174int cros_ec_info(struct cros_ec_dev *dev,
175 struct ec_response_cros_ec_info *info);
176
177/**
178 * Read the host event flags
179 *
180 * @param dev CROS-EC device
181 * @param events_ptr Destination for event flags. Not changed on error.
182 * @return 0 if ok, <0 on error
183 */
184int cros_ec_get_host_events(struct cros_ec_dev *dev, uint32_t *events_ptr);
185
186/**
187 * Clear the specified host event flags
188 *
189 * @param dev CROS-EC device
190 * @param events Event flags to clear
191 * @return 0 if ok, <0 on error
192 */
193int cros_ec_clear_host_events(struct cros_ec_dev *dev, uint32_t events);
194
195/**
196 * Get/set flash protection
197 *
198 * @param dev CROS-EC device
199 * @param set_mask Mask of flags to set; if 0, just retrieves existing
200 * protection state without changing it.
201 * @param set_flags New flag values; only bits in set_mask are applied;
202 * ignored if set_mask=0.
203 * @param prot Destination for updated protection state from EC.
204 * @return 0 if ok, <0 on error
205 */
206int cros_ec_flash_protect(struct cros_ec_dev *dev,
207 uint32_t set_mask, uint32_t set_flags,
208 struct ec_response_flash_protect *resp);
209
210
211/**
212 * Run internal tests on the cros_ec interface.
213 *
214 * @param dev CROS-EC device
215 * @return 0 if ok, <0 if the test failed
216 */
217int cros_ec_test(struct cros_ec_dev *dev);
218
219/**
220 * Update the EC RW copy.
221 *
222 * @param dev CROS-EC device
223 * @param image the content to write
224 * @param imafge_size content length
225 * @return 0 if ok, <0 if the test failed
226 */
227int cros_ec_flash_update_rw(struct cros_ec_dev *dev,
228 const uint8_t *image, int image_size);
229
230/**
231 * Return a pointer to the board's CROS-EC device
232 *
233 * This should be implemented by board files.
234 *
235 * @return pointer to CROS-EC device, or NULL if none is available
236 */
237struct cros_ec_dev *board_get_cros_ec_dev(void);
238
239
240/* Internal interfaces */
241int cros_ec_i2c_init(struct cros_ec_dev *dev, const void *blob);
242int cros_ec_spi_init(struct cros_ec_dev *dev, const void *blob);
243int cros_ec_lpc_init(struct cros_ec_dev *dev, const void *blob);
244
245/**
246 * Read information from the fdt for the i2c cros_ec interface
247 *
248 * @param dev CROS-EC device
249 * @param blob Device tree blob
250 * @return 0 if ok, -1 if we failed to read all required information
251 */
252int cros_ec_i2c_decode_fdt(struct cros_ec_dev *dev, const void *blob);
253
254/**
255 * Read information from the fdt for the spi cros_ec interface
256 *
257 * @param dev CROS-EC device
258 * @param blob Device tree blob
259 * @return 0 if ok, -1 if we failed to read all required information
260 */
261int cros_ec_spi_decode_fdt(struct cros_ec_dev *dev, const void *blob);
262
263/**
264 * Check whether the LPC interface supports new-style commands.
265 *
266 * LPC has its own way of doing this, which involves checking LPC values
267 * visible to the host. Do this, and update dev->cmd_version_is_supported
268 * accordingly.
269 *
270 * @param dev CROS-EC device to check
271 */
272int cros_ec_lpc_check_version(struct cros_ec_dev *dev);
273
274/**
275 * Send a command to an I2C CROS-EC device and return the reply.
276 *
277 * This rather complicated function deals with sending both old-style and
278 * new-style commands. The old ones have just a command byte and arguments.
279 * The new ones have version, command, arg-len, [args], chksum so are 3 bytes
280 * longer.
281 *
282 * The device's internal input/output buffers are used.
283 *
284 * @param dev CROS-EC device
285 * @param cmd Command to send (EC_CMD_...)
286 * @param cmd_version Version of command to send (EC_VER_...)
287 * @param dout Output data (may be NULL If dout_len=0)
288 * @param dout_len Size of output data in bytes
289 * @param dinp Returns pointer to response data
290 * @param din_len Maximum size of response in bytes
291 * @return number of bytes in response, or -1 on error
292 */
293int cros_ec_i2c_command(struct cros_ec_dev *dev, uint8_t cmd, int cmd_version,
294 const uint8_t *dout, int dout_len,
295 uint8_t **dinp, int din_len);
296
297/**
298 * Send a command to a LPC CROS-EC device and return the reply.
299 *
300 * The device's internal input/output buffers are used.
301 *
302 * @param dev CROS-EC device
303 * @param cmd Command to send (EC_CMD_...)
304 * @param cmd_version Version of command to send (EC_VER_...)
305 * @param dout Output data (may be NULL If dout_len=0)
306 * @param dout_len Size of output data in bytes
307 * @param dinp Returns pointer to response data
308 * @param din_len Maximum size of response in bytes
309 * @return number of bytes in response, or -1 on error
310 */
311int cros_ec_lpc_command(struct cros_ec_dev *dev, uint8_t cmd, int cmd_version,
312 const uint8_t *dout, int dout_len,
313 uint8_t **dinp, int din_len);
314
315int cros_ec_spi_command(struct cros_ec_dev *dev, uint8_t cmd, int cmd_version,
316 const uint8_t *dout, int dout_len,
317 uint8_t **dinp, int din_len);
318
319/**
320 * Dump a block of data for a command.
321 *
322 * @param name Name for data (e.g. 'in', 'out')
323 * @param cmd Command number associated with data, or -1 for none
324 * @param data Data block to dump
325 * @param len Length of data block to dump
326 */
327void cros_ec_dump_data(const char *name, int cmd, const uint8_t *data, int len);
328
329/**
330 * Calculate a simple 8-bit checksum of a data block
331 *
332 * @param data Data block to checksum
333 * @param size Size of data block in bytes
334 * @return checksum value (0 to 255)
335 */
336int cros_ec_calc_checksum(const uint8_t *data, int size);
337
338/**
339 * Decode a flash region parameter
340 *
341 * @param argc Number of params remaining
342 * @param argv List of remaining parameters
343 * @return flash region (EC_FLASH_REGION_...) or -1 on error
344 */
345int cros_ec_decode_region(int argc, char * const argv[]);
346
347int cros_ec_flash_erase(struct cros_ec_dev *dev, uint32_t offset,
348 uint32_t size);
349
350/**
351 * Read data from the flash
352 *
353 * Read an arbitrary amount of data from the EC flash, by repeatedly reading
354 * small blocks.
355 *
356 * The offset starts at 0. You can obtain the region information from
357 * cros_ec_flash_offset() to find out where to read for a particular region.
358 *
359 * @param dev CROS-EC device
360 * @param data Pointer to data buffer to read into
361 * @param offset Offset within flash to read from
362 * @param size Number of bytes to read
363 * @return 0 if ok, -1 on error
364 */
365int cros_ec_flash_read(struct cros_ec_dev *dev, uint8_t *data, uint32_t offset,
366 uint32_t size);
367
368/**
369 * Write data to the flash
370 *
371 * Write an arbitrary amount of data to the EC flash, by repeatedly writing
372 * small blocks.
373 *
374 * The offset starts at 0. You can obtain the region information from
375 * cros_ec_flash_offset() to find out where to write for a particular region.
376 *
377 * Attempting to write to the region where the EC is currently running from
378 * will result in an error.
379 *
380 * @param dev CROS-EC device
381 * @param data Pointer to data buffer to write
382 * @param offset Offset within flash to write to.
383 * @param size Number of bytes to write
384 * @return 0 if ok, -1 on error
385 */
386int cros_ec_flash_write(struct cros_ec_dev *dev, const uint8_t *data,
387 uint32_t offset, uint32_t size);
388
389/**
390 * Obtain position and size of a flash region
391 *
392 * @param dev CROS-EC device
393 * @param region Flash region to query
394 * @param offset Returns offset of flash region in EC flash
395 * @param size Returns size of flash region
396 * @return 0 if ok, -1 on error
397 */
398int cros_ec_flash_offset(struct cros_ec_dev *dev, enum ec_flash_region region,
399 uint32_t *offset, uint32_t *size);
400
401/**
402 * Read/write VbNvContext from/to a CROS-EC device.
403 *
404 * @param dev CROS-EC device
405 * @param block Buffer of VbNvContext to be read/write
406 * @return 0 if ok, -1 on error
407 */
408int cros_ec_read_vbnvcontext(struct cros_ec_dev *dev, uint8_t *block);
409int cros_ec_write_vbnvcontext(struct cros_ec_dev *dev, const uint8_t *block);
410
411/**
412 * Read the version information for the EC images
413 *
414 * @param dev CROS-EC device
415 * @param versionp This is set to point to the version information
416 * @return 0 if ok, -1 on error
417 */
418int cros_ec_read_version(struct cros_ec_dev *dev,
419 struct ec_response_get_version **versionp);
420
421/**
422 * Read the build information for the EC
423 *
424 * @param dev CROS-EC device
425 * @param versionp This is set to point to the build string
426 * @return 0 if ok, -1 on error
427 */
428int cros_ec_read_build_info(struct cros_ec_dev *dev, char **strp);
429
430/**
431 * Switch on/off a LDO / FET.
432 *
433 * @param dev CROS-EC device
434 * @param index index of the LDO/FET to switch
435 * @param state new state of the LDO/FET : EC_LDO_STATE_ON|OFF
436 * @return 0 if ok, -1 on error
437 */
438int cros_ec_set_ldo(struct cros_ec_dev *dev, uint8_t index, uint8_t state);
439
440/**
441 * Read back a LDO / FET current state.
442 *
443 * @param dev CROS-EC device
444 * @param index index of the LDO/FET to switch
445 * @param state current state of the LDO/FET : EC_LDO_STATE_ON|OFF
446 * @return 0 if ok, -1 on error
447 */
448int cros_ec_get_ldo(struct cros_ec_dev *dev, uint8_t index, uint8_t *state);
449#endif