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 + 0, 33 NUGGET_ERROR_RETRY, 34 NUGGET_ERROR_VERIFY, 35 }; 36 37 /****************************************************************************/ 38 /* Application functions */ 39 40 #define NUGGET_PARAM_VERSION 0x0000 41 /* 42 * Return the one-line version string of the running image 43 * 44 * @param args <none> 45 * @param arg_len 0 46 * @param reply Null-terminated ASCII string 47 * @param reply_len Max length to return 48 * 49 * @errors APP_ERROR_TOO_MUCH 50 */ 51 52 /****************************************************************************/ 53 /* Firmware upgrade stuff */ 54 55 #define NP_FLASH_BLOCK_SIZE 2048 56 struct nugget_app_flash_block { 57 uint32_t block_digest; /* first 4 bytes of sha1 of the rest */ 58 uint32_t offset; /* from start of flash */ 59 uint8_t payload[NP_FLASH_BLOCK_SIZE]; /* data to write */ 60 } __packed; 61 62 #define NUGGET_PARAM_FLASH_BLOCK 0x0001 63 /* 64 * Erase and write a single flash block. 65 * 66 * @param args struct nugget_app_flash_block 67 * @param arg_len sizeof(struct nugget_app_flash_block) 68 * @param reply <none> 69 * @param reply_len 0 70 * 71 * @errors NUGGET_ERROR_LOCKED, NUGGET_ERROR_RETRY 72 */ 73 74 #define NUGGET_PARAM_REBOOT 0x0002 75 /* 76 * Reboot Citadel 77 * 78 * @param args <none> 79 * @param arg_len 0 80 * @param reply <none> 81 * @param reply_len 0 82 */ 83 84 /********* 85 * Firmware updates are written to flash with invalid headers. If an update 86 * password exists, headers can only be marked valid by providing that 87 * password. 88 */ 89 90 /* 91 * An unassigned password is defined to be all 0xff, with a don't-care digest. 92 * Anything else must have a valid digest over all password bytes. The password 93 * length is chosen arbitrarily for now, but should always be a fixed size with 94 * all bytes used, to resist brute-force guesses. 95 */ 96 #define NUGGET_UPDATE_PASSWORD_LEN 32 97 struct nugget_app_password { 98 uint32_t digest; /* first 4 bytes of sha1 of password (little endian) */ 99 uint8_t password[NUGGET_UPDATE_PASSWORD_LEN]; 100 } __packed; 101 102 103 enum NUGGET_ENABLE_HEADER { 104 NUGGET_ENABLE_HEADER_RO = 0x01, 105 NUGGET_ENABLE_HEADER_RW = 0x02, 106 }; 107 struct nugget_app_enable_update { 108 struct nugget_app_password password; 109 uint8_t which_headers; /* bit 0 = RO, bit 1 = RW */ 110 } __packed; 111 #define NUGGET_PARAM_ENABLE_UPDATE 0x0003 112 /* 113 * Mark the specified image header(s) as valid, if the provided password 114 * matches. Returns true if either header was CHANGED to valid, which is an 115 * indication that the AP should request a reboot so that it can take effect. 116 * 117 * @param args struct nugget_app_enable_update 118 * @param arg_len sizeof(struct nugget_app_enable_update) 119 * @param reply 0 or 1 120 * @param reply_len 1 byte 121 * 122 * @errors APP_ERROR_BOGUS_ARGS 123 */ 124 125 126 struct nugget_app_change_update_password { 127 struct nugget_app_password old_password; 128 struct nugget_app_password new_password; 129 } __packed; 130 #define NUGGET_PARAM_CHANGE_UPDATE_PASSWORD 0x0004 131 /* 132 * Change the update password. 133 * 134 * @param args struct nugget_app_change_update_password 135 * @param arg_len sizeof(struct nugget_app_change_update_password) 136 * @param reply <none> 137 * @param reply_len 0 138 * 139 * @errors APP_ERROR_BOGUS_ARGS 140 */ 141 142 #define NUGGET_PARAM_NUKE_FROM_ORBIT 0x0005 143 #define ERASE_CONFIRMATION 0xc05fefee 144 /* 145 * This will erase ALL user secrets and reboot. 146 * 147 * @param args uint32_t containing the ERASE_CONFIRMATION value 148 * @param arg_len sizeof(uint32_t) 149 * @param reply <none> 150 * @param reply_len 0 151 * 152 * @errors APP_ERROR_BOGUS_ARGS 153 */ 154 155 #define NUGGET_PARAM_DEVICE_ID 0x0006 156 /* 157 * Get the device ID of the chip. 158 * 159 * @param args <none> 160 * @param arg_len 0 161 * @param reply Null-terminated ASCII string 162 * @param reply_len Max length to return 163 */ 164 165 166 #define NUGGET_PARAM_LONG_VERSION 0x0007 167 /* 168 * Return the multi-line description of all images 169 * 170 * @param args <none> 171 * @param arg_len 0 172 * @param reply Null-terminated ASCII string 173 * @param reply_len Max length to return 174 * 175 * @errors APP_ERROR_TOO_MUCH 176 */ 177 178 #define NUGGET_PARAM_HEADER_RO_A 0x0008 179 /* 180 * Return the signature header for RO_A 181 * 182 * @param args <none> 183 * @param arg_len 0 184 * @param reply struct SignedHeader 185 * @param reply_len Max length to return 186 * 187 * @errors APP_ERROR_TOO_MUCH 188 */ 189 190 #define NUGGET_PARAM_HEADER_RO_B 0x0009 191 /* 192 * Return the signature header for RO_B 193 * 194 * @param args <none> 195 * @param arg_len 0 196 * @param reply struct SignedHeader 197 * @param reply_len Max length to return 198 * 199 * @errors APP_ERROR_TOO_MUCH 200 */ 201 202 #define NUGGET_PARAM_HEADER_RW_A 0x000a 203 /* 204 * Return the signature header for RW_A 205 * 206 * @param args <none> 207 * @param arg_len 0 208 * @param reply struct SignedHeader 209 * @param reply_len Max length to return 210 * 211 * @errors APP_ERROR_TOO_MUCH 212 */ 213 214 #define NUGGET_PARAM_HEADER_RW_B 0x000b 215 /* 216 * Return the signature header for RW_B 217 * 218 * @param args <none> 219 * @param arg_len 0 220 * @param reply struct SignedHeader 221 * @param reply_len Max length to return 222 * 223 * @errors APP_ERROR_TOO_MUCH 224 */ 225 226 #define NUGGET_PARAM_REPO_SNAPSHOT 0x000c 227 /* 228 * Return the multi-line repo snapshot info for the current image 229 * 230 * @param args <none> 231 * @param arg_len 0 232 * @param reply Null-terminated ASCII string 233 * @param reply_len Max length to return 234 * 235 * @errors APP_ERROR_TOO_MUCH 236 */ 237 238 enum nugget_ap_uart_passthru_cfg { 239 NUGGET_AP_UART_OFF, /* off */ 240 NUGGET_AP_UART_IS_USB, /* USB CCD is in use over SBU */ 241 NUGGET_AP_UART_ENABLED, /* AP UART is on SBU lines */ 242 NUGGET_AP_UART_SSC_UART, /* This doesn't actually exist */ 243 NUGGET_AP_UART_CITADEL_UART, /* Citadel UART on SBU lines (ew) */ 244 245 NUGGET_AP_UART_NUM_CFGS, 246 }; 247 #define NUGGET_PARAM_AP_UART_PASSTHRU 0x000d 248 /* 249 * Enable/Disable the AP UART PASSTHRU function 250 * 251 * This always returns the current state of the AP UART passthru feature. Even 252 * if the AP UART is disabled, a SuzyQable may connected to use the SBU lines. 253 * 254 * The AP can only request that the AP UART passthru feature be enabled 255 * (NUGGET_AP_UART_ENABLED), or disabled (NUGGET_AP_UART_OFF). The other enums 256 * are for internal testing. 257 * 258 * @param args <none> OR enum nugget_ap_uart_passthru_cfg 259 * @param arg_len 0 OR 1 byte 260 * @param reply enum nugget_param_ap_uart_passthru 261 * @param reply_len 1 byte 262 * 263 * @errors APP_ERROR_BOGUS_ARGS 264 */ 265 266 #define NUGGET_PARAM_RDD_CFG 0x000e 267 /* 268 * Enable/Disable the RDD SuzyQable Detection 269 * 270 * This always returns the current state of the RDD SuzyQable detection 271 * feature. 272 * 273 * The AP can request that the RDD SuzyQable detection to be disabled (0) or 274 * enabled (1). 275 * 276 * @param args 0 OR 1 277 * @param arg_len 0 OR 1 byte 278 * @param reply current state (0 or 1) 279 * @param reply_len 1 byte 280 * 281 * @errors APP_ERROR_BOGUS_ARGS 282 */ 283 284 #define NUGGET_PARAM_BOARD_ID 0x000f 285 /* 286 * Set / Get Board ID 287 * 288 * This sets or gets the Board ID of the device. 289 * 290 * @param args <none> OR nugget_app_board_id 291 * @param arg_len 0 OR sizeof nugget_app_board_id 292 * @param reply struct nugget_app_board_id 293 * @param reply_len sizeof struct nugget_app_board_id 294 * 295 * @errors APP_ERROR_BOGUS_ARGS 296 */ 297 struct nugget_app_board_id { 298 uint32_t type; 299 uint32_t flag; 300 uint32_t inv; /* must equal ~type when setting */ 301 } __packed; 302 303 #define NUGGET_PARAM_GET_EVENT_REPORT 0x0010 304 /* 305 * This retrieves one pending event_report (defined in citadel_events.h). 306 * If none are pending, it returns nothing. 307 * 308 * @param args <none> 309 * @param arg_len 0 310 * @param reply struct event_report 311 * @param reply_len sizeof struct event_report OR 0 312 */ 313 314 #define NUGGET_PARAM_AP_IS_REBOOTING 0x0011 315 /* 316 * This can be used to replace the GPIO signal for some boards, if the 317 * communication path is trusted. If not, it has no effect. 318 * 319 * @param args <none> 320 * @param arg_len 0 321 * @param reply <none> 322 * @param reply_len 0 323 */ 324 325 #define FILE_ID_NUGGET_PERSIST 0 326 #define NUGGET_PERSIST_VERSION_1 1 327 struct nugget_persist_t { 328 uint8_t version; 329 uint8_t user_consent; 330 uint8_t reserved[2]; 331 }; 332 333 enum nugget_sjtag_user_consent_cfg { 334 NUGGET_SJTAG_USER_CONSENT_DISALLOW, /* DISALLOW */ 335 NUGGET_SJTAG_USER_CONSENT_ALLOW, /* ALLOW */ 336 337 NUGGET_SJTAG_USER_CONSENT_NUM_CFGS, 338 }; 339 340 #define NUGGET_PARAM_SJTAG_USER_CONSENT 0x0012 341 /* 342 * Set/Get the SJTAG USER CONSENT function 343 * 344 * This always returns the current state of the SJTAG USER CONSENT feature. 345 * 346 * @param args <none> OR enum nugget_sjtag_user_consent_cfg 347 * @param arg_len 0 OR 1 byte 348 * @param reply enum nugget_sjtag_user_consent_cfg 349 * @param reply_len 1 byte 350 * 351 * @errors APP_ERROR_BOGUS_ARGS 352 */ 353 354 enum nugget_sjtag_avb_boot_lock_result { 355 AVB_BOOT_LOCK_DISABLED, 356 AVB_BOOT_LOCK_ENABLED, 357 AVB_BOOT_LOCK_ERROR, 358 }; 359 360 #define NUGGET_PARAM_SJTAG_ALLOW 0x0013 361 /* 362 * Get the SJTAG ALLOW 363 * 364 * This always returns the current state of the SJTAG ALLOW feature. 365 * 366 * @param args <none> 367 * @param arg_len 0 368 * @param reply 0(DISALLOW) OR 1(ALLOW) 369 * @param reply_len 1 byte 370 * 371 * @errors APP_ERROR_BOGUS_ARGS 372 */ 373 374 /* 375 * Persistent storage of arbitrary data, up to 376 * (FS_MAX_FILE_SIZE - sizeof(struct nugget_app_data)) bytes. 377 */ 378 struct nugget_app_storage { 379 uint32_t flags; /* TBD, use zero for now */ 380 #ifndef __cplusplus 381 uint8_t data[]; /* Zero or more bytes */ 382 #endif 383 } __packed; 384 385 #define NUGGET_PARAM_STORAGE_WRITE 0x0014 386 /* 387 * Write arbitrary data. 388 * 389 * The current storage is erased, then new data (if any) is saved. 390 * 391 * .flags meaning is not yet defined; for now it must be 0x00000000 392 * Possible usage could restrict reading to the bootloader, 393 * erase data after N reads or reboots, etc. 394 * 395 * @param args struct nugget_app_storage + zero or more bytes 396 * @param arg_len To write: > sizeof(struct nugget_app_storage) 397 * To erase: <= sizeof(struct nugget_app_storage) 398 * @param reply <none> 399 * @param reply_len 0 400 * 401 * @errors APP_ERROR_BOGUS_ARGS 402 */ 403 #define NUGGET_PARAM_STORAGE_READ 0x0015 404 /* 405 * Read arbitrary data. 406 * 407 * On success, struct nugget_app_storage is returned, followed by zero 408 * or more bytes of .data 409 * 410 * @param args <none> 411 * @param arg_len 0 412 * @param reply struct nugget_app_storage + zero or more bytes 413 * @param reply_len <varies> 414 * 415 * @errors APP_ERROR_BOGUS_ARGS 416 */ 417 418 #define GSC_DEBUG_DUMP_VERSION 0 419 struct gsc_debug_dump_msg { 420 uint8_t timestamp[6]; // Bottom 48 bits of system time; enough for 8 years @ 1 us 421 uint8_t channel; // log channel (task_id or system call) 422 uint8_t version; // gsc_debug_dump_msg struct version 423 uint32_t error_code; // error code 424 uint32_t reserved; // reserved for other useful log 425 }; 426 427 #define DEBUG_MESSAGE_MAX_COUNT 64 428 #define DEBUG_MESSAGE_BUFFER_SIZE (DEBUG_MESSAGE_MAX_COUNT * sizeof(struct gsc_debug_dump_msg)) 429 430 #define NUGGET_PARAM_DEBUG_DUMP 0x0016 431 /* 432 * Get GSC debug message from 1KB ring buffer 433 * 434 * @param args <none> 435 * @param arg_len 0 436 * @param reply recent debug buffer output 437 * @param reply_len 1KB 438 */ 439 440 #define GSA_GSC_PAIRING_VERSION 0 441 #define EC_P256_PUBLIC_KEY_SIZE 64 442 #define EC_P256_PRIVATE_KEY_SIZE 32 443 #define PSK_KEY_SIZE 32 444 #define HAS_GSA_PUBKEY 0xa3 445 struct gsa_gsc_pairing_persist_storage { 446 uint8_t version; 447 uint8_t has_gsa_public_key_provision; 448 uint8_t gsa_public_key[EC_P256_PUBLIC_KEY_SIZE]; 449 uint8_t gsc_private_key[EC_P256_PRIVATE_KEY_SIZE]; 450 uint8_t gsc_public_key[EC_P256_PUBLIC_KEY_SIZE]; 451 }; 452 453 #define GSA_GSC_PSK_VERSION 0 454 #define HAS_GSA_GSC_PSK 0xa5 455 struct gsa_gsc_psk_persist_storage { 456 uint8_t version; 457 uint8_t has_gsa_gsc_psk_provision; 458 uint8_t gsa_gsc_psk[PSK_KEY_SIZE]; 459 }; 460 461 #define NUGGET_PARAM_GSA_KEY_PROVISION 0x0017 462 /* 463 * GSA key provision command 464 * 465 * @param args gsa unique public key 466 * @param arg_len 32 467 * @param reply gsc public key + sha256(pre-shared key) 468 * @param reply_len 64 + 32 469 */ 470 471 /** 472 * enum gsa_gsc_psk_state - GSA-GSC PSK state 473 * @GSA_GSC_PSK_STATE_UNKNOWN: Unknown state (initial state) 474 * @GSA_GSC_PSK_STATE_KEY_VERIFY_SUCCESS: GSA and GSC PSK match 475 * @GSA_GSC_PSK_STATE_KEY_MISMATCH: GSA and GSC PSK mismatch 476 * @GSA_GSC_PSK_STATE_GSA_INTERNAL_ERROR: GSA has internal error 477 * @GSA_GSC_PSK_STATE_GSA_HAS_NO_KEY: GSA has no PSK 478 * @GSA_GSC_PSK_STATE_GSA_CRYPTO_PRNG_FAIL: GSA crypto prng function fail 479 * @GSA_GSC_PSK_STATE_GSA_CRYPTO_HKDF_FAIL: GSA crypto HKDF function fail 480 * @GSA_GSC_PSK_STATE_GSA_CRYPTO_HMAC_FAIL: GSA crypto HMAC function fail 481 * @GSA_GSC_PSK_STATE_GSA_CRYPTO_DONE: GSA crypto operations complete 482 * @GSA_GSC_PSK_STATE_GSC_HAS_NO_KEY: GSC has no PSK 483 * @GSA_GSC_PSK_STATE_GSC_NOT_IN_BOOTLOADER: GSC is not in bootloader 484 * @GSA_GSC_PSK_STATE_GSC_INVALID_PARAMETER: GSC received invalid request data 485 * @GSA_GSC_PSK_STATE_GSC_INTERNAL_ERROR: GSC has internal error 486 * @GSA_GSC_PSK_STATE_GSC_CRYPTO_HKDF_FAIL: GSC crypto HKDF function fail 487 * @GSA_GSC_PSK_STATE_GSC_CRYPTO_HMAC_FAIL: GSC crypto HMAC function fail 488 * @GSA_GSC_PSK_STATE_GSC_EXCEED_MAX_RETRY_COUNT: exceed max psk verification retry count (100) 489 * @GSA_GSA_PSK_STATE_GSC_NOS_CALL_FAIL: GSC nos call fail 490 */ 491 enum gsa_gsc_psk_state { 492 GSA_GSC_PSK_STATE_UNKNOWN, 493 GSA_GSC_PSK_STATE_KEY_VERIFY_SUCCESS, 494 GSA_GSC_PSK_STATE_KEY_MISMATCH, 495 GSA_GSC_PSK_STATE_GSA_INTERNAL_ERROR, 496 GSA_GSC_PSK_STATE_GSA_HAS_NO_KEY, 497 GSA_GSC_PSK_STATE_GSA_CRYPTO_PRNG_FAIL, 498 GSA_GSC_PSK_STATE_GSA_CRYPTO_HKDF_FAIL, 499 GSA_GSC_PSK_STATE_GSA_CRYPTO_HMAC_FAIL, 500 GSA_GSC_PSK_STATE_GSA_CRYPTO_DONE, 501 GSA_GSC_PSK_STATE_GSC_HAS_NO_KEY, 502 GSA_GSC_PSK_STATE_GSC_NOT_IN_BOOTLOADER, 503 GSA_GSC_PSK_STATE_GSC_INVALID_PARAMETER, 504 GSA_GSC_PSK_STATE_GSC_INTERNAL_ERROR, 505 GSA_GSC_PSK_STATE_GSC_CRYPTO_HKDF_FAIL, 506 GSA_GSC_PSK_STATE_GSC_CRYPTO_HMAC_FAIL, 507 GSA_GSC_PSK_STATE_GSC_EXCEED_MAX_RETRY_COUNT, 508 GSA_GSA_PSK_STATE_GSC_NOS_CALL_FAIL, 509 }; 510 511 #define VERIFY_PSK_REQ_HEADER_SIZE 17 512 #define VERIFY_PSK_REQ_VERSION 0 513 #define VERIFY_PSK_NONCE_SIZE 32 514 #define VERIFY_PSK_HMAC_SIZE 32 515 /** 516 * struct verify_psk_request - verify gsa-gsc pre-shared key request 517 * @version: struct verify_psk_request version 518 * @header: header of verify_psk_request 519 * @nonce: 12 bytes random number 520 * @gsa_psk_state: GSA pre-shared key state 521 * @hmac: hmac = HMAC-SHA256(key = derived-psk, data = version || header || 522 * nonce || gsa_psk_state) 523 */ 524 struct verify_psk_request { 525 uint8_t header[VERIFY_PSK_REQ_HEADER_SIZE]; 526 uint8_t version; 527 uint8_t nonce[VERIFY_PSK_NONCE_SIZE]; 528 uint8_t gsa_psk_state; 529 uint8_t hmac[VERIFY_PSK_HMAC_SIZE]; 530 }; 531 532 #define VERIFY_SECURE_CHANNEL_RETRY_COUNT_VERSION 0 533 struct secure_channel_retry_count_persist_storage { 534 uint8_t version; 535 uint8_t verify_psk_retry_count; 536 uint8_t reserved[2]; 537 }; 538 539 #define NUGGET_PARAM_VERIFY_GSA_GSC_PSK 0x0018 540 /* 541 * Verify GSA GSC pre-shared key command 542 * 543 * @param args struct verify_psk_request 544 * @param arg_len 83 bytes 545 * @param reply psk verification result 546 * @param reply_len 1 bytes 547 */ 548 549 #define NUGGET_PARAM_SECURE_TRANSPORT_HANDSHAKE 0x0019 550 /* 551 * Secure transport handshak (noise protocol) command 552 * 553 * @param args GSA EC public_key + AES_GCM256("MSGA") + AES_GSC_TAG 554 * @param arg_len 64 + 4 + 16 bytes = 84 555 * @param reply GSC EC public_key + AES_GCM256("MSGB") + AES_GSC_TAG 556 * OR 1 byte error state 557 * @param reply_len 64 + 4 + 16 bytes = 84 OR 1 558 */ 559 560 #define NUGGET_PARAM_SECURE_TRANSPORT_REPORT_STATE 0x001a 561 /* 562 * Secure transport report noise handshake state command 563 * 564 * @param args GSA noise handshake state + report suez state 565 * @param arg_len 2 566 * @param reply <none> 567 * @param reply_len 1 568 */ 569 570 #define NUGGET_PARAM_GET_BIG_EVENT_REPORT 0x001b 571 /* 572 * This retrieves one pending big_event_report (defined in citadel_events.h). 573 * If none are pending, it returns nothing. 574 * 575 * @param args <none> 576 * @param arg_len 0 577 * @param reply struct big_event_report 578 * @param reply_len sizeof struct big_event_report OR 0 579 */ 580 581 #define NUGGET_PARAM_GET_FEATURE_SUPPORT 0x001c 582 /* 583 * Get the specific feature supportness from the specific TA. 584 * 585 * @param args feature_id 586 * @param arg_len 4 byte 587 * @param reply 0 or 1 588 * @param reply_len 1 byte 589 * 590 * @errors APP_ERROR_BOGUS_ARGS 591 */ 592 593 #define NUGGET_PARAM_SECURE_TRANSPORT_USECASE_HANDSHAKE 0x001d 594 /* 595 * Secure transport usecase handshake command 596 * 597 * @param args AES_GCM256(struct secure_transport_usecase) + 598 * AES_GCM_TAG_SIZE 599 * @param arg_len 64 + 16 = 80 bytes 600 * @param reply AES_GCM256(struct secure_transport_usecase) + 601 * AES_GCM_TAG_SIZE OR 1 byte error state 602 * @param reply_len 64 + 16 = 80 OR 1 bytes 603 */ 604 605 #define NUGGET_PARAM_SECURE_TRANSPORT_TEST 0x001e 606 /* 607 * Secure transport test command 608 * 609 * @param args 1008 (1024 - 16 bytes AES_TAG_SIZE) bytes test data 610 * @param arg_len 1008 bytes 611 * @param reply 1008 (1024 - 16 bytes AES_TAG_SIZE) bytes test data 612 * @param reply_len 1008 bytes 613 */ 614 615 /****************************************************************************/ 616 /* Test related commands */ 617 618 #define NUGGET_PARAM_CYCLES_SINCE_BOOT 0x0100 619 /* 620 * Get the number of cycles since boot 621 * 622 * @param args <none> 623 * @param arg_len 0 624 * @param reply uint32_t cycles 625 * @param reply_len sizeof(uint32_t) 626 */ 627 628 enum nugget_app_selftest_cmd { 629 /* Generic */ 630 NUGGET_APP_SELFTEST_CMD_DEFAULT = 0, 631 NUGGET_APP_SELFTEST_CMD_HELP, 632 633 /* Application SelfTests */ 634 NUGGET_APP_SELFTEST_CMD_TRNG = 0x10, 635 }; 636 637 #define NUGGET_PARAM_SELFTEST 0x0101 638 /* 639 * Run an intentionally vaguely specified internal test. 640 * 641 * This accepts arbitrary args and returns arbitrary results, as defined by the 642 * Citadel firmware. To allow changes to Nugget OS without requiring 643 * simultaneous changes to the AP, calling this with no args will run a default 644 * set of tests and return a null-terminated string with the result. 645 * 646 * @param args zero or more null-terminated strings, concatenated 647 * @param arg_len number of bytes in args 648 * @param reply null-terminated string (usually) 649 * @param reply_len number of bytes in reply (including trailing '\0') 650 */ 651 652 /****************************************************************************/ 653 /* Support for Power 1.1 HAL */ 654 655 /* 656 * This struct is specific to Citadel and Nugget OS, but it's enough for the 657 * AP-side implementation to translate into the info required for the power 658 * stats service. 659 */ 660 #define NUGGET_APP_LOW_POWER_STATS_MAGIC 0xC0DEACE1 661 struct nugget_app_low_power_stats { /* version 1 */ 662 /* All times in usecs */ 663 uint64_t hard_reset_count; /* Cleared by power loss */ 664 uint64_t time_since_hard_reset; 665 /* Below are only since the last hard reset */ 666 uint64_t wake_count; 667 uint64_t time_at_last_wake; 668 uint64_t time_spent_awake; 669 uint64_t deep_sleep_count; 670 uint64_t time_at_last_deep_sleep; 671 uint64_t time_spent_in_deep_sleep; 672 uint64_t time_at_ap_reset; 673 uint64_t time_at_ap_bootloader_done; 674 /* 675 * New fields for v1, used by factory tests. The caller can tell whether the 676 * firmare supports these fields by checking the v1_magic value. 677 */ 678 uint32_t v1_magic; /* NUGGET_APP_LOW_POWER_STATS_MAGIC */ 679 uint32_t temp; 680 struct { 681 unsigned int phone_on_l : 1; 682 unsigned int vol_up_l : 1; 683 unsigned int vol_dn_l : 1; 684 unsigned int _padding : 29; /* pad to 32 bits */ 685 } signals; 686 } __packed; 687 688 #define NUGGET_PARAM_GET_LOW_POWER_STATS 0x200 689 /* 690 * Return information regarding deep sleep transitions 691 * 692 * @param args <none> 693 * @param arg_len 0 694 * @param reply struct nugget_param_get_low_power_stats 695 * @param reply_len sizeof(struct nugget_param_get_low_power_stats) 696 */ 697 698 /* UNIMPLEMENTED */ 699 /* Reseved just in case we decide we need it */ 700 #define NUGGET_PARAM_CLEAR_LOW_POWER_STATS 0x201 701 /* UNIMPLEMENTED */ 702 703 /****************************************************************************/ 704 /* Commands for code coverage and quality assurance */ 705 706 #define NUGGET_GET_COVERAGE_COUNTERS 0x0300 707 /** 708 * Returns the counters back to the master 709 * 710 * @param args module counter 711 * @param arg_len 1 712 * @param reply buffer containing coverage data in utf-8 format 713 * @param reply_len depends on the counters in the file 714 */ 715 716 /* 717 * Error returned if coverage data didn't fit in the buffer. 718 * 719 * TODO: Should really have a second arg which is an offset in the coverage 720 * data. That way we could call repeatedly to return data too big to return in 721 * a single command. 722 */ 723 enum { 724 NUGGET_ERROR_COVERAGE_OVERFLOW = APP_SPECIFIC_ERROR + 0x300, 725 }; 726 727 /****************************************************************************/ 728 /* These are bringup / debug functions only. */ 729 730 #define NUGGET_PARAM_READ32 0xF000 731 /* 732 * Read a 32-bit value from memory. 733 * 734 * DANGER, WILL ROBINSON! DANGER! There is NO sanity checking on this AT ALL. 735 * Read the wrong address, and Bad Things(tm) WILL happen. 736 * 737 * @param args uint32_t address 738 * @param arg_len sizeof(uint32_t) 739 * @param reply uint32_t value 740 * @param reply_len sizeof(uint32_t) 741 */ 742 743 struct nugget_app_write32 { 744 uint32_t address; 745 uint32_t value; 746 } __packed; 747 748 #define NUGGET_PARAM_WRITE32 0xF001 749 /* 750 * Write a 32-bit value to memory 751 * 752 * DANGER, WILL ROBINSON! DANGER! There is NO sanity checking on this AT ALL. 753 * Write the wrong values to the wrong address, and Bad Things(tm) WILL happen. 754 * 755 * @param args struct nugget_app_write32 756 * @param arg_len sizeof(struct nugget_app_write32) 757 * @param reply <none> 758 * @param reply_len 0 759 */ 760 761 #define NUGGET_PARAM_CONSOLE 0xF002 762 /* 763 * Send optional command, return recent console output 764 * 765 * @param args command, if any 766 * @param arg_len sizeof(command) 767 * @param reply recent console output 768 * @param reply_len len(recent console output) 769 */ 770 771 #define NUGGET_PARAM_MODULE_TEST 0xF003 772 /** 773 * Run a module test based on a provided command. 774 * 775 * A default command is afforded (0x00), which runs each module test that is 776 * currently enabled. Specific tests can be specified, but are not enumerated 777 * here. 778 * 779 * The return code of the command (enum app_status) encodes the success state of 780 * the tests. A result of `APP_SUCCESS` is, unsurprisingly, a success for all 781 * specified tests. A failure of a given test is encoded using the 782 * `APP_SPECIFIC_ERROR` values. This allows a given test to not only report that 783 * an error has occured, but also to report which test threw the error, and in 784 * what point of the test the error was thrown. 785 * The encoding is as follows: 786 * `rv = (APP_SPECIFIC_ERROR + command + test_step)` 787 * where `command` is the 4-byte test value (in steps of 0x10), and where the 788 * test_step is a subdivision of the test, valued from 0-15. 789 * 790 * The return string will describe each test that passes, and each test that 791 * fails, and how it failed. Tests should abort after the first failure. 792 * 793 * @param args uint32_t command 794 * @param arg_len sizeof(uint32_t) 795 * @param reply null-terminated string (usually) 796 * @param reply_len number of bytes in reply (including trailing '\0') 797 */ 798 799 enum nugget_app_sleep_mode { 800 NUGGET_APP_SLEEP_MODE_DEFAULT, 801 NUGGET_APP_SLEEP_MODE_WFI, 802 NUGGET_APP_SLEEP_MODE_SLEEP 803 }; 804 #define NUGGET_PARAM_SET_SLEEP_MODE 0xF004 805 /** 806 * Set the Sleep mode of the GSC. 807 * 808 * In certain tests, we expect the GSC to be in either WFI mode, or in deep 809 * sleep mode. The sleep state should be provided by the host to the GSC, to 810 * ensure that the test is performed in the correct circumstances. 811 * 812 * @param args enum nugget_app_sleep_mode selection 813 * @param arg_len 4 814 * @param reply <none> 815 * @param reply_len 0 816 */ 817 818 #define NUGGET_PARAM_TRIGGER_PIN 0xF005 819 /** 820 * Get/Set trigger pin level 821 * 822 * This command asks GSC to set the level (0|1) of an otherwise unused GPIO, 823 * to signal external test equipment. 824 * 825 * @param args 0 OR 1 826 * @param arg_len 0 OR 1 byte 827 * @param reply current state (0 or 1) 828 * @param reply_len 1 byte 829 * 830 * @errors APP_ERROR_BOGUS_ARGS 831 */ 832 833 #ifdef __cplusplus 834 } 835 #endif 836 837 #endif /* __CROS_EC_INCLUDE_APP_NUGGET_H */ 838