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