include/linux/mfd/chromeos_ec_commands.h

   1 /* Copyright (c) 2012 The Chromium OS Authors. All rights reserved.
   2  * Use of this source code is governed by a BSD-style license that can be
   3  * found in the LICENSE file.
   4  */
   5
   6 /* Host communication command constants for Chrome EC */
   7
   8 #ifndef __CROS_EC_COMMANDS_H
   9 #define __CROS_EC_COMMANDS_H
  10
  11 /* Protocol overview
  12  *
  13  * request:  CMD [ P0 P1 P2 ... Pn S ]
  14  * response: ERR [ P0 P1 P2 ... Pn S ]
  15  *
  16  * where the bytes are defined as follow :
  17  *      - CMD is the command code. (defined by EC_CMD_ constants)
  18  *      - ERR is the error code. (defined by EC_RES_ constants)
  19  *      - Px is the optional payload.
  20  *        it is not sent if the error code is not success.
  21  *        (defined by ec_params_ and ec_response_ structures)
  22  *      - S is the checksum which is the sum of all payload bytes.
  23  *
  24  * On LPC, CMD and ERR are sent/received at EC_LPC_ADDR_KERNEL|USER_CMD
  25  * and the payloads are sent/received at EC_LPC_ADDR_KERNEL|USER_PARAM.
  26  * On I2C, all bytes are sent serially in the same message.
  27  */
  28
  29
  30 /* During the development stage, the LPC bus has high error bit rate.
  31  * Using checksum can detect the error and trigger re-transmit.
  32  * FIXME: remove this after mass production.
  33  */
  34 #define SUPPORT_CHECKSUM
  35
  36 /* Current version of this protocol */
  37 #define EC_PROTO_VERSION          0x00000002
  38
  39 /* I/O addresses for LPC commands */
  40 #define EC_LPC_ADDR_KERNEL_DATA   0x62
  41 #define EC_LPC_ADDR_KERNEL_CMD    0x66
  42 #define EC_LPC_ADDR_KERNEL_PARAM 0x800
  43 #define EC_LPC_ADDR_USER_DATA    0x200
  44 #define EC_LPC_ADDR_USER_CMD     0x204
  45 #define EC_LPC_ADDR_USER_PARAM   0x880
  46 #define EC_PARAM_SIZE          128  /* Size of each param area in bytes */
  47
  48 /* EC command register bit functions */
  49 #define EC_LPC_CMDR_DATA        (1 << 0)
  50 #define EC_LPC_CMDR_PENDING     (1 << 1)
  51 #define EC_LPC_CMDR_BUSY        (1 << 2)
  52 #define EC_LPC_CMDR_CMD         (1 << 3)
  53 #define EC_LPC_CMDR_ACPI_BRST   (1 << 4)
  54 #define EC_LPC_CMDR_SCI         (1 << 5)
  55 #define EC_LPC_CMDR_SMI         (1 << 6)
  56
  57 #define EC_LPC_ADDR_MEMMAP       0x900
  58 #define EC_MEMMAP_SIZE         255 /* ACPI IO buffer max is 255 bytes */
  59 #define EC_MEMMAP_TEXT_MAX     8   /* Size of a string in the memory map */
  60
  61 /* The offset address of each type of data in mapped memory. */
  62 #define EC_MEMMAP_TEMP_SENSOR 0x00
  63 #define EC_MEMMAP_FAN         0x10
  64 #define EC_MEMMAP_SWITCHES    0x30
  65 #define EC_MEMMAP_HOST_EVENTS 0x34
  66 #define EC_MEMMAP_BATT_VOLT   0x40 /* Battery Present Voltage */
  67 #define EC_MEMMAP_BATT_RATE   0x44 /* Battery Present Rate */
  68 #define EC_MEMMAP_BATT_CAP    0x48 /* Battery Remaining Capacity */
  69 #define EC_MEMMAP_BATT_FLAG   0x4c /* Battery State, defined below */
  70 #define EC_MEMMAP_BATT_DCAP   0x50 /* Battery Design Capacity */
  71 #define EC_MEMMAP_BATT_DVLT   0x54 /* Battery Design Voltage */
  72 #define EC_MEMMAP_BATT_LFCC   0x58 /* Battery Last Full Charge Capacity */
  73 #define EC_MEMMAP_BATT_CCNT   0x5c /* Battery Cycle Count */
  74 #define EC_MEMMAP_BATT_MFGR   0x60 /* Battery Manufacturer String */
  75 #define EC_MEMMAP_BATT_MODEL  0x68 /* Battery Model Number String */
  76 #define EC_MEMMAP_BATT_SERIAL 0x70 /* Battery Serial Number String */
  77 #define EC_MEMMAP_BATT_TYPE   0x78 /* Battery Type String */
  78
  79 /* Battery bit flags at EC_MEMMAP_BATT_FLAG. */
  80 #define EC_BATT_FLAG_AC_PRESENT   0x01
  81 #define EC_BATT_FLAG_BATT_PRESENT 0x02
  82 #define EC_BATT_FLAG_DISCHARGING  0x04
  83 #define EC_BATT_FLAG_CHARGING     0x08
  84 #define EC_BATT_FLAG_LEVEL_CRITICAL 0x10
  85
  86 /* Switch flags at EC_MEMMAP_SWITCHES */
  87 #define EC_SWITCH_LID_OPEN               0x01
  88 #define EC_SWITCH_POWER_BUTTON_PRESSED   0x02
  89 #define EC_SWITCH_WRITE_PROTECT_DISABLED 0x04
  90 /* Recovery requested via keyboard */
  91 #define EC_SWITCH_KEYBOARD_RECOVERY      0x08
  92 /* Recovery requested via dedicated signal (from servo board) */
  93 #define EC_SWITCH_DEDICATED_RECOVERY     0x10
  94 /* Fake developer switch (for testing) */
  95 #define EC_SWITCH_FAKE_DEVELOPER         0x20
  96
  97 /* The offset of temperature value stored in mapped memory.
  98  * This allows reporting a temperature range of
  99  * 200K to 454K = -73C to 181C.
 100  */
 101 #define EC_TEMP_SENSOR_OFFSET 200
 102
 103 /*
 104  * This header file is used in coreboot both in C and ACPI code.
 105  * The ACPI code is pre-processed to handle constants but the ASL
 106  * compiler is unable to handle actual C code so keep it separate.
 107  */
 108 #ifndef __ACPI__
 109
 110 /* LPC command status byte masks */
 111 /* EC has written a byte in the data register and host hasn't read it yet */
 112 #define EC_LPC_STATUS_TO_HOST     0x01
 113 /* Host has written a command/data byte and the EC hasn't read it yet */
 114 #define EC_LPC_STATUS_FROM_HOST   0x02
 115 /* EC is processing a command */
 116 #define EC_LPC_STATUS_PROCESSING  0x04
 117 /* Last write to EC was a command, not data */
 118 #define EC_LPC_STATUS_LAST_CMD    0x08
 119 /* EC is in burst mode.  Chrome EC doesn't support this, so this bit is never
 120  * set. */
 121 #define EC_LPC_STATUS_BURST_MODE  0x10
 122 /* SCI event is pending (requesting SCI query) */
 123 #define EC_LPC_STATUS_SCI_PENDING 0x20
 124 /* SMI event is pending (requesting SMI query) */
 125 #define EC_LPC_STATUS_SMI_PENDING 0x40
 126 /* (reserved) */
 127 #define EC_LPC_STATUS_RESERVED    0x80
 128
 129 /* EC is busy.  This covers both the EC processing a command, and the host has
 130  * written a new command but the EC hasn't picked it up yet. */
 131 #define EC_LPC_STATUS_BUSY_MASK \
 132         (EC_LPC_STATUS_FROM_HOST | EC_LPC_STATUS_PROCESSING)
 133
 134 /* Host command response codes */
 135 /* TODO: move these so they don't overlap SCI/SMI data? */
 136 enum ec_status {
 137         EC_RES_SUCCESS = 0,
 138         EC_RES_INVALID_COMMAND = 1,
 139         EC_RES_ERROR = 2,
 140         EC_RES_INVALID_PARAM = 3,
 141         EC_RES_ACCESS_DENIED = 4,
 142 };
 143
 144
 145 /* Host event codes.  Note these are 1-based, not 0-based, because ACPI query
 146  * EC command uses code 0 to mean "no event pending".  We explicitly specify
 147  * each value in the enum listing so they won't change if we delete/insert an
 148  * item or rearrange the list (it needs to be stable across platforms, not
 149  * just within a single compiled instance). */
 150 enum host_event_code {
 151         EC_HOST_EVENT_LID_CLOSED = 1,
 152         EC_HOST_EVENT_LID_OPEN = 2,
 153         EC_HOST_EVENT_POWER_BUTTON = 3,
 154         EC_HOST_EVENT_AC_CONNECTED = 4,
 155         EC_HOST_EVENT_AC_DISCONNECTED = 5,
 156         EC_HOST_EVENT_BATTERY_LOW = 6,
 157         EC_HOST_EVENT_BATTERY_CRITICAL = 7,
 158         EC_HOST_EVENT_BATTERY = 8,
 159         EC_HOST_EVENT_THERMAL_THRESHOLD = 9,
 160         EC_HOST_EVENT_THERMAL_OVERLOAD = 10,
 161         EC_HOST_EVENT_THERMAL = 11,
 162         EC_HOST_EVENT_USB_CHARGER = 12,
 163         EC_HOST_EVENT_KEY_PRESSED = 13,
 164 };
 165 /* Host event mask */
 166 #define EC_HOST_EVENT_MASK(event_code) (1 << ((event_code) - 1))
 167
 168 /* Notes on commands:
 169  *
 170  * Each command is an 8-byte command value.  Commands which take
 171  * params or return response data specify structs for that data.  If
 172  * no struct is specified, the command does not input or output data,
 173  * respectively. */
 174
 175 /*****************************************************************************/
 176 /* General / test commands */
 177
 178 /* Get protocol version, used to deal with non-backward compatible protocol
 179  * changes. */
 180 #define EC_CMD_PROTO_VERSION 0x00
 181 struct ec_response_proto_version {
 182         uint32_t version;
 183 } __attribute__ ((packed));
 184
 185 /* Hello.  This is a simple command to test the EC is responsive to
 186  * commands. */
 187 #define EC_CMD_HELLO 0x01
 188 struct ec_params_hello {
 189         uint32_t in_data;  /* Pass anything here */
 190 } __attribute__ ((packed));
 191 struct ec_response_hello {
 192         uint32_t out_data;  /* Output will be in_data + 0x01020304 */
 193 } __attribute__ ((packed));
 194
 195
 196 /* Get version number */
 197 #define EC_CMD_GET_VERSION 0x02
 198 enum ec_current_image {
 199         EC_IMAGE_UNKNOWN = 0,
 200         EC_IMAGE_RO,
 201         EC_IMAGE_RW_A,
 202         EC_IMAGE_RW_B
 203 };
 204 struct ec_response_get_version {
 205         /* Null-terminated version strings for RO, RW-A, RW-B */
 206         char version_string_ro[32];
 207         char version_string_rw_a[32];
 208         char version_string_rw_b[32];
 209         uint32_t current_image;  /* One of ec_current_image */
 210 } __attribute__ ((packed));
 211
 212
 213 /* Read test */
 214 #define EC_CMD_READ_TEST 0x03
 215 struct ec_params_read_test {
 216         uint32_t offset;   /* Starting value for read buffer */
 217         uint32_t size;     /* Size to read in bytes */
 218 } __attribute__ ((packed));
 219 struct ec_response_read_test {
 220         uint32_t data[32];
 221 } __attribute__ ((packed));
 222
 223
 224 /* Get build information */
 225 #define EC_CMD_GET_BUILD_INFO 0x04
 226 struct ec_response_get_build_info {
 227         char build_string[EC_PARAM_SIZE];
 228 } __attribute__ ((packed));
 229
 230
 231 /* Get chip info */
 232 #define EC_CMD_GET_CHIP_INFO 0x05
 233 struct ec_response_get_chip_info {
 234         /* Null-terminated strings */
 235         char vendor[32];
 236         char name[32];
 237         char revision[32];  /* Mask version */
 238 } __attribute__ ((packed));
 239
 240
 241 /*****************************************************************************/
 242 /* Flash commands */
 243
 244 /* Maximum bytes that can be read/written in a single command */
 245 #define EC_FLASH_SIZE_MAX 64
 246
 247 /* Get flash info */
 248 #define EC_CMD_FLASH_INFO 0x10
 249 struct ec_response_flash_info {
 250         /* Usable flash size, in bytes */
 251         uint32_t flash_size;
 252         /* Write block size.  Write offset and size must be a multiple
 253          * of this. */
 254         uint32_t write_block_size;
 255         /* Erase block size.  Erase offset and size must be a multiple
 256          * of this. */
 257         uint32_t erase_block_size;
 258         /* Protection block size.  Protection offset and size must be a
 259          * multiple of this. */
 260         uint32_t protect_block_size;
 261 } __attribute__ ((packed));
 262
 263 /* Read flash */
 264 #define EC_CMD_FLASH_READ 0x11
 265 struct ec_params_flash_read {
 266         uint32_t offset;   /* Byte offset to read */
 267         uint32_t size;     /* Size to read in bytes */
 268 } __attribute__ ((packed));
 269 struct ec_response_flash_read {
 270         uint8_t data[EC_FLASH_SIZE_MAX];
 271 } __attribute__ ((packed));
 272
 273 /* Write flash */
 274 #define EC_CMD_FLASH_WRITE 0x12
 275 struct ec_params_flash_write {
 276         uint32_t offset;   /* Byte offset to write */
 277         uint32_t size;     /* Size to write in bytes */
 278         uint8_t data[EC_FLASH_SIZE_MAX];
 279 } __attribute__ ((packed));
 280
 281 /* Erase flash */
 282 #define EC_CMD_FLASH_ERASE 0x13
 283 struct ec_params_flash_erase {
 284         uint32_t offset;   /* Byte offset to erase */
 285         uint32_t size;     /* Size to erase in bytes */
 286 } __attribute__ ((packed));
 287
 288 /* Flashmap offset */
 289 #define EC_CMD_FLASH_GET_FLASHMAP 0x14
 290 struct ec_response_flash_flashmap {
 291         uint32_t offset;   /* Flashmap offset */
 292 } __attribute__ ((packed));
 293
 294 /* Enable/disable flash write protect */
 295 #define EC_CMD_FLASH_WP_ENABLE 0x15
 296 struct ec_params_flash_wp_enable {
 297         uint32_t enable_wp;
 298 } __attribute__ ((packed));
 299
 300 /* Get flash write protection commit state */
 301 #define EC_CMD_FLASH_WP_GET_STATE 0x16
 302 struct ec_response_flash_wp_enable {
 303         uint32_t enable_wp;
 304 } __attribute__ ((packed));
 305
 306 /* Set/get flash write protection range */
 307 #define EC_CMD_FLASH_WP_SET_RANGE 0x17
 308 struct ec_params_flash_wp_range {
 309         /* Byte offset aligned to info.protect_block_size */
 310         uint32_t offset;
 311         /* Size should be multiply of info.protect_block_size */
 312         uint32_t size;
 313 } __attribute__ ((packed));
 314
 315 #define EC_CMD_FLASH_WP_GET_RANGE 0x18
 316 struct ec_response_flash_wp_range {
 317         uint32_t offset;
 318         uint32_t size;
 319 } __attribute__ ((packed));
 320
 321 /* Read flash write protection GPIO pin */
 322 #define EC_CMD_FLASH_WP_GET_GPIO 0x19
 323 struct ec_params_flash_wp_gpio {
 324         uint32_t pin_no;
 325 } __attribute__ ((packed));
 326 struct ec_response_flash_wp_gpio {
 327         uint32_t value;
 328 } __attribute__ ((packed));
 329
 330 #ifdef SUPPORT_CHECKSUM
 331 /* Checksum a range of flash datq */
 332 #define EC_CMD_FLASH_CHECKSUM 0x1f
 333 struct ec_params_flash_checksum {
 334         uint32_t offset;   /* Byte offset to read */
 335         uint32_t size;     /* Size to read in bytes */
 336 } __attribute__ ((packed));
 337 struct ec_response_flash_checksum {
 338         uint8_t checksum;
 339 } __attribute__ ((packed));
 340 #define BYTE_IN(sum, byte) do {  \
 341                 sum = (sum << 1) | (sum >> 7);  \
 342                 sum ^= (byte ^ 0x53);  \
 343         } while (0)
 344 #endif  /* SUPPORT_CHECKSUM */
 345
 346 /*****************************************************************************/
 347 /* PWM commands */
 348
 349 /* Get fan RPM */
 350 #define EC_CMD_PWM_GET_FAN_RPM 0x20
 351 struct ec_response_pwm_get_fan_rpm {
 352         uint32_t rpm;
 353 } __attribute__ ((packed));
 354
 355 /* Set target fan RPM */
 356 #define EC_CMD_PWM_SET_FAN_TARGET_RPM 0x21
 357 struct ec_params_pwm_set_fan_target_rpm {
 358         uint32_t rpm;
 359 } __attribute__ ((packed));
 360
 361 /* Get keyboard backlight */
 362 #define EC_CMD_PWM_GET_KEYBOARD_BACKLIGHT 0x22
 363 struct ec_response_pwm_get_keyboard_backlight {
 364         uint8_t percent;
 365 } __attribute__ ((packed));
 366
 367 /* Set keyboard backlight */
 368 #define EC_CMD_PWM_SET_KEYBOARD_BACKLIGHT 0x23
 369 struct ec_params_pwm_set_keyboard_backlight {
 370         uint8_t percent;
 371 } __attribute__ ((packed));
 372
 373 /*****************************************************************************/
 374 /* Lightbar commands. This looks worse than it is. Since we only use one LPC
 375  * command to say "talk to the lightbar", we put the "and tell it to do X"
 376  * part into a subcommand. We'll make separate structs for subcommands with
 377  * different input args, so that we know how much to expect. */
 378 #define EC_CMD_LIGHTBAR_CMD 0x28
 379 struct ec_params_lightbar_cmd {
 380         union {
 381                 union {
 382                         uint8_t cmd;
 383                         struct {
 384                                 uint8_t cmd;
 385                         } dump, off, on, init, get_seq;
 386                         struct num {
 387                                 uint8_t cmd;
 388                                 uint8_t num;
 389                         } brightness, seq;
 390
 391                         struct reg {
 392                                 uint8_t cmd;
 393                                 uint8_t ctrl, reg, value;
 394                         } reg;
 395                         struct rgb {
 396                                 uint8_t cmd;
 397                                 uint8_t led, red, green, blue;
 398                         } rgb;
 399                 } in;
 400                 union {
 401                         struct dump {
 402                                 struct {
 403                                         uint8_t reg;
 404                                         uint8_t ic0;
 405                                         uint8_t ic1;
 406                                 } vals[23];
 407                         } dump;
 408                         struct get_seq {
 409                                 uint8_t num;
 410                         } get_seq;
 411                         struct {
 412                                 /* no return params */
 413                         } off, on, init, brightness, seq, reg, rgb;
 414                 } out;
 415         };
 416 } __attribute__ ((packed));
 417
 418 /*****************************************************************************/
 419 /* USB charging control commands */
 420
 421 /* Set USB port charging mode */
 422 #define EC_CMD_USB_CHARGE_SET_MODE 0x30
 423 struct ec_params_usb_charge_set_mode {
 424         uint8_t usb_port_id;
 425         uint8_t mode;
 426 } __attribute__ ((packed));
 427
 428 /*****************************************************************************/
 429 /* Persistent storage for host */
 430
 431 /* Maximum bytes that can be read/written in a single command */
 432 #define EC_PSTORE_SIZE_MAX 64
 433
 434 /* Get persistent storage info */
 435 #define EC_CMD_PSTORE_INFO 0x40
 436 struct ec_response_pstore_info {
 437         /* Persistent storage size, in bytes */
 438         uint32_t pstore_size;
 439         /* Access size.  Read/write offset and size must be a multiple
 440          * of this. */
 441         uint32_t access_size;
 442 } __attribute__ ((packed));
 443
 444 /* Read persistent storage */
 445 #define EC_CMD_PSTORE_READ 0x41
 446 struct ec_params_pstore_read {
 447         uint32_t offset;   /* Byte offset to read */
 448         uint32_t size;     /* Size to read in bytes */
 449 } __attribute__ ((packed));
 450 struct ec_response_pstore_read {
 451         uint8_t data[EC_PSTORE_SIZE_MAX];
 452 } __attribute__ ((packed));
 453
 454 /* Write persistent storage */
 455 #define EC_CMD_PSTORE_WRITE 0x42
 456 struct ec_params_pstore_write {
 457         uint32_t offset;   /* Byte offset to write */
 458         uint32_t size;     /* Size to write in bytes */
 459         uint8_t data[EC_PSTORE_SIZE_MAX];
 460 } __attribute__ ((packed));
 461
 462 /*****************************************************************************/
 463 /* Thermal engine commands */
 464
 465 /* Set thershold value */
 466 #define EC_CMD_THERMAL_SET_THRESHOLD 0x50
 467 struct ec_params_thermal_set_threshold {
 468         uint8_t sensor_type;
 469         uint8_t threshold_id;
 470         uint16_t value;
 471 } __attribute__ ((packed));
 472
 473 /* Get threshold value */
 474 #define EC_CMD_THERMAL_GET_THRESHOLD 0x51
 475 struct ec_params_thermal_get_threshold {
 476         uint8_t sensor_type;
 477         uint8_t threshold_id;
 478 } __attribute__ ((packed));
 479 struct ec_response_thermal_get_threshold {
 480         uint16_t value;
 481 } __attribute__ ((packed));
 482
 483 /* Toggling automatic fan control */
 484 #define EC_CMD_THERMAL_AUTO_FAN_CTRL 0x52
 485
 486 /*****************************************************************************/
 487 /* Matrix KeyBoard Protocol */
 488
 489 /* Read key state */
 490 #define EC_CMD_MKBP_STATE 0x60
 491 struct ec_response_mkbp_state {
 492         uint8_t cols[32];
 493 } __attribute__ ((packed));
 494
 495 /* Provide information about the matrix : number of rows and columns */
 496 #define EC_CMD_MKBP_INFO 0x61
 497 struct ec_response_mkbp_info {
 498         uint32_t rows;
 499         uint32_t cols;
 500 } __attribute__ ((packed));
 501
 502 /*****************************************************************************/
 503 /* Host event commands */
 504
 505 /* Host event mask params and response structures, shared by all of the host
 506  * event commands below. */
 507 struct ec_params_host_event_mask {
 508         uint32_t mask;
 509 } __attribute__ ((packed));
 510
 511 struct ec_response_host_event_mask {
 512         uint32_t mask;
 513 } __attribute__ ((packed));
 514
 515 /* These all use ec_response_host_event_mask */
 516 #define EC_CMD_HOST_EVENT_GET_SMI_MASK  0x88
 517 #define EC_CMD_HOST_EVENT_GET_SCI_MASK  0x89
 518 #define EC_CMD_HOST_EVENT_GET_WAKE_MASK 0x8d
 519
 520 /* These all use ec_params_host_event_mask */
 521 #define EC_CMD_HOST_EVENT_SET_SMI_MASK  0x8a
 522 #define EC_CMD_HOST_EVENT_SET_SCI_MASK  0x8b
 523 #define EC_CMD_HOST_EVENT_CLEAR         0x8c
 524 #define EC_CMD_HOST_EVENT_SET_WAKE_MASK 0x8e
 525
 526 /*****************************************************************************/
 527 /* Special commands
 528  *
 529  * These do not follow the normal rules for commands.  See each command for
 530  * details. */
 531
 532 /* ACPI Query Embedded Controller
 533  *
 534  * This clears the lowest-order bit in the currently pending host events, and
 535  * sets the result code to the 1-based index of the bit (event 0x00000001 = 1,
 536  * event 0x80000000 = 32), or 0 if no event was pending. */
 537 #define EC_CMD_ACPI_QUERY_EVENT 0x84
 538
 539 /* Reboot
 540  *
 541  * This command will work even when the EC LPC interface is busy, because the
 542  * reboot command is processed at interrupt level.  Note that when the EC
 543  * reboots, the host will reboot too, so there is no response to this
 544  * command. */
 545 #define EC_CMD_REBOOT 0xd1  /* Think "die" */
 546
 547 #define EC_CMD_REBOOT_EC 0xd2
 548 #define EC_CMD_REBOOT_BIT_RECOVERY (1 << 0)
 549
 550 struct ec_params_reboot_ec {
 551         uint8_t target;  /* enum ec_current_image */
 552         uint8_t reboot_flags;
 553 } __attribute__ ((packed));
 554
 555 #endif  /* !__ACPI__ */
 556
 557 #endif  /* __CROS_EC_COMMANDS_H */