• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /* Copyright (c) 2013 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 /*
12  * Protocol overview
13  *
14  * request:  CMD [ P0 P1 P2 ... Pn S ]
15  * response: ERR [ P0 P1 P2 ... Pn S ]
16  *
17  * where the bytes are defined as follow :
18  *      - CMD is the command code. (defined by EC_CMD_ constants)
19  *      - ERR is the error code. (defined by EC_RES_ constants)
20  *      - Px is the optional payload.
21  *        it is not sent if the error code is not success.
22  *        (defined by ec_params_ and ec_response_ structures)
23  *      - S is the checksum which is the sum of all payload bytes.
24  *
25  * On LPC, CMD and ERR are sent/received at EC_LPC_ADDR_KERNEL|USER_CMD
26  * and the payloads are sent/received at EC_LPC_ADDR_KERNEL|USER_PARAM.
27  * On I2C, all bytes are sent serially in the same message.
28  */
29 
30 /* Current version of this protocol */
31 #define EC_PROTO_VERSION          0x00000002
32 
33 /* Command version mask */
34 #define EC_VER_MASK(version) (1UL << (version))
35 
36 /* I/O addresses for ACPI commands */
37 #define EC_LPC_ADDR_ACPI_DATA  0x62
38 #define EC_LPC_ADDR_ACPI_CMD   0x66
39 
40 /* I/O addresses for host command */
41 #define EC_LPC_ADDR_HOST_DATA  0x200
42 #define EC_LPC_ADDR_HOST_CMD   0x204
43 
44 /* I/O addresses for host command args and params */
45 /* Protocol version 2 */
46 #define EC_LPC_ADDR_HOST_ARGS    0x800  /* And 0x801, 0x802, 0x803 */
47 #define EC_LPC_ADDR_HOST_PARAM   0x804  /* For version 2 params; size is
48 					 * EC_PROTO2_MAX_PARAM_SIZE */
49 /* Protocol version 3 */
50 #define EC_LPC_ADDR_HOST_PACKET  0x800  /* Offset of version 3 packet */
51 #define EC_LPC_HOST_PACKET_SIZE  0x100  /* Max size of version 3 packet */
52 
53 /* The actual block is 0x800-0x8ff, but some BIOSes think it's 0x880-0x8ff
54  * and they tell the kernel that so we have to think of it as two parts. */
55 #define EC_HOST_CMD_REGION0    0x800
56 #define EC_HOST_CMD_REGION1    0x880
57 #define EC_HOST_CMD_REGION_SIZE 0x80
58 
59 /* EC command register bit functions */
60 #define EC_LPC_CMDR_DATA	(1 << 0)  /* Data ready for host to read */
61 #define EC_LPC_CMDR_PENDING	(1 << 1)  /* Write pending to EC */
62 #define EC_LPC_CMDR_BUSY	(1 << 2)  /* EC is busy processing a command */
63 #define EC_LPC_CMDR_CMD		(1 << 3)  /* Last host write was a command */
64 #define EC_LPC_CMDR_ACPI_BRST	(1 << 4)  /* Burst mode (not used) */
65 #define EC_LPC_CMDR_SCI		(1 << 5)  /* SCI event is pending */
66 #define EC_LPC_CMDR_SMI		(1 << 6)  /* SMI event is pending */
67 
68 #define EC_LPC_ADDR_MEMMAP       0x900
69 #define EC_MEMMAP_SIZE         255 /* ACPI IO buffer max is 255 bytes */
70 #define EC_MEMMAP_TEXT_MAX     8   /* Size of a string in the memory map */
71 
72 /* The offset address of each type of data in mapped memory. */
73 #define EC_MEMMAP_TEMP_SENSOR      0x00 /* Temp sensors */
74 #define EC_MEMMAP_FAN              0x10 /* Fan speeds */
75 #define EC_MEMMAP_TEMP_SENSOR_B    0x18 /* Temp sensors (second set) */
76 #define EC_MEMMAP_ID               0x20 /* 'E' 'C' */
77 #define EC_MEMMAP_ID_VERSION       0x22 /* Version of data in 0x20 - 0x2f */
78 #define EC_MEMMAP_THERMAL_VERSION  0x23 /* Version of data in 0x00 - 0x1f */
79 #define EC_MEMMAP_BATTERY_VERSION  0x24 /* Version of data in 0x40 - 0x7f */
80 #define EC_MEMMAP_SWITCHES_VERSION 0x25 /* Version of data in 0x30 - 0x33 */
81 #define EC_MEMMAP_EVENTS_VERSION   0x26 /* Version of data in 0x34 - 0x3f */
82 #define EC_MEMMAP_HOST_CMD_FLAGS   0x27 /* Host command interface flags */
83 #define EC_MEMMAP_SWITCHES         0x30
84 #define EC_MEMMAP_HOST_EVENTS      0x34
85 #define EC_MEMMAP_BATT_VOLT        0x40 /* Battery Present Voltage */
86 #define EC_MEMMAP_BATT_RATE        0x44 /* Battery Present Rate */
87 #define EC_MEMMAP_BATT_CAP         0x48 /* Battery Remaining Capacity */
88 #define EC_MEMMAP_BATT_FLAG        0x4c /* Battery State, defined below */
89 #define EC_MEMMAP_BATT_DCAP        0x50 /* Battery Design Capacity */
90 #define EC_MEMMAP_BATT_DVLT        0x54 /* Battery Design Voltage */
91 #define EC_MEMMAP_BATT_LFCC        0x58 /* Battery Last Full Charge Capacity */
92 #define EC_MEMMAP_BATT_CCNT        0x5c /* Battery Cycle Count */
93 #define EC_MEMMAP_BATT_MFGR        0x60 /* Battery Manufacturer String */
94 #define EC_MEMMAP_BATT_MODEL       0x68 /* Battery Model Number String */
95 #define EC_MEMMAP_BATT_SERIAL      0x70 /* Battery Serial Number String */
96 #define EC_MEMMAP_BATT_TYPE        0x78 /* Battery Type String */
97 
98 /* Number of temp sensors at EC_MEMMAP_TEMP_SENSOR */
99 #define EC_TEMP_SENSOR_ENTRIES     16
100 /*
101  * Number of temp sensors at EC_MEMMAP_TEMP_SENSOR_B.
102  *
103  * Valid only if EC_MEMMAP_THERMAL_VERSION returns >= 2.
104  */
105 #define EC_TEMP_SENSOR_B_ENTRIES      8
106 #define EC_TEMP_SENSOR_NOT_PRESENT    0xff
107 #define EC_TEMP_SENSOR_ERROR          0xfe
108 #define EC_TEMP_SENSOR_NOT_POWERED    0xfd
109 #define EC_TEMP_SENSOR_NOT_CALIBRATED 0xfc
110 /*
111  * The offset of temperature value stored in mapped memory.  This allows
112  * reporting a temperature range of 200K to 454K = -73C to 181C.
113  */
114 #define EC_TEMP_SENSOR_OFFSET      200
115 
116 #define EC_FAN_SPEED_ENTRIES       4       /* Number of fans at EC_MEMMAP_FAN */
117 #define EC_FAN_SPEED_NOT_PRESENT   0xffff  /* Entry not present */
118 #define EC_FAN_SPEED_STALLED       0xfffe  /* Fan stalled */
119 
120 /* Battery bit flags at EC_MEMMAP_BATT_FLAG. */
121 #define EC_BATT_FLAG_AC_PRESENT   0x01
122 #define EC_BATT_FLAG_BATT_PRESENT 0x02
123 #define EC_BATT_FLAG_DISCHARGING  0x04
124 #define EC_BATT_FLAG_CHARGING     0x08
125 #define EC_BATT_FLAG_LEVEL_CRITICAL 0x10
126 
127 /* Switch flags at EC_MEMMAP_SWITCHES */
128 #define EC_SWITCH_LID_OPEN               0x01
129 #define EC_SWITCH_POWER_BUTTON_PRESSED   0x02
130 #define EC_SWITCH_WRITE_PROTECT_DISABLED 0x04
131 /* Was recovery requested via keyboard; now unused. */
132 #define EC_SWITCH_IGNORE1		 0x08
133 /* Recovery requested via dedicated signal (from servo board) */
134 #define EC_SWITCH_DEDICATED_RECOVERY     0x10
135 /* Was fake developer mode switch; now unused.  Remove in next refactor. */
136 #define EC_SWITCH_IGNORE0                0x20
137 
138 /* Host command interface flags */
139 /* Host command interface supports LPC args (LPC interface only) */
140 #define EC_HOST_CMD_FLAG_LPC_ARGS_SUPPORTED  0x01
141 /* Host command interface supports version 3 protocol */
142 #define EC_HOST_CMD_FLAG_VERSION_3   0x02
143 
144 /* Wireless switch flags */
145 #define EC_WIRELESS_SWITCH_WLAN      0x01
146 #define EC_WIRELESS_SWITCH_BLUETOOTH 0x02
147 #define EC_WIRELESS_SWITCH_WWAN      0x04
148 
149 /*
150  * This header file is used in coreboot both in C and ACPI code.  The ACPI code
151  * is pre-processed to handle constants but the ASL compiler is unable to
152  * handle actual C code so keep it separate.
153  */
154 #ifndef __ACPI__
155 
156 /*
157  * Define __packed if someone hasn't beat us to it.  Linux kernel style
158  * checking prefers __packed over __attribute__((packed)).
159  */
160 #ifndef __packed
161 #define __packed __attribute__((packed))
162 #endif
163 
164 /* LPC command status byte masks */
165 /* EC has written a byte in the data register and host hasn't read it yet */
166 #define EC_LPC_STATUS_TO_HOST     0x01
167 /* Host has written a command/data byte and the EC hasn't read it yet */
168 #define EC_LPC_STATUS_FROM_HOST   0x02
169 /* EC is processing a command */
170 #define EC_LPC_STATUS_PROCESSING  0x04
171 /* Last write to EC was a command, not data */
172 #define EC_LPC_STATUS_LAST_CMD    0x08
173 /* EC is in burst mode.  Unsupported by Chrome EC, so this bit is never set */
174 #define EC_LPC_STATUS_BURST_MODE  0x10
175 /* SCI event is pending (requesting SCI query) */
176 #define EC_LPC_STATUS_SCI_PENDING 0x20
177 /* SMI event is pending (requesting SMI query) */
178 #define EC_LPC_STATUS_SMI_PENDING 0x40
179 /* (reserved) */
180 #define EC_LPC_STATUS_RESERVED    0x80
181 
182 /*
183  * EC is busy.  This covers both the EC processing a command, and the host has
184  * written a new command but the EC hasn't picked it up yet.
185  */
186 #define EC_LPC_STATUS_BUSY_MASK \
187 	(EC_LPC_STATUS_FROM_HOST | EC_LPC_STATUS_PROCESSING)
188 
189 /* Host command response codes */
190 enum ec_status {
191 	EC_RES_SUCCESS = 0,
192 	EC_RES_INVALID_COMMAND = 1,
193 	EC_RES_ERROR = 2,
194 	EC_RES_INVALID_PARAM = 3,
195 	EC_RES_ACCESS_DENIED = 4,
196 	EC_RES_INVALID_RESPONSE = 5,
197 	EC_RES_INVALID_VERSION = 6,
198 	EC_RES_INVALID_CHECKSUM = 7,
199 	EC_RES_IN_PROGRESS = 8,		/* Accepted, command in progress */
200 	EC_RES_UNAVAILABLE = 9,		/* No response available */
201 	EC_RES_TIMEOUT = 10,		/* We got a timeout */
202 	EC_RES_OVERFLOW = 11,		/* Table / data overflow */
203 	EC_RES_INVALID_HEADER = 12,     /* Header contains invalid data */
204 	EC_RES_REQUEST_TRUNCATED = 13,  /* Didn't get the entire request */
205 	EC_RES_RESPONSE_TOO_BIG = 14    /* Response was too big to handle */
206 };
207 
208 /*
209  * Host event codes.  Note these are 1-based, not 0-based, because ACPI query
210  * EC command uses code 0 to mean "no event pending".  We explicitly specify
211  * each value in the enum listing so they won't change if we delete/insert an
212  * item or rearrange the list (it needs to be stable across platforms, not
213  * just within a single compiled instance).
214  */
215 enum host_event_code {
216 	EC_HOST_EVENT_LID_CLOSED = 1,
217 	EC_HOST_EVENT_LID_OPEN = 2,
218 	EC_HOST_EVENT_POWER_BUTTON = 3,
219 	EC_HOST_EVENT_AC_CONNECTED = 4,
220 	EC_HOST_EVENT_AC_DISCONNECTED = 5,
221 	EC_HOST_EVENT_BATTERY_LOW = 6,
222 	EC_HOST_EVENT_BATTERY_CRITICAL = 7,
223 	EC_HOST_EVENT_BATTERY = 8,
224 	EC_HOST_EVENT_THERMAL_THRESHOLD = 9,
225 	EC_HOST_EVENT_THERMAL_OVERLOAD = 10,
226 	EC_HOST_EVENT_THERMAL = 11,
227 	EC_HOST_EVENT_USB_CHARGER = 12,
228 	EC_HOST_EVENT_KEY_PRESSED = 13,
229 	/*
230 	 * EC has finished initializing the host interface.  The host can check
231 	 * for this event following sending a EC_CMD_REBOOT_EC command to
232 	 * determine when the EC is ready to accept subsequent commands.
233 	 */
234 	EC_HOST_EVENT_INTERFACE_READY = 14,
235 	/* Keyboard recovery combo has been pressed */
236 	EC_HOST_EVENT_KEYBOARD_RECOVERY = 15,
237 
238 	/* Shutdown due to thermal overload */
239 	EC_HOST_EVENT_THERMAL_SHUTDOWN = 16,
240 	/* Shutdown due to battery level too low */
241 	EC_HOST_EVENT_BATTERY_SHUTDOWN = 17,
242 
243 	/*
244 	 * The high bit of the event mask is not used as a host event code.  If
245 	 * it reads back as set, then the entire event mask should be
246 	 * considered invalid by the host.  This can happen when reading the
247 	 * raw event status via EC_MEMMAP_HOST_EVENTS but the LPC interface is
248 	 * not initialized on the EC, or improperly configured on the host.
249 	 */
250 	EC_HOST_EVENT_INVALID = 32
251 };
252 /* Host event mask */
253 #define EC_HOST_EVENT_MASK(event_code) (1UL << ((event_code) - 1))
254 
255 /* Arguments at EC_LPC_ADDR_HOST_ARGS */
256 struct ec_lpc_host_args {
257 	uint8_t flags;
258 	uint8_t command_version;
259 	uint8_t data_size;
260 	/*
261 	 * Checksum; sum of command + flags + command_version + data_size +
262 	 * all params/response data bytes.
263 	 */
264 	uint8_t checksum;
265 } __packed;
266 
267 /* Flags for ec_lpc_host_args.flags */
268 /*
269  * Args are from host.  Data area at EC_LPC_ADDR_HOST_PARAM contains command
270  * params.
271  *
272  * If EC gets a command and this flag is not set, this is an old-style command.
273  * Command version is 0 and params from host are at EC_LPC_ADDR_OLD_PARAM with
274  * unknown length.  EC must respond with an old-style response (that is,
275  * withouth setting EC_HOST_ARGS_FLAG_TO_HOST).
276  */
277 #define EC_HOST_ARGS_FLAG_FROM_HOST 0x01
278 /*
279  * Args are from EC.  Data area at EC_LPC_ADDR_HOST_PARAM contains response.
280  *
281  * If EC responds to a command and this flag is not set, this is an old-style
282  * response.  Command version is 0 and response data from EC is at
283  * EC_LPC_ADDR_OLD_PARAM with unknown length.
284  */
285 #define EC_HOST_ARGS_FLAG_TO_HOST   0x02
286 
287 /*****************************************************************************/
288 
289 /*
290  * Protocol version 2 for I2C and SPI send a request this way:
291  *
292  *	0	EC_CMD_VERSION0 + (command version)
293  *	1	Command number
294  *	2	Length of params = N
295  *	3..N+2	Params, if any
296  *	N+3	8-bit checksum of bytes 0..N+2
297  *
298  * The corresponding response is:
299  *
300  *	0	Result code (EC_RES_*)
301  *	1	Length of params = M
302  *	2..M+1	Params, if any
303  *	M+2	8-bit checksum of bytes 0..M+1
304  */
305 #define EC_PROTO2_REQUEST_HEADER_BYTES 3
306 #define EC_PROTO2_REQUEST_TRAILER_BYTES 1
307 #define EC_PROTO2_REQUEST_OVERHEAD (EC_PROTO2_REQUEST_HEADER_BYTES +	\
308 				    EC_PROTO2_REQUEST_TRAILER_BYTES)
309 
310 #define EC_PROTO2_RESPONSE_HEADER_BYTES 2
311 #define EC_PROTO2_RESPONSE_TRAILER_BYTES 1
312 #define EC_PROTO2_RESPONSE_OVERHEAD (EC_PROTO2_RESPONSE_HEADER_BYTES +	\
313 				     EC_PROTO2_RESPONSE_TRAILER_BYTES)
314 
315 /* Parameter length was limited by the LPC interface */
316 #define EC_PROTO2_MAX_PARAM_SIZE 0xfc
317 
318 /* Maximum request and response packet sizes for protocol version 2 */
319 #define EC_PROTO2_MAX_REQUEST_SIZE (EC_PROTO2_REQUEST_OVERHEAD +	\
320 				    EC_PROTO2_MAX_PARAM_SIZE)
321 #define EC_PROTO2_MAX_RESPONSE_SIZE (EC_PROTO2_RESPONSE_OVERHEAD +	\
322 				     EC_PROTO2_MAX_PARAM_SIZE)
323 
324 /*****************************************************************************/
325 
326 /*
327  * Value written to legacy command port / prefix byte to indicate protocol
328  * 3+ structs are being used.  Usage is bus-dependent.
329  */
330 #define EC_COMMAND_PROTOCOL_3 0xda
331 
332 #define EC_HOST_REQUEST_VERSION 3
333 
334 /* Version 3 request from host */
335 struct ec_host_request {
336 	/* Struct version (=3)
337 	 *
338 	 * EC will return EC_RES_INVALID_HEADER if it receives a header with a
339 	 * version it doesn't know how to parse.
340 	 */
341 	uint8_t struct_version;
342 
343 	/*
344 	 * Checksum of request and data; sum of all bytes including checksum
345 	 * should total to 0.
346 	 */
347 	uint8_t checksum;
348 
349 	/* Command code */
350 	uint16_t command;
351 
352 	/* Command version */
353 	uint8_t command_version;
354 
355 	/* Unused byte in current protocol version; set to 0 */
356 	uint8_t reserved;
357 
358 	/* Length of data which follows this header */
359 	uint16_t data_len;
360 } __packed;
361 
362 #define EC_HOST_RESPONSE_VERSION 3
363 
364 /* Version 3 response from EC */
365 struct ec_host_response {
366 	/* Struct version (=3) */
367 	uint8_t struct_version;
368 
369 	/*
370 	 * Checksum of response and data; sum of all bytes including checksum
371 	 * should total to 0.
372 	 */
373 	uint8_t checksum;
374 
375 	/* Result code (EC_RES_*) */
376 	uint16_t result;
377 
378 	/* Length of data which follows this header */
379 	uint16_t data_len;
380 
381 	/* Unused bytes in current protocol version; set to 0 */
382 	uint16_t reserved;
383 } __packed;
384 
385 /*****************************************************************************/
386 /*
387  * Notes on commands:
388  *
389  * Each command is an 8-byte command value.  Commands which take params or
390  * return response data specify structs for that data.  If no struct is
391  * specified, the command does not input or output data, respectively.
392  * Parameter/response length is implicit in the structs.  Some underlying
393  * communication protocols (I2C, SPI) may add length or checksum headers, but
394  * those are implementation-dependent and not defined here.
395  */
396 
397 /*****************************************************************************/
398 /* General / test commands */
399 
400 /*
401  * Get protocol version, used to deal with non-backward compatible protocol
402  * changes.
403  */
404 #define EC_CMD_PROTO_VERSION 0x00
405 
406 struct ec_response_proto_version {
407 	uint32_t version;
408 } __packed;
409 
410 /*
411  * Hello.  This is a simple command to test the EC is responsive to
412  * commands.
413  */
414 #define EC_CMD_HELLO 0x01
415 
416 struct ec_params_hello {
417 	uint32_t in_data;  /* Pass anything here */
418 } __packed;
419 
420 struct ec_response_hello {
421 	uint32_t out_data;  /* Output will be in_data + 0x01020304 */
422 } __packed;
423 
424 /* Get version number */
425 #define EC_CMD_GET_VERSION 0x02
426 
427 enum ec_current_image {
428 	EC_IMAGE_UNKNOWN = 0,
429 	EC_IMAGE_RO,
430 	EC_IMAGE_RW
431 };
432 
433 struct ec_response_get_version {
434 	/* Null-terminated version strings for RO, RW */
435 	char version_string_ro[32];
436 	char version_string_rw[32];
437 	char reserved[32];       /* Was previously RW-B string */
438 	uint32_t current_image;  /* One of ec_current_image */
439 } __packed;
440 
441 /* Read test */
442 #define EC_CMD_READ_TEST 0x03
443 
444 struct ec_params_read_test {
445 	uint32_t offset;   /* Starting value for read buffer */
446 	uint32_t size;     /* Size to read in bytes */
447 } __packed;
448 
449 struct ec_response_read_test {
450 	uint32_t data[32];
451 } __packed;
452 
453 /*
454  * Get build information
455  *
456  * Response is null-terminated string.
457  */
458 #define EC_CMD_GET_BUILD_INFO 0x04
459 
460 /* Get chip info */
461 #define EC_CMD_GET_CHIP_INFO 0x05
462 
463 struct ec_response_get_chip_info {
464 	/* Null-terminated strings */
465 	char vendor[32];
466 	char name[32];
467 	char revision[32];  /* Mask version */
468 } __packed;
469 
470 /* Get board HW version */
471 #define EC_CMD_GET_BOARD_VERSION 0x06
472 
473 struct ec_response_board_version {
474 	uint16_t board_version;  /* A monotonously incrementing number. */
475 } __packed;
476 
477 /*
478  * Read memory-mapped data.
479  *
480  * This is an alternate interface to memory-mapped data for bus protocols
481  * which don't support direct-mapped memory - I2C, SPI, etc.
482  *
483  * Response is params.size bytes of data.
484  */
485 #define EC_CMD_READ_MEMMAP 0x07
486 
487 struct ec_params_read_memmap {
488 	uint8_t offset;   /* Offset in memmap (EC_MEMMAP_*) */
489 	uint8_t size;     /* Size to read in bytes */
490 } __packed;
491 
492 /* Read versions supported for a command */
493 #define EC_CMD_GET_CMD_VERSIONS 0x08
494 
495 struct ec_params_get_cmd_versions {
496 	uint8_t cmd;      /* Command to check */
497 } __packed;
498 
499 struct ec_response_get_cmd_versions {
500 	/*
501 	 * Mask of supported versions; use EC_VER_MASK() to compare with a
502 	 * desired version.
503 	 */
504 	uint32_t version_mask;
505 } __packed;
506 
507 /*
508  * Check EC communcations status (busy). This is needed on i2c/spi but not
509  * on lpc since it has its own out-of-band busy indicator.
510  *
511  * lpc must read the status from the command register. Attempting this on
512  * lpc will overwrite the args/parameter space and corrupt its data.
513  */
514 #define EC_CMD_GET_COMMS_STATUS		0x09
515 
516 /* Avoid using ec_status which is for return values */
517 enum ec_comms_status {
518 	EC_COMMS_STATUS_PROCESSING	= 1 << 0,	/* Processing cmd */
519 };
520 
521 struct ec_response_get_comms_status {
522 	uint32_t flags;		/* Mask of enum ec_comms_status */
523 } __packed;
524 
525 /*
526  * Fake a variety of responses, purely for testing purposes.
527  * FIXME: Would be nice to force checksum errors.
528  */
529 #define EC_CMD_TEST_PROTOCOL		0x0a
530 
531 /* Tell the EC what to send back to us. */
532 struct ec_params_test_protocol {
533 	uint32_t ec_result;
534 	uint32_t ret_len;
535 	uint8_t buf[32];
536 } __packed;
537 
538 /* Here it comes... */
539 struct ec_response_test_protocol {
540 	uint8_t buf[32];
541 } __packed;
542 
543 /* Get prococol information */
544 #define EC_CMD_GET_PROTOCOL_INFO	0x0b
545 
546 /* Flags for ec_response_get_protocol_info.flags */
547 /* EC_RES_IN_PROGRESS may be returned if a command is slow */
548 #define EC_PROTOCOL_INFO_IN_PROGRESS_SUPPORTED (1 << 0)
549 
550 struct ec_response_get_protocol_info {
551 	/* Fields which exist if at least protocol version 3 supported */
552 
553 	/* Bitmask of protocol versions supported (1 << n means version n)*/
554 	uint32_t protocol_versions;
555 
556 	/* Maximum request packet size, in bytes */
557 	uint16_t max_request_packet_size;
558 
559 	/* Maximum response packet size, in bytes */
560 	uint16_t max_response_packet_size;
561 
562 	/* Flags; see EC_PROTOCOL_INFO_* */
563 	uint32_t flags;
564 } __packed;
565 
566 /*****************************************************************************/
567 /* Flash commands */
568 
569 /* Get flash info */
570 #define EC_CMD_FLASH_INFO 0x10
571 
572 struct ec_response_flash_info {
573 	/* Usable flash size, in bytes */
574 	uint32_t flash_size;
575 	/*
576 	 * Write block size.  Write offset and size must be a multiple
577 	 * of this.
578 	 */
579 	uint32_t write_block_size;
580 	/*
581 	 * Erase block size.  Erase offset and size must be a multiple
582 	 * of this.
583 	 */
584 	uint32_t erase_block_size;
585 	/*
586 	 * Protection block size.  Protection offset and size must be a
587 	 * multiple of this.
588 	 */
589 	uint32_t protect_block_size;
590 } __packed;
591 
592 /*
593  * Read flash
594  *
595  * Response is params.size bytes of data.
596  */
597 #define EC_CMD_FLASH_READ 0x11
598 
599 struct ec_params_flash_read {
600 	uint32_t offset;   /* Byte offset to read */
601 	uint32_t size;     /* Size to read in bytes */
602 } __packed;
603 
604 /* Write flash */
605 #define EC_CMD_FLASH_WRITE 0x12
606 #define EC_VER_FLASH_WRITE 1
607 
608 /* Version 0 of the flash command supported only 64 bytes of data */
609 #define EC_FLASH_WRITE_VER0_SIZE 64
610 
611 struct ec_params_flash_write {
612 	uint32_t offset;   /* Byte offset to write */
613 	uint32_t size;     /* Size to write in bytes */
614 	/* Followed by data to write */
615 } __packed;
616 
617 /* Erase flash */
618 #define EC_CMD_FLASH_ERASE 0x13
619 
620 struct ec_params_flash_erase {
621 	uint32_t offset;   /* Byte offset to erase */
622 	uint32_t size;     /* Size to erase in bytes */
623 } __packed;
624 
625 /*
626  * Get/set flash protection.
627  *
628  * If mask!=0, sets/clear the requested bits of flags.  Depending on the
629  * firmware write protect GPIO, not all flags will take effect immediately;
630  * some flags require a subsequent hard reset to take effect.  Check the
631  * returned flags bits to see what actually happened.
632  *
633  * If mask=0, simply returns the current flags state.
634  */
635 #define EC_CMD_FLASH_PROTECT 0x15
636 #define EC_VER_FLASH_PROTECT 1  /* Command version 1 */
637 
638 /* Flags for flash protection */
639 /* RO flash code protected when the EC boots */
640 #define EC_FLASH_PROTECT_RO_AT_BOOT         (1 << 0)
641 /*
642  * RO flash code protected now.  If this bit is set, at-boot status cannot
643  * be changed.
644  */
645 #define EC_FLASH_PROTECT_RO_NOW             (1 << 1)
646 /* Entire flash code protected now, until reboot. */
647 #define EC_FLASH_PROTECT_ALL_NOW            (1 << 2)
648 /* Flash write protect GPIO is asserted now */
649 #define EC_FLASH_PROTECT_GPIO_ASSERTED      (1 << 3)
650 /* Error - at least one bank of flash is stuck locked, and cannot be unlocked */
651 #define EC_FLASH_PROTECT_ERROR_STUCK        (1 << 4)
652 /*
653  * Error - flash protection is in inconsistent state.  At least one bank of
654  * flash which should be protected is not protected.  Usually fixed by
655  * re-requesting the desired flags, or by a hard reset if that fails.
656  */
657 #define EC_FLASH_PROTECT_ERROR_INCONSISTENT (1 << 5)
658 /* Entile flash code protected when the EC boots */
659 #define EC_FLASH_PROTECT_ALL_AT_BOOT        (1 << 6)
660 
661 struct ec_params_flash_protect {
662 	uint32_t mask;   /* Bits in flags to apply */
663 	uint32_t flags;  /* New flags to apply */
664 } __packed;
665 
666 struct ec_response_flash_protect {
667 	/* Current value of flash protect flags */
668 	uint32_t flags;
669 	/*
670 	 * Flags which are valid on this platform.  This allows the caller
671 	 * to distinguish between flags which aren't set vs. flags which can't
672 	 * be set on this platform.
673 	 */
674 	uint32_t valid_flags;
675 	/* Flags which can be changed given the current protection state */
676 	uint32_t writable_flags;
677 } __packed;
678 
679 /*
680  * Note: commands 0x14 - 0x19 version 0 were old commands to get/set flash
681  * write protect.  These commands may be reused with version > 0.
682  */
683 
684 /* Get the region offset/size */
685 #define EC_CMD_FLASH_REGION_INFO 0x16
686 #define EC_VER_FLASH_REGION_INFO 1
687 
688 enum ec_flash_region {
689 	/* Region which holds read-only EC image */
690 	EC_FLASH_REGION_RO = 0,
691 	/* Region which holds rewritable EC image */
692 	EC_FLASH_REGION_RW,
693 	/*
694 	 * Region which should be write-protected in the factory (a superset of
695 	 * EC_FLASH_REGION_RO)
696 	 */
697 	EC_FLASH_REGION_WP_RO,
698 	/* Number of regions */
699 	EC_FLASH_REGION_COUNT,
700 };
701 
702 struct ec_params_flash_region_info {
703 	uint32_t region;  /* enum ec_flash_region */
704 } __packed;
705 
706 struct ec_response_flash_region_info {
707 	uint32_t offset;
708 	uint32_t size;
709 } __packed;
710 
711 /* Read/write VbNvContext */
712 #define EC_CMD_VBNV_CONTEXT 0x17
713 #define EC_VER_VBNV_CONTEXT 1
714 #define EC_VBNV_BLOCK_SIZE 16
715 
716 enum ec_vbnvcontext_op {
717 	EC_VBNV_CONTEXT_OP_READ,
718 	EC_VBNV_CONTEXT_OP_WRITE,
719 };
720 
721 struct ec_params_vbnvcontext {
722 	uint32_t op;
723 	uint8_t block[EC_VBNV_BLOCK_SIZE];
724 } __packed;
725 
726 struct ec_response_vbnvcontext {
727 	uint8_t block[EC_VBNV_BLOCK_SIZE];
728 } __packed;
729 
730 /*****************************************************************************/
731 /* PWM commands */
732 
733 /* Get fan target RPM */
734 #define EC_CMD_PWM_GET_FAN_TARGET_RPM 0x20
735 
736 struct ec_response_pwm_get_fan_rpm {
737 	uint32_t rpm;
738 } __packed;
739 
740 /* Set target fan RPM */
741 #define EC_CMD_PWM_SET_FAN_TARGET_RPM 0x21
742 
743 struct ec_params_pwm_set_fan_target_rpm {
744 	uint32_t rpm;
745 } __packed;
746 
747 /* Get keyboard backlight */
748 #define EC_CMD_PWM_GET_KEYBOARD_BACKLIGHT 0x22
749 
750 struct ec_response_pwm_get_keyboard_backlight {
751 	uint8_t percent;
752 	uint8_t enabled;
753 } __packed;
754 
755 /* Set keyboard backlight */
756 #define EC_CMD_PWM_SET_KEYBOARD_BACKLIGHT 0x23
757 
758 struct ec_params_pwm_set_keyboard_backlight {
759 	uint8_t percent;
760 } __packed;
761 
762 /* Set target fan PWM duty cycle */
763 #define EC_CMD_PWM_SET_FAN_DUTY 0x24
764 
765 struct ec_params_pwm_set_fan_duty {
766 	uint32_t percent;
767 } __packed;
768 
769 /*****************************************************************************/
770 /*
771  * Lightbar commands. This looks worse than it is. Since we only use one HOST
772  * command to say "talk to the lightbar", we put the "and tell it to do X" part
773  * into a subcommand. We'll make separate structs for subcommands with
774  * different input args, so that we know how much to expect.
775  */
776 #define EC_CMD_LIGHTBAR_CMD 0x28
777 
778 struct rgb_s {
779 	uint8_t r, g, b;
780 };
781 
782 #define LB_BATTERY_LEVELS 4
783 /* List of tweakable parameters. NOTE: It's __packed so it can be sent in a
784  * host command, but the alignment is the same regardless. Keep it that way.
785  */
786 struct lightbar_params {
787 	/* Timing */
788 	int google_ramp_up;
789 	int google_ramp_down;
790 	int s3s0_ramp_up;
791 	int s0_tick_delay[2];			/* AC=0/1 */
792 	int s0a_tick_delay[2];			/* AC=0/1 */
793 	int s0s3_ramp_down;
794 	int s3_sleep_for;
795 	int s3_ramp_up;
796 	int s3_ramp_down;
797 
798 	/* Oscillation */
799 	uint8_t new_s0;
800 	uint8_t osc_min[2];			/* AC=0/1 */
801 	uint8_t osc_max[2];			/* AC=0/1 */
802 	uint8_t w_ofs[2];			/* AC=0/1 */
803 
804 	/* Brightness limits based on the backlight and AC. */
805 	uint8_t bright_bl_off_fixed[2];		/* AC=0/1 */
806 	uint8_t bright_bl_on_min[2];		/* AC=0/1 */
807 	uint8_t bright_bl_on_max[2];		/* AC=0/1 */
808 
809 	/* Battery level thresholds */
810 	uint8_t battery_threshold[LB_BATTERY_LEVELS - 1];
811 
812 	/* Map [AC][battery_level] to color index */
813 	uint8_t s0_idx[2][LB_BATTERY_LEVELS];	/* AP is running */
814 	uint8_t s3_idx[2][LB_BATTERY_LEVELS];	/* AP is sleeping */
815 
816 	/* Color palette */
817 	struct rgb_s color[8];			/* 0-3 are Google colors */
818 } __packed;
819 
820 struct ec_params_lightbar {
821 	uint8_t cmd;		      /* Command (see enum lightbar_command) */
822 	union {
823 		struct {
824 			/* no args */
825 		} dump, off, on, init, get_seq, get_params;
826 
827 		struct num {
828 			uint8_t num;
829 		} brightness, seq, demo;
830 
831 		struct reg {
832 			uint8_t ctrl, reg, value;
833 		} reg;
834 
835 		struct rgb {
836 			uint8_t led, red, green, blue;
837 		} rgb;
838 
839 		struct lightbar_params set_params;
840 	};
841 } __packed;
842 
843 struct ec_response_lightbar {
844 	union {
845 		struct dump {
846 			struct {
847 				uint8_t reg;
848 				uint8_t ic0;
849 				uint8_t ic1;
850 			} vals[23];
851 		} dump;
852 
853 		struct get_seq {
854 			uint8_t num;
855 		} get_seq;
856 
857 		struct lightbar_params get_params;
858 
859 		struct {
860 			/* no return params */
861 		} off, on, init, brightness, seq, reg, rgb, demo, set_params;
862 	};
863 } __packed;
864 
865 /* Lightbar commands */
866 enum lightbar_command {
867 	LIGHTBAR_CMD_DUMP = 0,
868 	LIGHTBAR_CMD_OFF = 1,
869 	LIGHTBAR_CMD_ON = 2,
870 	LIGHTBAR_CMD_INIT = 3,
871 	LIGHTBAR_CMD_BRIGHTNESS = 4,
872 	LIGHTBAR_CMD_SEQ = 5,
873 	LIGHTBAR_CMD_REG = 6,
874 	LIGHTBAR_CMD_RGB = 7,
875 	LIGHTBAR_CMD_GET_SEQ = 8,
876 	LIGHTBAR_CMD_DEMO = 9,
877 	LIGHTBAR_CMD_GET_PARAMS = 10,
878 	LIGHTBAR_CMD_SET_PARAMS = 11,
879 	LIGHTBAR_NUM_CMDS
880 };
881 
882 /*****************************************************************************/
883 /* LED control commands */
884 
885 #define EC_CMD_LED_CONTROL 0x29
886 
887 enum ec_led_id {
888 	EC_LED_ID_BATTERY_LED = 0,
889 	EC_LED_ID_POWER_BUTTON_LED,
890 	EC_LED_ID_ADAPTER_LED,
891 };
892 
893 /* LED control flags */
894 #define EC_LED_FLAGS_QUERY (1 << 0) /* Query LED capability only */
895 #define EC_LED_FLAGS_AUTO  (1 << 1) /* Switch LED back to automatic control */
896 
897 enum ec_led_colors {
898 	EC_LED_COLOR_RED = 0,
899 	EC_LED_COLOR_GREEN,
900 	EC_LED_COLOR_BLUE,
901 	EC_LED_COLOR_YELLOW,
902 	EC_LED_COLOR_WHITE,
903 
904 	EC_LED_COLOR_COUNT
905 };
906 
907 struct ec_params_led_control {
908 	uint8_t led_id;     /* Which LED to control */
909 	uint8_t flags;      /* Control flags */
910 
911 	uint8_t brightness[EC_LED_COLOR_COUNT];
912 } __packed;
913 
914 struct ec_response_led_control {
915 	/*
916 	 * Available brightness value range.
917 	 *
918 	 * Range 0 means color channel not present.
919 	 * Range 1 means on/off control.
920 	 * Other values means the LED is control by PWM.
921 	 */
922 	uint8_t brightness_range[EC_LED_COLOR_COUNT];
923 } __packed;
924 
925 /*****************************************************************************/
926 /* Verified boot commands */
927 
928 /*
929  * Note: command code 0x29 version 0 was VBOOT_CMD in Link EVT; it may be
930  * reused for other purposes with version > 0.
931  */
932 
933 /* Verified boot hash command */
934 #define EC_CMD_VBOOT_HASH 0x2A
935 
936 struct ec_params_vboot_hash {
937 	uint8_t cmd;             /* enum ec_vboot_hash_cmd */
938 	uint8_t hash_type;       /* enum ec_vboot_hash_type */
939 	uint8_t nonce_size;      /* Nonce size; may be 0 */
940 	uint8_t reserved0;       /* Reserved; set 0 */
941 	uint32_t offset;         /* Offset in flash to hash */
942 	uint32_t size;           /* Number of bytes to hash */
943 	uint8_t nonce_data[64];  /* Nonce data; ignored if nonce_size=0 */
944 } __packed;
945 
946 struct ec_response_vboot_hash {
947 	uint8_t status;          /* enum ec_vboot_hash_status */
948 	uint8_t hash_type;       /* enum ec_vboot_hash_type */
949 	uint8_t digest_size;     /* Size of hash digest in bytes */
950 	uint8_t reserved0;       /* Ignore; will be 0 */
951 	uint32_t offset;         /* Offset in flash which was hashed */
952 	uint32_t size;           /* Number of bytes hashed */
953 	uint8_t hash_digest[64]; /* Hash digest data */
954 } __packed;
955 
956 enum ec_vboot_hash_cmd {
957 	EC_VBOOT_HASH_GET = 0,       /* Get current hash status */
958 	EC_VBOOT_HASH_ABORT = 1,     /* Abort calculating current hash */
959 	EC_VBOOT_HASH_START = 2,     /* Start computing a new hash */
960 	EC_VBOOT_HASH_RECALC = 3,    /* Synchronously compute a new hash */
961 };
962 
963 enum ec_vboot_hash_type {
964 	EC_VBOOT_HASH_TYPE_SHA256 = 0, /* SHA-256 */
965 };
966 
967 enum ec_vboot_hash_status {
968 	EC_VBOOT_HASH_STATUS_NONE = 0, /* No hash (not started, or aborted) */
969 	EC_VBOOT_HASH_STATUS_DONE = 1, /* Finished computing a hash */
970 	EC_VBOOT_HASH_STATUS_BUSY = 2, /* Busy computing a hash */
971 };
972 
973 /*
974  * Special values for offset for EC_VBOOT_HASH_START and EC_VBOOT_HASH_RECALC.
975  * If one of these is specified, the EC will automatically update offset and
976  * size to the correct values for the specified image (RO or RW).
977  */
978 #define EC_VBOOT_HASH_OFFSET_RO 0xfffffffe
979 #define EC_VBOOT_HASH_OFFSET_RW 0xfffffffd
980 
981 /*****************************************************************************/
982 /* USB charging control commands */
983 
984 /* Set USB port charging mode */
985 #define EC_CMD_USB_CHARGE_SET_MODE 0x30
986 
987 struct ec_params_usb_charge_set_mode {
988 	uint8_t usb_port_id;
989 	uint8_t mode;
990 } __packed;
991 
992 /*****************************************************************************/
993 /* Persistent storage for host */
994 
995 /* Maximum bytes that can be read/written in a single command */
996 #define EC_PSTORE_SIZE_MAX 64
997 
998 /* Get persistent storage info */
999 #define EC_CMD_PSTORE_INFO 0x40
1000 
1001 struct ec_response_pstore_info {
1002 	/* Persistent storage size, in bytes */
1003 	uint32_t pstore_size;
1004 	/* Access size; read/write offset and size must be a multiple of this */
1005 	uint32_t access_size;
1006 } __packed;
1007 
1008 /*
1009  * Read persistent storage
1010  *
1011  * Response is params.size bytes of data.
1012  */
1013 #define EC_CMD_PSTORE_READ 0x41
1014 
1015 struct ec_params_pstore_read {
1016 	uint32_t offset;   /* Byte offset to read */
1017 	uint32_t size;     /* Size to read in bytes */
1018 } __packed;
1019 
1020 /* Write persistent storage */
1021 #define EC_CMD_PSTORE_WRITE 0x42
1022 
1023 struct ec_params_pstore_write {
1024 	uint32_t offset;   /* Byte offset to write */
1025 	uint32_t size;     /* Size to write in bytes */
1026 	uint8_t data[EC_PSTORE_SIZE_MAX];
1027 } __packed;
1028 
1029 /*****************************************************************************/
1030 /* Real-time clock */
1031 
1032 /* RTC params and response structures */
1033 struct ec_params_rtc {
1034 	uint32_t time;
1035 } __packed;
1036 
1037 struct ec_response_rtc {
1038 	uint32_t time;
1039 } __packed;
1040 
1041 /* These use ec_response_rtc */
1042 #define EC_CMD_RTC_GET_VALUE 0x44
1043 #define EC_CMD_RTC_GET_ALARM 0x45
1044 
1045 /* These all use ec_params_rtc */
1046 #define EC_CMD_RTC_SET_VALUE 0x46
1047 #define EC_CMD_RTC_SET_ALARM 0x47
1048 
1049 /*****************************************************************************/
1050 /* Port80 log access */
1051 
1052 /* Get last port80 code from previous boot */
1053 #define EC_CMD_PORT80_LAST_BOOT 0x48
1054 
1055 struct ec_response_port80_last_boot {
1056 	uint16_t code;
1057 } __packed;
1058 
1059 /*****************************************************************************/
1060 /* Thermal engine commands */
1061 
1062 /* Set thershold value */
1063 #define EC_CMD_THERMAL_SET_THRESHOLD 0x50
1064 
1065 struct ec_params_thermal_set_threshold {
1066 	uint8_t sensor_type;
1067 	uint8_t threshold_id;
1068 	uint16_t value;
1069 } __packed;
1070 
1071 /* Get threshold value */
1072 #define EC_CMD_THERMAL_GET_THRESHOLD 0x51
1073 
1074 struct ec_params_thermal_get_threshold {
1075 	uint8_t sensor_type;
1076 	uint8_t threshold_id;
1077 } __packed;
1078 
1079 struct ec_response_thermal_get_threshold {
1080 	uint16_t value;
1081 } __packed;
1082 
1083 /* Toggle automatic fan control */
1084 #define EC_CMD_THERMAL_AUTO_FAN_CTRL 0x52
1085 
1086 /* Get TMP006 calibration data */
1087 #define EC_CMD_TMP006_GET_CALIBRATION 0x53
1088 
1089 struct ec_params_tmp006_get_calibration {
1090 	uint8_t index;
1091 } __packed;
1092 
1093 struct ec_response_tmp006_get_calibration {
1094 	float s0;
1095 	float b0;
1096 	float b1;
1097 	float b2;
1098 } __packed;
1099 
1100 /* Set TMP006 calibration data */
1101 #define EC_CMD_TMP006_SET_CALIBRATION 0x54
1102 
1103 struct ec_params_tmp006_set_calibration {
1104 	uint8_t index;
1105 	uint8_t reserved[3];  /* Reserved; set 0 */
1106 	float s0;
1107 	float b0;
1108 	float b1;
1109 	float b2;
1110 } __packed;
1111 
1112 /*****************************************************************************/
1113 /* MKBP - Matrix KeyBoard Protocol */
1114 
1115 /*
1116  * Read key state
1117  *
1118  * Returns raw data for keyboard cols; see ec_response_mkbp_info.cols for
1119  * expected response size.
1120  */
1121 #define EC_CMD_MKBP_STATE 0x60
1122 
1123 /* Provide information about the matrix : number of rows and columns */
1124 #define EC_CMD_MKBP_INFO 0x61
1125 
1126 struct ec_response_mkbp_info {
1127 	uint32_t rows;
1128 	uint32_t cols;
1129 	uint8_t switches;
1130 } __packed;
1131 
1132 /* Simulate key press */
1133 #define EC_CMD_MKBP_SIMULATE_KEY 0x62
1134 
1135 struct ec_params_mkbp_simulate_key {
1136 	uint8_t col;
1137 	uint8_t row;
1138 	uint8_t pressed;
1139 } __packed;
1140 
1141 /* Configure keyboard scanning */
1142 #define EC_CMD_MKBP_SET_CONFIG 0x64
1143 #define EC_CMD_MKBP_GET_CONFIG 0x65
1144 
1145 /* flags */
1146 enum mkbp_config_flags {
1147 	EC_MKBP_FLAGS_ENABLE = 1,	/* Enable keyboard scanning */
1148 };
1149 
1150 enum mkbp_config_valid {
1151 	EC_MKBP_VALID_SCAN_PERIOD		= 1 << 0,
1152 	EC_MKBP_VALID_POLL_TIMEOUT		= 1 << 1,
1153 	EC_MKBP_VALID_MIN_POST_SCAN_DELAY	= 1 << 3,
1154 	EC_MKBP_VALID_OUTPUT_SETTLE		= 1 << 4,
1155 	EC_MKBP_VALID_DEBOUNCE_DOWN		= 1 << 5,
1156 	EC_MKBP_VALID_DEBOUNCE_UP		= 1 << 6,
1157 	EC_MKBP_VALID_FIFO_MAX_DEPTH		= 1 << 7,
1158 };
1159 
1160 /* Configuration for our key scanning algorithm */
1161 struct ec_mkbp_config {
1162 	uint32_t valid_mask;		/* valid fields */
1163 	uint8_t flags;		/* some flags (enum mkbp_config_flags) */
1164 	uint8_t valid_flags;		/* which flags are valid */
1165 	uint16_t scan_period_us;	/* period between start of scans */
1166 	/* revert to interrupt mode after no activity for this long */
1167 	uint32_t poll_timeout_us;
1168 	/*
1169 	 * minimum post-scan relax time. Once we finish a scan we check
1170 	 * the time until we are due to start the next one. If this time is
1171 	 * shorter this field, we use this instead.
1172 	 */
1173 	uint16_t min_post_scan_delay_us;
1174 	/* delay between setting up output and waiting for it to settle */
1175 	uint16_t output_settle_us;
1176 	uint16_t debounce_down_us;	/* time for debounce on key down */
1177 	uint16_t debounce_up_us;	/* time for debounce on key up */
1178 	/* maximum depth to allow for fifo (0 = no keyscan output) */
1179 	uint8_t fifo_max_depth;
1180 } __packed;
1181 
1182 struct ec_params_mkbp_set_config {
1183 	struct ec_mkbp_config config;
1184 } __packed;
1185 
1186 struct ec_response_mkbp_get_config {
1187 	struct ec_mkbp_config config;
1188 } __packed;
1189 
1190 /* Run the key scan emulation */
1191 #define EC_CMD_KEYSCAN_SEQ_CTRL 0x66
1192 
1193 enum ec_keyscan_seq_cmd {
1194 	EC_KEYSCAN_SEQ_STATUS = 0,	/* Get status information */
1195 	EC_KEYSCAN_SEQ_CLEAR = 1,	/* Clear sequence */
1196 	EC_KEYSCAN_SEQ_ADD = 2,		/* Add item to sequence */
1197 	EC_KEYSCAN_SEQ_START = 3,	/* Start running sequence */
1198 	EC_KEYSCAN_SEQ_COLLECT = 4,	/* Collect sequence summary data */
1199 };
1200 
1201 enum ec_collect_flags {
1202 	/*
1203 	 * Indicates this scan was processed by the EC. Due to timing, some
1204 	 * scans may be skipped.
1205 	 */
1206 	EC_KEYSCAN_SEQ_FLAG_DONE	= 1 << 0,
1207 };
1208 
1209 struct ec_collect_item {
1210 	uint8_t flags;		/* some flags (enum ec_collect_flags) */
1211 };
1212 
1213 struct ec_params_keyscan_seq_ctrl {
1214 	uint8_t cmd;	/* Command to send (enum ec_keyscan_seq_cmd) */
1215 	union {
1216 		struct {
1217 			uint8_t active;		/* still active */
1218 			uint8_t num_items;	/* number of items */
1219 			/* Current item being presented */
1220 			uint8_t cur_item;
1221 		} status;
1222 		struct {
1223 			/*
1224 			 * Absolute time for this scan, measured from the
1225 			 * start of the sequence.
1226 			 */
1227 			uint32_t time_us;
1228 			uint8_t scan[0];	/* keyscan data */
1229 		} add;
1230 		struct {
1231 			uint8_t start_item;	/* First item to return */
1232 			uint8_t num_items;	/* Number of items to return */
1233 		} collect;
1234 	};
1235 } __packed;
1236 
1237 struct ec_result_keyscan_seq_ctrl {
1238 	union {
1239 		struct {
1240 			uint8_t num_items;	/* Number of items */
1241 			/* Data for each item */
1242 			struct ec_collect_item item[0];
1243 		} collect;
1244 	};
1245 } __packed;
1246 
1247 /*****************************************************************************/
1248 /* Temperature sensor commands */
1249 
1250 /* Read temperature sensor info */
1251 #define EC_CMD_TEMP_SENSOR_GET_INFO 0x70
1252 
1253 struct ec_params_temp_sensor_get_info {
1254 	uint8_t id;
1255 } __packed;
1256 
1257 struct ec_response_temp_sensor_get_info {
1258 	char sensor_name[32];
1259 	uint8_t sensor_type;
1260 } __packed;
1261 
1262 /*****************************************************************************/
1263 
1264 /*
1265  * Note: host commands 0x80 - 0x87 are reserved to avoid conflict with ACPI
1266  * commands accidentally sent to the wrong interface.  See the ACPI section
1267  * below.
1268  */
1269 
1270 /*****************************************************************************/
1271 /* Host event commands */
1272 
1273 /*
1274  * Host event mask params and response structures, shared by all of the host
1275  * event commands below.
1276  */
1277 struct ec_params_host_event_mask {
1278 	uint32_t mask;
1279 } __packed;
1280 
1281 struct ec_response_host_event_mask {
1282 	uint32_t mask;
1283 } __packed;
1284 
1285 /* These all use ec_response_host_event_mask */
1286 #define EC_CMD_HOST_EVENT_GET_B         0x87
1287 #define EC_CMD_HOST_EVENT_GET_SMI_MASK  0x88
1288 #define EC_CMD_HOST_EVENT_GET_SCI_MASK  0x89
1289 #define EC_CMD_HOST_EVENT_GET_WAKE_MASK 0x8d
1290 
1291 /* These all use ec_params_host_event_mask */
1292 #define EC_CMD_HOST_EVENT_SET_SMI_MASK  0x8a
1293 #define EC_CMD_HOST_EVENT_SET_SCI_MASK  0x8b
1294 #define EC_CMD_HOST_EVENT_CLEAR         0x8c
1295 #define EC_CMD_HOST_EVENT_SET_WAKE_MASK 0x8e
1296 #define EC_CMD_HOST_EVENT_CLEAR_B       0x8f
1297 
1298 /*****************************************************************************/
1299 /* Switch commands */
1300 
1301 /* Enable/disable LCD backlight */
1302 #define EC_CMD_SWITCH_ENABLE_BKLIGHT 0x90
1303 
1304 struct ec_params_switch_enable_backlight {
1305 	uint8_t enabled;
1306 } __packed;
1307 
1308 /* Enable/disable WLAN/Bluetooth */
1309 #define EC_CMD_SWITCH_ENABLE_WIRELESS 0x91
1310 
1311 struct ec_params_switch_enable_wireless {
1312 	uint8_t enabled;
1313 } __packed;
1314 
1315 /*****************************************************************************/
1316 /* GPIO commands. Only available on EC if write protect has been disabled. */
1317 
1318 /* Set GPIO output value */
1319 #define EC_CMD_GPIO_SET 0x92
1320 
1321 struct ec_params_gpio_set {
1322 	char name[32];
1323 	uint8_t val;
1324 } __packed;
1325 
1326 /* Get GPIO value */
1327 #define EC_CMD_GPIO_GET 0x93
1328 
1329 struct ec_params_gpio_get {
1330 	char name[32];
1331 } __packed;
1332 struct ec_response_gpio_get {
1333 	uint8_t val;
1334 } __packed;
1335 
1336 /*****************************************************************************/
1337 /* I2C commands. Only available when flash write protect is unlocked. */
1338 
1339 /* Read I2C bus */
1340 #define EC_CMD_I2C_READ 0x94
1341 
1342 struct ec_params_i2c_read {
1343 	uint16_t addr; /* 8-bit address (7-bit shifted << 1) */
1344 	uint8_t read_size; /* Either 8 or 16. */
1345 	uint8_t port;
1346 	uint8_t offset;
1347 } __packed;
1348 struct ec_response_i2c_read {
1349 	uint16_t data;
1350 } __packed;
1351 
1352 /* Write I2C bus */
1353 #define EC_CMD_I2C_WRITE 0x95
1354 
1355 struct ec_params_i2c_write {
1356 	uint16_t data;
1357 	uint16_t addr; /* 8-bit address (7-bit shifted << 1) */
1358 	uint8_t write_size; /* Either 8 or 16. */
1359 	uint8_t port;
1360 	uint8_t offset;
1361 } __packed;
1362 
1363 /*****************************************************************************/
1364 /* Charge state commands. Only available when flash write protect unlocked. */
1365 
1366 /* Force charge state machine to stop in idle mode */
1367 #define EC_CMD_CHARGE_FORCE_IDLE 0x96
1368 
1369 struct ec_params_force_idle {
1370 	uint8_t enabled;
1371 } __packed;
1372 
1373 /*****************************************************************************/
1374 /* Console commands. Only available when flash write protect is unlocked. */
1375 
1376 /* Snapshot console output buffer for use by EC_CMD_CONSOLE_READ. */
1377 #define EC_CMD_CONSOLE_SNAPSHOT 0x97
1378 
1379 /*
1380  * Read next chunk of data from saved snapshot.
1381  *
1382  * Response is null-terminated string.  Empty string, if there is no more
1383  * remaining output.
1384  */
1385 #define EC_CMD_CONSOLE_READ 0x98
1386 
1387 /*****************************************************************************/
1388 
1389 /*
1390  * Cut off battery power output if the battery supports.
1391  *
1392  * For unsupported battery, just don't implement this command and lets EC
1393  * return EC_RES_INVALID_COMMAND.
1394  */
1395 #define EC_CMD_BATTERY_CUT_OFF 0x99
1396 
1397 /*****************************************************************************/
1398 /* USB port mux control. */
1399 
1400 /*
1401  * Switch USB mux or return to automatic switching.
1402  */
1403 #define EC_CMD_USB_MUX 0x9a
1404 
1405 struct ec_params_usb_mux {
1406 	uint8_t mux;
1407 } __packed;
1408 
1409 /*****************************************************************************/
1410 /* LDOs / FETs control. */
1411 
1412 enum ec_ldo_state {
1413 	EC_LDO_STATE_OFF = 0,	/* the LDO / FET is shut down */
1414 	EC_LDO_STATE_ON = 1,	/* the LDO / FET is ON / providing power */
1415 };
1416 
1417 /*
1418  * Switch on/off a LDO.
1419  */
1420 #define EC_CMD_LDO_SET 0x9b
1421 
1422 struct ec_params_ldo_set {
1423 	uint8_t index;
1424 	uint8_t state;
1425 } __packed;
1426 
1427 /*
1428  * Get LDO state.
1429  */
1430 #define EC_CMD_LDO_GET 0x9c
1431 
1432 struct ec_params_ldo_get {
1433 	uint8_t index;
1434 } __packed;
1435 
1436 struct ec_response_ldo_get {
1437 	uint8_t state;
1438 } __packed;
1439 
1440 /*****************************************************************************/
1441 /* Power info. */
1442 
1443 /*
1444  * Get power info.
1445  */
1446 #define EC_CMD_POWER_INFO 0x9d
1447 
1448 struct ec_response_power_info {
1449 	uint32_t usb_dev_type;
1450 	uint16_t voltage_ac;
1451 	uint16_t voltage_system;
1452 	uint16_t current_system;
1453 	uint16_t usb_current_limit;
1454 } __packed;
1455 
1456 /*****************************************************************************/
1457 /* I2C passthru command */
1458 
1459 #define EC_CMD_I2C_PASSTHRU 0x9e
1460 
1461 /* Slave address is 10 (not 7) bit */
1462 #define EC_I2C_FLAG_10BIT	(1 << 16)
1463 
1464 /* Read data; if not present, message is a write */
1465 #define EC_I2C_FLAG_READ	(1 << 15)
1466 
1467 /* Mask for address */
1468 #define EC_I2C_ADDR_MASK	0x3ff
1469 
1470 #define EC_I2C_STATUS_NAK	(1 << 0) /* Transfer was not acknowledged */
1471 #define EC_I2C_STATUS_TIMEOUT	(1 << 1) /* Timeout during transfer */
1472 
1473 /* Any error */
1474 #define EC_I2C_STATUS_ERROR	(EC_I2C_STATUS_NAK | EC_I2C_STATUS_TIMEOUT)
1475 
1476 struct ec_params_i2c_passthru_msg {
1477 	uint16_t addr_flags;	/* I2C slave address (7 or 10 bits) and flags */
1478 	uint16_t len;		/* Number of bytes to read or write */
1479 } __packed;
1480 
1481 struct ec_params_i2c_passthru {
1482 	uint8_t port;		/* I2C port number */
1483 	uint8_t num_msgs;	/* Number of messages */
1484 	struct ec_params_i2c_passthru_msg msg[];
1485 	/* Data to write for all messages is concatenated here */
1486 } __packed;
1487 
1488 struct ec_response_i2c_passthru {
1489 	uint8_t i2c_status;	/* Status flags (EC_I2C_STATUS_...) */
1490 	uint8_t num_msgs;	/* Number of messages processed */
1491 	uint8_t data[];		/* Data read by messages concatenated here */
1492 } __packed;
1493 
1494 
1495 /*****************************************************************************/
1496 /* Temporary debug commands. TODO: remove this crosbug.com/p/13849 */
1497 
1498 /*
1499  * Dump charge state machine context.
1500  *
1501  * Response is a binary dump of charge state machine context.
1502  */
1503 #define EC_CMD_CHARGE_DUMP 0xa0
1504 
1505 /*
1506  * Set maximum battery charging current.
1507  */
1508 #define EC_CMD_CHARGE_CURRENT_LIMIT 0xa1
1509 
1510 struct ec_params_current_limit {
1511 	uint32_t limit; /* in mA */
1512 } __packed;
1513 
1514 /*
1515  * Set maximum external power current.
1516  */
1517 #define EC_CMD_EXT_POWER_CURRENT_LIMIT 0xa2
1518 
1519 struct ec_params_ext_power_current_limit {
1520 	uint32_t limit; /* in mA */
1521 } __packed;
1522 
1523 /*****************************************************************************/
1524 /* Smart battery pass-through */
1525 
1526 /* Get / Set 16-bit smart battery registers */
1527 #define EC_CMD_SB_READ_WORD   0xb0
1528 #define EC_CMD_SB_WRITE_WORD  0xb1
1529 
1530 /* Get / Set string smart battery parameters
1531  * formatted as SMBUS "block".
1532  */
1533 #define EC_CMD_SB_READ_BLOCK  0xb2
1534 #define EC_CMD_SB_WRITE_BLOCK 0xb3
1535 
1536 struct ec_params_sb_rd {
1537 	uint8_t reg;
1538 } __packed;
1539 
1540 struct ec_response_sb_rd_word {
1541 	uint16_t value;
1542 } __packed;
1543 
1544 struct ec_params_sb_wr_word {
1545 	uint8_t reg;
1546 	uint16_t value;
1547 } __packed;
1548 
1549 struct ec_response_sb_rd_block {
1550 	uint8_t data[32];
1551 } __packed;
1552 
1553 struct ec_params_sb_wr_block {
1554 	uint8_t reg;
1555 	uint16_t data[32];
1556 } __packed;
1557 
1558 /*
1559  * Entering Verified Boot Mode Command
1560  * Default mode is VBOOT_MODE_NORMAL if EC did not receive this command.
1561  * Valid Modes are: normal, developer, and recovery.
1562  */
1563 #define EC_CMD_ENTERING_MODE 0xb6
1564 
1565 struct ec_params_entering_mode {
1566 	int vboot_mode;
1567 } __packed;
1568 
1569 #define VBOOT_MODE_NORMAL    0
1570 #define VBOOT_MODE_DEVELOPER 1
1571 #define VBOOT_MODE_RECOVERY  2
1572 
1573 /*****************************************************************************/
1574 /* System commands */
1575 
1576 /*
1577  * TODO: this is a confusing name, since it doesn't necessarily reboot the EC.
1578  * Rename to "set image" or something similar.
1579  */
1580 #define EC_CMD_REBOOT_EC 0xd2
1581 
1582 /* Command */
1583 enum ec_reboot_cmd {
1584 	EC_REBOOT_CANCEL = 0,        /* Cancel a pending reboot */
1585 	EC_REBOOT_JUMP_RO = 1,       /* Jump to RO without rebooting */
1586 	EC_REBOOT_JUMP_RW = 2,       /* Jump to RW without rebooting */
1587 	/* (command 3 was jump to RW-B) */
1588 	EC_REBOOT_COLD = 4,          /* Cold-reboot */
1589 	EC_REBOOT_DISABLE_JUMP = 5,  /* Disable jump until next reboot */
1590 	EC_REBOOT_HIBERNATE = 6      /* Hibernate EC */
1591 };
1592 
1593 /* Flags for ec_params_reboot_ec.reboot_flags */
1594 #define EC_REBOOT_FLAG_RESERVED0      (1 << 0)  /* Was recovery request */
1595 #define EC_REBOOT_FLAG_ON_AP_SHUTDOWN (1 << 1)  /* Reboot after AP shutdown */
1596 
1597 struct ec_params_reboot_ec {
1598 	uint8_t cmd;           /* enum ec_reboot_cmd */
1599 	uint8_t flags;         /* See EC_REBOOT_FLAG_* */
1600 } __packed;
1601 
1602 /*
1603  * Get information on last EC panic.
1604  *
1605  * Returns variable-length platform-dependent panic information.  See panic.h
1606  * for details.
1607  */
1608 #define EC_CMD_GET_PANIC_INFO 0xd3
1609 
1610 /*****************************************************************************/
1611 /*
1612  * ACPI commands
1613  *
1614  * These are valid ONLY on the ACPI command/data port.
1615  */
1616 
1617 /*
1618  * ACPI Read Embedded Controller
1619  *
1620  * This reads from ACPI memory space on the EC (EC_ACPI_MEM_*).
1621  *
1622  * Use the following sequence:
1623  *
1624  *    - Write EC_CMD_ACPI_READ to EC_LPC_ADDR_ACPI_CMD
1625  *    - Wait for EC_LPC_CMDR_PENDING bit to clear
1626  *    - Write address to EC_LPC_ADDR_ACPI_DATA
1627  *    - Wait for EC_LPC_CMDR_DATA bit to set
1628  *    - Read value from EC_LPC_ADDR_ACPI_DATA
1629  */
1630 #define EC_CMD_ACPI_READ 0x80
1631 
1632 /*
1633  * ACPI Write Embedded Controller
1634  *
1635  * This reads from ACPI memory space on the EC (EC_ACPI_MEM_*).
1636  *
1637  * Use the following sequence:
1638  *
1639  *    - Write EC_CMD_ACPI_WRITE to EC_LPC_ADDR_ACPI_CMD
1640  *    - Wait for EC_LPC_CMDR_PENDING bit to clear
1641  *    - Write address to EC_LPC_ADDR_ACPI_DATA
1642  *    - Wait for EC_LPC_CMDR_PENDING bit to clear
1643  *    - Write value to EC_LPC_ADDR_ACPI_DATA
1644  */
1645 #define EC_CMD_ACPI_WRITE 0x81
1646 
1647 /*
1648  * ACPI Query Embedded Controller
1649  *
1650  * This clears the lowest-order bit in the currently pending host events, and
1651  * sets the result code to the 1-based index of the bit (event 0x00000001 = 1,
1652  * event 0x80000000 = 32), or 0 if no event was pending.
1653  */
1654 #define EC_CMD_ACPI_QUERY_EVENT 0x84
1655 
1656 /* Valid addresses in ACPI memory space, for read/write commands */
1657 /* Memory space version; set to EC_ACPI_MEM_VERSION_CURRENT */
1658 #define EC_ACPI_MEM_VERSION            0x00
1659 /*
1660  * Test location; writing value here updates test compliment byte to (0xff -
1661  * value).
1662  */
1663 #define EC_ACPI_MEM_TEST               0x01
1664 /* Test compliment; writes here are ignored. */
1665 #define EC_ACPI_MEM_TEST_COMPLIMENT    0x02
1666 /* Keyboard backlight brightness percent (0 - 100) */
1667 #define EC_ACPI_MEM_KEYBOARD_BACKLIGHT 0x03
1668 
1669 /* Current version of ACPI memory address space */
1670 #define EC_ACPI_MEM_VERSION_CURRENT 1
1671 
1672 
1673 /*****************************************************************************/
1674 /*
1675  * Special commands
1676  *
1677  * These do not follow the normal rules for commands.  See each command for
1678  * details.
1679  */
1680 
1681 /*
1682  * Reboot NOW
1683  *
1684  * This command will work even when the EC LPC interface is busy, because the
1685  * reboot command is processed at interrupt level.  Note that when the EC
1686  * reboots, the host will reboot too, so there is no response to this command.
1687  *
1688  * Use EC_CMD_REBOOT_EC to reboot the EC more politely.
1689  */
1690 #define EC_CMD_REBOOT 0xd1  /* Think "die" */
1691 
1692 /*
1693  * Resend last response (not supported on LPC).
1694  *
1695  * Returns EC_RES_UNAVAILABLE if there is no response available - for example,
1696  * there was no previous command, or the previous command's response was too
1697  * big to save.
1698  */
1699 #define EC_CMD_RESEND_RESPONSE 0xdb
1700 
1701 /*
1702  * This header byte on a command indicate version 0. Any header byte less
1703  * than this means that we are talking to an old EC which doesn't support
1704  * versioning. In that case, we assume version 0.
1705  *
1706  * Header bytes greater than this indicate a later version. For example,
1707  * EC_CMD_VERSION0 + 1 means we are using version 1.
1708  *
1709  * The old EC interface must not use commands 0dc or higher.
1710  */
1711 #define EC_CMD_VERSION0 0xdc
1712 
1713 #endif  /* !__ACPI__ */
1714 
1715 #endif  /* __CROS_EC_COMMANDS_H */
1716