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