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
  17 #ifndef CONFIG_DM_CROS_EC
  18 /* Which interface is the device on? */
  19 enum 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 */
  29 struct 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 */
  69 struct mbkp_keyscan {
  70         uint8_t data[CROS_EC_KEYSCAN_COLS];
  71 };
  72
  73 /* Holds information about the Chrome EC */
  74 struct 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  */
  94 int 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  */
 105 int 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  */
 114 int 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  */
 124 int 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  */
 137 int 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  */
 149 int cros_ec_interrupt_pending(struct cros_ec_dev *dev);
 150
 151 enum {
 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  */
 169 int 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  */
 177 int 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  */
 187 int 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  */
 196 int 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  */
 209 int 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  */
 220 int 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  */
 230 int 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  */
 240 struct cros_ec_dev *board_get_cros_ec_dev(void);
 241
 242 #ifdef CONFIG_DM_CROS_EC
 243
 244 struct 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
 255 int cros_ec_register(struct udevice *dev);
 256
 257 #else /* !CONFIG_DM_CROS_EC */
 258
 259 /* Internal interfaces */
 260 int cros_ec_i2c_init(struct cros_ec_dev *dev, const void *blob);
 261 int cros_ec_spi_init(struct cros_ec_dev *dev, const void *blob);
 262 int cros_ec_lpc_init(struct cros_ec_dev *dev, const void *blob);
 263 int 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  */
 272 int 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  */
 281 int 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  */
 290 int 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  */
 300 int 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  */
 321 int 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  */
 339 int 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
 343 int 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  */
 358 int cros_ec_spi_packet(struct cros_ec_dev *dev, int out_bytes, int in_bytes);
 359 int 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  */
 371 void 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  */
 380 int 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  */
 389 int cros_ec_decode_region(int argc, char * const argv[]);
 390
 391 int 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  */
 409 int 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  */
 430 int 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  */
 442 int 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  */
 452 int cros_ec_read_vbnvcontext(struct cros_ec_dev *dev, uint8_t *block);
 453 int 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  */
 462 int 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  */
 472 int 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  */
 482 int 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  */
 492 int 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  */
 499 int 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  */
 509 int 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  */
 518 int 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  */
 527 void 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  */
 540 int 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