1 /* Copyright 2018 The ChromiumOS Authors 2 * Use of this source code is governed by a BSD-style license that can be 3 * found in the LICENSE file. 4 * 5 * A reference implementation for AP (and supporting images) firmware updater. 6 */ 7 8 #ifndef VBOOT_REFERENCE_FUTILITY_UPDATER_H_ 9 #define VBOOT_REFERENCE_FUTILITY_UPDATER_H_ 10 11 #include "futility.h" 12 #include "updater_utils.h" 13 14 /* FMAP section names. */ 15 static const char * const FMAP_RO = "WP_RO", 16 * const FMAP_RO_FMAP = "FMAP", 17 * const FMAP_RO_FRID = "RO_FRID", 18 * const FMAP_RO_SECTION = "RO_SECTION", 19 * const FMAP_RO_CBFS = "COREBOOT", 20 * const FMAP_RO_GBB = "GBB", 21 * const FMAP_RO_GSCVD = "RO_GSCVD", 22 * const FMAP_RO_VPD = "RO_VPD", 23 * const FMAP_RW_VBLOCK_A = "VBLOCK_A", 24 * const FMAP_RW_VBLOCK_B = "VBLOCK_B", 25 * const FMAP_RW_FW_MAIN_A = "FW_MAIN_A", 26 * const FMAP_RW_FW_MAIN_B = "FW_MAIN_B", 27 * const FMAP_RW_SECTION_A = "RW_SECTION_A", 28 * const FMAP_RW_SECTION_B = "RW_SECTION_B", 29 * const FMAP_RW_FWID = "RW_FWID", 30 * const FMAP_RW_FWID_A = "RW_FWID_A", 31 * const FMAP_RW_FWID_B = "RW_FWID_B", 32 * const FMAP_RW_SHARED = "RW_SHARED", 33 * const FMAP_RW_LEGACY = "RW_LEGACY", 34 * const FMAP_RW_VPD = "RW_VPD", 35 * const FMAP_RW_DIAG_NVRAM = "DIAG_NVRAM", 36 * const FMAP_SI_DESC = "SI_DESC", 37 * const FMAP_SI_ME = "SI_ME"; 38 39 struct updater_config; 40 struct quirk_entry { 41 const char *name; 42 const char *help; 43 int (*apply)(struct updater_config *cfg); 44 int value; 45 }; 46 47 enum quirk_types { 48 /* Platform-independent quirks */ 49 QUIRK_NO_CHECK_PLATFORM, 50 QUIRK_NO_VERIFY, 51 QUIRK_ENLARGE_IMAGE, 52 QUIRK_MIN_PLATFORM_VERSION, 53 QUIRK_EXTRA_RETRIES, 54 /* Arch-specific quirks */ 55 QUIRK_EC_PARTIAL_RECOVERY, 56 QUIRK_CLEAR_MRC_DATA, 57 QUIRK_PRESERVE_ME, 58 /* Platform-specific quirks (removed after AUE) */ 59 QUIRK_OVERRIDE_CUSTOM_LABEL, 60 QUIRK_EVE_SMM_STORE, 61 QUIRK_UNLOCK_CSME_EVE, 62 QUIRK_UNLOCK_CSME, 63 /* End of quirks */ 64 QUIRK_MAX, 65 }; 66 67 /* Return values from QUIRK_EC_PARTIAL_RECOVERY. */ 68 enum { 69 EC_RECOVERY_FULL = 0, /* Must be 0 as default value of quirks. */ 70 EC_RECOVERY_RO, 71 EC_RECOVERY_DONE 72 }; 73 74 enum try_update_type { 75 TRY_UPDATE_OFF = 0, 76 TRY_UPDATE_AUTO, 77 TRY_UPDATE_DEFERRED_HOLD, 78 TRY_UPDATE_DEFERRED_APPLY, 79 }; 80 81 struct updater_config { 82 struct firmware_image image, image_current; 83 struct firmware_image ec_image; 84 struct dut_property dut_properties[DUT_PROP_MAX]; 85 struct quirk_entry quirks[QUIRK_MAX]; 86 struct u_archive *archive; 87 struct tempfile tempfiles; 88 enum try_update_type try_update; 89 int force_update; 90 int legacy_update; 91 int factory_update; 92 int check_platform; 93 int use_diff_image; 94 int do_verify; 95 int verbosity; 96 const char *emulation; 97 char *emulation_programmer; 98 const char *original_programmer; 99 const char *prepare_ctrl_name; 100 int override_gbb_flags; 101 uint32_t gbb_flags; 102 bool detect_model; 103 bool dut_is_remote; 104 bool output_only; 105 }; 106 107 enum manifest_print_format { 108 MANIFEST_PRINT_FORMAT_JSON = 0, 109 MANIFEST_PRINT_FORMAT_PARSEABLE, 110 }; 111 112 struct updater_config_arguments { 113 char *image, *ec_image; 114 char *archive, *quirks, *mode; 115 const char *programmer, *write_protection; 116 char *model; 117 char *emulation, *sys_props; 118 char *output_dir; 119 char *repack, *unpack; 120 int is_factory, try_update, force_update, do_manifest, host_only; 121 enum manifest_print_format manifest_format; 122 int fast_update; 123 int verbosity; 124 int override_gbb_flags; 125 int detect_servo; 126 int use_flash; 127 uint32_t gbb_flags; 128 bool detect_model_only; 129 bool unlock_me; 130 }; 131 132 /* 133 * Shared getopt arguments controlling flash behaviour. 134 * These are shared by multiple commands. 135 */ 136 enum { 137 OPT_CCD = 0x100, 138 OPT_EMULATE, 139 OPT_SERVO, 140 OPT_SERVO_PORT, 141 }; 142 143 #ifdef USE_FLASHROM 144 #define SHARED_FLASH_ARGS_SHORTOPTS "p:" 145 146 #define SHARED_FLASH_ARGS_LONGOPTS \ 147 {"programmer", 1, NULL, 'p'}, \ 148 {"ccd_without_servod", 2, NULL, OPT_CCD}, \ 149 {"servo", 0, NULL, OPT_SERVO}, \ 150 {"servo_port", 1, NULL, OPT_SERVO_PORT}, \ 151 {"emulate", 1, NULL, OPT_EMULATE}, 152 153 #define SHARED_FLASH_ARGS_HELP \ 154 "-p, --programmer=PRG\tChange AP (host) flashrom programmer\n" \ 155 " --ccd_without_servod[=SERIAL] \tFlash via CCD without servod\n" \ 156 " --emulate=FILE \tEmulate system firmware using file\n" \ 157 " --servo \tFlash using Servo (v2, v4, micro, ...)\n" \ 158 " --servo_port=PRT\tOverride servod port, implies --servo\n" 159 #else 160 #define SHARED_FLASH_ARGS_HELP 161 #define SHARED_FLASH_ARGS_LONGOPTS 162 #define SHARED_FLASH_ARGS_SHORTOPTS 163 #endif /* USE_FLASHROM */ 164 165 struct patch_config { 166 char *rootkey; 167 char *vblock_a; 168 char *vblock_b; 169 char *gscvd; 170 }; 171 172 struct model_config { 173 char *name; 174 char *image, *ec_image; 175 struct patch_config patches; 176 bool has_custom_label; 177 }; 178 179 struct manifest { 180 int num; 181 struct model_config *models; 182 struct u_archive *archive; 183 int default_model; 184 }; 185 186 enum updater_error_codes { 187 UPDATE_ERR_DONE, 188 UPDATE_ERR_NEED_RO_UPDATE, 189 UPDATE_ERR_NO_IMAGE, 190 UPDATE_ERR_SYSTEM_IMAGE, 191 UPDATE_ERR_INVALID_IMAGE, 192 UPDATE_ERR_SET_COOKIES, 193 UPDATE_ERR_WRITE_FIRMWARE, 194 UPDATE_ERR_PLATFORM, 195 UPDATE_ERR_TARGET, 196 UPDATE_ERR_ROOT_KEY, 197 UPDATE_ERR_TPM_ROLLBACK, 198 UPDATE_ERR_UNLOCK_CSME, 199 UPDATE_ERR_UNKNOWN, 200 }; 201 202 /* Messages explaining enum updater_error_codes. */ 203 extern const char * const updater_error_messages[]; 204 205 /* 206 * Returns a valid root key from GBB header, or NULL on failure. 207 */ 208 const struct vb2_packed_key *get_rootkey( 209 const struct vb2_gbb_header *gbb); 210 211 /* 212 * The main updater to update system firmware using the configuration parameter. 213 * Returns UPDATE_ERR_DONE if success, otherwise failure. 214 */ 215 enum updater_error_codes update_firmware(struct updater_config *cfg); 216 217 /* 218 * Allocates and initializes a updater_config object with default values. 219 * Returns the newly allocated object, or NULL on error. 220 */ 221 struct updater_config *updater_new_config(void); 222 223 /* 224 * Releases all resources in an updater configuration object. 225 */ 226 void updater_delete_config(struct updater_config *cfg); 227 228 /* 229 * Handle an argument if it is a shared updater option. 230 * Returns 1 if argument was used. 231 */ 232 int handle_flash_argument(struct updater_config_arguments *args, int opt, 233 char *optarg); 234 235 /** 236 * Helper function to setup an allocated updater_config object. 237 * Returns number of failures, or 0 on success. 238 * @param[out] updater_config, 239 * @param[int] updater_config_arguments, 240 */ 241 int updater_setup_config(struct updater_config *cfg, 242 const struct updater_config_arguments *arg); 243 244 /** 245 * Helper function to determine if to perform a update. 246 * Returns true to perform update otherwise false. 247 * @param[in] updater_config_arguments, 248 */ 249 bool updater_should_update(const struct updater_config_arguments *arg); 250 251 /* Prints the name and description from all supported quirks. */ 252 void updater_list_config_quirks(const struct updater_config *cfg); 253 254 /* 255 * Registers known quirks to a updater_config object. 256 */ 257 void updater_register_quirks(struct updater_config *cfg); 258 259 /* Gets the value (setting) of specified quirks from updater configuration. */ 260 int get_config_quirk(enum quirk_types quirk, const struct updater_config *cfg); 261 262 /* 263 * Gets the default quirk config string from target image name. 264 * Returns a string (in same format as --quirks) to load or NULL if no quirks. 265 */ 266 const char * const updater_get_model_quirks(struct updater_config *cfg); 267 268 /* 269 * Gets the quirk config string from target image CBFS. 270 * Returns a string (in same format as --quirks) to load or NULL if no quirks. 271 */ 272 char * updater_get_cbfs_quirks(struct updater_config *cfg); 273 274 /* 275 * Overrides the custom label config if the device was shipped with known 276 * special rootkey. 277 */ 278 const struct model_config *quirk_override_custom_label( 279 struct updater_config *cfg, 280 const struct manifest *manifest, 281 const struct model_config *model); 282 283 /* Functions from updater_archive.c */ 284 285 /* 286 * Opens an archive from given path. 287 * The type of archive will be determined automatically. 288 * Returns a pointer to reference to archive (must be released by archive_close 289 * when not used), otherwise NULL on error. 290 */ 291 struct u_archive *archive_open(const char *path); 292 293 /* 294 * Closes an archive reference. 295 * Returns 0 on success, otherwise non-zero as failure. 296 */ 297 int archive_close(struct u_archive *ar); 298 299 /* 300 * Checks if an entry (either file or directory) exists in archive. 301 * Returns 1 if exists, otherwise 0 302 */ 303 int archive_has_entry(struct u_archive *ar, const char *name); 304 305 /* 306 * Reads a file from archive. 307 * Returns 0 on success (data and size reflects the file content), 308 * otherwise non-zero as failure. 309 */ 310 int archive_read_file(struct u_archive *ar, const char *fname, 311 uint8_t **data, uint32_t *size, int64_t *mtime); 312 313 /* 314 * Writes a file into archive. 315 * If entry name (fname) is an absolute path (/file), always write into real 316 * file system. 317 * Returns 0 on success, otherwise non-zero as failure. 318 */ 319 int archive_write_file(struct u_archive *ar, const char *fname, 320 uint8_t *data, uint32_t size, int64_t mtime); 321 322 /* 323 * Traverses all files within archive (directories are ignored). 324 * For every entry, the path (relative the archive root) will be passed to 325 * callback function, until the callback returns non-zero. 326 * The arg argument will also be passed to callback. 327 * Returns 0 on success otherwise non-zero as failure. 328 */ 329 int archive_walk(struct u_archive *ar, void *arg, 330 int (*callback)(const char *path, void *arg)); 331 332 /* 333 * Copies all entries from one archive to another. 334 * Returns 0 on success, otherwise non-zero as failure. 335 */ 336 int archive_copy(struct u_archive *from, struct u_archive *to); 337 338 /* 339 * Creates a new manifest object by scanning files in archive. 340 * Returns the manifest on success, otherwise NULL for failure. 341 */ 342 struct manifest *new_manifest_from_archive(struct u_archive *archive); 343 344 /* Releases all resources allocated by given manifest object. */ 345 void delete_manifest(struct manifest *manifest); 346 347 /* Prints the information of objects in manifest (models and images) in JSON. */ 348 void print_json_manifest(const struct manifest *manifest); 349 350 /* Prints the manifest in parseable double-colon-separated tokens format. */ 351 void print_parseable_manifest(const struct manifest *manifest); 352 353 /* 354 * Modifies a firmware image from patch information specified in model config. 355 * Returns 0 on success, otherwise number of failures. 356 */ 357 int patch_image_by_model( 358 struct firmware_image *image, const struct model_config *model, 359 struct u_archive *archive); 360 361 /* 362 * Finds the existing model_config from manifest that best matches current 363 * system (as defined by model_name). 364 * Returns a model_config from manifest, or NULL if not found. 365 */ 366 const struct model_config *manifest_find_model(struct updater_config *cfg, 367 const struct manifest *manifest, 368 const char *model_name); 369 370 /* 371 * Finds the first existing model_config from manifest that matches current 372 * system by reading RO_FRID from the existing host firmware. 373 * Returns a model_config from manifest, or NULL if not found. 374 */ 375 const struct model_config * 376 manifest_detect_model_from_frid(struct updater_config *cfg, 377 struct manifest *manifest); 378 379 /* 380 * Finds the custom label model config from the base model + system tag. 381 * The system tag came from the firmware VPD section. 382 * Returns the matched model_config, base if no applicable custom label data, 383 * or NULL for any critical error. 384 */ 385 const struct model_config *manifest_find_custom_label_model( 386 struct updater_config *cfg, 387 const struct manifest *manifest, 388 const struct model_config *base_model); 389 390 #endif /* VBOOT_REFERENCE_FUTILITY_UPDATER_H_ */ 391