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 int cros_ec_flash_erase(struct cros_ec_dev *dev, uint32_t offset,
 254                 uint32_t size);
 255
 256 /**
 257  * Read data from the flash
 258  *
 259  * Read an arbitrary amount of data from the EC flash, by repeatedly reading
 260  * small blocks.
 261  *
 262  * The offset starts at 0. You can obtain the region information from
 263  * cros_ec_flash_offset() to find out where to read for a particular region.
 264  *
 265  * @param dev           CROS-EC device
 266  * @param data          Pointer to data buffer to read into
 267  * @param offset        Offset within flash to read from
 268  * @param size          Number of bytes to read
 269  * @return 0 if ok, -1 on error
 270  */
 271 int cros_ec_flash_read(struct cros_ec_dev *dev, uint8_t *data, uint32_t offset,
 272                     uint32_t size);
 273
 274 /**
 275  * Read back flash parameters
 276  *
 277  * This function reads back parameters of the flash as reported by the EC
 278  *
 279  * @param dev  Pointer to device
 280  * @param info Pointer to output flash info struct
 281  */
 282 int cros_ec_read_flashinfo(struct cros_ec_dev *dev,
 283                           struct ec_response_flash_info *info);
 284
 285 /**
 286  * Write data to the flash
 287  *
 288  * Write an arbitrary amount of data to the EC flash, by repeatedly writing
 289  * small blocks.
 290  *
 291  * The offset starts at 0. You can obtain the region information from
 292  * cros_ec_flash_offset() to find out where to write for a particular region.
 293  *
 294  * Attempting to write to the region where the EC is currently running from
 295  * will result in an error.
 296  *
 297  * @param dev           CROS-EC device
 298  * @param data          Pointer to data buffer to write
 299  * @param offset        Offset within flash to write to.
 300  * @param size          Number of bytes to write
 301  * @return 0 if ok, -1 on error
 302  */
 303 int cros_ec_flash_write(struct cros_ec_dev *dev, const uint8_t *data,
 304                      uint32_t offset, uint32_t size);
 305
 306 /**
 307  * Obtain position and size of a flash region
 308  *
 309  * @param dev           CROS-EC device
 310  * @param region        Flash region to query
 311  * @param offset        Returns offset of flash region in EC flash
 312  * @param size          Returns size of flash region
 313  * @return 0 if ok, -1 on error
 314  */
 315 int cros_ec_flash_offset(struct cros_ec_dev *dev, enum ec_flash_region region,
 316                       uint32_t *offset, uint32_t *size);
 317
 318 /**
 319  * Read/write VbNvContext from/to a CROS-EC device.
 320  *
 321  * @param dev           CROS-EC device
 322  * @param block         Buffer of VbNvContext to be read/write
 323  * @return 0 if ok, -1 on error
 324  */
 325 int cros_ec_read_vbnvcontext(struct cros_ec_dev *dev, uint8_t *block);
 326 int cros_ec_write_vbnvcontext(struct cros_ec_dev *dev, const uint8_t *block);
 327
 328 /**
 329  * Read the version information for the EC images
 330  *
 331  * @param dev           CROS-EC device
 332  * @param versionp      This is set to point to the version information
 333  * @return 0 if ok, -1 on error
 334  */
 335 int cros_ec_read_version(struct cros_ec_dev *dev,
 336                        struct ec_response_get_version **versionp);
 337
 338 /**
 339  * Read the build information for the EC
 340  *
 341  * @param dev           CROS-EC device
 342  * @param versionp      This is set to point to the build string
 343  * @return 0 if ok, -1 on error
 344  */
 345 int cros_ec_read_build_info(struct cros_ec_dev *dev, char **strp);
 346
 347 /**
 348  * Switch on/off a LDO / FET.
 349  *
 350  * @param dev           CROS-EC device
 351  * @param index         index of the LDO/FET to switch
 352  * @param state         new state of the LDO/FET : EC_LDO_STATE_ON|OFF
 353  * @return 0 if ok, -1 on error
 354  */
 355 int cros_ec_set_ldo(struct udevice *dev, uint8_t index, uint8_t state);
 356
 357 /**
 358  * Read back a LDO / FET current state.
 359  *
 360  * @param dev           CROS-EC device
 361  * @param index         index of the LDO/FET to switch
 362  * @param state         current state of the LDO/FET : EC_LDO_STATE_ON|OFF
 363  * @return 0 if ok, -1 on error
 364  */
 365 int cros_ec_get_ldo(struct udevice *dev, uint8_t index, uint8_t *state);
 366
 367 /**
 368  * Get access to the error reported when cros_ec_board_init() was called
 369  *
 370  * This permits delayed reporting of the EC error if it failed during
 371  * early init.
 372  *
 373  * @return error (0 if there was no error, -ve if there was an error)
 374  */
 375 int cros_ec_get_error(void);
 376
 377 /**
 378  * Returns information from the FDT about the Chrome EC flash
 379  *
 380  * @param blob          FDT blob to use
 381  * @param node          Node offset to read from
 382  * @param config        Structure to use to return information
 383  */
 384 int cros_ec_decode_ec_flash(const void *blob, int node,
 385                             struct fdt_cros_ec *config);
 386
 387 /**
 388  * Check the current keyboard state, in case recovery mode is requested.
 389  * This function is for sandbox only.
 390  *
 391  * @param ec            CROS-EC device
 392  */
 393 void cros_ec_check_keyboard(struct cros_ec_dev *dev);
 394
 395 struct i2c_msg;
 396 /*
 397  * Tunnel an I2C transfer to the EC
 398  *
 399  * @param dev           CROS-EC device
 400  * @param port          The remote port on EC to use
 401  * @param msg           List of messages to transfer
 402  * @param nmsgs         Number of messages to transfer
 403  */
 404 int cros_ec_i2c_tunnel(struct udevice *dev, int port, struct i2c_msg *msg,
 405                        int nmsgs);
 406
 407 #endif