include/cros_ec.h

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