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 #include "flash_layout.h" 20 21 #ifdef __cplusplus 22 extern "C" { 23 #endif 24 25 /****************************************************************************/ 26 /* 27 * APP_ID_NUGGET uses the Transport API 28 */ 29 /****************************************************************************/ 30 31 /* App-specific errors */ 32 enum { 33 NUGGET_ERROR_LOCKED = APP_SPECIFIC_ERROR, 34 NUGGET_ERROR_RETRY, 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 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[CHIP_FLASH_BANK_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 * Set / Get Board ID 268 * 269 * This sets or gets the Board ID of the device. 270 * 271 * @param args <none> OR nugget_app_board_id 272 * @param arg_len 0 OR sizeof nugget_app_board_id 273 * @param reply struct nugget_app_board_id 274 * @param reply_len sizeof struct nugget_app_board_id 275 * 276 * @errors APP_ERROR_BOGUS_ARGS 277 */ 278 struct nugget_app_board_id { 279 uint32_t type; 280 uint32_t flag; 281 uint32_t inv; /* must equal ~type when setting */ 282 } __packed; 283 #define NUGGET_PARAM_BOARD_ID 0x000f 284 285 /* 286 * Enable/Disable the RDD SuzyQable Deteaction 287 * 288 * This always returns the current state of the RDD SuezyQable detection 289 * feature. 290 * 291 * The AP can request that the RDD SuezyQable detection to be disabled (0) or 292 * enabled (1). 293 * 294 * @param args 0 OR 1 295 * @param arg_len 0 OR 1 byte 296 * @param reply 0 OR 1 current state 297 * @param reply_len 1 byte 298 * 299 * @errors APP_ERROR_BOGUS_ARGS 300 */ 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 /****************************************************************************/ 314 /* Test related commands */ 315 316 #define NUGGET_PARAM_CYCLES_SINCE_BOOT 0x0100 317 /* 318 * Get the number of cycles since boot 319 * 320 * @param args <none> 321 * @param arg_len 0 322 * @param reply uint32_t cycles 323 * @param reply_len sizeof(uint32_t) 324 */ 325 326 #define NUGGET_PARAM_SELFTEST 0x0101 327 /* 328 * Run an intentionally vaguely specified internal test. 329 * 330 * This accepts arbitrary args and returns arbitrary results, as defined by the 331 * Citadel firmware. To allow changes to Nugget OS without requiring 332 * simultaneous changes to the AP, calling this with no args will run a default 333 * set of tests and return a null-terminated string with the result. 334 * 335 * @param args zero or more null-terminated strings, concatenated 336 * @param arg_len number of bytes in args 337 * @param reply null-terminated string (usually) 338 * @param reply_len number of bytes in reply (including trailing '\0') 339 */ 340 341 /****************************************************************************/ 342 /* Support for Power 1.1 HAL */ 343 344 /* 345 * This struct is specific to Citadel and Nugget OS, but it's enough for the 346 * AP-side implementation to translate into the info required for the HAL 347 * structs. 348 */ 349 struct nugget_app_low_power_stats { 350 /* All times in usecs */ 351 uint64_t hard_reset_count; /* Cleared by power loss */ 352 uint64_t time_since_hard_reset; 353 /* Below are only since the last hard reset */ 354 uint64_t wake_count; 355 uint64_t time_at_last_wake; 356 uint64_t time_spent_awake; 357 uint64_t deep_sleep_count; 358 uint64_t time_at_last_deep_sleep; 359 uint64_t time_spent_in_deep_sleep; 360 uint64_t time_at_ap_reset; 361 uint64_t time_at_ap_bootloader_done; 362 } __packed; 363 364 #define NUGGET_PARAM_GET_LOW_POWER_STATS 0x200 365 /* 366 * Return information regarding deep sleep transitions 367 * 368 * @param args <none> 369 * @param arg_len 0 370 * @param reply struct nugget_param_get_low_power_stats 371 * @param reply_len sizeof(struct nugget_param_get_low_power_stats) 372 */ 373 374 /* UNIMPLEMENTED */ 375 /* Reseved just in case we decide we need it */ 376 #define NUGGET_PARAM_CLEAR_LOW_POWER_STATS 0x201 377 /* UNIMPLEMENTED */ 378 379 /****************************************************************************/ 380 /* These are bringup / debug functions only. */ 381 382 #define NUGGET_PARAM_READ32 0xF000 383 /* 384 * Read a 32-bit value from memory. 385 * 386 * DANGER, WILL ROBINSON! DANGER! There is NO sanity checking on this AT ALL. 387 * Read the wrong address, and Bad Things(tm) WILL happen. 388 * 389 * @param args uint32_t address 390 * @param arg_len sizeof(uint32_t) 391 * @param reply uint32_t value 392 * @param reply_len sizeof(uint32_t) 393 */ 394 395 struct nugget_app_write32 { 396 uint32_t address; 397 uint32_t value; 398 } __packed; 399 400 #define NUGGET_PARAM_WRITE32 0xF001 401 /* 402 * Write a 32-bit value to memory 403 * 404 * DANGER, WILL ROBINSON! DANGER! There is NO sanity checking on this AT ALL. 405 * Write the wrong values to the wrong address, and Bad Things(tm) WILL happen. 406 * 407 * @param args struct nugget_app_write32 408 * @param arg_len sizeof(struct nugget_app_write32) 409 * @param reply <none> 410 * @param reply_len 0 411 */ 412 413 #define NUGGET_PARAM_CONSOLE 0xF002 414 /* 415 * Send optional command, return recent console output 416 * 417 * @param args command, if any 418 * @param arg_len sizeof(command) 419 * @param reply recent console output 420 * @param reply_len len(recent console output) 421 */ 422 423 #ifdef __cplusplus 424 } 425 #endif 426 427 #endif /* __CROS_EC_INCLUDE_APP_NUGGET_H */ 428