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