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_REPORT 0x0010 303 /* 304 * This retrieves one pending event_report (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_report 310 * @param reply_len sizeof struct event_report 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 #define GSC_DEBUG_DUMP_VERSION 0 418 struct gsc_debug_dump_msg { 419 uint8_t timestamp[6]; // Bottom 48 bits of system time; enough for 8 years @ 1 us 420 uint8_t channel; // log channel (task_id or system call) 421 uint8_t version; // gsc_debug_dump_msg struct version 422 uint32_t error_code; // error code 423 uint32_t reserved; // reserved for other useful log 424 }; 425 426 #define DEBUG_MESSAGE_MAX_COUNT 64 427 #define DEBUG_MESSAGE_BUFFER_SIZE (DEBUG_MESSAGE_MAX_COUNT * sizeof(struct gsc_debug_dump_msg)) 428 429 #define NUGGET_PARAM_DEBUG_DUMP 0x0016 430 /* 431 * Get GSC debug message from 1KB ring buffer 432 * 433 * @param args <none> 434 * @param arg_len 0 435 * @param reply recent debug buffer output 436 * @param reply_len 1KB 437 */ 438 439 #define GSA_GSC_PAIRING_VERSION 0 440 #define EC_P256_PUBLIC_KEY_SIZE 64 441 #define EC_P256_PRIVATE_KEY_SIZE 32 442 #define PSK_KEY_SIZE 32 443 #define HAS_GSA_PUBKEY 0xa3 444 struct gsa_gsc_pairing_persist_storage { 445 uint8_t version; 446 uint8_t has_gsa_public_key_provision; 447 uint8_t gsa_public_key[EC_P256_PUBLIC_KEY_SIZE]; 448 uint8_t gsc_private_key[EC_P256_PRIVATE_KEY_SIZE]; 449 uint8_t gsc_public_key[EC_P256_PUBLIC_KEY_SIZE]; 450 }; 451 452 #define GSA_GSC_PSK_VERSION 0 453 #define HAS_GSA_GSC_PSK 0xa5 454 struct gsa_gsc_psk_persist_storage { 455 uint8_t version; 456 uint8_t has_gsa_gsc_psk_provision; 457 uint8_t gsa_gsc_psk[PSK_KEY_SIZE]; 458 }; 459 460 #define NUGGET_PARAM_GSA_KEY_PROVISION 0x0017 461 /* 462 * GSA key provision command 463 * 464 * @param args gsa unique public key 465 * @param arg_len 32 466 * @param reply gsc public key + sha256(pre-shared key) 467 * @param reply_len 64 + 32 468 */ 469 470 /** 471 * enum gsa_gsc_psk_state - GSA-GSC PSK state 472 * @GSA_GSC_PSK_STATE_UNKNOWN: Unknown state (initial state) 473 * @GSA_GSC_PSK_STATE_KEY_VERIFY_SUCCESS: GSA and GSC PSK match 474 * @GSA_GSC_PSK_STATE_KEY_MISMATCH: GSA and GSC PSK mismatch 475 * @GSA_GSC_PSK_STATE_GSA_INTERNAL_ERROR: GSA has internal error 476 * @GSA_GSC_PSK_STATE_GSA_HAS_NO_KEY: GSA has no PSK 477 * @GSA_GSC_PSK_STATE_GSA_CRYPTO_PRNG_FAIL: GSA crypto prng function fail 478 * @GSA_GSC_PSK_STATE_GSA_CRYPTO_HKDF_FAIL: GSA crypto HKDF function fail 479 * @GSA_GSC_PSK_STATE_GSA_CRYPTO_HMAC_FAIL: GSA crypto HMAC function fail 480 * @GSA_GSC_PSK_STATE_GSA_CRYPTO_DONE: GSA crypto operations complete 481 * @GSA_GSC_PSK_STATE_GSC_HAS_NO_KEY: GSC has no PSK 482 * @GSA_GSC_PSK_STATE_GSC_NOT_IN_BOOTLOADER: GSC is not in bootloader 483 * @GSA_GSC_PSK_STATE_GSC_INVALID_PARAMETER: GSC received invalid request data 484 * @GSA_GSC_PSK_STATE_GSC_INTERNAL_ERROR: GSC has internal error 485 * @GSA_GSC_PSK_STATE_GSC_CRYPTO_HKDF_FAIL: GSC crypto HKDF function fail 486 * @GSA_GSC_PSK_STATE_GSC_CRYPTO_HMAC_FAIL: GSC crypto HMAC function fail 487 * @GSA_GSC_PSK_STATE_GSC_EXCEED_MAX_RETRY_COUNT: exceed max psk verification retry count (100) 488 * @GSA_GSA_PSK_STATE_GSC_NOS_CALL_FAIL: GSC nos call fail 489 */ 490 enum gsa_gsc_psk_state { 491 GSA_GSC_PSK_STATE_UNKNOWN, 492 GSA_GSC_PSK_STATE_KEY_VERIFY_SUCCESS, 493 GSA_GSC_PSK_STATE_KEY_MISMATCH, 494 GSA_GSC_PSK_STATE_GSA_INTERNAL_ERROR, 495 GSA_GSC_PSK_STATE_GSA_HAS_NO_KEY, 496 GSA_GSC_PSK_STATE_GSA_CRYPTO_PRNG_FAIL, 497 GSA_GSC_PSK_STATE_GSA_CRYPTO_HKDF_FAIL, 498 GSA_GSC_PSK_STATE_GSA_CRYPTO_HMAC_FAIL, 499 GSA_GSC_PSK_STATE_GSA_CRYPTO_DONE, 500 GSA_GSC_PSK_STATE_GSC_HAS_NO_KEY, 501 GSA_GSC_PSK_STATE_GSC_NOT_IN_BOOTLOADER, 502 GSA_GSC_PSK_STATE_GSC_INVALID_PARAMETER, 503 GSA_GSC_PSK_STATE_GSC_INTERNAL_ERROR, 504 GSA_GSC_PSK_STATE_GSC_CRYPTO_HKDF_FAIL, 505 GSA_GSC_PSK_STATE_GSC_CRYPTO_HMAC_FAIL, 506 GSA_GSC_PSK_STATE_GSC_EXCEED_MAX_RETRY_COUNT, 507 GSA_GSA_PSK_STATE_GSC_NOS_CALL_FAIL, 508 }; 509 510 #define VERIFY_PSK_REQ_HEADER_SIZE 17 511 #define VERIFY_PSK_REQ_VERSION 0 512 #define VERIFY_PSK_NONCE_SIZE 32 513 #define VERIFY_PSK_HMAC_SIZE 32 514 /** 515 * struct verify_psk_request - verify gsa-gsc pre-shared key request 516 * @version: struct verify_psk_request version 517 * @header: header of verify_psk_request 518 * @nonce: 12 bytes random number 519 * @gsa_psk_state: GSA pre-shared key state 520 * @hmac: hmac = HMAC-SHA256(key = derived-psk, data = version || header || 521 * nonce || gsa_psk_state) 522 */ 523 struct verify_psk_request { 524 uint8_t header[VERIFY_PSK_REQ_HEADER_SIZE]; 525 uint8_t version; 526 uint8_t nonce[VERIFY_PSK_NONCE_SIZE]; 527 uint8_t gsa_psk_state; 528 uint8_t hmac[VERIFY_PSK_HMAC_SIZE]; 529 }; 530 531 #define VERIFY_SECURE_CHANNEL_RETRY_COUNT_VERSION 0 532 struct secure_channel_retry_count_persist_storage { 533 uint8_t version; 534 uint8_t verify_psk_retry_count; 535 uint8_t reserved[2]; 536 }; 537 538 #define NUGGET_PARAM_VERIFY_GSA_GSC_PSK 0x0018 539 /* 540 * Verify GSA GSC pre-shared key command 541 * 542 * @param args struct verify_psk_request 543 * @param arg_len 83 bytes 544 * @param reply psk verification result 545 * @param reply_len 1 bytes 546 */ 547 548 #define NUGGET_PARAM_SECURE_TRANSPORT_HANDSHAKE 0x0019 549 /* 550 * Secure transport handshak (noise protocol) command 551 * 552 * @param args GSA EC public_key + AES_GCM256("MSGA") + AES_GSC_TAG 553 * @param arg_len 64 + 4 + 16 bytes = 84 554 * @param reply GSC EC public_key + AES_GCM256("MSGB") + AES_GSC_TAG OR 1 byte error state 555 * @param reply_len 64 + 4 + 16 bytes = 84 OR 1 556 */ 557 558 #define NUGGET_PARAM_SECURE_TRANSPORT_REPORT_STATE 0x001a 559 /* 560 * Secure transport report noise handshake state command 561 * 562 * @param args GSA noise handshake state 563 * @param arg_len 1 564 * @param reply <none> 565 * @param reply_len 1 566 */ 567 #define NUGGET_PARAM_GET_BIG_EVENT_REPORT 0x001b 568 /* 569 * This retrieves one pending big_event_report (defined in citadel_events.h). 570 * If none are pending, it returns nothing. 571 * 572 * @param args <none> 573 * @param arg_len 0 574 * @param reply struct big_event_report 575 * @param reply_len sizeof struct big_event_report OR 0 576 */ 577 #define NUGGET_PARAM_GET_BIG_EVENT_REPORT 0x001b 578 /* 579 * This retrieves one pending big_event_report (defined in citadel_events.h). 580 * If none are pending, it returns nothing. 581 * 582 * @param args <none> 583 * @param arg_len 0 584 * @param reply struct big_event_report 585 * @param reply_len sizeof struct big_event_report OR 0 586 */ 587 588 /****************************************************************************/ 589 /* Test related commands */ 590 591 #define NUGGET_PARAM_CYCLES_SINCE_BOOT 0x0100 592 /* 593 * Get the number of cycles since boot 594 * 595 * @param args <none> 596 * @param arg_len 0 597 * @param reply uint32_t cycles 598 * @param reply_len sizeof(uint32_t) 599 */ 600 601 enum nugget_app_selftest_cmd { 602 /* Generic */ 603 NUGGET_APP_SELFTEST_CMD_DEFAULT = 0, 604 NUGGET_APP_SELFTEST_CMD_HELP, 605 606 /* Application SelfTests */ 607 NUGGET_APP_SELFTEST_CMD_TRNG = 0x10, 608 }; 609 610 #define NUGGET_PARAM_SELFTEST 0x0101 611 /* 612 * Run an intentionally vaguely specified internal test. 613 * 614 * This accepts arbitrary args and returns arbitrary results, as defined by the 615 * Citadel firmware. To allow changes to Nugget OS without requiring 616 * simultaneous changes to the AP, calling this with no args will run a default 617 * set of tests and return a null-terminated string with the result. 618 * 619 * @param args zero or more null-terminated strings, concatenated 620 * @param arg_len number of bytes in args 621 * @param reply null-terminated string (usually) 622 * @param reply_len number of bytes in reply (including trailing '\0') 623 */ 624 625 /****************************************************************************/ 626 /* Support for Power 1.1 HAL */ 627 628 /* 629 * This struct is specific to Citadel and Nugget OS, but it's enough for the 630 * AP-side implementation to translate into the info required for the power 631 * stats service. 632 */ 633 #define NUGGET_APP_LOW_POWER_STATS_MAGIC 0xC0DEACE1 634 struct nugget_app_low_power_stats { /* version 1 */ 635 /* All times in usecs */ 636 uint64_t hard_reset_count; /* Cleared by power loss */ 637 uint64_t time_since_hard_reset; 638 /* Below are only since the last hard reset */ 639 uint64_t wake_count; 640 uint64_t time_at_last_wake; 641 uint64_t time_spent_awake; 642 uint64_t deep_sleep_count; 643 uint64_t time_at_last_deep_sleep; 644 uint64_t time_spent_in_deep_sleep; 645 uint64_t time_at_ap_reset; 646 uint64_t time_at_ap_bootloader_done; 647 /* 648 * New fields for v1, used by factory tests. The caller can tell whether the 649 * firmare supports these fields by checking the v1_magic value. 650 */ 651 uint32_t v1_magic; /* NUGGET_APP_LOW_POWER_STATS_MAGIC */ 652 uint32_t temp; 653 struct { 654 unsigned int phone_on_l : 1; 655 unsigned int vol_up_l : 1; 656 unsigned int vol_dn_l : 1; 657 unsigned int _padding : 29; /* pad to 32 bits */ 658 } signals; 659 } __packed; 660 661 #define NUGGET_PARAM_GET_LOW_POWER_STATS 0x200 662 /* 663 * Return information regarding deep sleep transitions 664 * 665 * @param args <none> 666 * @param arg_len 0 667 * @param reply struct nugget_param_get_low_power_stats 668 * @param reply_len sizeof(struct nugget_param_get_low_power_stats) 669 */ 670 671 /* UNIMPLEMENTED */ 672 /* Reseved just in case we decide we need it */ 673 #define NUGGET_PARAM_CLEAR_LOW_POWER_STATS 0x201 674 /* UNIMPLEMENTED */ 675 676 /****************************************************************************/ 677 /* Commands for code coverage and quality assurance */ 678 679 #define NUGGET_GET_COVERAGE_COUNTERS 0x0300 680 /** 681 * Returns the counters back to the master 682 * 683 * @param args module counter 684 * @param arg_len 1 685 * @param reply buffer containing coverage data in utf-8 format 686 * @param reply_len depends on the counters in the file 687 */ 688 689 /* 690 * Error returned if coverage data didn't fit in the buffer. 691 * 692 * TODO: Should really have a second arg which is an offset in the coverage 693 * data. That way we could call repeatedly to return data too big to return in 694 * a single command. 695 */ 696 enum { 697 NUGGET_ERROR_COVERAGE_OVERFLOW = APP_SPECIFIC_ERROR + 0x300, 698 }; 699 700 /****************************************************************************/ 701 /* These are bringup / debug functions only. */ 702 703 #define NUGGET_PARAM_READ32 0xF000 704 /* 705 * Read a 32-bit value from memory. 706 * 707 * DANGER, WILL ROBINSON! DANGER! There is NO sanity checking on this AT ALL. 708 * Read the wrong address, and Bad Things(tm) WILL happen. 709 * 710 * @param args uint32_t address 711 * @param arg_len sizeof(uint32_t) 712 * @param reply uint32_t value 713 * @param reply_len sizeof(uint32_t) 714 */ 715 716 struct nugget_app_write32 { 717 uint32_t address; 718 uint32_t value; 719 } __packed; 720 721 #define NUGGET_PARAM_WRITE32 0xF001 722 /* 723 * Write a 32-bit value to memory 724 * 725 * DANGER, WILL ROBINSON! DANGER! There is NO sanity checking on this AT ALL. 726 * Write the wrong values to the wrong address, and Bad Things(tm) WILL happen. 727 * 728 * @param args struct nugget_app_write32 729 * @param arg_len sizeof(struct nugget_app_write32) 730 * @param reply <none> 731 * @param reply_len 0 732 */ 733 734 #define NUGGET_PARAM_CONSOLE 0xF002 735 /* 736 * Send optional command, return recent console output 737 * 738 * @param args command, if any 739 * @param arg_len sizeof(command) 740 * @param reply recent console output 741 * @param reply_len len(recent console output) 742 */ 743 744 #define NUGGET_PARAM_MODULE_TEST 0xF003 745 /** 746 * Run a module test based on a provided command. 747 * 748 * A default command is afforded (0x00), which runs each module test that is 749 * currently enabled. Specific tests can be specified, but are not enumerated 750 * here. 751 * 752 * The return code of the command (enum app_status) encodes the success state of 753 * the tests. A result of `APP_SUCCESS` is, unsurprisingly, a success for all 754 * specified tests. A failure of a given test is encoded using the 755 * `APP_SPECIFIC_ERROR` values. This allows a given test to not only report that 756 * an error has occured, but also to report which test threw the error, and in 757 * what point of the test the error was thrown. 758 * The encoding is as follows: 759 * `rv = (APP_SPECIFIC_ERROR + command + test_step)` 760 * where `command` is the 4-byte test value (in steps of 0x10), and where the 761 * test_step is a subdivision of the test, valued from 0-15. 762 * 763 * The return string will describe each test that passes, and each test that 764 * fails, and how it failed. Tests should abort after the first failure. 765 * 766 * @param args uint32_t command 767 * @param arg_len sizeof(uint32_t) 768 * @param reply null-terminated string (usually) 769 * @param reply_len number of bytes in reply (including trailing '\0') 770 */ 771 772 enum nugget_app_sleep_mode { 773 NUGGET_APP_SLEEP_MODE_DEFAULT, 774 NUGGET_APP_SLEEP_MODE_WFI, 775 NUGGET_APP_SLEEP_MODE_SLEEP 776 }; 777 #define NUGGET_PARAM_SET_SLEEP_MODE 0xF004 778 /** 779 * Set the Sleep mode of the GSC. 780 * 781 * In certain tests, we expect the GSC to be in either WFI mode, or in deep 782 * sleep mode. The sleep state should be provided by the host to the GSC, to 783 * ensure that the test is performed in the correct circumstances. 784 * 785 * @param args enum nugget_app_sleep_mode selection 786 * @param arg_len 4 787 * @param reply <none> 788 * @param reply_len 0 789 */ 790 791 #define NUGGET_PARAM_TRIGGER_PIN 0xF005 792 /** 793 * Get/Set trigger pin level 794 * 795 * This command asks GSC to set the level (0|1) of an otherwise unused GPIO, 796 * to signal external test equipment. 797 * 798 * @param args 0 OR 1 799 * @param arg_len 0 OR 1 byte 800 * @param reply current state (0 or 1) 801 * @param reply_len 1 byte 802 * 803 * @errors APP_ERROR_BOGUS_ARGS 804 */ 805 806 #ifdef __cplusplus 807 } 808 #endif 809 810 #endif /* __CROS_EC_INCLUDE_APP_NUGGET_H */ 811