1 /* Copyright (c) 2013 The Chromium OS Authors. All rights reserved. 2 * Use of this source code is governed by a BSD-style license that can be 3 * found in the LICENSE file. 4 */ 5 6 /* APIs provided by firmware to vboot_reference. 7 * 8 * General notes: 9 * 10 * All verified boot functions now start with "Vb" for namespace clarity. This 11 * fixes the problem where uboot and vboot both defined assert(). 12 * 13 * Verified boot APIs to be implemented by the calling firmware and exported to 14 * vboot_reference start with "VbEx". 15 * 16 * TODO: split this file into a vboot_entry_points.h file which contains the 17 * entry points for the firmware to call vboot_reference, and a 18 * vboot_firmware_exports.h which contains the APIs to be implemented by the 19 * calling firmware and exported to vboot_reference. 20 */ 21 22 #ifndef VBOOT_REFERENCE_VBOOT_API_H_ 23 #define VBOOT_REFERENCE_VBOOT_API_H_ 24 #include <stdint.h> 25 #include <stdlib.h> 26 27 /*****************************************************************************/ 28 /* Error codes */ 29 30 /* 31 * Functions which return an error all return this type. This is a 32-bit 32 * value rather than an int so it's consistent across UEFI, which is 32-bit 33 * during PEI and 64-bit during DXE/BDS. 34 */ 35 typedef uint32_t VbError_t; 36 37 /* 38 * Predefined error numbers. Success is 0. Errors are non-zero, but differ 39 * between functions. For example, the TPM functions may pass through TPM 40 * error codes, some of which may be recoverable. 41 */ 42 enum VbErrorPredefined_t { 43 /* No error; function completed successfully. */ 44 VBERROR_SUCCESS = 0, 45 46 /* 47 * The verified boot entry points VbInit(), VbSelectFirmware(), 48 * VbSelectAndLoadKernel() may return the following errors. 49 */ 50 /* Unknown error */ 51 VBERROR_UNKNOWN = 0x10000, 52 /* Unable to initialize shared data */ 53 VBERROR_INIT_SHARED_DATA = 0x10001, 54 /* Error resuming TPM during a S3 resume */ 55 VBERROR_TPM_S3_RESUME = 0x10002, 56 /* VbSelectFirmware() failed to find a valid firmware */ 57 VBERROR_LOAD_FIRMWARE = 0x10003, 58 /* Unable to write firmware versions to TPM */ 59 VBERROR_TPM_WRITE_FIRMWARE = 0x10004, 60 /* Unable to lock firmware versions in TPM */ 61 VBERROR_TPM_LOCK_FIRMWARE = 0x10005, 62 /* Unable to set boot mode state in TPM */ 63 VBERROR_TPM_SET_BOOT_MODE_STATE = 0x10006, 64 /* TPM requires reboot */ 65 VBERROR_TPM_REBOOT_REQUIRED = 0x10007, 66 /* Unable to set up TPM */ 67 VBERROR_TPM_FIRMWARE_SETUP = 0x10008, 68 /* Unable to read kernel versions from TPM */ 69 VBERROR_TPM_READ_KERNEL = 0x10009, 70 /* Attempt to load developer-only firmware with developer switch off */ 71 VBERROR_DEV_FIRMWARE_SWITCH_MISMATCH = 0x1000A, 72 /* Unable to write kernel versions to TPM */ 73 VBERROR_TPM_WRITE_KERNEL = 0x1000B, 74 /* Unable to lock kernel versions in TPM */ 75 VBERROR_TPM_LOCK_KERNEL = 0x1000C, 76 /* Calling firmware requested shutdown via VbExIsShutdownRequested() */ 77 VBERROR_SHUTDOWN_REQUESTED = 0x1000D, 78 /* Unable to find a boot device on which to look for a kernel */ 79 VBERROR_NO_DISK_FOUND = 0x1000E, 80 /* No OS kernel found on any boot device */ 81 VBERROR_NO_KERNEL_FOUND = 0x1000F, 82 /* All OS kernels found were invalid (corrupt, improperly signed...) */ 83 VBERROR_INVALID_KERNEL_FOUND = 0x10010, 84 /* VbSelectAndLoadKernel() requested recovery mode */ 85 VBERROR_LOAD_KERNEL_RECOVERY = 0x10011, 86 /* Other error inside VbSelectAndLoadKernel() */ 87 VBERROR_LOAD_KERNEL = 0x10012, 88 /* Invalid Google binary block */ 89 VBERROR_INVALID_GBB = 0x10013, 90 /* Invalid bitmap volume */ 91 VBERROR_INVALID_BMPFV = 0x10014, 92 /* Invalid screen index */ 93 VBERROR_INVALID_SCREEN_INDEX = 0x10015, 94 /* Simulated (test) error */ 95 VBERROR_SIMULATED = 0x10016, 96 /* Invalid parameter */ 97 VBERROR_INVALID_PARAMETER = 0x10017, 98 /* VbExBeep() can't make sounds at all */ 99 VBERROR_NO_SOUND = 0x10018, 100 /* VbExBeep() can't make sound in the background */ 101 VBERROR_NO_BACKGROUND_SOUND = 0x10019, 102 /* Developer has requested a BIOS shell */ 103 VBERROR_BIOS_SHELL_REQUESTED = 0x10020, 104 /* Need VGA and don't have it, or vice-versa */ 105 VBERROR_VGA_OPROM_MISMATCH = 0x10021, 106 /* Need EC to reboot to read-only code */ 107 VBERROR_EC_REBOOT_TO_RO_REQUIRED = 0x10022, 108 /* Invalid region read parameters */ 109 VBERROR_REGION_READ_INVALID = 0x10023, 110 /* Cannot read from region */ 111 VBERROR_REGION_READ_FAILED = 0x10024, 112 /* Unsupported region type */ 113 VBERROR_UNSUPPORTED_REGION = 0x10025, 114 /* No image present (returned from VbGbbReadImage() for missing image) */ 115 VBERROR_NO_IMAGE_PRESENT = 0x10026, 116 117 /* VbExEcGetExpectedRWHash() may return the following codes */ 118 /* Compute expected RW hash from the EC image; BIOS doesn't have it */ 119 VBERROR_EC_GET_EXPECTED_HASH_FROM_IMAGE = 0x20000, 120 }; 121 122 123 /*****************************************************************************/ 124 /* Main entry points from firmware into vboot_reference */ 125 126 /* 127 * Minimum and recommended size of shared_data_blob in bytes. Shared data blob 128 * is used to communicate data between calls to VbInit(), VbSelectFirmware(), 129 * the OS. Minimum size is enough to hold all required data for verified boot 130 * but may not be able to hold debug output. 131 */ 132 #define VB_SHARED_DATA_MIN_SIZE 3072 133 #define VB_SHARED_DATA_REC_SIZE 16384 134 135 /* 136 * Data passed by firmware to VbInit(), VbSelectFirmware() and 137 * VbSelectAndLoadKernel(). 138 * 139 * Note that in UEFI, these are called by different phases in different 140 * processor modes (VbInit() and VbSelectFirmware() = 32-bit PEI, 141 * VbSelectAndLoadKernel() = 64-bit BDS), so the data may be at a different 142 * location between calls. 143 */ 144 typedef struct VbCommonParams { 145 /* Pointer to GBB data */ 146 void *gbb_data; 147 /* Size of GBB data in bytes */ 148 uint32_t gbb_size; 149 150 /* 151 * Shared data blob for data shared between verified boot entry points. 152 * This should be at least VB_SHARED_DATA_MIN_SIZE bytes long, and 153 * ideally is VB_SHARED_DATA_REC_SIZE bytes long. 154 */ 155 /* Pointer to shared data blob buffer */ 156 void *shared_data_blob; 157 /* 158 * On input, set to size of shared data blob buffer, in bytes. On 159 * output, this will contain the actual data size placed into the 160 * buffer. 161 */ 162 uint32_t shared_data_size; 163 164 /* 165 * Internal context/data for verified boot, to maintain state during 166 * calls to other API functions such as VbExHashFirmwareBody(). 167 * Allocated and freed inside the entry point; firmware should not look 168 * at this. 169 */ 170 void *vboot_context; 171 172 /* 173 * Internal context/data for firmware / VbExHashFirmwareBody(). Needed 174 * because the PEI phase of UEFI boot runs out of ROM and thus can't 175 * modify global variables; everything needs to get passed around on 176 * the stack. 177 */ 178 void *caller_context; 179 180 /* For internal use of Vboot - do not examine or modify! */ 181 struct GoogleBinaryBlockHeader *gbb; 182 struct BmpBlockHeader *bmp; 183 } VbCommonParams; 184 185 /* Flags for VbInitParams.flags */ 186 /* Developer switch was on at boot time. */ 187 #define VB_INIT_FLAG_DEV_SWITCH_ON 0x00000001 188 /* Recovery button was pressed at boot time. */ 189 #define VB_INIT_FLAG_REC_BUTTON_PRESSED 0x00000002 190 /* Hardware write protect was enabled at boot time. */ 191 #define VB_INIT_FLAG_WP_ENABLED 0x00000004 192 /* This is a S3 resume, not a normal boot. */ 193 #define VB_INIT_FLAG_S3_RESUME 0x00000008 194 /* 195 * Previous boot attempt failed for reasons external to verified boot (RAM 196 * init failure, SSD missing, etc.). 197 * 198 * TODO: add a field to VbInitParams which holds a reason code, and report 199 * that via VbSharedData. 200 */ 201 #define VB_INIT_FLAG_PREVIOUS_BOOT_FAIL 0x00000010 202 /* 203 * Calling firmware supports read only firmware for normal/developer boot path. 204 */ 205 #define VB_INIT_FLAG_RO_NORMAL_SUPPORT 0x00000020 206 /* 207 * This platform does not have a physical dev-switch, so we must rely on a 208 * virtual switch (kept in the TPM) instead. When this flag is set, 209 * VB_INIT_FLAG_DEV_SWITCH_ON is ignored. 210 */ 211 #define VB_INIT_FLAG_VIRTUAL_DEV_SWITCH 0x00000040 212 /* Set when the VGA Option ROM has been loaded already. */ 213 #define VB_INIT_FLAG_OPROM_LOADED 0x00000080 214 /* Set if we care about the VGA Option ROM - some platforms don't. */ 215 #define VB_INIT_FLAG_OPROM_MATTERS 0x00000100 216 /* EC on this platform supports EC software sync. */ 217 #define VB_INIT_FLAG_EC_SOFTWARE_SYNC 0x00000200 218 /* EC on this platform is slow to update. */ 219 #define VB_INIT_FLAG_EC_SLOW_UPDATE 0x00000400 220 /* 221 * Software write protect was enabled at boot time. This is separate from the 222 * HW write protect. Both must be set for flash write protection to work. 223 */ 224 #define VB_INIT_FLAG_SW_WP_ENABLED 0x00000800 225 /* 226 * This platform does not have a physical recovery switch which, when present, 227 * can (and should) be used for additional physical presence checks. 228 */ 229 #define VB_INIT_FLAG_VIRTUAL_REC_SWITCH 0x00001000 230 /* Set when we are calling VbInit() before loading Option ROMs */ 231 #define VB_INIT_FLAG_BEFORE_OPROM_LOAD 0x00002000 232 233 /* 234 * Output flags for VbInitParams.out_flags. Used to indicate potential boot 235 * paths and configuration to the calling firmware early in the boot process, 236 * so that it can properly configure itself for the capabilities subsequently 237 * required by VbSelectFirmware() and VbSelectAndLoadKernel(). 238 */ 239 /* 240 * Enable recovery path. Do not rely on any rewritable data (cached RAM 241 * timings, etc.). Reliable operation is more important than boot speed. 242 */ 243 #define VB_INIT_OUT_ENABLE_RECOVERY 0x00000001 244 /* RAM must be cleared before calling VbSelectFirmware(). */ 245 #define VB_INIT_OUT_CLEAR_RAM 0x00000002 246 /* 247 * Load display drivers; VbExDisplay*() functions may be called. If this flag 248 * is not present, VbExDisplay*() functions will not be called this boot. 249 */ 250 #define VB_INIT_OUT_ENABLE_DISPLAY 0x00000004 251 /* 252 * Load USB storage drivers; VbExDisk*() functions may be called with the 253 * VB_DISK_FLAG_REMOVABLE flag. If this flag is not present, VbExDisk*() 254 * functions will only be called for fixed disks. 255 */ 256 #define VB_INIT_OUT_ENABLE_USB_STORAGE 0x00000008 257 /* If this is a S3 resume, do a debug reset boot instead */ 258 #define VB_INIT_OUT_S3_DEBUG_BOOT 0x00000010 259 /* BIOS should load any PCI option ROMs it finds, not just internal video */ 260 #define VB_INIT_OUT_ENABLE_OPROM 0x00000020 261 /* BIOS may be asked to boot something other than ChromeOS */ 262 #define VB_INIT_OUT_ENABLE_ALTERNATE_OS 0x00000040 263 /* Enable developer path. */ 264 #define VB_INIT_OUT_ENABLE_DEVELOPER 0x00000080 265 266 /* Data only used by VbInit() */ 267 typedef struct VbInitParams { 268 /* Inputs to VbInit() */ 269 /* Flags (see VB_INIT_FLAG_*) */ 270 uint32_t flags; 271 272 /* Outputs from VbInit(); valid only if it returns success. */ 273 /* Output flags for firmware; see VB_INIT_OUT_*) */ 274 uint32_t out_flags; 275 } VbInitParams; 276 277 /* 278 * Firmware types for VbHashFirmwareBody() and 279 * VbSelectFirmwareParams.selected_firmware. Note that we store these in a 280 * uint32_t because enum maps to int, which isn't fixed-size. 281 */ 282 enum VbSelectFirmware_t { 283 /* Recovery mode */ 284 VB_SELECT_FIRMWARE_RECOVERY = 0, 285 /* Rewritable firmware A/B for normal or developer path */ 286 VB_SELECT_FIRMWARE_A = 1, 287 VB_SELECT_FIRMWARE_B = 2, 288 /* Read only firmware for normal or developer path. */ 289 VB_SELECT_FIRMWARE_READONLY = 3, 290 VB_SELECT_FIRMWARE_COUNT, 291 }; 292 293 /* Data only used by VbSelectFirmware() */ 294 typedef struct VbSelectFirmwareParams { 295 /* Inputs to VbSelectFirmware() */ 296 /* Key block + preamble for firmware A */ 297 void *verification_block_A; 298 /* Key block + preamble for firmware B */ 299 void *verification_block_B; 300 /* Verification block A size in bytes */ 301 uint32_t verification_size_A; 302 /* Verification block B size in bytes */ 303 uint32_t verification_size_B; 304 305 /* Outputs from VbSelectFirmware(); valid only if it returns success. */ 306 /* Main firmware to run; see VB_SELECT_FIRMWARE_*. */ 307 uint32_t selected_firmware; 308 } VbSelectFirmwareParams; 309 310 /* 311 * We use disk handles rather than indices. Using indices causes problems if 312 * a disk is removed/inserted in the middle of processing. 313 */ 314 typedef void *VbExDiskHandle_t; 315 316 /* Data used only by VbSelectAndLoadKernel() */ 317 typedef struct VbSelectAndLoadKernelParams { 318 /* Inputs to VbSelectAndLoadKernel() */ 319 /* Destination buffer for kernel (normally at 0x100000 on x86) */ 320 void *kernel_buffer; 321 /* Size of kernel buffer in bytes */ 322 uint32_t kernel_buffer_size; 323 324 /* 325 * Outputs from VbSelectAndLoadKernel(); valid only if it returns 326 * success. 327 */ 328 /* Handle of disk containing loaded kernel */ 329 VbExDiskHandle_t disk_handle; 330 /* Partition number on disk to boot (1...M) */ 331 uint32_t partition_number; 332 /* Address of bootloader image in RAM */ 333 uint64_t bootloader_address; 334 /* Size of bootloader image in bytes */ 335 uint32_t bootloader_size; 336 /* UniquePartitionGuid for boot partition */ 337 uint8_t partition_guid[16]; 338 /* Flags passed in by signer */ 339 uint32_t flags; 340 /* 341 * TODO: in H2C, all that pretty much just gets passed to the 342 * bootloader as KernelBootloaderOptions, though the disk handle is 343 * passed as an index instead of a handle. Is that used anymore now 344 * that we're passing partition_guid? 345 */ 346 } VbSelectAndLoadKernelParams; 347 348 /** 349 * Initialize the verified boot library. 350 * 351 * Returns VBERROR_SUCCESS if success, non-zero if error; on error, 352 * caller should reboot. 353 */ 354 VbError_t VbInit(VbCommonParams *cparams, VbInitParams *iparams); 355 356 /** 357 * Select the main firmware. 358 * 359 * Returns VBERROR_SUCCESS if success, non-zero if error; on error, 360 * caller should reboot. 361 * 362 * NOTE: This is now called in all modes, including recovery. Previously, 363 * LoadFirmware() was not called in recovery mode, which meant that 364 * LoadKernel() needed to duplicate the TPM and VbSharedData initialization 365 * code. 366 */ 367 VbError_t VbSelectFirmware(VbCommonParams *cparams, 368 VbSelectFirmwareParams *fparams); 369 370 /** 371 * Update the data hash for the current firmware image, extending it by [size] 372 * bytes stored in [*data]. This function must only be called inside 373 * VbExHashFirmwareBody(), which is in turn called by VbSelectFirmware(). 374 */ 375 void VbUpdateFirmwareBodyHash(VbCommonParams *cparams, 376 uint8_t *data, uint32_t size); 377 378 /** 379 * Select and loads the kernel. 380 * 381 * Returns VBERROR_SUCCESS if success, non-zero if error; on error, caller 382 * should reboot. */ 383 VbError_t VbSelectAndLoadKernel(VbCommonParams *cparams, 384 VbSelectAndLoadKernelParams *kparams); 385 386 /*****************************************************************************/ 387 /* Debug output (from utility.h) */ 388 389 /** 390 * Output an error message and quit. Does not return. Supports 391 * printf()-style formatting. 392 */ 393 void VbExError(const char *format, ...); 394 395 /** 396 * Output a debug message. Supports printf()-style formatting. 397 */ 398 void VbExDebug(const char *format, ...) 399 __attribute__ ((format (__printf__, 1, 2))); 400 401 /*****************************************************************************/ 402 /* Memory (from utility.h) */ 403 404 /** 405 * Allocate [size] bytes and return a pointer to the allocated memory. Abort 406 * on error; this always either returns a good pointer or never returns. 407 * 408 * If any of the firmware API implementations require aligned data (for 409 * example, disk access on ARM), all pointers returned by VbExMalloc() must 410 * also be aligned. 411 */ 412 void *VbExMalloc(size_t size); 413 414 /** 415 * Free memory pointed to by [ptr] previously allocated by VbExMalloc(). 416 */ 417 void VbExFree(void *ptr); 418 419 /*****************************************************************************/ 420 /* Timer and delay (first two from utility.h) */ 421 422 /** 423 * Read a high-resolution timer. Returns the current timer value in arbitrary 424 * units. 425 * 426 * This is intended for benchmarking, so this call MUST be fast. The timer 427 * frequency must be >1 KHz (preferably >1 MHz), and the timer must not wrap 428 * around for at least 10 minutes. It is preferable (but not required) that 429 * the timer be initialized to 0 at boot. 430 * 431 * It is assumed that the firmware has some other way of communicating the 432 * timer frequency to the OS. For example, on x86 we use TSC, and the OS 433 * kernel reports the initial TSC value at kernel-start and calculates the 434 * frequency. */ 435 uint64_t VbExGetTimer(void); 436 437 /** 438 * Delay for at least the specified number of milliseconds. Should be accurate 439 * to within 10% (a requested delay of 1000 ms should result in an actual delay 440 * of between 1000 - 1100 ms). 441 */ 442 void VbExSleepMs(uint32_t msec); 443 444 /** 445 * Play a beep tone of the specified frequency in Hz and duration in msec. 446 * This is effectively a VbSleep() variant that makes noise. 447 * 448 * If the audio codec can run in the background, then: 449 * zero frequency means OFF, non-zero frequency means ON 450 * zero msec means return immediately, non-zero msec means delay (and 451 * then OFF if needed) 452 * otherwise, 453 * non-zero msec and non-zero frequency means ON, delay, OFF, return 454 * zero msec or zero frequency means do nothing and return immediately 455 * 456 * The return value is used by the caller to determine the capabilities. The 457 * implementation should always do the best it can if it cannot fully support 458 * all features - for example, beeping at a fixed frequency if frequency 459 * support is not available. At a minimum, it must delay for the specified 460 * non-zero duration. 461 */ 462 VbError_t VbExBeep(uint32_t msec, uint32_t frequency); 463 464 /*****************************************************************************/ 465 /* TPM (from tlcl_stub.h) */ 466 467 /** 468 * Initialize the stub library. */ 469 VbError_t VbExTpmInit(void); 470 471 /** 472 * Close and open the device. This is needed for running more complex commands 473 * at user level, such as TPM_TakeOwnership, since the TPM device can be opened 474 * only by one process at a time. 475 */ 476 VbError_t VbExTpmClose(void); 477 VbError_t VbExTpmOpen(void); 478 479 /** 480 * Send a request_length-byte request to the TPM and receive a response. On 481 * input, response_length is the size of the response buffer in bytes. On 482 * exit, response_length is set to the actual received response length in 483 * bytes. */ 484 VbError_t VbExTpmSendReceive(const uint8_t *request, uint32_t request_length, 485 uint8_t *response, uint32_t *response_length); 486 487 /*****************************************************************************/ 488 /* Non-volatile storage */ 489 490 #define VBNV_BLOCK_SIZE 16 /* Size of NV storage block in bytes */ 491 492 /** 493 * Read the VBNV_BLOCK_SIZE-byte non-volatile storage into buf. 494 */ 495 VbError_t VbExNvStorageRead(uint8_t *buf); 496 497 /** 498 * Write the VBNV_BLOCK_SIZE-byte non-volatile storage from buf. 499 */ 500 VbError_t VbExNvStorageWrite(const uint8_t *buf); 501 502 /*****************************************************************************/ 503 /* Firmware / EEPROM access (previously in load_firmware_fw.h) */ 504 505 /** 506 * Calculate the hash of the firmware body data for [firmware_index], which is 507 * either VB_SELECT_FIRMWARE_A or VB_SELECT_FIRMWARE B. 508 * 509 * This function must call VbUpdateFirmwareBodyHash() before returning, to 510 * update the secure hash for the firmware image. For best performance, the 511 * implementation should call VbUpdateFirmwareBodyHash() periodically during 512 * the read, so that updating the hash can be pipelined with the read. If the 513 * reader cannot update the hash during the read process, it should call 514 * VbUpdateFirmwareBodyHash() on the entire firmware data after the read, 515 * before returning. 516 * 517 * It is recommended that the firmware use this call to copy the requested 518 * firmware body from EEPROM into RAM, so that it doesn't need to do a second 519 * slow copy from EEPROM to RAM if this firmware body is selected. 520 * 521 * Note this function doesn't actually pass the firmware body data to verified 522 * boot, because verified boot doesn't actually need the firmware body, just 523 * its hash. This is important on x86, where the firmware is stored 524 * compressed. We hash the compressed data, but the BIOS decompresses it 525 * during read. Simply updating a hash is compatible with the x86 526 * read-and-decompress pipeline. 527 */ 528 VbError_t VbExHashFirmwareBody(VbCommonParams *cparams, 529 uint32_t firmware_index); 530 531 /*****************************************************************************/ 532 /* Disk access (previously in boot_device.h) */ 533 534 /* Flags for VbDisk APIs */ 535 /* Disk is removable. Example removable disks: SD cards, USB keys. */ 536 #define VB_DISK_FLAG_REMOVABLE 0x00000001 537 /* 538 * Disk is fixed. If this flag is present, disk is internal to the system and 539 * not removable. Example fixed disks: internal SATA SSD, eMMC. 540 */ 541 #define VB_DISK_FLAG_FIXED 0x00000002 542 /* 543 * Note that VB_DISK_FLAG_REMOVABLE and VB_DISK_FLAG_FIXED are 544 * mutually-exclusive for a single disk. VbExDiskGetInfo() may specify both 545 * flags to request disks of both types in a single call. 546 * 547 * At some point we could specify additional flags, but we don't currently 548 * have a way to make use of these: 549 * 550 * USB Device is known to be attached to USB. Note that the SD 551 * card reader inside x86 systems is attached to USB so this 552 * isn't super useful. 553 * SD Device is known to be a SD card. Note that external card 554 * readers might not return this information, so also of 555 * questionable use. 556 * READ_ONLY Device is known to be read-only. Could be used by recovery 557 * when processing read-only recovery image. 558 */ 559 560 /* 561 * Disks are used in two ways: 562 * - As a random-access device to read and write the GPT 563 * - As a streaming device to read the kernel 564 * These are implemented differently on raw NAND vs eMMC/SATA/USB 565 * - On eMMC/SATA/USB, both of these refer to the same underlying 566 * storage, so they have the same size and LBA size. In this case, 567 * the GPT should not point to the same address as itself. 568 * - On raw NAND, the GPT is held on a portion of the SPI flash. 569 * Random access GPT operations refer to the SPI and streaming 570 * operations refer to NAND. The GPT may therefore point into 571 * the same offsets as itself. 572 * These types are distinguished by the following flag and VbDiskInfo 573 * has separate fields to describe the random-access ("GPT") and 574 * streaming aspects of the disk. If a disk is random-access (i.e. 575 * not raw NAND) then these fields are equal. 576 */ 577 #define VB_DISK_FLAG_EXTERNAL_GPT 0x00000004 578 579 /* Information on a single disk */ 580 typedef struct VbDiskInfo { 581 /* Disk handle */ 582 VbExDiskHandle_t handle; 583 /* Size of a random-access LBA sector in bytes */ 584 uint64_t bytes_per_lba; 585 /* Number of random-access LBA sectors on the device. 586 * If streaming_lba_count is 0, this stands in for the size of the 587 * randomly accessed portion as well as the streaming portion. 588 * Otherwise, this is only the randomly-accessed portion. */ 589 uint64_t lba_count; 590 /* Number of streaming sectors on the device */ 591 uint64_t streaming_lba_count; 592 /* Flags (see VB_DISK_FLAG_* constants) */ 593 uint32_t flags; 594 /* 595 * Optional name string, for use in debugging. May be empty or null if 596 * not available. 597 */ 598 const char *name; 599 } VbDiskInfo; 600 601 /** 602 * Store information into [info] for all disks (storage devices) attached to 603 * the system which match all of the disk_flags. 604 * 605 * On output, count indicates how many disks are present, and [infos_ptr] 606 * points to a [count]-sized array of VbDiskInfo structs with the information 607 * on those disks; this pointer must be freed by calling VbExDiskFreeInfo(). 608 * If count=0, infos_ptr may point to NULL. If [infos_ptr] points to NULL 609 * because count=0 or error, it is not necessary to call VbExDiskFreeInfo(). 610 * 611 * A multi-function device (such as a 4-in-1 card reader) should provide 612 * multiple disk handles. 613 * 614 * The firmware must not alter or free the list pointed to by [infos_ptr] until 615 * VbExDiskFreeInfo() is called. 616 */ 617 VbError_t VbExDiskGetInfo(VbDiskInfo **infos_ptr, uint32_t *count, 618 uint32_t disk_flags); 619 620 /** 621 * Free a disk information list [infos] previously returned by 622 * VbExDiskGetInfo(). If [preserve_handle] != NULL, the firmware must ensure 623 * that handle remains valid after this call; all other handles from the info 624 * list need not remain valid after this call. 625 */ 626 VbError_t VbExDiskFreeInfo(VbDiskInfo *infos, 627 VbExDiskHandle_t preserve_handle); 628 629 /** 630 * Read lba_count LBA sectors, starting at sector lba_start, from the disk, 631 * into the buffer. 632 * 633 * This is used for random access to the GPT. It is not for the partition 634 * contents. The upper limit is lba_count. 635 * 636 * If the disk handle is invalid (for example, the handle refers to a disk 637 * which as been removed), the function must return error but must not 638 * crash. 639 */ 640 VbError_t VbExDiskRead(VbExDiskHandle_t handle, uint64_t lba_start, 641 uint64_t lba_count, void *buffer); 642 643 /** 644 * Write lba_count LBA sectors, starting at sector lba_start, to the disk, from 645 * the buffer. 646 * 647 * This is used for random access to the GPT. It does not (necessarily) access 648 * the streaming portion of the device. 649 * 650 * If the disk handle is invalid (for example, the handle refers to a disk 651 * which as been removed), the function must return error but must not 652 * crash. 653 */ 654 VbError_t VbExDiskWrite(VbExDiskHandle_t handle, uint64_t lba_start, 655 uint64_t lba_count, const void *buffer); 656 657 /* Streaming read interface */ 658 typedef void *VbExStream_t; 659 660 /** 661 * Open a stream on a disk 662 * 663 * @param handle Disk to open the stream against 664 * @param lba_start Starting sector offset within the disk to stream from 665 * @param lba_count Maximum extent of the stream in sectors 666 * @param stream out-paramter for the generated stream 667 * 668 * @return Error code, or VBERROR_SUCCESS. 669 * 670 * This is used for access to the contents of the actual partitions on the 671 * device. It is not used to access the GPT. The size of the content addressed 672 * is within streaming_lba_count. 673 */ 674 VbError_t VbExStreamOpen(VbExDiskHandle_t handle, uint64_t lba_start, 675 uint64_t lba_count, VbExStream_t *stream_ptr); 676 677 /** 678 * Read from a stream on a disk 679 * 680 * @param stream Stream to read from 681 * @param bytes Number of bytes to read 682 * @param buffer Destination to read into 683 * 684 * @return Error code, or VBERROR_SUCCESS. Failure to read as much data as 685 * requested is an error. 686 * 687 * This is used for access to the contents of the actual partitions on the 688 * device. It is not used to access the GPT. 689 */ 690 VbError_t VbExStreamRead(VbExStream_t stream, uint32_t bytes, void *buffer); 691 692 /** 693 * Close a stream 694 * 695 * @param stream Stream to close 696 */ 697 void VbExStreamClose(VbExStream_t stream); 698 699 700 /*****************************************************************************/ 701 /* Display */ 702 703 /* Predefined (default) screens for VbExDisplayScreen(). */ 704 enum VbScreenType_t { 705 /* Blank (clear) screen */ 706 VB_SCREEN_BLANK = 0, 707 /* Developer - warning */ 708 VB_SCREEN_DEVELOPER_WARNING = 0x101, 709 /* Developer - easter egg */ 710 VB_SCREEN_DEVELOPER_EGG = 0x102, 711 /* Recovery - remove inserted devices */ 712 VB_SCREEN_RECOVERY_REMOVE = 0x201, 713 /* Recovery - insert recovery image */ 714 VB_SCREEN_RECOVERY_INSERT = 0x202, 715 /* Recovery - inserted image invalid */ 716 VB_SCREEN_RECOVERY_NO_GOOD = 0x203, 717 /* Recovery - confirm dev mode */ 718 VB_SCREEN_RECOVERY_TO_DEV = 0x204, 719 /* Developer - confirm normal mode */ 720 VB_SCREEN_DEVELOPER_TO_NORM = 0x205, 721 /* Please wait - programming EC */ 722 VB_SCREEN_WAIT = 0x206, 723 /* Confirm after DEVELOPER_TO_NORM */ 724 VB_SCREEN_TO_NORM_CONFIRMED = 0x207, 725 }; 726 727 /** 728 * Initialize and clear the display. Set width and height to the screen 729 * dimensions in pixels. 730 */ 731 VbError_t VbExDisplayInit(uint32_t *width, uint32_t *height); 732 733 /** 734 * Enable (enable!=0) or disable (enable=0) the display backlight. 735 */ 736 VbError_t VbExDisplayBacklight(uint8_t enable); 737 738 /** 739 * Sets the logical dimension to display. 740 * 741 * If the physical display is larger or smaller than given dimension, display 742 * provider may decide to scale or shift images (from VbExDisplayImage)to proper 743 * location. 744 */ 745 VbError_t VbExDisplaySetDimension(uint32_t width, uint32_t height); 746 747 /** 748 * Display a predefined screen; see VB_SCREEN_* for valid screens. 749 * 750 * This is a backup method of screen display, intended for use if the GBB does 751 * not contain a full set of bitmaps. It is acceptable for the backup screen 752 * to be simple ASCII text such as "NO GOOD" or "INSERT"; these screens should 753 * only be seen during development. 754 */ 755 VbError_t VbExDisplayScreen(uint32_t screen_type); 756 757 /** 758 * Write an image to the display, with the upper left corner at the specified 759 * pixel coordinates. The bitmap buffer is a pointer to the platform-dependent 760 * uncompressed binary blob with dimensions and format specified internally 761 * (for example, a raw BMP, GIF, PNG, whatever). We pass the size just for 762 * convenience. 763 */ 764 VbError_t VbExDisplayImage(uint32_t x, uint32_t y, 765 void *buffer, uint32_t buffersize); 766 767 /** 768 * Display a string containing debug information on the screen, rendered in a 769 * platform-dependent font. Should be able to handle newlines '\n' in the 770 * string. Firmware must support displaying at least 20 lines of text, where 771 * each line may be at least 80 characters long. If the firmware has its own 772 * debug state, it may display it to the screen below this information. 773 * 774 * NOTE: This is what we currently display when TAB is pressed. Some 775 * information (HWID, recovery reason) is ours; some (CMOS breadcrumbs) is 776 * platform-specific. If we decide to soft-render the HWID string 777 * (chrome-os-partner:3693), we'll need to maintain our own fonts, so we'll 778 * likely display it via VbExDisplayImage() above. 779 */ 780 VbError_t VbExDisplayDebugInfo(const char *info_str); 781 782 /*****************************************************************************/ 783 /* Keyboard and switches */ 784 785 /* Key codes for required non-printable-ASCII characters. */ 786 enum VbKeyCode_t { 787 VB_KEY_UP = 0x100, 788 VB_KEY_DOWN = 0x101, 789 VB_KEY_LEFT = 0x102, 790 VB_KEY_RIGHT = 0x103, 791 VB_KEY_CTRL_ENTER = 0x104, 792 }; 793 794 /* Flags for additional information. 795 * TODO(semenzato): consider adding flags for modifiers instead of 796 * making up some of the key codes above. 797 */ 798 enum VbKeyFlags_t { 799 VB_KEY_FLAG_TRUSTED_KEYBOARD = 1 << 0, 800 }; 801 802 /** 803 * Read the next keypress from the keyboard buffer. 804 * 805 * Returns the keypress, or zero if no keypress is pending or error. 806 * 807 * The following keys must be returned as ASCII character codes: 808 * 0x08 Backspace 809 * 0x09 Tab 810 * 0x0D Enter (carriage return) 811 * 0x01 - 0x1A Ctrl+A - Ctrl+Z (yes, those alias with backspace/tab/enter) 812 * 0x1B Esc 813 * 0x20 Space 814 * 0x30 - 0x39 '0' - '9' 815 * 0x60 - 0x7A 'a' - 'z' 816 * 817 * Some extended keys must also be supported; see the VB_KEY_* defines above. 818 * 819 * Keys ('/') or key-chords (Fn+Q) not defined above may be handled in any of 820 * the following ways: 821 * 1. Filter (don't report anything if one of these keys is pressed). 822 * 2. Report as ASCII (if a well-defined ASCII value exists for the key). 823 * 3. Report as any other value in the range 0x200 - 0x2FF. 824 * It is not permitted to report a key as a multi-byte code (for example, 825 * sending an arrow key as the sequence of keys '\x1b', '[', '1', 'A'). */ 826 uint32_t VbExKeyboardRead(void); 827 828 /** 829 * Same as VbExKeyboardRead(), but return extra information. 830 */ 831 uint32_t VbExKeyboardReadWithFlags(uint32_t *flags_ptr); 832 833 /** 834 * Return the current state of the switches specified in request_mask 835 */ 836 uint32_t VbExGetSwitches(uint32_t request_mask); 837 838 /*****************************************************************************/ 839 /* Embedded controller (EC) */ 840 841 /* 842 * All these functions take a devidx parameter, which indicates which embedded 843 * processor the call applies to. At present, only devidx=0 is valid, but 844 * upcoming CLs will add support for multiple devices. 845 */ 846 847 /** 848 * This is called only if the system implements a keyboard-based (virtual) 849 * developer switch. It must return true only if the system has an embedded 850 * controller which is provably running in its RO firmware at the time the 851 * function is called. 852 */ 853 int VbExTrustEC(int devidx); 854 855 /** 856 * Check if the EC is currently running rewritable code. 857 * 858 * If the EC is in RO code, sets *in_rw=0. 859 * If the EC is in RW code, sets *in_rw non-zero. 860 * If the current EC image is unknown, returns error. */ 861 VbError_t VbExEcRunningRW(int devidx, int *in_rw); 862 863 /** 864 * Request the EC jump to its rewritable code. If successful, returns when the 865 * EC has booting its RW code far enough to respond to subsequent commands. 866 * Does nothing if the EC is already in its rewritable code. 867 */ 868 VbError_t VbExEcJumpToRW(int devidx); 869 870 /** 871 * Tell the EC to refuse another jump until it reboots. Subsequent calls to 872 * VbExEcJumpToRW() in this boot will fail. 873 */ 874 VbError_t VbExEcDisableJump(int devidx); 875 876 /** 877 * Read the SHA-256 hash of the rewriteable EC image. 878 */ 879 VbError_t VbExEcHashRW(int devidx, const uint8_t **hash, int *hash_size); 880 881 /** 882 * Get the expected contents of the EC image associated with the main firmware 883 * specified by the "select" argument. 884 */ 885 VbError_t VbExEcGetExpectedRW(int devidx, enum VbSelectFirmware_t select, 886 const uint8_t **image, int *image_size); 887 888 /** 889 * Read the SHA-256 hash of the expected contents of the EC image associated 890 * with the main firmware specified by the "select" argument. 891 */ 892 VbError_t VbExEcGetExpectedRWHash(int devidx, enum VbSelectFirmware_t select, 893 const uint8_t **hash, int *hash_size); 894 895 /** 896 * Update the EC rewritable image. 897 */ 898 VbError_t VbExEcUpdateRW(int devidx, const uint8_t *image, int image_size); 899 900 /** 901 * Lock the EC code to prevent updates until the EC is rebooted. 902 * Subsequent calls to VbExEcUpdateRW() this boot will fail. 903 */ 904 VbError_t VbExEcProtectRW(int devidx); 905 906 /** 907 * Info the EC of the boot mode selected by the AP. 908 * mode: Normal, Developer, or Recovery 909 */ 910 enum VbEcBootMode_t {VB_EC_NORMAL, VB_EC_DEVELOPER, VB_EC_RECOVERY }; 911 VbError_t VbExEcEnteringMode(int devidx, enum VbEcBootMode_t mode); 912 913 /*****************************************************************************/ 914 /* Misc */ 915 916 /* Args to VbExProtectFlash() */ 917 enum VbProtectFlash_t { VBPROTECT_RW_A, VBPROTECT_RW_B, VBPROTECT_RW_DEVKEY }; 918 919 /** 920 * Lock a section of the BIOS flash address space to prevent updates until the 921 * host is rebooted. Subsequent attempts to erase or modify the specified BIOS 922 * image will fail. If this function is called more than once each call should 923 * be cumulative. 924 */ 925 VbError_t VbExProtectFlash(enum VbProtectFlash_t region); 926 927 /** 928 * Check if the firmware needs to shut down the system. 929 * 930 * Returns a non-zero VB_SHUTDOWN_REQUEST mask indicating the reason(s) for 931 * shutdown if a shutdown is being requested (see VB_SHUTDOWN_REQUEST_*), or 0 932 * if a shutdown is not being requested. 933 * 934 * NOTE: When we're displaying a screen, pressing the power button should shut 935 * down the computer. We need a way to break out of our control loop so this 936 * can occur cleanly. 937 */ 938 uint32_t VbExIsShutdownRequested(void); 939 940 /* 941 * Shutdown requested for a reason which is not defined among other 942 * VB_SHUTDOWN_REQUEST_* values. This must be defined as 1 for backward 943 * compatibility with old versions of the API. 944 */ 945 #define VB_SHUTDOWN_REQUEST_OTHER 0x00000001 946 /* Shutdown requested due to a lid switch being closed. */ 947 #define VB_SHUTDOWN_REQUEST_LID_CLOSED 0x00000002 948 /* Shutdown requested due to a power button being pressed. */ 949 #define VB_SHUTDOWN_REQUEST_POWER_BUTTON 0x00000004 950 951 /** 952 * Expose the BIOS' built-in decompression routine to the vboot wrapper. The 953 * caller must know how large the uncompressed data will be and must manage 954 * that memory. The decompression routine just puts the uncompressed data into 955 * the specified buffer. We pass in the size of the outbuf, and get back the 956 * actual size used. 957 */ 958 VbError_t VbExDecompress(void *inbuf, uint32_t in_size, 959 uint32_t compression_type, 960 void *outbuf, uint32_t *out_size); 961 962 /* Constants for compression_type */ 963 enum { 964 COMPRESS_NONE = 0, 965 COMPRESS_EFIv1, /* The x86 BIOS only supports this */ 966 COMPRESS_LZMA1, /* The ARM BIOS supports LZMA1 */ 967 MAX_COMPRESS, 968 }; 969 970 /** 971 * Execute legacy boot option. 972 */ 973 int VbExLegacy(void); 974 975 /* Regions for VbExRegionRead() */ 976 enum vb_firmware_region { 977 VB_REGION_GBB, /* Google Binary Block - see gbbheader.h */ 978 979 VB_REGION_COUNT, 980 }; 981 982 /** 983 * Read data from a region of the firmware image 984 * 985 * Vboot wants access to a region, to read data from it. This function 986 * reads it (typically from the firmware image such as SPI flash) and 987 * returns the data. 988 * 989 * cparams is passed so that the boot loader has some context for the 990 * operation. 991 * 992 * @param cparams Common parameters, e.g. use member caller_context 993 * to point to useful context data 994 * @param region Firmware region to read 995 * @param offset Start offset within region 996 * @param size Number of bytes to read 997 * @param buf Place to put data 998 * @return VBERROR_... error, VBERROR_SUCCESS on success, 999 */ 1000 VbError_t VbExRegionRead(VbCommonParams *cparams, 1001 enum vb_firmware_region region, uint32_t offset, 1002 uint32_t size, void *buf); 1003 1004 #endif /* VBOOT_REFERENCE_VBOOT_API_H_ */ 1005