src/ec/google/chromeec/ec.h

   1 /* SPDX-License-Identifier: GPL-2.0-only */
   2
   3 /*
   4  * Mailbox EC communication interface for Google Chrome Embedded Controller.
   5  */
   6
   7 #ifndef _EC_GOOGLE_CHROMEEC_EC_H
   8 #define _EC_GOOGLE_CHROMEEC_EC_H
   9 #include <types.h>
  10 #include <device/device.h>
  11 #include "ec_commands.h"
  12 #include <device/usbc_mux.h>
  13
  14 /* Fill in base and size of the IO port resources used. */
  15 void google_chromeec_ioport_range(uint16_t *base, size_t *size);
  16
  17 int google_chromeec_i2c_xfer(uint8_t chip, uint8_t addr, int alen,
  18                              uint8_t *buffer, int len, int is_read);
  19 uint64_t google_chromeec_get_wake_mask(void);
  20 int google_chromeec_set_sci_mask(uint64_t mask);
  21 int google_chromeec_set_smi_mask(uint64_t mask);
  22 int google_chromeec_set_wake_mask(uint64_t mask);
  23 enum host_event_code google_chromeec_get_event(void);
  24
  25 /* Check if EC supports feature EC_FEATURE_UNIFIED_WAKE_MASKS */
  26 bool google_chromeec_is_uhepi_supported(void);
  27 int google_ec_running_ro(void);
  28 enum ec_image google_chromeec_get_current_image(void);
  29 void google_chromeec_init(void);
  30 /* Check for the current mux state in EC
  31  * in: int port physical port number of the type-c port
  32  * out: uint8_t flags representing the status of the mux such as
  33  *      usb capability, dp capability, cable type, etc
  34  */
  35 int google_chromeec_usb_get_pd_mux_info(int port, uint8_t *flags);
  36 /* Poll (up to `timeout_ms` ms) for DisplayPort to be ready
  37  * Return:      -1: Error. 0: Timeout.
  38  *              >=1: Bitmask of the ports that DP device is connected
  39  */
  40 int google_chromeec_wait_for_displayport(long timeout_ms);
  41 /* Poll (up to `timeout_ms` ms) for the DP mode entry
  42  * event on the specified port.
  43  * Return: 0 on DP mode entry success, -1 on timeout */
  44 int google_chromeec_wait_for_dp_mode_entry(int port, long timeout_ms);
  45 /* Poll (up to `timeout_ms` ms) for a Hot-Plug Detect (HPD)
  46  * event on the specified port.
  47  * Return: 0 on HPD ready, -1 on timeout */
  48 int google_chromeec_wait_for_hpd(int port, long timeout_ms);
  49 /* Send command to EC to request to enter DisplayPort ALT mode on the
  50  * specified port.
  51  * Return: 0 on success, -1 on error */
  52 int google_chromeec_typec_control_enter_dp_mode(int port);
  53 /*
  54  * Obtain any USB-C mux data needed for the specified port
  55  * in: int port physical port number of the type-c port
  56  * out: struct usbc_mux_info mux_info stores USB-C mux data
  57  * Return: 0 on success, -1 on error
  58  */
  59 int google_chromeec_get_usbc_mux_info(int port, struct usbc_mux_info *mux_info);
  60
  61 /* Device events */
  62 uint64_t google_chromeec_get_device_enabled_events(void);
  63 int google_chromeec_set_device_enabled_events(uint64_t mask);
  64 uint64_t google_chromeec_get_device_current_events(void);
  65
  66 int google_chromeec_check_feature(int feature);
  67 uint8_t google_chromeec_calc_checksum(const uint8_t *data, int size);
  68
  69 /**
  70  * google_chromeec_get_board_version() - Get the board version
  71  * @version: Out parameter to retrieve the board Version
  72  *
  73  * Return: 0 on success or -1 on failure/error.
  74  *
  75  * This function is used to get the board version information from EC.
  76  */
  77 int google_chromeec_get_board_version(uint32_t *version);
  78 uint32_t google_chromeec_get_sku_id(void);
  79 int google_chromeec_set_sku_id(uint32_t skuid);
  80 uint64_t  google_chromeec_get_events_b(void);
  81 int google_chromeec_clear_events_b(uint64_t mask);
  82 int google_chromeec_kbbacklight(int percent);
  83 void google_chromeec_post(uint8_t postcode);
  84 uint8_t google_chromeec_get_switches(void);
  85 bool google_chromeec_get_ap_watchdog_flag(void);
  86
  87 /* Temporary secure storage commands */
  88 int google_chromeec_vstore_supported(void);
  89 int google_chromeec_vstore_info(uint32_t *locked);
  90 int google_chromeec_vstore_read(int slot, uint8_t *data);
  91 int google_chromeec_vstore_write(int slot, uint8_t *data, size_t size);
  92
  93 /* Issue reboot command to EC with specified type and flags. Returns 0 on
  94    success, < 0 otherwise. */
  95 int google_chromeec_reboot(enum ec_reboot_cmd type, uint8_t flags);
  96
  97 /**
  98  * Get data from Cros Board Info
  99  *
 100  * @param id/fw_config/buf [OUT] value from CBI.
 101  * @return 0 on success or negative integer for errors.
 102  */
 103 int google_chromeec_cbi_get_oem_id(uint32_t *id);
 104 int google_chromeec_cbi_get_sku_id(uint32_t *id);
 105 int google_chromeec_cbi_get_fw_config(uint64_t *fw_config);
 106 int google_chromeec_cbi_get_dram_part_num(char *buf, size_t bufsize);
 107 int google_chromeec_cbi_get_oem_name(char *buf, size_t bufsize);
 108 /* version may be stored in CBI as a smaller integer width, but the EC code
 109    handles it correctly. */
 110 int google_chromeec_cbi_get_board_version(uint32_t *version);
 111 int google_chromeec_cbi_get_ssfc(uint32_t *ssfc);
 112
 113 #define CROS_SKU_UNKNOWN        0xFFFFFFFF
 114 #define CROS_SKU_UNPROVISIONED  0x7FFFFFFF
 115 /* Returns CROS_SKU_UNKNOWN on failure. */
 116 uint32_t google_chromeec_get_board_sku(void);
 117 const char *google_chromeec_smbios_system_sku(void);
 118
 119 /* MEC uses 0x800/0x804 as register/index pair, thus an 8-byte resource. */
 120 #define MEC_EMI_BASE            0x800
 121 #define MEC_EMI_SIZE            8
 122
 123 /* For MEC, access ranges 0x800 thru 0x9ff using EMI interface instead of LPC */
 124 #define MEC_EMI_RANGE_START EC_HOST_CMD_REGION0
 125 #define MEC_EMI_RANGE_END   (EC_LPC_ADDR_MEMMAP + EC_MEMMAP_SIZE)
 126
 127 int google_chromeec_set_usb_charge_mode(uint8_t port_id, enum usb_charge_mode mode);
 128 int google_chromeec_set_usb_pd_role(uint8_t port, enum usb_pd_control_role role);
 129 /*
 130  * Retrieve the charger type and max wattage.
 131  *
 132  * @param type      charger type
 133  * @param current_max charger max current
 134  * @param voltage_max charger max voltage
 135  * @return non-zero for error, otherwise 0.
 136  */
 137 int google_chromeec_get_usb_pd_power_info(enum usb_chg_type *type,
 138                                           uint16_t *current_max, uint16_t *voltage_max);
 139
 140 /* Check if a USB Power Delivery (PD) charger is attached */
 141 bool google_chromeec_is_usb_pd_attached(void);
 142
 143 /**
 144  * Check if charger is present.
 145  *
 146  * @return              true: if the charger is present
 147  *                      false: if the charger is not present
 148  */
 149 bool google_chromeec_is_charger_present(void);
 150
 151 /**
 152  * Check if barrel charger is present.
 153  *
 154  * @return              true: if the barrel charger is present
 155  *                      false: if the barrel charger is not present
 156  */
 157 bool google_chromeec_is_barrel_charger_present(void);
 158
 159 /*
 160  * Set max current and voltage of a dedicated charger.
 161  *
 162  * @param current_lim Max current in mA
 163  * @param voltage_lim Max voltage in mV
 164  * @return non-zero for error, otherwise 0.
 165  */
 166 int google_chromeec_override_dedicated_charger_limit(uint16_t current_lim,
 167                                                      uint16_t voltage_lim);
 168
 169 /* internal structure to send a command to the EC and wait for response. */
 170 struct chromeec_command {
 171         uint16_t    cmd_code;     /* command code in, status out */
 172         uint8_t     cmd_version;  /* command version */
 173         const void* cmd_data_in;  /* command data, if any */
 174         void*       cmd_data_out; /* command response, if any */
 175         uint16_t    cmd_size_in;  /* size of command data */
 176         uint16_t    cmd_size_out; /* expected size of command response in,
 177                                    * actual received size out */
 178         int         cmd_dev_index;/* device index for passthru */
 179 };
 180
 181 /*
 182  * There are transport level constraints for sending protov3 packets. Because
 183  * of this provide a way for the generic protocol layer to request buffers
 184  * so that there is zero copying being done through the layers.
 185  *
 186  * Request the buffer provided the size. If 'req' is non-zero then the
 187  * buffer requested is for EC requests. Otherwise it's for responses. Return
 188  * non-NULL on success, NULL on error.
 189  */
 190 void *crosec_get_buffer(size_t size, int req);
 191
 192 /*
 193  * The lower level transport works on the buffers handed out to the
 194  * upper level. Therefore, only the size of the request and response
 195  * are required.
 196  */
 197 typedef int (*crosec_io_t)(size_t req_size, size_t resp_size, void *context);
 198 int crosec_command_proto(struct chromeec_command *cec_command,
 199                          crosec_io_t crosec_io, void *context);
 200
 201 /**
 202  * Performs light verification of the EC<->AP communication channel.
 203  *
 204  * @return              0 on success, -1 on error
 205  */
 206 int google_chromeec_hello(void);
 207
 208 /**
 209  * Send a command to a CrOS EC
 210  *
 211  * @param cec_command: CrOS EC command to send
 212  * @return 0 for success. Non-zero for error.
 213  */
 214 int google_chromeec_command(struct chromeec_command *cec_command);
 215
 216 struct google_chromeec_event_info {
 217         uint64_t log_events;
 218         uint64_t sci_events;
 219         uint64_t smi_events;
 220         uint64_t s3_wake_events;
 221         uint64_t s3_device_events;
 222         uint64_t s5_wake_events;
 223         uint64_t s0ix_wake_events;
 224 };
 225 void google_chromeec_events_init(const struct google_chromeec_event_info *info,
 226                                         bool is_s3_wakeup);
 227
 228 /*
 229  * Get next available MKBP event in ec_response_get_next_event. Returns 0 on
 230  * success, < 0 otherwise.
 231  */
 232 int google_chromeec_get_mkbp_event(struct ec_response_get_next_event *event);
 233
 234 /* Log host events to eventlog based on the mask provided. */
 235 void google_chromeec_log_events(uint64_t mask);
 236
 237 /**
 238  * Protect/un-protect EC flash regions.
 239  *
 240  * @param mask          Set/clear the requested bits in 'flags'
 241  * @param flags         Flash protection flags
 242  * @param resp          Pointer to response structure
 243  * @return              0 on success, -1 on error
 244  */
 245 int google_chromeec_flash_protect(uint32_t mask, uint32_t flags,
 246                                   struct ec_response_flash_protect *resp);
 247 /**
 248  * Calculate image hash for vboot.
 249  *
 250  * @param hash_type     The hash types supported by the EC for vboot
 251  * @param offset        The offset to start hashing in flash
 252  * @param resp          Pointer to response structure
 253  * @return              0 on success, -1 on error
 254  */
 255 int google_chromeec_start_vboot_hash(enum ec_vboot_hash_type hash_type,
 256                                      uint32_t offset,
 257                                      struct ec_response_vboot_hash *resp);
 258 /**
 259  * Return the EC's vboot image hash.
 260  *
 261  * @param offset        Get hash for flash region beginning here
 262  * @param resp          Pointer to response structure
 263  * @return              0 on success, -1 on error
 264  *
 265  */
 266 int google_chromeec_get_vboot_hash(uint32_t offset,
 267                                    struct ec_response_vboot_hash *resp);
 268
 269 /**
 270  * Get offset and size of the specified EC flash region.
 271  *
 272  * @param region        Which region of EC flash
 273  * @param offset        Gets filled with region's offset
 274  * @param size          Gets filled with region's size
 275  * @return              0 on success, -1 on error
 276  */
 277 int google_chromeec_flash_region_info(enum ec_flash_region region,
 278                                       uint32_t *offset, uint32_t *size);
 279 /**
 280  * Erase a region of EC flash.
 281  *
 282  * @param offset        Where to begin erasing
 283  * @param size          Size of area to erase
 284  * @return              0 on success, -1 on error
 285  */
 286 int google_chromeec_flash_erase(uint32_t region_offset, uint32_t region_size);
 287
 288 /**
 289  * Return information about the entire flash.
 290  *
 291  * @param info          Pointer to response structure
 292  * @return              0 on success, -1 on error
 293  */
 294 int google_chromeec_flash_info(struct ec_response_flash_info *info);
 295
 296 /**
 297  * Write a block into EC flash.
 298  *
 299  * @param data          Pointer to data to write to flash, prefixed by a
 300  *                      struct ec_params_flash_write
 301  * @param offset        Offset to begin writing data
 302  * @param size          Number of bytes to be written to flash from data
 303  * @return              0 on success, -1 on error
 304  */
 305 int google_chromeec_flash_write_block(const uint8_t *data, uint32_t size);
 306
 307 /**
 308  * Verify flash using EFS if available.
 309  *
 310  * @param region        Which flash region to verify
 311  * @return              0 on success, -1 on error
 312  */
 313 int google_chromeec_efs_verify(enum ec_flash_region region);
 314
 315 /**
 316  * Command EC to perform battery cutoff.
 317  *
 318  * @param flags         Flags to pass to the EC
 319  * @return              0 on success, -1 on error
 320  */
 321 int google_chromeec_battery_cutoff(uint8_t flags);
 322
 323 /**
 324  * Check if the EC is requesting the system to limit input power.
 325  *
 326  * @param limit_power   If successful, limit_power is 1 if EC is requesting
 327  *                      input power limits, otherwise 0.
 328  * @return              0 on success, -1 on error
 329  */
 330 int google_chromeec_read_limit_power_request(int *limit_power);
 331
 332 /**
 333  * Get information about the protocol that the EC speaks.
 334  *
 335  * @param resp          Filled with host command protocol information.
 336  * @return              0 on success, -1 on error
 337  */
 338 int google_chromeec_get_protocol_info(
 339         struct ec_response_get_protocol_info *resp);
 340
 341 /**
 342  * Get available versions of the specified command.
 343  *
 344  * @param command       Command ID
 345  * @param pmask         Pointer to version mask
 346  * @return              0 on success, -1 on error
 347  */
 348 int google_chromeec_get_cmd_versions(int command, uint32_t *pmask);
 349
 350 /**
 351  * Get number of PD-capable USB ports from EC.
 352  *
 353  * @param *num_ports    If successful, num_ports is the number
 354  *                      of PD-capable USB ports according to the EC.
 355  * @return              0 on success, -1 on error
 356  */
 357 int google_chromeec_get_num_pd_ports(unsigned int *num_ports);
 358
 359 /**
 360  * Return a port's PD chip information.
 361  *
 362  * @param port          The desired port number
 363  * @param renew         Refresh cached value
 364  * @param r             Result buffer for chip info
 365  *
 366  * @return 0 if ok, -1 on error
 367  */
 368 int google_chromeec_get_pd_chip_info(int port, int renew,
 369                                 struct ec_response_pd_chip_info *r);
 370
 371 /* Structure representing the capabilities of a USB-PD port */
 372 struct usb_pd_port_caps {
 373         enum ec_pd_power_role_caps power_role_cap;
 374         enum ec_pd_try_power_role_caps try_power_role_cap;
 375         enum ec_pd_data_role_caps data_role_cap;
 376         enum ec_pd_port_location port_location;
 377 };
 378
 379 /**
 380  * Get role-based capabilities for a USB-PD port
 381  *
 382  * @param port                  Which port to get information about
 383  * @param *power_role_cap       The power-role capability of the port
 384  * @param *try_power_role_cap   The Try-power-role capability of the port
 385  * @param *data_role_cap        The data role capability of the port
 386  * @param *port_location        Location of the port on the device
 387  * @return                      0 on success, -1 on error
 388  */
 389 int google_chromeec_get_pd_port_caps(int port,
 390                                 struct usb_pd_port_caps *port_caps);
 391
 392 /**
 393  * Get the keyboard configuration / layout information from EC
 394  *
 395  * @param *keybd        If successful, this is filled with EC filled parameters
 396  * @return              0 on success, -1 on error
 397  */
 398 int google_chromeec_get_keybd_config(struct ec_response_keybd_config *keybd);
 399
 400 /**
 401  * Send EC command to perform AP reset
 402  *
 403  * @return      0 on success, -1 on error
 404  */
 405 int google_chromeec_ap_reset(void);
 406
 407 /**
 408  * Configure the regulator as enabled / disabled.
 409  *
 410  * @param index         Regulator ID
 411  * @param enable        Set to enable / disable the regulator
 412  * @return              0 on success, -1 on error
 413  */
 414 int google_chromeec_regulator_enable(uint32_t index, uint8_t enable);
 415
 416 /**
 417  * Query if the regulator is enabled.
 418  *
 419  * @param index         Regulator ID
 420  * @param *enabled      If successful, enabled indicates enable/disable status.
 421  * @return              0 on success, -1 on error
 422  */
 423 int google_chromeec_regulator_is_enabled(uint32_t index, uint8_t *enabled);
 424
 425 /**
 426  * Set voltage for the voltage regulator within the range specified.
 427  *
 428  * @param index         Regulator ID
 429  * @param min_mv        Minimum voltage
 430  * @param max_mv        Maximum voltage
 431  * @return              0 on success, -1 on error
 432  */
 433 int google_chromeec_regulator_set_voltage(uint32_t index, uint32_t min_mv,
 434                                           uint32_t max_mv);
 435
 436 /**
 437  * Get the currently configured voltage for the voltage regulator.
 438  *
 439  * @param index         Regulator ID
 440  * @param *voltage_mv   If successful, voltage_mv is filled with current voltage
 441  * @return              0 on success, -1 on error
 442  */
 443 int google_chromeec_regulator_get_voltage(uint32_t index, uint32_t *voltage_mv);
 444
 445 /**
 446  * Clear EC AP_IDLE flag
 447  */
 448 void google_chromeec_clear_ec_ap_idle(void);
 449
 450 /**
 451  * Check if battery is present and battery level is above critical threshold.
 452  *
 453  * @return              true: if the battery is present and battery level is above critical threshold
 454  *                      false: any of the above conditions is not true
 455  */
 456 bool google_chromeec_is_battery_present_and_above_critical_threshold(void);
 457
 458 /**
 459  * Check if battery level is below critical threshold.
 460  *
 461  * @return              true: if the battery level is below critical threshold
 462  *                      false: any the above conditions is not true
 463  */
 464 bool google_chromeec_is_below_critical_threshold(void);
 465
 466 /**
 467  * Check if battery is present.
 468  *
 469  * @return              true: if the battery is present
 470  *                      false: if the battery is not present
 471  */
 472 bool google_chromeec_is_battery_present(void);
 473
 474 /**
 475  * Determine if the UCSI stack is currently active.
 476  *
 477  * @return true if EC implements the UCSI stack
 478  */
 479 bool google_chromeec_get_ucsi_enabled(void);
 480
 481 #if CONFIG(HAVE_ACPI_TABLES)
 482 /**
 483  * Writes USB Type-C PD related information to the SSDT
 484  *
 485  * @param dev                   EC device
 486  */
 487 void google_chromeec_fill_ssdt_generator(const struct device *dev);
 488
 489 /**
 490  * Returns the ACPI name for the EC device.
 491  *
 492  * @param dev                   EC device
 493  */
 494 const char *google_chromeec_acpi_name(const struct device *dev);
 495
 496 #endif /* HAVE_ACPI_TABLES */
 497
 498 #endif /* _EC_GOOGLE_CHROMEEC_EC_H */