]>
Commit | Line | Data |
---|---|---|
9c92ab61 | 1 | /* SPDX-License-Identifier: GPL-2.0-only */ |
4ab6174e SG |
2 | /* |
3 | * ChromeOS EC multi-function device | |
4 | * | |
5 | * Copyright (C) 2012 Google, Inc | |
4ab6174e SG |
6 | */ |
7 | ||
8 | #ifndef __LINUX_MFD_CROS_EC_H | |
9 | #define __LINUX_MFD_CROS_EC_H | |
10 | ||
05c11ac4 | 11 | #include <linux/cdev.h> |
57b33ff0 | 12 | #include <linux/device.h> |
7e6cb5b4 | 13 | #include <linux/notifier.h> |
4ab6174e | 14 | #include <linux/mfd/cros_ec_commands.h> |
7e6cb5b4 | 15 | #include <linux/mutex.h> |
4ab6174e | 16 | |
57b33ff0 | 17 | #define CROS_EC_DEV_NAME "cros_ec" |
90486af5 | 18 | #define CROS_EC_DEV_FP_NAME "cros_fp" |
57b33ff0 | 19 | #define CROS_EC_DEV_PD_NAME "cros_pd" |
4f8f2bb7 | 20 | #define CROS_EC_DEV_TP_NAME "cros_tp" |
d4cee950 | 21 | #define CROS_EC_DEV_ISH_NAME "cros_ish" |
57b33ff0 | 22 | |
d3654070 SB |
23 | /* |
24 | * The EC is unresponsive for a time after a reboot command. Add a | |
25 | * simple delay to make sure that the bus stays locked. | |
26 | */ | |
27 | #define EC_REBOOT_DELAY_MS 50 | |
28 | ||
2c7589af SB |
29 | /* |
30 | * Max bus-specific overhead incurred by request/responses. | |
31 | * I2C requires 1 additional byte for requests. | |
32 | * I2C requires 2 additional bytes for responses. | |
b2376407 | 33 | * SPI requires up to 32 additional bytes for responses. |
e2bbf91c | 34 | */ |
2c7589af SB |
35 | #define EC_PROTO_VERSION_UNKNOWN 0 |
36 | #define EC_MAX_REQUEST_OVERHEAD 1 | |
b2376407 | 37 | #define EC_MAX_RESPONSE_OVERHEAD 32 |
2c7589af | 38 | |
4ab6174e SG |
39 | /* |
40 | * Command interface between EC and AP, for LPC, I2C and SPI interfaces. | |
41 | */ | |
42 | enum { | |
43 | EC_MSG_TX_HEADER_BYTES = 3, | |
44 | EC_MSG_TX_TRAILER_BYTES = 1, | |
45 | EC_MSG_TX_PROTO_BYTES = EC_MSG_TX_HEADER_BYTES + | |
46 | EC_MSG_TX_TRAILER_BYTES, | |
47 | EC_MSG_RX_PROTO_BYTES = 3, | |
48 | ||
5d749d0b GG |
49 | /* Max length of messages for proto 2*/ |
50 | EC_PROTO2_MSG_BYTES = EC_PROTO2_MAX_PARAM_SIZE + | |
5271db29 | 51 | EC_MSG_TX_PROTO_BYTES, |
5d749d0b GG |
52 | |
53 | EC_MAX_MSG_BYTES = 64 * 1024, | |
4ab6174e SG |
54 | }; |
55 | ||
e2bbf91c EBS |
56 | /** |
57 | * struct cros_ec_command - Information about a ChromeOS EC command. | |
58 | * @version: Command version number (often 0). | |
59 | * @command: Command to send (EC_CMD_...). | |
60 | * @outsize: Outgoing length in bytes. | |
61 | * @insize: Max number of bytes to accept from the EC. | |
62 | * @result: EC's response to the command (separate from communication failure). | |
63 | * @data: Where to put the incoming data from EC and outgoing data to EC. | |
4ab6174e | 64 | */ |
5d4773e2 BR |
65 | struct cros_ec_command { |
66 | uint32_t version; | |
67 | uint32_t command; | |
5d4773e2 | 68 | uint32_t outsize; |
5d4773e2 BR |
69 | uint32_t insize; |
70 | uint32_t result; | |
a8411784 | 71 | uint8_t data[0]; |
4ab6174e SG |
72 | }; |
73 | ||
74 | /** | |
e2bbf91c EBS |
75 | * struct cros_ec_device - Information about a ChromeOS EC device. |
76 | * @phys_name: Name of physical comms layer (e.g. 'i2c-4'). | |
05c11ac4 | 77 | * @dev: Device pointer for physical comms device |
e2bbf91c EBS |
78 | * @was_wake_device: True if this device was set to wake the system from |
79 | * sleep at the last suspend. | |
80 | * @cros_class: The class structure for this device. | |
81 | * @cmd_readmem: Direct read of the EC memory-mapped region, if supported. | |
82 | * @offset: Is within EC_LPC_ADDR_MEMMAP region. | |
83 | * @bytes: Number of bytes to read. zero means "read a string" (including | |
84 | * the trailing '\0'). At most only EC_MEMMAP_SIZE bytes can be | |
85 | * read. Caller must ensure that the buffer is large enough for the | |
86 | * result when reading a string. | |
87 | * @max_request: Max size of message requested. | |
88 | * @max_response: Max size of message response. | |
89 | * @max_passthru: Max sice of passthru message. | |
90 | * @proto_version: The protocol version used for this device. | |
91 | * @priv: Private data. | |
92 | * @irq: Interrupt to use. | |
93 | * @id: Device id. | |
94 | * @din: Input buffer (for data from EC). This buffer will always be | |
95 | * dword-aligned and include enough space for up to 7 word-alignment | |
96 | * bytes also, so we can ensure that the body of the message is always | |
97 | * dword-aligned (64-bit). We use this alignment to keep ARM and x86 | |
98 | * happy. Probably word alignment would be OK, there might be a small | |
99 | * performance advantage to using dword. | |
100 | * @dout: Output buffer (for data to EC). This buffer will always be | |
101 | * dword-aligned and include enough space for up to 7 word-alignment | |
102 | * bytes also, so we can ensure that the body of the message is always | |
103 | * dword-aligned (64-bit). We use this alignment to keep ARM and x86 | |
104 | * happy. Probably word alignment would be OK, there might be a small | |
105 | * performance advantage to using dword. | |
106 | * @din_size: Size of din buffer to allocate (zero to use static din). | |
107 | * @dout_size: Size of dout buffer to allocate (zero to use static dout). | |
108 | * @wake_enabled: True if this device can wake the system from sleep. | |
109 | * @suspended: True if this device had been suspended. | |
110 | * @cmd_xfer: Send command to EC and get response. | |
111 | * Returns the number of bytes received if the communication | |
112 | * succeeded, but that doesn't mean the EC was happy with the | |
113 | * command. The caller should check msg.result for the EC's result | |
114 | * code. | |
115 | * @pkt_xfer: Send packet to EC and get response. | |
116 | * @lock: One transaction at a time. | |
117 | * @mkbp_event_supported: True if this EC supports the MKBP event protocol. | |
7235560a | 118 | * @host_sleep_v1: True if this EC supports the sleep v1 command. |
e2bbf91c EBS |
119 | * @event_notifier: Interrupt event notifier for transport devices. |
120 | * @event_data: Raw payload transferred with the MKBP event. | |
121 | * @event_size: Size in bytes of the event data. | |
122 | * @host_event_wake_mask: Mask of host events that cause wake from suspend. | |
4ab6174e SG |
123 | */ |
124 | struct cros_ec_device { | |
7e6cb5b4 | 125 | /* These are used by other drivers that want to talk to the EC */ |
7e6cb5b4 BR |
126 | const char *phys_name; |
127 | struct device *dev; | |
128 | bool was_wake_device; | |
129 | struct class *cros_class; | |
05c11ac4 JMC |
130 | int (*cmd_readmem)(struct cros_ec_device *ec, unsigned int offset, |
131 | unsigned int bytes, void *dest); | |
7e6cb5b4 BR |
132 | |
133 | /* These are used to implement the platform-specific interface */ | |
2c7589af SB |
134 | u16 max_request; |
135 | u16 max_response; | |
136 | u16 max_passthru; | |
137 | u16 proto_version; | |
4ab6174e SG |
138 | void *priv; |
139 | int irq; | |
2c7589af SB |
140 | u8 *din; |
141 | u8 *dout; | |
4ab6174e SG |
142 | int din_size; |
143 | int dout_size; | |
4ab6174e | 144 | bool wake_enabled; |
a9eb186e | 145 | bool suspended; |
a6551a76 AB |
146 | int (*cmd_xfer)(struct cros_ec_device *ec, |
147 | struct cros_ec_command *msg); | |
2c7589af SB |
148 | int (*pkt_xfer)(struct cros_ec_device *ec, |
149 | struct cros_ec_command *msg); | |
7e6cb5b4 | 150 | struct mutex lock; |
6f1d912b | 151 | bool mkbp_event_supported; |
7235560a | 152 | bool host_sleep_v1; |
6f1d912b VY |
153 | struct blocking_notifier_head event_notifier; |
154 | ||
57e94c8b | 155 | struct ec_response_get_next_event_v1 event_data; |
6f1d912b | 156 | int event_size; |
29d99b96 | 157 | u32 host_event_wake_mask; |
4ab6174e SG |
158 | }; |
159 | ||
974e6f02 | 160 | /** |
e2bbf91c | 161 | * struct cros_ec_sensor_platform - ChromeOS EC sensor platform information. |
974e6f02 EBS |
162 | * @sensor_num: Id of the sensor, as reported by the EC. |
163 | */ | |
164 | struct cros_ec_sensor_platform { | |
165 | u8 sensor_num; | |
166 | }; | |
167 | ||
e2bbf91c EBS |
168 | /** |
169 | * struct cros_ec_platform - ChromeOS EC platform information. | |
170 | * @ec_name: Name of EC device (e.g. 'cros-ec', 'cros-pd', ...) | |
171 | * used in /dev/ and sysfs. | |
172 | * @cmd_offset: Offset to apply for each command. Set when | |
173 | * registering a device behind another one. | |
57b33ff0 GG |
174 | */ |
175 | struct cros_ec_platform { | |
176 | const char *ec_name; | |
177 | u16 cmd_offset; | |
178 | }; | |
179 | ||
e8626459 EC |
180 | struct cros_ec_debugfs; |
181 | ||
e2bbf91c EBS |
182 | /** |
183 | * struct cros_ec_dev - ChromeOS EC device entry point. | |
184 | * @class_dev: Device structure used in sysfs. | |
185 | * @cdev: Character device structure in /dev. | |
186 | * @ec_dev: cros_ec_device structure to talk to the physical device. | |
187 | * @dev: Pointer to the platform device. | |
188 | * @debug_info: cros_ec_debugfs structure for debugging information. | |
189 | * @has_kb_wake_angle: True if at least 2 accelerometer are connected to the EC. | |
190 | * @cmd_offset: Offset to apply for each command. | |
191 | * @features: Features supported by the EC. | |
57b33ff0 GG |
192 | */ |
193 | struct cros_ec_dev { | |
194 | struct device class_dev; | |
195 | struct cdev cdev; | |
196 | struct cros_ec_device *ec_dev; | |
197 | struct device *dev; | |
e8626459 | 198 | struct cros_ec_debugfs *debug_info; |
c1d1e91a | 199 | bool has_kb_wake_angle; |
57b33ff0 | 200 | u16 cmd_offset; |
e4244ebd | 201 | u32 features[2]; |
57b33ff0 GG |
202 | }; |
203 | ||
79a3d603 GG |
204 | #define to_cros_ec_dev(dev) container_of(dev, struct cros_ec_dev, class_dev) |
205 | ||
4ab6174e | 206 | /** |
e2bbf91c EBS |
207 | * cros_ec_suspend() - Handle a suspend operation for the ChromeOS EC device. |
208 | * @ec_dev: Device to suspend. | |
4ab6174e SG |
209 | * |
210 | * This can be called by drivers to handle a suspend event. | |
211 | * | |
e2bbf91c | 212 | * Return: 0 on success or negative error code. |
4ab6174e SG |
213 | */ |
214 | int cros_ec_suspend(struct cros_ec_device *ec_dev); | |
215 | ||
216 | /** | |
e2bbf91c EBS |
217 | * cros_ec_resume() - Handle a resume operation for the ChromeOS EC device. |
218 | * @ec_dev: Device to resume. | |
4ab6174e SG |
219 | * |
220 | * This can be called by drivers to handle a resume event. | |
221 | * | |
e2bbf91c | 222 | * Return: 0 on success or negative error code. |
4ab6174e SG |
223 | */ |
224 | int cros_ec_resume(struct cros_ec_device *ec_dev); | |
225 | ||
226 | /** | |
e2bbf91c EBS |
227 | * cros_ec_prepare_tx() - Prepare an outgoing message in the output buffer. |
228 | * @ec_dev: Device to register. | |
229 | * @msg: Message to write. | |
4ab6174e SG |
230 | * |
231 | * This is intended to be used by all ChromeOS EC drivers, but at present | |
232 | * only SPI uses it. Once LPC uses the same protocol it can start using it. | |
233 | * I2C could use it now, with a refactor of the existing code. | |
234 | * | |
e2bbf91c | 235 | * Return: 0 on success or negative error code. |
4ab6174e SG |
236 | */ |
237 | int cros_ec_prepare_tx(struct cros_ec_device *ec_dev, | |
5d4773e2 | 238 | struct cros_ec_command *msg); |
4ab6174e | 239 | |
6db07b63 | 240 | /** |
e2bbf91c EBS |
241 | * cros_ec_check_result() - Check ec_msg->result. |
242 | * @ec_dev: EC device. | |
243 | * @msg: Message to check. | |
6db07b63 BR |
244 | * |
245 | * This is used by ChromeOS EC drivers to check the ec_msg->result for | |
246 | * errors and to warn about them. | |
247 | * | |
e2bbf91c | 248 | * Return: 0 on success or negative error code. |
6db07b63 BR |
249 | */ |
250 | int cros_ec_check_result(struct cros_ec_device *ec_dev, | |
251 | struct cros_ec_command *msg); | |
252 | ||
a6551a76 | 253 | /** |
e2bbf91c EBS |
254 | * cros_ec_cmd_xfer() - Send a command to the ChromeOS EC. |
255 | * @ec_dev: EC device. | |
256 | * @msg: Message to write. | |
a6551a76 AB |
257 | * |
258 | * Call this to send a command to the ChromeOS EC. This should be used | |
259 | * instead of calling the EC's cmd_xfer() callback directly. | |
260 | * | |
e2bbf91c | 261 | * Return: 0 on success or negative error code. |
a6551a76 AB |
262 | */ |
263 | int cros_ec_cmd_xfer(struct cros_ec_device *ec_dev, | |
264 | struct cros_ec_command *msg); | |
9798ac6d TV |
265 | |
266 | /** | |
e2bbf91c EBS |
267 | * cros_ec_cmd_xfer_status() - Send a command to the ChromeOS EC. |
268 | * @ec_dev: EC device. | |
269 | * @msg: Message to write. | |
9798ac6d TV |
270 | * |
271 | * This function is identical to cros_ec_cmd_xfer, except it returns success | |
272 | * status only if both the command was transmitted successfully and the EC | |
273 | * replied with success status. It's not necessary to check msg->result when | |
274 | * using this function. | |
275 | * | |
e2bbf91c | 276 | * Return: The number of bytes transferred on success or negative error code. |
9798ac6d TV |
277 | */ |
278 | int cros_ec_cmd_xfer_status(struct cros_ec_device *ec_dev, | |
279 | struct cros_ec_command *msg); | |
a6551a76 | 280 | |
4ab6174e | 281 | /** |
e2bbf91c EBS |
282 | * cros_ec_register() - Register a new ChromeOS EC, using the provided info. |
283 | * @ec_dev: Device to register. | |
4ab6174e SG |
284 | * |
285 | * Before calling this, allocate a pointer to a new device and then fill | |
286 | * in all the fields up to the --private-- marker. | |
287 | * | |
e2bbf91c | 288 | * Return: 0 on success or negative error code. |
4ab6174e SG |
289 | */ |
290 | int cros_ec_register(struct cros_ec_device *ec_dev); | |
291 | ||
2c7589af | 292 | /** |
e2bbf91c EBS |
293 | * cros_ec_query_all() - Query the protocol version supported by the |
294 | * ChromeOS EC. | |
295 | * @ec_dev: Device to register. | |
2c7589af | 296 | * |
e2bbf91c | 297 | * Return: 0 on success or negative error code. |
2c7589af SB |
298 | */ |
299 | int cros_ec_query_all(struct cros_ec_device *ec_dev); | |
300 | ||
6f1d912b | 301 | /** |
e2bbf91c EBS |
302 | * cros_ec_get_next_event() - Fetch next event from the ChromeOS EC. |
303 | * @ec_dev: Device to fetch event from. | |
29d99b96 SN |
304 | * @wake_event: Pointer to a bool set to true upon return if the event might be |
305 | * treated as a wake event. Ignored if null. | |
6f1d912b | 306 | * |
475b0873 BN |
307 | * Return: negative error code on errors; 0 for no data; or else number of |
308 | * bytes received (i.e., an event was retrieved successfully). Event types are | |
309 | * written out to @ec_dev->event_data.event_type on success. | |
6f1d912b | 310 | */ |
29d99b96 | 311 | int cros_ec_get_next_event(struct cros_ec_device *ec_dev, bool *wake_event); |
6f1d912b | 312 | |
68c35ea2 | 313 | /** |
e2bbf91c EBS |
314 | * cros_ec_get_host_event() - Return a mask of event set by the ChromeOS EC. |
315 | * @ec_dev: Device to fetch event from. | |
68c35ea2 | 316 | * |
e2bbf91c EBS |
317 | * When MKBP is supported, when the EC raises an interrupt, we collect the |
318 | * events raised and call the functions in the ec notifier. This function | |
319 | * is a helper to know which events are raised. | |
68c35ea2 | 320 | * |
475b0873 | 321 | * Return: 0 on error or non-zero bitmask of one or more EC_HOST_EVENT_*. |
68c35ea2 GG |
322 | */ |
323 | u32 cros_ec_get_host_event(struct cros_ec_device *ec_dev); | |
324 | ||
4ab6174e | 325 | #endif /* __LINUX_MFD_CROS_EC_H */ |