1/* SPDX-License-Identifier: GPL-2.0 */ 2/* 3 * ChromeOS Embedded Controller protocol interface. 4 * 5 * Copyright (C) 2012 Google, Inc 6 */ 7 8#ifndef __LINUX_CROS_EC_PROTO_H 9#define __LINUX_CROS_EC_PROTO_H 10 11#include <linux/device.h> 12#include <linux/mutex.h> 13#include <linux/notifier.h> 14 15#include <linux/platform_data/cros_ec_commands.h> 16 17#define CROS_EC_DEV_NAME "cros_ec" 18#define CROS_EC_DEV_FP_NAME "cros_fp" 19#define CROS_EC_DEV_ISH_NAME "cros_ish" 20#define CROS_EC_DEV_PD_NAME "cros_pd" 21#define CROS_EC_DEV_SCP_NAME "cros_scp" 22#define CROS_EC_DEV_TP_NAME "cros_tp" 23 24/* 25 * The EC is unresponsive for a time after a reboot command. Add a 26 * simple delay to make sure that the bus stays locked. 27 */ 28#define EC_REBOOT_DELAY_MS 50 29 30/* 31 * Max bus-specific overhead incurred by request/responses. 32 * I2C requires 1 additional byte for requests. 33 * I2C requires 2 additional bytes for responses. 34 * SPI requires up to 32 additional bytes for responses. 35 */ 36#define EC_PROTO_VERSION_UNKNOWN 0 37#define EC_MAX_REQUEST_OVERHEAD 1 38#define EC_MAX_RESPONSE_OVERHEAD 32 39 40/* 41 * Command interface between EC and AP, for LPC, I2C and SPI interfaces. 42 */ 43enum { 44 EC_MSG_TX_HEADER_BYTES = 3, 45 EC_MSG_TX_TRAILER_BYTES = 1, 46 EC_MSG_TX_PROTO_BYTES = EC_MSG_TX_HEADER_BYTES + 47 EC_MSG_TX_TRAILER_BYTES, 48 EC_MSG_RX_PROTO_BYTES = 3, 49 50 /* Max length of messages for proto 2*/ 51 EC_PROTO2_MSG_BYTES = EC_PROTO2_MAX_PARAM_SIZE + 52 EC_MSG_TX_PROTO_BYTES, 53 54 EC_MAX_MSG_BYTES = 64 * 1024, 55}; 56 57/** 58 * struct cros_ec_command - Information about a ChromeOS EC command. 59 * @version: Command version number (often 0). 60 * @command: Command to send (EC_CMD_...). 61 * @outsize: Outgoing length in bytes. 62 * @insize: Max number of bytes to accept from the EC. 63 * @result: EC's response to the command (separate from communication failure). 64 * @data: Where to put the incoming data from EC and outgoing data to EC. 65 */ 66struct cros_ec_command { 67 uint32_t version; 68 uint32_t command; 69 uint32_t outsize; 70 uint32_t insize; 71 uint32_t result; 72 uint8_t data[]; 73}; 74 75/** 76 * struct cros_ec_device - Information about a ChromeOS EC device. 77 * @phys_name: Name of physical comms layer (e.g. 'i2c-4'). 78 * @dev: Device pointer for physical comms device 79 * @was_wake_device: True if this device was set to wake the system from 80 * sleep at the last suspend. 81 * @cros_class: The class structure for this device. 82 * @cmd_readmem: Direct read of the EC memory-mapped region, if supported. 83 * @offset: Is within EC_LPC_ADDR_MEMMAP region. 84 * @bytes: Number of bytes to read. zero means "read a string" (including 85 * the trailing '\0'). At most only EC_MEMMAP_SIZE bytes can be 86 * read. Caller must ensure that the buffer is large enough for the 87 * result when reading a string. 88 * @max_request: Max size of message requested. 89 * @max_response: Max size of message response. 90 * @max_passthru: Max sice of passthru message. 91 * @proto_version: The protocol version used for this device. 92 * @priv: Private data. 93 * @irq: Interrupt to use. 94 * @id: Device id. 95 * @din: Input buffer (for data from EC). This buffer will always be 96 * dword-aligned and include enough space for up to 7 word-alignment 97 * bytes also, so we can ensure that the body of the message is always 98 * dword-aligned (64-bit). We use this alignment to keep ARM and x86 99 * happy. Probably word alignment would be OK, there might be a small 100 * performance advantage to using dword. 101 * @dout: Output buffer (for data to EC). This buffer will always be 102 * dword-aligned and include enough space for up to 7 word-alignment 103 * bytes also, so we can ensure that the body of the message is always 104 * dword-aligned (64-bit). We use this alignment to keep ARM and x86 105 * happy. Probably word alignment would be OK, there might be a small 106 * performance advantage to using dword. 107 * @din_size: Size of din buffer to allocate (zero to use static din). 108 * @dout_size: Size of dout buffer to allocate (zero to use static dout). 109 * @wake_enabled: True if this device can wake the system from sleep. 110 * @suspended: True if this device had been suspended. 111 * @cmd_xfer: Send command to EC and get response. 112 * Returns the number of bytes received if the communication 113 * succeeded, but that doesn't mean the EC was happy with the 114 * command. The caller should check msg.result for the EC's result 115 * code. 116 * @pkt_xfer: Send packet to EC and get response. 117 * @lock: One transaction at a time. 118 * @mkbp_event_supported: 0 if MKBP not supported. Otherwise its value is 119 * the maximum supported version of the MKBP host event 120 * command + 1. 121 * @host_sleep_v1: True if this EC supports the sleep v1 command. 122 * @event_notifier: Interrupt event notifier for transport devices. 123 * @event_data: Raw payload transferred with the MKBP event. 124 * @event_size: Size in bytes of the event data. 125 * @host_event_wake_mask: Mask of host events that cause wake from suspend. 126 * @last_event_time: exact time from the hard irq when we got notified of 127 * a new event. 128 * @notifier_ready: The notifier_block to let the kernel re-query EC 129 * communication protocol when the EC sends 130 * EC_HOST_EVENT_INTERFACE_READY. 131 * @ec: The platform_device used by the mfd driver to interface with the 132 * main EC. 133 * @pd: The platform_device used by the mfd driver to interface with the 134 * PD behind an EC. 135 */ 136struct cros_ec_device { 137 /* These are used by other drivers that want to talk to the EC */ 138 const char *phys_name; 139 struct device *dev; 140 bool was_wake_device; 141 struct class *cros_class; 142 int (*cmd_readmem)(struct cros_ec_device *ec, unsigned int offset, 143 unsigned int bytes, void *dest); 144 145 /* These are used to implement the platform-specific interface */ 146 u16 max_request; 147 u16 max_response; 148 u16 max_passthru; 149 u16 proto_version; 150 void *priv; 151 int irq; 152 u8 *din; 153 u8 *dout; 154 int din_size; 155 int dout_size; 156 bool wake_enabled; 157 bool suspended; 158 int (*cmd_xfer)(struct cros_ec_device *ec, 159 struct cros_ec_command *msg); 160 int (*pkt_xfer)(struct cros_ec_device *ec, 161 struct cros_ec_command *msg); 162 struct mutex lock; 163 u8 mkbp_event_supported; 164 bool host_sleep_v1; 165 struct blocking_notifier_head event_notifier; 166 167 struct ec_response_get_next_event_v1 event_data; 168 int event_size; 169 u32 host_event_wake_mask; 170 u32 last_resume_result; 171 ktime_t last_event_time; 172 struct notifier_block notifier_ready; 173 174 /* The platform devices used by the mfd driver */ 175 struct platform_device *ec; 176 struct platform_device *pd; 177}; 178 179/** 180 * struct cros_ec_platform - ChromeOS EC platform information. 181 * @ec_name: Name of EC device (e.g. 'cros-ec', 'cros-pd', ...) 182 * used in /dev/ and sysfs. 183 * @cmd_offset: Offset to apply for each command. Set when 184 * registering a device behind another one. 185 */ 186struct cros_ec_platform { 187 const char *ec_name; 188 u16 cmd_offset; 189}; 190 191/** 192 * struct cros_ec_dev - ChromeOS EC device entry point. 193 * @class_dev: Device structure used in sysfs. 194 * @ec_dev: cros_ec_device structure to talk to the physical device. 195 * @dev: Pointer to the platform device. 196 * @debug_info: cros_ec_debugfs structure for debugging information. 197 * @has_kb_wake_angle: True if at least 2 accelerometer are connected to the EC. 198 * @cmd_offset: Offset to apply for each command. 199 * @features: Features supported by the EC. 200 */ 201struct cros_ec_dev { 202 struct device class_dev; 203 struct cros_ec_device *ec_dev; 204 struct device *dev; 205 struct cros_ec_debugfs *debug_info; 206 bool has_kb_wake_angle; 207 u16 cmd_offset; 208 u32 features[2]; 209}; 210 211#define to_cros_ec_dev(dev) container_of(dev, struct cros_ec_dev, class_dev) 212 213int cros_ec_prepare_tx(struct cros_ec_device *ec_dev, 214 struct cros_ec_command *msg); 215 216int cros_ec_check_result(struct cros_ec_device *ec_dev, 217 struct cros_ec_command *msg); 218 219int cros_ec_cmd_xfer_status(struct cros_ec_device *ec_dev, 220 struct cros_ec_command *msg); 221 222int cros_ec_query_all(struct cros_ec_device *ec_dev); 223 224int cros_ec_get_next_event(struct cros_ec_device *ec_dev, 225 bool *wake_event, 226 bool *has_more_events); 227 228u32 cros_ec_get_host_event(struct cros_ec_device *ec_dev); 229 230int cros_ec_check_features(struct cros_ec_dev *ec, int feature); 231 232int cros_ec_get_sensor_count(struct cros_ec_dev *ec); 233 234/** 235 * cros_ec_get_time_ns() - Return time in ns. 236 * 237 * This is the function used to record the time for last_event_time in struct 238 * cros_ec_device during the hard irq. 239 * 240 * Return: ktime_t format since boot. 241 */ 242static inline ktime_t cros_ec_get_time_ns(void) 243{ 244 return ktime_get_boottime_ns(); 245} 246 247#endif /* __LINUX_CROS_EC_PROTO_H */ 248