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 struct updater_config_arguments { 108 char *image, *ec_image; 109 char *archive, *quirks, *mode; 110 const char *programmer, *write_protection; 111 char *model; 112 char *emulation, *sys_props; 113 char *output_dir; 114 char *repack, *unpack; 115 int is_factory, try_update, force_update, do_manifest, host_only; 116 int fast_update; 117 int verbosity; 118 int override_gbb_flags; 119 int detect_servo; 120 int use_flash; 121 uint32_t gbb_flags; 122 bool detect_model_only; 123 bool unlock_me; 124 }; 125 126 /* 127 * Shared getopt arguments controlling flash behaviour. 128 * These are shared by multiple commands. 129 */ 130 enum { 131 OPT_CCD = 0x100, 132 OPT_EMULATE, 133 OPT_SERVO, 134 OPT_SERVO_PORT, 135 }; 136 137 #ifdef USE_FLASHROM 138 #define SHARED_FLASH_ARGS_SHORTOPTS "p:" 139 140 #define SHARED_FLASH_ARGS_LONGOPTS \ 141 {"programmer", 1, NULL, 'p'}, \ 142 {"ccd_without_servod", 2, NULL, OPT_CCD}, \ 143 {"servo", 0, NULL, OPT_SERVO}, \ 144 {"servo_port", 1, NULL, OPT_SERVO_PORT}, \ 145 {"emulate", 1, NULL, OPT_EMULATE}, 146 147 #define SHARED_FLASH_ARGS_HELP \ 148 "-p, --programmer=PRG\tChange AP (host) flashrom programmer\n" \ 149 " --ccd_without_servod[=SERIAL] \tFlash via CCD without servod\n" \ 150 " --emulate=FILE \tEmulate system firmware using file\n" \ 151 " --servo \tFlash using Servo (v2, v4, micro, ...)\n" \ 152 " --servo_port=PRT\tOverride servod port, implies --servo\n" 153 #else 154 #define SHARED_FLASH_ARGS_HELP 155 #define SHARED_FLASH_ARGS_LONGOPTS 156 #define SHARED_FLASH_ARGS_SHORTOPTS 157 #endif /* USE_FLASHROM */ 158 159 struct patch_config { 160 char *rootkey; 161 char *vblock_a; 162 char *vblock_b; 163 char *gscvd; 164 }; 165 166 struct model_config { 167 char *name; 168 char *image, *ec_image; 169 struct patch_config patches; 170 bool has_custom_label; 171 }; 172 173 struct manifest { 174 int num; 175 struct model_config *models; 176 struct u_archive *archive; 177 int default_model; 178 }; 179 180 enum updater_error_codes { 181 UPDATE_ERR_DONE, 182 UPDATE_ERR_NEED_RO_UPDATE, 183 UPDATE_ERR_NO_IMAGE, 184 UPDATE_ERR_SYSTEM_IMAGE, 185 UPDATE_ERR_INVALID_IMAGE, 186 UPDATE_ERR_SET_COOKIES, 187 UPDATE_ERR_WRITE_FIRMWARE, 188 UPDATE_ERR_PLATFORM, 189 UPDATE_ERR_TARGET, 190 UPDATE_ERR_ROOT_KEY, 191 UPDATE_ERR_TPM_ROLLBACK, 192 UPDATE_ERR_UNLOCK_CSME, 193 UPDATE_ERR_UNKNOWN, 194 }; 195 196 /* Messages explaining enum updater_error_codes. */ 197 extern const char * const updater_error_messages[]; 198 199 /* 200 * Returns a valid root key from GBB header, or NULL on failure. 201 */ 202 const struct vb2_packed_key *get_rootkey( 203 const struct vb2_gbb_header *gbb); 204 205 /* 206 * The main updater to update system firmware using the configuration parameter. 207 * Returns UPDATE_ERR_DONE if success, otherwise failure. 208 */ 209 enum updater_error_codes update_firmware(struct updater_config *cfg); 210 211 /* 212 * Allocates and initializes a updater_config object with default values. 213 * Returns the newly allocated object, or NULL on error. 214 */ 215 struct updater_config *updater_new_config(void); 216 217 /* 218 * Releases all resources in an updater configuration object. 219 */ 220 void updater_delete_config(struct updater_config *cfg); 221 222 /* 223 * Handle an argument if it is a shared updater option. 224 * Returns 1 if argument was used. 225 */ 226 int handle_flash_argument(struct updater_config_arguments *args, int opt, 227 char *optarg); 228 229 /** 230 * Helper function to setup an allocated updater_config object. 231 * Returns number of failures, or 0 on success. 232 * @param[out] updater_config, 233 * @param[int] updater_config_arguments, 234 */ 235 int updater_setup_config(struct updater_config *cfg, 236 const struct updater_config_arguments *arg); 237 238 /** 239 * Helper function to determine if to perform a update. 240 * Returns true to perform update otherwise false. 241 * @param[in] updater_config_arguments, 242 */ 243 bool updater_should_update(const struct updater_config_arguments *arg); 244 245 /* Prints the name and description from all supported quirks. */ 246 void updater_list_config_quirks(const struct updater_config *cfg); 247 248 /* 249 * Registers known quirks to a updater_config object. 250 */ 251 void updater_register_quirks(struct updater_config *cfg); 252 253 /* Gets the value (setting) of specified quirks from updater configuration. */ 254 int get_config_quirk(enum quirk_types quirk, const struct updater_config *cfg); 255 256 /* 257 * Gets the default quirk config string from target image name. 258 * Returns a string (in same format as --quirks) to load or NULL if no quirks. 259 */ 260 const char * const updater_get_model_quirks(struct updater_config *cfg); 261 262 /* 263 * Gets the quirk config string from target image CBFS. 264 * Returns a string (in same format as --quirks) to load or NULL if no quirks. 265 */ 266 char * updater_get_cbfs_quirks(struct updater_config *cfg); 267 268 /* 269 * Overrides the custom label config if the device was shipped with known 270 * special rootkey. 271 */ 272 const struct model_config *quirk_override_custom_label( 273 struct updater_config *cfg, 274 const struct manifest *manifest, 275 const struct model_config *model); 276 277 /* Functions from updater_archive.c */ 278 279 /* 280 * Opens an archive from given path. 281 * The type of archive will be determined automatically. 282 * Returns a pointer to reference to archive (must be released by archive_close 283 * when not used), otherwise NULL on error. 284 */ 285 struct u_archive *archive_open(const char *path); 286 287 /* 288 * Closes an archive reference. 289 * Returns 0 on success, otherwise non-zero as failure. 290 */ 291 int archive_close(struct u_archive *ar); 292 293 /* 294 * Checks if an entry (either file or directory) exists in archive. 295 * Returns 1 if exists, otherwise 0 296 */ 297 int archive_has_entry(struct u_archive *ar, const char *name); 298 299 /* 300 * Reads a file from archive. 301 * Returns 0 on success (data and size reflects the file content), 302 * otherwise non-zero as failure. 303 */ 304 int archive_read_file(struct u_archive *ar, const char *fname, 305 uint8_t **data, uint32_t *size, int64_t *mtime); 306 307 /* 308 * Writes a file into archive. 309 * If entry name (fname) is an absolute path (/file), always write into real 310 * file system. 311 * Returns 0 on success, otherwise non-zero as failure. 312 */ 313 int archive_write_file(struct u_archive *ar, const char *fname, 314 uint8_t *data, uint32_t size, int64_t mtime); 315 316 /* 317 * Traverses all files within archive (directories are ignored). 318 * For every entry, the path (relative the archive root) will be passed to 319 * callback function, until the callback returns non-zero. 320 * The arg argument will also be passed to callback. 321 * Returns 0 on success otherwise non-zero as failure. 322 */ 323 int archive_walk(struct u_archive *ar, void *arg, 324 int (*callback)(const char *path, void *arg)); 325 326 /* 327 * Copies all entries from one archive to another. 328 * Returns 0 on success, otherwise non-zero as failure. 329 */ 330 int archive_copy(struct u_archive *from, struct u_archive *to); 331 332 /* 333 * Creates a new manifest object by scanning files in archive. 334 * Returns the manifest on success, otherwise NULL for failure. 335 */ 336 struct manifest *new_manifest_from_archive(struct u_archive *archive); 337 338 /* Releases all resources allocated by given manifest object. */ 339 void delete_manifest(struct manifest *manifest); 340 341 /* Prints the information of objects in manifest (models and images) in JSON. */ 342 void print_json_manifest(const struct manifest *manifest); 343 344 /* 345 * Modifies a firmware image from patch information specified in model config. 346 * Returns 0 on success, otherwise number of failures. 347 */ 348 int patch_image_by_model( 349 struct firmware_image *image, const struct model_config *model, 350 struct u_archive *archive); 351 352 /* 353 * Finds the existing model_config from manifest that best matches current 354 * system (as defined by model_name). 355 * Returns a model_config from manifest, or NULL if not found. 356 */ 357 const struct model_config *manifest_find_model(struct updater_config *cfg, 358 const struct manifest *manifest, 359 const char *model_name); 360 361 /* 362 * Finds the first existing model_config from manifest that matches current 363 * system by reading RO_FRID from the existing host firmware. 364 * Returns a model_config from manifest, or NULL if not found. 365 */ 366 const struct model_config * 367 manifest_detect_model_from_frid(struct updater_config *cfg, 368 struct manifest *manifest); 369 370 /* 371 * Finds the custom label model config from the base model + system tag. 372 * The system tag came from the firmware VPD section. 373 * Returns the matched model_config, base if no applicable custom label data, 374 * or NULL for any critical error. 375 */ 376 const struct model_config *manifest_find_custom_label_model( 377 struct updater_config *cfg, 378 const struct manifest *manifest, 379 const struct model_config *base_model); 380 381 #endif /* VBOOT_REFERENCE_FUTILITY_UPDATER_H_ */ 382