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