1 /* 2 * Copyright (C) 2017 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 #ifndef __CROS_EC_INCLUDE_APP_NUGGET_H 17 #define __CROS_EC_INCLUDE_APP_NUGGET_H 18 #include "application.h" 19 20 #ifdef __cplusplus 21 extern "C" { 22 #endif 23 24 /****************************************************************************/ 25 /* 26 * APP_ID_NUGGET uses the Transport API 27 */ 28 /****************************************************************************/ 29 30 /* App-specific errors (across all commands) */ 31 enum { 32 NUGGET_ERROR_LOCKED = APP_SPECIFIC_ERROR, 33 NUGGET_ERROR_RETRY, 34 }; 35 36 /****************************************************************************/ 37 /* Application functions */ 38 39 #define NUGGET_PARAM_VERSION 0x0000 40 /* 41 * Return the one-line version string of the running image 42 * 43 * @param args <none> 44 * @param arg_len 0 45 * @param reply Null-terminated ASCII string 46 * @param reply_len Max length to return 47 * 48 * @errors APP_ERROR_TOO_MUCH 49 */ 50 51 /****************************************************************************/ 52 /* Firmware upgrade stuff */ 53 54 #define NP_FLASH_BLOCK_SIZE 2048 55 struct nugget_app_flash_block { 56 uint32_t block_digest; /* first 4 bytes of sha1 of the rest */ 57 uint32_t offset; /* from start of flash */ 58 uint8_t payload[NP_FLASH_BLOCK_SIZE]; /* data to write */ 59 } __packed; 60 61 #define NUGGET_PARAM_FLASH_BLOCK 0x0001 62 /* 63 * Erase and write a single flash block. 64 * 65 * @param args struct nugget_app_flash_block 66 * @param arg_len sizeof(struct nugget_app_flash_block) 67 * @param reply <none> 68 * @param reply_len 0 69 * 70 * @errors NUGGET_ERROR_LOCKED, NUGGET_ERROR_RETRY 71 */ 72 73 #define NUGGET_PARAM_REBOOT 0x0002 74 /* 75 * Reboot Citadel 76 * 77 * @param args <none> 78 * @param arg_len 0 79 * @param reply <none> 80 * @param reply_len 0 81 */ 82 83 /********* 84 * Firmware updates are written to flash with invalid headers. If an update 85 * password exists, headers can only be marked valid by providing that 86 * password. 87 */ 88 89 /* 90 * An unassigned password is defined to be all 0xff, with a don't-care digest. 91 * Anything else must have a valid digest over all password bytes. The password 92 * length is chosen arbitrarily for now, but should always be a fixed size with 93 * all bytes used, to resist brute-force guesses. 94 */ 95 #define NUGGET_UPDATE_PASSWORD_LEN 32 96 struct nugget_app_password { 97 uint32_t digest; /* first 4 bytes of sha1 of password (little endian) */ 98 uint8_t password[NUGGET_UPDATE_PASSWORD_LEN]; 99 } __packed; 100 101 102 enum NUGGET_ENABLE_HEADER { 103 NUGGET_ENABLE_HEADER_RO = 0x01, 104 NUGGET_ENABLE_HEADER_RW = 0x02, 105 }; 106 struct nugget_app_enable_update { 107 struct nugget_app_password password; 108 uint8_t which_headers; /* bit 0 = RO, bit 1 = RW */ 109 } __packed; 110 #define NUGGET_PARAM_ENABLE_UPDATE 0x0003 111 /* 112 * Mark the specified image header(s) as valid, if the provided password 113 * matches. Returns true if either header was CHANGED to valid, which is an 114 * indication that the AP should request a reboot so that it can take effect. 115 * 116 * @param args struct nugget_app_enable_update 117 * @param arg_len sizeof(struct nugget_app_enable_update) 118 * @param reply 0 or 1 119 * @param reply_len 1 byte 120 * 121 * @errors APP_ERROR_BOGUS_ARGS 122 */ 123 124 125 struct nugget_app_change_update_password { 126 struct nugget_app_password old_password; 127 struct nugget_app_password new_password; 128 } __packed; 129 #define NUGGET_PARAM_CHANGE_UPDATE_PASSWORD 0x0004 130 /* 131 * Change the update password. 132 * 133 * @param args struct nugget_app_change_update_password 134 * @param arg_len sizeof(struct nugget_app_change_update_password) 135 * @param reply <none> 136 * @param reply_len 0 137 * 138 * @errors APP_ERROR_BOGUS_ARGS 139 */ 140 141 #define NUGGET_PARAM_NUKE_FROM_ORBIT 0x0005 142 #define ERASE_CONFIRMATION 0xc05fefee 143 /* 144 * This will erase ALL user secrets and reboot. 145 * 146 * @param args uint32_t containing the ERASE_CONFIRMATION value 147 * @param arg_len sizeof(uint32_t) 148 * @param reply <none> 149 * @param reply_len 0 150 * 151 * @errors APP_ERROR_BOGUS_ARGS 152 */ 153 154 #define NUGGET_PARAM_DEVICE_ID 0x0006 155 /* 156 * Get the device ID of the chip. 157 * 158 * @param args <none> 159 * @param arg_len 0 160 * @param reply Null-terminated ASCII string 161 * @param reply_len Max length to return 162 */ 163 164 165 #define NUGGET_PARAM_LONG_VERSION 0x0007 166 /* 167 * Return the multi-line description of all images 168 * 169 * @param args <none> 170 * @param arg_len 0 171 * @param reply Null-terminated ASCII string 172 * @param reply_len Max length to return 173 * 174 * @errors APP_ERROR_TOO_MUCH 175 */ 176 177 #define NUGGET_PARAM_HEADER_RO_A 0x0008 178 /* 179 * Return the signature header for RO_A 180 * 181 * @param args <none> 182 * @param arg_len 0 183 * @param reply struct SignedHeader 184 * @param reply_len Max length to return 185 * 186 * @errors APP_ERROR_TOO_MUCH 187 */ 188 189 #define NUGGET_PARAM_HEADER_RO_B 0x0009 190 /* 191 * Return the signature header for RO_B 192 * 193 * @param args <none> 194 * @param arg_len 0 195 * @param reply struct SignedHeader 196 * @param reply_len Max length to return 197 * 198 * @errors APP_ERROR_TOO_MUCH 199 */ 200 201 #define NUGGET_PARAM_HEADER_RW_A 0x000a 202 /* 203 * Return the signature header for RW_A 204 * 205 * @param args <none> 206 * @param arg_len 0 207 * @param reply struct SignedHeader 208 * @param reply_len Max length to return 209 * 210 * @errors APP_ERROR_TOO_MUCH 211 */ 212 213 #define NUGGET_PARAM_HEADER_RW_B 0x000b 214 /* 215 * Return the signature header for RW_B 216 * 217 * @param args <none> 218 * @param arg_len 0 219 * @param reply struct SignedHeader 220 * @param reply_len Max length to return 221 * 222 * @errors APP_ERROR_TOO_MUCH 223 */ 224 225 #define NUGGET_PARAM_REPO_SNAPSHOT 0x000c 226 /* 227 * Return the multi-line repo snapshot info for the current image 228 * 229 * @param args <none> 230 * @param arg_len 0 231 * @param reply Null-terminated ASCII string 232 * @param reply_len Max length to return 233 * 234 * @errors APP_ERROR_TOO_MUCH 235 */ 236 237 enum nugget_ap_uart_passthru_cfg { 238 NUGGET_AP_UART_OFF, /* off */ 239 NUGGET_AP_UART_IS_USB, /* USB CCD is in use over SBU */ 240 NUGGET_AP_UART_ENABLED, /* AP UART is on SBU lines */ 241 NUGGET_AP_UART_SSC_UART, /* This doesn't actually exist */ 242 NUGGET_AP_UART_CITADEL_UART, /* Citadel UART on SBU lines (ew) */ 243 244 NUGGET_AP_UART_NUM_CFGS, 245 }; 246 #define NUGGET_PARAM_AP_UART_PASSTHRU 0x000d 247 /* 248 * Enable/Disable the AP UART PASSTHRU function 249 * 250 * This always returns the current state of the AP UART passthru feature. Even 251 * if the AP UART is disabled, a SuzyQable may connected to use the SBU lines. 252 * 253 * The AP can only request that the AP UART passthru feature be enabled 254 * (NUGGET_AP_UART_ENABLED), or disabled (NUGGET_AP_UART_OFF). The other enums 255 * are for internal testing. 256 * 257 * @param args <none> OR enum nugget_ap_uart_passthru_cfg 258 * @param arg_len 0 OR 1 byte 259 * @param reply enum nugget_param_ap_uart_passthru 260 * @param reply_len 1 byte 261 * 262 * @errors APP_ERROR_BOGUS_ARGS 263 */ 264 265 #define NUGGET_PARAM_RDD_CFG 0x000e 266 /* 267 * Enable/Disable the RDD SuzyQable Detection 268 * 269 * This always returns the current state of the RDD SuzyQable detection 270 * feature. 271 * 272 * The AP can request that the RDD SuzyQable detection to be disabled (0) or 273 * enabled (1). 274 * 275 * @param args 0 OR 1 276 * @param arg_len 0 OR 1 byte 277 * @param reply current state (0 or 1) 278 * @param reply_len 1 byte 279 * 280 * @errors APP_ERROR_BOGUS_ARGS 281 */ 282 283 #define NUGGET_PARAM_BOARD_ID 0x000f 284 /* 285 * Set / Get Board ID 286 * 287 * This sets or gets the Board ID of the device. 288 * 289 * @param args <none> OR nugget_app_board_id 290 * @param arg_len 0 OR sizeof nugget_app_board_id 291 * @param reply struct nugget_app_board_id 292 * @param reply_len sizeof struct nugget_app_board_id 293 * 294 * @errors APP_ERROR_BOGUS_ARGS 295 */ 296 struct nugget_app_board_id { 297 uint32_t type; 298 uint32_t flag; 299 uint32_t inv; /* must equal ~type when setting */ 300 } __packed; 301 302 #define NUGGET_PARAM_GET_EVENT_RECORD 0x0010 303 /* 304 * This retrieves one pending event_record (defined in citadel_events.h). 305 * If none are pending, it returns nothing. 306 * 307 * @param args <none> 308 * @param arg_len 0 309 * @param reply struct event_record 310 * @param reply_len sizeof struct event_record OR 0 311 */ 312 313 #define NUGGET_PARAM_AP_IS_REBOOTING 0x0011 314 /* 315 * This can be used to replace the GPIO signal for some boards, if the 316 * communication path is trusted. If not, it has no effect. 317 * 318 * @param args <none> 319 * @param arg_len 0 320 * @param reply <none> 321 * @param reply_len 0 322 */ 323 324 #define FILE_ID_NUGGET_PERSIST 0 325 #define NUGGET_PERSIST_VERSION_1 1 326 struct nugget_persist_t { 327 uint8_t version; 328 uint8_t user_consent; 329 uint8_t reserved[2]; 330 }; 331 332 enum nugget_sjtag_user_consent_cfg { 333 NUGGET_SJTAG_USER_CONSENT_DISALLOW, /* DISALLOW */ 334 NUGGET_SJTAG_USER_CONSENT_ALLOW, /* ALLOW */ 335 336 NUGGET_SJTAG_USER_CONSENT_NUM_CFGS, 337 }; 338 339 #define NUGGET_PARAM_SJTAG_USER_CONSENT 0x0012 340 /* 341 * Set/Get the SJTAG USER CONSENT function 342 * 343 * This always returns the current state of the SJTAG USER CONSENT feature. 344 * 345 * @param args <none> OR enum nugget_sjtag_user_consent_cfg 346 * @param arg_len 0 OR 1 byte 347 * @param reply enum nugget_sjtag_user_consent_cfg 348 * @param reply_len 1 byte 349 * 350 * @errors APP_ERROR_BOGUS_ARGS 351 */ 352 353 enum nugget_sjtag_avb_boot_lock_result { 354 AVB_BOOT_LOCK_DISABLED, 355 AVB_BOOT_LOCK_ENABLED, 356 AVB_BOOT_LOCK_ERROR, 357 }; 358 359 #define NUGGET_PARAM_SJTAG_ALLOW 0x0013 360 /* 361 * Get the SJTAG ALLOW 362 * 363 * This always returns the current state of the SJTAG ALLOW feature. 364 * 365 * @param args <none> 366 * @param arg_len 0 367 * @param reply 0(DISALLOW) OR 1(ALLOW) 368 * @param reply_len 1 byte 369 * 370 * @errors APP_ERROR_BOGUS_ARGS 371 */ 372 373 /* 374 * Persistent storage of arbitrary data, up to 375 * (FS_MAX_FILE_SIZE - sizeof(struct nugget_app_data)) bytes. 376 */ 377 struct nugget_app_storage { 378 uint32_t flags; /* TBD, use zero for now */ 379 #ifndef __cplusplus 380 uint8_t data[]; /* Zero or more bytes */ 381 #endif 382 } __packed; 383 384 #define NUGGET_PARAM_STORAGE_WRITE 0x0014 385 /* 386 * Write arbitrary data. 387 * 388 * The current storage is erased, then new data (if any) is saved. 389 * 390 * .flags meaning is not yet defined; for now it must be 0x00000000 391 * Possible usage could restrict reading to the bootloader, 392 * erase data after N reads or reboots, etc. 393 * 394 * @param args struct nugget_app_storage + zero or more bytes 395 * @param arg_len To write: > sizeof(struct nugget_app_storage) 396 * To erase: <= sizeof(struct nugget_app_storage) 397 * @param reply <none> 398 * @param reply_len 0 399 * 400 * @errors APP_ERROR_BOGUS_ARGS 401 */ 402 #define NUGGET_PARAM_STORAGE_READ 0x0015 403 /* 404 * Read arbitrary data. 405 * 406 * On success, struct nugget_app_storage is returned, followed by zero 407 * or more bytes of .data 408 * 409 * @param args <none> 410 * @param arg_len 0 411 * @param reply struct nugget_app_storage + zero or more bytes 412 * @param reply_len <varies> 413 * 414 * @errors APP_ERROR_BOGUS_ARGS 415 */ 416 417 /****************************************************************************/ 418 /* Test related commands */ 419 420 #define NUGGET_PARAM_CYCLES_SINCE_BOOT 0x0100 421 /* 422 * Get the number of cycles since boot 423 * 424 * @param args <none> 425 * @param arg_len 0 426 * @param reply uint32_t cycles 427 * @param reply_len sizeof(uint32_t) 428 */ 429 430 enum nugget_app_selftest_cmd { 431 /* Generic */ 432 NUGGET_APP_SELFTEST_CMD_DEFAULT = 0, 433 NUGGET_APP_SELFTEST_CMD_HELP, 434 435 /* Application SelfTests */ 436 NUGGET_APP_SELFTEST_CMD_TRNG = 0x10, 437 }; 438 439 #define NUGGET_PARAM_SELFTEST 0x0101 440 /* 441 * Run an intentionally vaguely specified internal test. 442 * 443 * This accepts arbitrary args and returns arbitrary results, as defined by the 444 * Citadel firmware. To allow changes to Nugget OS without requiring 445 * simultaneous changes to the AP, calling this with no args will run a default 446 * set of tests and return a null-terminated string with the result. 447 * 448 * @param args zero or more null-terminated strings, concatenated 449 * @param arg_len number of bytes in args 450 * @param reply null-terminated string (usually) 451 * @param reply_len number of bytes in reply (including trailing '\0') 452 */ 453 454 /****************************************************************************/ 455 /* Support for Power 1.1 HAL */ 456 457 /* 458 * This struct is specific to Citadel and Nugget OS, but it's enough for the 459 * AP-side implementation to translate into the info required for the power 460 * stats service. 461 */ 462 #define NUGGET_APP_LOW_POWER_STATS_MAGIC 0xC0DEACE1 463 struct nugget_app_low_power_stats { /* version 1 */ 464 /* All times in usecs */ 465 uint64_t hard_reset_count; /* Cleared by power loss */ 466 uint64_t time_since_hard_reset; 467 /* Below are only since the last hard reset */ 468 uint64_t wake_count; 469 uint64_t time_at_last_wake; 470 uint64_t time_spent_awake; 471 uint64_t deep_sleep_count; 472 uint64_t time_at_last_deep_sleep; 473 uint64_t time_spent_in_deep_sleep; 474 uint64_t time_at_ap_reset; 475 uint64_t time_at_ap_bootloader_done; 476 /* 477 * New fields for v1, used by factory tests. The caller can tell whether the 478 * firmare supports these fields by checking the v1_magic value. 479 */ 480 uint32_t v1_magic; /* NUGGET_APP_LOW_POWER_STATS_MAGIC */ 481 uint32_t temp; 482 struct { 483 unsigned int phone_on_l : 1; 484 unsigned int vol_up_l : 1; 485 unsigned int vol_dn_l : 1; 486 unsigned int _padding : 29; /* pad to 32 bits */ 487 } signals; 488 } __packed; 489 490 #define NUGGET_PARAM_GET_LOW_POWER_STATS 0x200 491 /* 492 * Return information regarding deep sleep transitions 493 * 494 * @param args <none> 495 * @param arg_len 0 496 * @param reply struct nugget_param_get_low_power_stats 497 * @param reply_len sizeof(struct nugget_param_get_low_power_stats) 498 */ 499 500 /* UNIMPLEMENTED */ 501 /* Reseved just in case we decide we need it */ 502 #define NUGGET_PARAM_CLEAR_LOW_POWER_STATS 0x201 503 /* UNIMPLEMENTED */ 504 505 /****************************************************************************/ 506 /* Commands for code coverage and quality assurance */ 507 508 #define NUGGET_GET_COVERAGE_COUNTERS 0x0300 509 /** 510 * Returns the counters back to the master 511 * 512 * @param args module counter 513 * @param arg_len 1 514 * @param reply buffer containing coverage data in utf-8 format 515 * @param reply_len depends on the counters in the file 516 */ 517 518 /* 519 * Error returned if coverage data didn't fit in the buffer. 520 * 521 * TODO: Should really have a second arg which is an offset in the coverage 522 * data. That way we could call repeatedly to return data too big to return in 523 * a single command. 524 */ 525 enum { 526 NUGGET_ERROR_COVERAGE_OVERFLOW = APP_SPECIFIC_ERROR + 0x300, 527 }; 528 529 /****************************************************************************/ 530 /* These are bringup / debug functions only. */ 531 532 #define NUGGET_PARAM_READ32 0xF000 533 /* 534 * Read a 32-bit value from memory. 535 * 536 * DANGER, WILL ROBINSON! DANGER! There is NO sanity checking on this AT ALL. 537 * Read the wrong address, and Bad Things(tm) WILL happen. 538 * 539 * @param args uint32_t address 540 * @param arg_len sizeof(uint32_t) 541 * @param reply uint32_t value 542 * @param reply_len sizeof(uint32_t) 543 */ 544 545 struct nugget_app_write32 { 546 uint32_t address; 547 uint32_t value; 548 } __packed; 549 550 #define NUGGET_PARAM_WRITE32 0xF001 551 /* 552 * Write a 32-bit value to memory 553 * 554 * DANGER, WILL ROBINSON! DANGER! There is NO sanity checking on this AT ALL. 555 * Write the wrong values to the wrong address, and Bad Things(tm) WILL happen. 556 * 557 * @param args struct nugget_app_write32 558 * @param arg_len sizeof(struct nugget_app_write32) 559 * @param reply <none> 560 * @param reply_len 0 561 */ 562 563 #define NUGGET_PARAM_CONSOLE 0xF002 564 /* 565 * Send optional command, return recent console output 566 * 567 * @param args command, if any 568 * @param arg_len sizeof(command) 569 * @param reply recent console output 570 * @param reply_len len(recent console output) 571 */ 572 573 #define NUGGET_PARAM_MODULE_TEST 0xF003 574 /** 575 * Run a module test based on a provided command. 576 * 577 * A default command is afforded (0x00), which runs each module test that is 578 * currently enabled. Specific tests can be specified, but are not enumerated 579 * here. 580 * 581 * The return code of the command (enum app_status) encodes the success state of 582 * the tests. A result of `APP_SUCCESS` is, unsurprisingly, a success for all 583 * specified tests. A failure of a given test is encoded using the 584 * `APP_SPECIFIC_ERROR` values. This allows a given test to not only report that 585 * an error has occured, but also to report which test threw the error, and in 586 * what point of the test the error was thrown. 587 * The encoding is as follows: 588 * `rv = (APP_SPECIFIC_ERROR + command + test_step)` 589 * where `command` is the 4-byte test value (in steps of 0x10), and where the 590 * test_step is a subdivision of the test, valued from 0-15. 591 * 592 * The return string will describe each test that passes, and each test that 593 * fails, and how it failed. Tests should abort after the first failure. 594 * 595 * @param args uint32_t command 596 * @param arg_len sizeof(uint32_t) 597 * @param reply null-terminated string (usually) 598 * @param reply_len number of bytes in reply (including trailing '\0') 599 */ 600 601 enum nugget_app_sleep_mode { 602 NUGGET_APP_SLEEP_MODE_DEFAULT, 603 NUGGET_APP_SLEEP_MODE_WFI, 604 NUGGET_APP_SLEEP_MODE_SLEEP 605 }; 606 #define NUGGET_PARAM_SET_SLEEP_MODE 0xF004 607 /** 608 * Set the Sleep mode of the GSC. 609 * 610 * In certain tests, we expect the GSC to be in either WFI mode, or in deep 611 * sleep mode. The sleep state should be provided by the host to the GSC, to 612 * ensure that the test is performed in the correct circumstances. 613 * 614 * @param args enum nugget_app_sleep_mode selection 615 * @param arg_len 4 616 * @param reply <none> 617 * @param reply_len 0 618 */ 619 620 #define NUGGET_PARAM_TRIGGER_PIN 0xF005 621 /** 622 * Get/Set trigger pin level 623 * 624 * This command asks GSC to set the level (0|1) of an otherwise unused GPIO, 625 * to signal external test equipment. 626 * 627 * @param args 0 OR 1 628 * @param arg_len 0 OR 1 byte 629 * @param reply current state (0 or 1) 630 * @param reply_len 1 byte 631 * 632 * @errors APP_ERROR_BOGUS_ARGS 633 */ 634 635 #ifdef __cplusplus 636 } 637 #endif 638 639 #endif /* __CROS_EC_INCLUDE_APP_NUGGET_H */ 640