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 /****************************************************************************/ 266 /* Test related commands */ 267 268 #define NUGGET_PARAM_CYCLES_SINCE_BOOT 0x0100 269 /* 270 * Get the number of cycles since boot 271 * 272 * @param args <none> 273 * @param arg_len 0 274 * @param reply uint32_t cycles 275 * @param reply_len sizeof(uint32_t) 276 */ 277 278 /****************************************************************************/ 279 /* Support for Power 1.1 HAL */ 280 281 /* 282 * This struct is specific to Citadel and Nugget OS, but it's enough for the 283 * AP-side implementation to translate into the info required for the HAL 284 * structs. 285 */ 286 struct nugget_app_low_power_stats { 287 /* All times in usecs */ 288 uint64_t hard_reset_count; /* Cleared by power loss */ 289 uint64_t time_since_hard_reset; 290 /* Below are only since the last hard reset */ 291 uint64_t wake_count; 292 uint64_t time_at_last_wake; 293 uint64_t time_spent_awake; 294 uint64_t deep_sleep_count; 295 uint64_t time_at_last_deep_sleep; 296 uint64_t time_spent_in_deep_sleep; 297 } __packed; 298 299 #define NUGGET_PARAM_GET_LOW_POWER_STATS 0x200 300 /* 301 * Return information regarding deep sleep transitions 302 * 303 * @param args <none> 304 * @param arg_len 0 305 * @param reply struct nugget_param_get_low_power_stats 306 * @param reply_len sizeof(struct nugget_param_get_low_power_stats) 307 */ 308 309 /* UNIMPLEMENTED */ 310 /* Reseved just in case we decide we need it */ 311 #define NUGGET_PARAM_CLEAR_LOW_POWER_STATS 0x201 312 /* UNIMPLEMENTED */ 313 314 /****************************************************************************/ 315 /* These are bringup / debug functions only. 316 * 317 * TODO(b/65067435): Remove all of these. 318 */ 319 320 #define NUGGET_PARAM_READ32 0xF000 321 /* 322 * Read a 32-bit value from memory. 323 * 324 * DANGER, WILL ROBINSON! DANGER! There is NO sanity checking on this AT ALL. 325 * Read the wrong address, and Bad Things(tm) WILL happen. 326 * 327 * @param args uint32_t address 328 * @param arg_len sizeof(uint32_t) 329 * @param reply uint32_t value 330 * @param reply_len sizeof(uint32_t) 331 */ 332 333 struct nugget_app_write32 { 334 uint32_t address; 335 uint32_t value; 336 } __packed; 337 338 #define NUGGET_PARAM_WRITE32 0xF001 339 /* 340 * Write a 32-bit value to memory 341 * 342 * DANGER, WILL ROBINSON! DANGER! There is NO sanity checking on this AT ALL. 343 * Write the wrong values to the wrong address, and Bad Things(tm) WILL happen. 344 * 345 * @param args struct nugget_app_write32 346 * @param arg_len sizeof(struct nugget_app_write32) 347 * @param reply <none> 348 * @param reply_len 0 349 */ 350 351 #ifdef __cplusplus 352 } 353 #endif 354 355 #endif /* __CROS_EC_INCLUDE_APP_NUGGET_H */ 356
