1 /* 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? */ 33 enum 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 */ 41 struct 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 */ 77 struct 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 */ 91 int 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 */ 102 int 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 */ 111 int 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 */ 121 int 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 */ 134 int 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 */ 146 int cros_ec_interrupt_pending(struct cros_ec_dev *dev); 147 148 enum { 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 */ 166 int 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 */ 174 int 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 */ 184 int 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 */ 193 int 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 */ 206 int 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 */ 217 int 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 */ 227 int 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 */ 237 struct cros_ec_dev *board_get_cros_ec_dev(void); 238 239 240 /* Internal interfaces */ 241 int cros_ec_i2c_init(struct cros_ec_dev *dev, const void *blob); 242 int cros_ec_spi_init(struct cros_ec_dev *dev, const void *blob); 243 int 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 */ 252 int 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 */ 261 int 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 */ 272 int 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 */ 293 int 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 */ 311 int 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 315 int 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 */ 327 void 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 */ 336 int 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 */ 345 int cros_ec_decode_region(int argc, char * const argv[]); 346 347 int 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 */ 365 int 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 */ 386 int 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 */ 398 int 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 */ 408 int cros_ec_read_vbnvcontext(struct cros_ec_dev *dev, uint8_t *block); 409 int 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 */ 418 int 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 */ 428 int 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 */ 438 int 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 */ 448 int cros_ec_get_ldo(struct cros_ec_dev *dev, uint8_t index, uint8_t *state); 449 #endif 450