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