Reformat header files to kernel style

No code changes, just reformatting. BUG=none BRANCH=none TEST=make runtests Change-Id: Id5bac79545e9803d19b45da160c535f7e06465c6 Signed-off-by: Randall Spangler <rspangler@chromium.org> Reviewed-on: https://gerrit.chromium.org/gerrit/42016 Reviewed-by: Bill Richardson <wfrichar@chromium.org>
2025-11-24 02:05:01 +00:00 · 2013-01-24 16:15:35 -08:00
parent 786a5dca74
commit a2db67d204
10 changed files with 1292 additions and 937 deletions
--- a/firmware/include/bmpblk_header.h
+++ b/firmware/include/bmpblk_header.h
@@ -1,4 +1,4 @@
-/* Copyright (c) 2010-2011 The Chromium OS Authors. All rights reserved.
+/* Copyright (c) 2013 The Chromium OS Authors. All rights reserved.
 * Use of this source code is governed by a BSD-style license that can be
 * found in the LICENSE file.
 *
@@ -40,7 +40,6 @@
 *  +-----------------------------------------+
 *  |        List of locale names             |
 *  +-----------------------------------------+
 *
 */
 #ifndef VBOOT_REFERENCE_BMPBLK_HEADER_H_
@@ -60,26 +59,32 @@ __pragma(pack(push, 1))  /* Support packing for MSVC. */
 /* BMPBLOCK header, describing how many screen layouts and image infos */
 typedef struct BmpBlockHeader {
-  uint8_t  signature[BMPBLOCK_SIGNATURE_SIZE];  /* BMPBLOCK_SIGNATURE $BMP */
+	/* BMPBLOCK_SIGNATURE $BMP */
 	uint8_t  signature[BMPBLOCK_SIGNATURE_SIZE];
 	uint16_t major_version;            /* see BMPBLOCK_MAJOR_VER */
 	uint16_t minor_version;            /* see BMPBLOCK_MINOR_VER */
 	uint32_t number_of_localizations;  /* Number of localizations */
-  uint32_t number_of_screenlayouts;  /* Number of screen layouts in each
+	/* Number of screen layouts in each localization */
-                                      * localization */
+	uint32_t number_of_screenlayouts;
 	uint32_t number_of_imageinfos;     /* Number of image infos */
-  uint32_t locale_string_offset;     /* Offset of locale-translation string */
+	/* Offset of locale-translation string */
 	uint32_t locale_string_offset;
 	uint32_t reserved[2];
 } __attribute__((packed)) BmpBlockHeader;
 /* Screen layout, describing how to stack multiple images on screen */
 typedef struct ScreenLayout {
 	/*
 	 * Images contained in the screen. Will be rendered from 0 to
 	 * (number_of_images-1).
 	 */
 	struct {
-    uint32_t x;                   /* X-offset of the image to be rendered */
+		/* (X,Y) offset of image to be rendered */
-    uint32_t y;                   /* Y-offset of the image to be rendered */
+		uint32_t x;
-    uint32_t image_info_offset;   /* Offset of image info from start of
+		uint32_t y;
-                                   * BMPBLOCK. 0 means end of it. */
+		/* Offset of image info from start of BMPBLOCK; 0=end it. */
-  } images[MAX_IMAGE_IN_LAYOUT];  /* Images contained in the screen. Will be
+		uint32_t image_info_offset;
-                                   * rendered from 0 to (number_of_images-1). */
+	} images[MAX_IMAGE_IN_LAYOUT];
 } __attribute__((packed)) ScreenLayout;
 /* Constants for screen index */
@@ -104,9 +109,11 @@ typedef struct ImageInfo {
 	uint32_t format;           /* File format of the image */
 	uint32_t compression;      /* Compression method for the image file */
 	uint32_t original_size;    /* Size of the original uncompressed image */
-  uint32_t compressed_size;  /* Size of the compressed image; if image is not
+	/*
-                              * compressed, this will be the same as the
+	 * Size of the compressed image; if image is not compressed, this will
-                              * original size. */
+	 * be the same as the original size.
 	 */
 	uint32_t compressed_size;
 	uint32_t reserved;
  /* NOTE: The actual image content (if any) follows immediately. */
 } __attribute__((packed)) ImageInfo;
@@ -133,10 +140,12 @@ typedef enum Compression {
 	MAX_COMPRESS,
 } Compression;
-/* These magic image names can be used in the .yaml file to indicate that
+/*
-   the ASCII HWID should be displayed. For RENDER_HWID, the image coordinates
+ * These magic image names can be used in the .yaml file to indicate that the
-   specify upper-left corner of the HWID string. For RENDER_HWID_RTOL, they
+ * ASCII HWID should be displayed. For RENDER_HWID, the image coordinates
-   indicate the upper-right corner (handy for right-to-left languages). */
+ * specify upper-left corner of the HWID string. For RENDER_HWID_RTOL, they
 * indicate the upper-right corner (handy for right-to-left languages).
 */
 #define RENDER_HWID       "$HWID"
 #define RENDER_HWID_RTOL  "$HWID.rtol"
--- a/firmware/include/gbb_header.h
+++ b/firmware/include/gbb_header.h
@@ -1,4 +1,4 @@
-/* Copyright (c) 2011 The Chromium OS Authors. All rights reserved.
+/* Copyright (c) 2013 The Chromium OS Authors. All rights reserved.
 * Use of this source code is governed by a BSD-style license that can be
 * found in the LICENSE file.
 *
@@ -15,17 +15,18 @@
 #define GBB_SIGNATURE      "$GBB"
 #define GBB_SIGNATURE_SIZE 4
-/* GBB version constants.
+/*
 * GBB version constants.
 *
- * If the major version is different than the reader can handle, it
+ * If the major version is different than the reader can handle, it shouldn't
- * shouldn't attempt to parse the GBB.
+ * attempt to parse the GBB.
 *
- * If the minor version is different, the reader can still parse it.
+ * If the minor version is different, the reader can still parse it.  If the
- * If the minor version is greater than expected, new fields were
+ * minor version is greater than expected, new fields were added in a way which
- * added in a way which does not interfere with the old fields.  If
+ * does not interfere with the old fields.  If it's less than expected, some of
- * it's less than expected, some of the fields expected by the reader
+ * the fields expected by the reader aren't initialized, and the reader should
- * aren't initialized, and the reader should return default values for
+ * return default values for those fields.
- * those fields. */
+ */
 #define GBB_MAJOR_VER      1
 #define GBB_MINOR_VER      1
@@ -35,13 +36,17 @@
 /* Flags for .flags field */
 /* Reduce the dev screen delay to 2 sec from 30 sec to speedup factory. */
 #define GBB_FLAG_DEV_SCREEN_SHORT_DELAY   0x00000001
-/* BIOS should load option ROMs from arbitrary PCI devices. We'll never enable
+/*
- * this ourselves because it executes non-verified code, but if a customer wants
+ * BIOS should load option ROMs from arbitrary PCI devices. We'll never enable
- * to void their warranty and set this flag in the read-only flash, they should
+ * this ourselves because it executes non-verified code, but if a customer
- * be able to do so. */
+ * wants to void their warranty and set this flag in the read-only flash, they
 * should be able to do so.
 */
 #define GBB_FLAG_LOAD_OPTION_ROMS         0x00000002
-/* The factory flow may need the BIOS to boot a non-ChromeOS kernel if the
+/*
- * dev-switch is on. This flag allows that. */
+ * The factory flow may need the BIOS to boot a non-ChromeOS kernel if the
 * dev-switch is on. This flag allows that.
 */
 #define GBB_FLAG_ENABLE_ALTERNATE_OS      0x00000004
 /* Force dev switch on, regardless of physical/keyboard dev switch position. */
 #define GBB_FLAG_FORCE_DEV_SWITCH_ON      0x00000008
@@ -60,22 +65,23 @@
 extern "C" {
 #endif  /* __cplusplus */
-typedef struct GoogleBinaryBlockHeader {
+typedef struct GoogleBinaryBlockHeader
 {
 	/* Fields present in version 1.0 */
 	uint8_t  signature[GBB_SIGNATURE_SIZE]; /* GBB_SIGNATURE "$GBB" */
 	uint16_t major_version;   /* See GBB_MAJOR_VER */
 	uint16_t minor_version;   /* See GBB_MINOR_VER */
 	uint32_t header_size;     /* size of GBB header in bytes */
 	uint32_t flags;  /* Flags (see GBB_FLAG_*), should be 0 for 1.0. */
-
+	/* Offsets (from start of header) and sizes (in bytes) of components */
-  uint32_t hwid_offset;     /* HWID offset from start of header */
+	uint32_t hwid_offset;		/* HWID */
-  uint32_t hwid_size;       /* HWID size in bytes */
+	uint32_t hwid_size;
-  uint32_t rootkey_offset;  /* Root Key offset from start of header */
+	uint32_t rootkey_offset;	/* Root key */
-  uint32_t rootkey_size;    /* Root Key size in bytes */
+	uint32_t rootkey_size;
-  uint32_t bmpfv_offset;    /* BMP FV offset from start of header */
+	uint32_t bmpfv_offset;		/* BMP FV */
-  uint32_t bmpfv_size;      /* BMP FV size in bytes */
+	uint32_t bmpfv_size;
-  uint32_t recovery_key_offset;  /* Recovery Key offset from start of header */
+	uint32_t recovery_key_offset;	/* Recovery key */
-  uint32_t recovery_key_size;    /* Recovery Key size in bytes */
+	uint32_t recovery_key_size;
 	uint8_t  pad[80]; /* To match GBB_HEADER_SIZE.  Initialize to 0. */
 } __attribute__((packed)) GoogleBinaryBlockHeader;
--- a/firmware/include/load_firmware_fw.h
+++ b/firmware/include/load_firmware_fw.h
@@ -1,4 +1,4 @@
-/* Copyright (c) 2011 The Chromium OS Authors. All rights reserved.
+/* Copyright (c) 2013 The Chromium OS Authors. All rights reserved.
 * Use of this source code is governed by a BSD-style license that can be
 * found in the LICENSE file.
 *
@@ -14,14 +14,16 @@
 #include "vboot_nvstorage.h"
 #include "vboot_struct.h"
-/* Load the rewritable firmware.
+/**
 * Load the rewritable firmware.
 *
 * Pass the common and firmware params from VbSelectFirmware(), and a
 * VbNvContext.  Caller is responsible for calling VbNvSetup() and
 * VbNvTeardown() on the VbNvContext.
 *
 * Returns VBERROR_SUCCESS if successful.  If unsuccessful, sets a recovery
- * reason via VbNvStorage and returns an error code. */
+ * reason via VbNvStorage and returns an error code.
 */
 int LoadFirmware(VbCommonParams *cparams, VbSelectFirmwareParams *fparams,
 		 VbNvContext *vnc);
--- a/firmware/include/load_kernel_fw.h
+++ b/firmware/include/load_kernel_fw.h
@@ -1,4 +1,4 @@
-/* Copyright (c) 2011 The Chromium OS Authors. All rights reserved.
+/* Copyright (c) 2013 The Chromium OS Authors. All rights reserved.
 * Use of this source code is governed by a BSD-style license that can be
 * found in the LICENSE file.
 *
@@ -20,63 +20,82 @@
 #define BOOT_FLAG_DEVELOPER UINT64_C(0x01)
 /* In recovery mode */
 #define BOOT_FLAG_RECOVERY  UINT64_C(0x02)
 /* Skip check of kernel buffer address.  Since body load address check is
 * omitted; this flag is deprecated and not used anywhere in the codebase. */
 #define BOOT_FLAG_SKIP_ADDR_CHECK UINT64_C(0x04)
 typedef struct LoadKernelParams {
 	/* Inputs to LoadKernel() */
-  void* shared_data_blob;       /* Buffer for data shared between
+	/*
-                                 * LoadFirmware() and LoadKernel().  Pass the
+	 * Buffer for data shared between LoadFirmware() and LoadKernel().
-                                 * same buffer which was passed to
+	 * Pass the same buffer which was passed to LoadFirmware().
-                                 * LoadFirmware(). */
+	 */
-  uint64_t shared_data_size;    /* Size of shared data blob buffer, in bytes.
+	void *shared_data_blob;
-                                 * On output, this will contain the actual
+	/*
-                                 * data size placed into the buffer. */
+	 * Size of shared data blob buffer, in bytes.  On output, this will
-  void* gbb_data;               /* Pointer to GBB data */
+	 * contain the actual data size placed into the buffer.
-  uint64_t gbb_size;            /* Size of GBB data in bytes */
+	 */
 	uint64_t shared_data_size;
 	/* Pointer to GBB data */
 	void *gbb_data;
 	/* Size of GBB data in bytes */
 	uint64_t gbb_size;
 	/* Disk handle for current device */
 	VbExDiskHandle_t disk_handle;
 	/* Bytes per lba sector on current device */
 	uint64_t bytes_per_lba;
 	/* Last addressable lba sector on current device */
 	uint64_t ending_lba;
 	/* Destination buffer for kernel (normally at 0x100000) */
 	void *kernel_buffer;
 	/* Size of kernel buffer in bytes */
 	uint64_t kernel_buffer_size;
 	/* Boot flags */
 	uint64_t boot_flags;
 	/*
 	 * Context for NV storage.  Caller is responsible for calling
 	 * VbNvSetup() and VbNvTeardown() on the context.
 	 */
 	VbNvContext *nv_context;
-  VbExDiskHandle_t disk_handle; /* Disk handle for current device */
+	/*
-  uint64_t bytes_per_lba;       /* Bytes per lba sector on current device */
+	 * Outputs from LoadKernel(); valid only if LoadKernel() returns
-  uint64_t ending_lba;          /* Last addressable lba sector on current
+	 * LOAD_KERNEL_SUCCESS
-                                 * device */
+	 */
-
+	/* Partition number to boot on current device (1...M) */
-  void* kernel_buffer;          /* Destination buffer for kernel
+	uint64_t partition_number;
-                                 * (normally at 0x100000) */
+	/* Address of bootloader image in RAM */
-  uint64_t kernel_buffer_size;  /* Size of kernel buffer in bytes */
+	uint64_t bootloader_address;
-  uint64_t boot_flags;          /* Boot flags */
+	/* Size of bootloader image in bytes */
-  VbNvContext* nv_context;      /* Context for NV storage.  Caller is
+	uint64_t bootloader_size;
-                                 * responsible for calling VbNvSetup() and
+	/* UniquePartitionGuid for boot partition */
-                                 * VbNvTeardown() on the context. */
+	uint8_t  partition_guid[16];
  /* Outputs from LoadKernel(); valid only if LoadKernel() returns
   * LOAD_KERNEL_SUCCESS */
  uint64_t partition_number;    /* Partition number to boot on current device
                                 * (1...M) */
  uint64_t bootloader_address;  /* Address of bootloader image in RAM */
  uint64_t bootloader_size;     /* Size of bootloader image in bytes */
  uint8_t  partition_guid[16];  /* UniquePartitionGuid for boot partition */
 } LoadKernelParams;
-VbError_t LoadKernel(LoadKernelParams* params);
+/**
-/* Attempts to load the kernel from the current device.
+ * Attempt to load the kernel from the current device.
 *
 * Returns VBERROR_SUCCESS if successful.  If unsuccessful, sets a recovery
- * reason via VbNvStorage and returns an error code. */
+ * reason via VbNvStorage and returns an error code.
-
+ */
 VbError_t LoadKernel(LoadKernelParams *params);
 /*
 * The bootloader is loaded using the EFI LoadImage() and StartImage() calls.
 * Pass this struct via loaded_image->load_options.
 */
 typedef struct KernelBootloaderOptions {
-  /* The bootloader is loaded using the EFI LoadImage() and StartImage()
+	/* Drive number of boot device (0...N) */
-   * calls.  Pass this struct via loaded_image->load_options. */
+	uint64_t drive_number;
-  uint64_t drive_number;        /* Drive number of boot device (0...N) */
+	/*
-  uint64_t partition_number;    /* Partition number, as returned from
+	 * Partition number, as returned from LoadKernel() in
-                                 * LoadKernel() in
+	 * LoadKernelParams.partition_number
-                                 * LoadKernelParams.partition_number */
+	 */
-  uint64_t original_address;    /* Absolute bootloader start adddress,
+	uint64_t partition_number;
-                                 * as returned from LoadKernel() in
+	/*
-                                 * LoadKernelParams.bootloader_start */
+	 * Absolute bootloader start adddress, as returned from LoadKernel() in
-  uint8_t  partition_guid[16];  /* UniquePartitionGuid for boot partition */
+	 * LoadKernelParams.bootloader_start
 	 */
 	uint64_t original_address;
 	  /* UniquePartitionGuid for boot partition */
 	uint8_t partition_guid[16];
 } KernelBootloaderOptions;
 #endif  /* VBOOT_REFERENCE_LOAD_KERNEL_FW_H_ */
--- a/firmware/include/tlcl.h
+++ b/firmware/include/tlcl.h
@@ -1,9 +1,10 @@
-/* Copyright (c) 2012 The Chromium OS Authors. All rights reserved.
+/* Copyright (c) 2013 The Chromium OS Authors. All rights reserved.
 * Use of this source code is governed by a BSD-style license that can be
 * found in the LICENSE file.
 */
-/* TPM Lightweight Command Library.
+/*
 * TPM Lightweight Command Library.
 *
 * A low-level library for interfacing to TPM hardware or an emulator.
 */
@@ -17,162 +18,199 @@
 /*****************************************************************************/
 /* Functions implemented in tlcl.c */
-/* Call this first.  Returns 0 if success, nonzero if error.
+/**
 * Call this first.  Returns 0 if success, nonzero if error.
 */
 uint32_t TlclLibInit(void);
-/* Call this on shutdown.  Returns 0 if success, nonzero if error.
+/**
 * Call this on shutdown.  Returns 0 if success, nonzero if error.
 */
 uint32_t TlclLibClose(void);
-/* Logs to stdout.  Arguments like printf.
+/**
 * Log to stdout.  Arguments like printf.
 */
 void TlclLog(char *format, ...);
-/* Sets the log level.  0 is quietest.
+/**
 * Set the log level.  0 is quietest.
 */
 void TlclSetLogLevel(int level);
 /* Low-level operations */
-/* Performs a raw TPM request/response transaction.
+/**
 * Perform a raw TPM request/response transaction.
 */
 uint32_t TlclSendReceive(const uint8_t *request, uint8_t *response,
                         int max_length);
-/* Returns the size of a TPM request or response packet.
+/**
 * Return the size of a TPM request or response packet.
 */
 int TlclPacketSize(const uint8_t *packet);
 /* Commands */
-/* Sends a TPM_Startup(ST_CLEAR).  The TPM error code is returned (0
+/**
- * for success).
+ * Send a TPM_Startup(ST_CLEAR).  The TPM error code is returned (0 for
 * success).
 */
 uint32_t TlclStartup(void);
-/* Save the TPM state.  Normally done by the kernel before a suspend, included
+/**
 * Save the TPM state.  Normally done by the kernel before a suspend, included
 * here for tests.  The TPM error code is returned (0 for success).
 */
 uint32_t TlclSaveState(void);
-/* Resumes by sending a TPM_Startup(ST_STATE).  The TPM error code is returned
+/**
 * Resume by sending a TPM_Startup(ST_STATE).  The TPM error code is returned
 * (0 for success).
 */
 uint32_t TlclResume(void);
-/* Runs the self test.  Note---this is synchronous.  To run this in parallel
+/**
- * with other firmware, use ContinueSelfTest.  The TPM error code is returned.
+ * Run the self test.
 *
 * Note---this is synchronous.  To run this in parallel with other firmware,
 * use ContinueSelfTest().  The TPM error code is returned.
 */
 uint32_t TlclSelfTestFull(void);
-/* Runs the self test in the background.
+/**
 * Run the self test in the background.
 */
 uint32_t TlclContinueSelfTest(void);
-/* Defines a space with permission [perm].  [index] is the index for the space,
+/**
 * Define a space with permission [perm].  [index] is the index for the space,
 * [size] the usable data size.  The TPM error code is returned.
 */
 uint32_t TlclDefineSpace(uint32_t index, uint32_t perm, uint32_t size);
-/* Writes [length] bytes of [data] to space at [index].  The TPM error code is
+/**
 * Write [length] bytes of [data] to space at [index].  The TPM error code is
 * returned.
 */
 uint32_t TlclWrite(uint32_t index, const void *data, uint32_t length);
-/* Reads [length] bytes from space at [index] into [data].  The TPM error code
+/**
 * Read [length] bytes from space at [index] into [data].  The TPM error code
 * is returned.
 */
 uint32_t TlclRead(uint32_t index, void *data, uint32_t length);
-/* Reads PCR at [index] into [data].  [length] must be TPM_PCR_DIGEST or
+/**
 * Read PCR at [index] into [data].  [length] must be TPM_PCR_DIGEST or
 * larger. The TPM error code is returned.
 */
 uint32_t TlclPCRRead(uint32_t index, void *data, uint32_t length);
-/* Write-locks space at [index].  The TPM error code is returned.
+/**
 * Write-lock space at [index].  The TPM error code is returned.
 */
 uint32_t TlclWriteLock(uint32_t index);
-/* Read-locks space at [index].  The TPM error code is returned.
+/**
 * Read-lock space at [index].  The TPM error code is returned.
 */
 uint32_t TlclReadLock(uint32_t index);
-/* Asserts physical presence in software.  The TPM error code is returned.
+/**
 * Assert physical presence in software.  The TPM error code is returned.
 */
 uint32_t TlclAssertPhysicalPresence(void);
-/* Enables the physical presence command.  The TPM error code is returned.
+/**
 * Enable the physical presence command.  The TPM error code is returned.
 */
 uint32_t TlclPhysicalPresenceCMDEnable(void);
-/* Finalizes the physical presence settings: sofware PP is enabled, hardware PP
+/**
 * Finalize the physical presence settings: sofware PP is enabled, hardware PP
 * is disabled, and the lifetime lock is set.  The TPM error code is returned.
 */
 uint32_t TlclFinalizePhysicalPresence(void);
-/* Turns off physical presence and locks it off until next reboot.  The TPM
+/**
 * Turn off physical presence and locks it off until next reboot.  The TPM
 * error code is returned.
 */
 uint32_t TlclLockPhysicalPresence(void);
-/* Sets the nvLocked bit.  The TPM error code is returned.
+/**
 * Set the nvLocked bit.  The TPM error code is returned.
 */
 uint32_t TlclSetNvLocked(void);
-/* Returns 1 if the TPM is owned, 0 otherwise.
+/**
 * Return 1 if the TPM is owned, 0 otherwise.
 */
 int TlclIsOwned(void);
-/* Issues a ForceClear.  The TPM error code is returned.
+/**
 * Issue a ForceClear.  The TPM error code is returned.
 */
 uint32_t TlclForceClear(void);
-/* Issues a PhysicalEnable.  The TPM error code is returned.
+/**
 * Issue a PhysicalEnable.  The TPM error code is returned.
 */
 uint32_t TlclSetEnable(void);
-/* Issues a PhysicalDisable.  The TPM error code is returned.
+/**
 * Issue a PhysicalDisable.  The TPM error code is returned.
 */
 uint32_t TlclClearEnable(void);
-/* Issues a SetDeactivated.  Pass 0 to activate.  Returns result code.
+/**
 * Issue a SetDeactivated.  Pass 0 to activate.  Returns result code.
 */
 uint32_t TlclSetDeactivated(uint8_t flag);
-/* Gets flags of interest.  Pointers for flags you aren't interested in may
+/**
 * Get flags of interest.  Pointers for flags you aren't interested in may
 * be NULL.  The TPM error code is returned.
 */
 uint32_t TlclGetFlags(uint8_t *disable, uint8_t *deactivated,
                      uint8_t *nvlocked);
-/* Sets the bGlobalLock flag, which only a reboot can clear.  The TPM error
+/**
 * Set the bGlobalLock flag, which only a reboot can clear.  The TPM error
 * code is returned.
 */
 uint32_t TlclSetGlobalLock(void);
-/* Performs a TPM_Extend.
+/**
 * Perform a TPM_Extend.
 */
 uint32_t TlclExtend(int pcr_num, const uint8_t *in_digest, uint8_t *out_digest);
-/* Gets the permission bits for the NVRAM space with |index|.
+/**
 * Get the permission bits for the NVRAM space with |index|.
 */
 uint32_t TlclGetPermissions(uint32_t index, uint32_t *permissions);
-/* Gets the entire set of permanent flags.
+/**
 * Get the entire set of permanent flags.
 */
 uint32_t TlclGetPermanentFlags(TPM_PERMANENT_FLAGS *pflags);
-/* Gets the entire set of volatile (ST_CLEAR) flags.
+/**
 * Get the entire set of volatile (ST_CLEAR) flags.
 */
 uint32_t TlclGetSTClearFlags(TPM_STCLEAR_FLAGS *pflags);
-/* Gets ownership flag. The TPM error code is returned.
+/**
 * Get the ownership flag. The TPM error code is returned.
 */
 uint32_t TlclGetOwnership(uint8_t *owned);
-/* Requests [length] bytes from TPM RNG to be stored in [data]. Actual
+/**
- * number of bytes read is stored in [size]. The TPM error code is returned.
+ * Request [length] bytes from TPM RNG to be stored in [data]. Actual number of
 * bytes read is stored in [size]. The TPM error code is returned.
 */
 uint32_t TlclGetRandom(uint8_t *data, uint32_t length, uint32_t *size);
--- a/firmware/include/tss_constants.h
+++ b/firmware/include/tss_constants.h
@@ -1,9 +1,9 @@
-/* Copyright (c) 2012 The Chromium OS Authors. All rights reserved.
+/* Copyright (c) 2013 The Chromium OS Authors. All rights reserved.
 * Use of this source code is governed by a BSD-style license that can be
 * found in the LICENSE file.
 *
- * Some TPM constants and type definitions for standalone compilation for use in
+ * Some TPM constants and type definitions for standalone compilation for use
- * the firmware
+ * in the firmware
 */
 #ifndef VBOOT_REFERENCE_TSS_CONSTANTS_H_
--- a/firmware/include/utility.h
+++ b/firmware/include/utility.h
@@ -1,9 +1,10 @@
-/* Copyright (c) 2010 The Chromium OS Authors. All rights reserved.
+/* Copyright (c) 2013 The Chromium OS Authors. All rights reserved.
 * Use of this source code is governed by a BSD-style license that can be
 * found in the LICENSE file.
 */
-/* Helper functions/wrappers for memory allocations, manipulation and
+/*
 * Helper functions/wrappers for memory allocations, manipulation and
 * comparison.
 */
@@ -20,7 +21,8 @@
 #endif
 #ifndef VBOOT_PERFORMANCE
-/* Define performance macros as nothing.  If you enable VBOOT_PERFORMANCE,
+/*
 * Define performance macros as nothing.  If you enable VBOOT_PERFORMANCE,
 * you must define these macros in your platform's biosincludes.h.
 *
 * Intended usage for using a performance counter called 'foo':
@@ -50,32 +52,43 @@
 #define VBEASTEREGG 0
 #endif
-/* Combine [msw] and [lsw] uint16s to a uint32_t with its [msw] and
+/*
- * [lsw] forming the most and least signficant 16-bit words.
+ * Combine [msw] and [lsw] uint16s to a uint32_t with its [msw] and [lsw]
 * forming the most and least signficant 16-bit words.
 */
 #define CombineUint16Pair(msw,lsw) (((uint32_t)(msw) << 16) |   \
                                    (((lsw)) & 0xFFFF))
 /* Return the minimum of (a) or (b). */
 #define Min(a, b) (((a) < (b)) ? (a) : (b))
-/* Compare [n] bytes in [src1] and [src2]
+/**
- * Returns an integer less than, equal to, or greater than zero if the first [n]
+ * Compare [n] bytes in [src1] and [src2].
- * bytes of [src1] is found, respectively, to be less than, to match, or be
+ *
 * Returns an integer less than, equal to, or greater than zero if the first
 * [n] bytes of [src1] is found, respectively, to be less than, to match, or be
 * greater than the first n bytes of [src2]. */
 int Memcmp(const void *src1, const void *src2, size_t n);
-/* Copy [n] bytes from [src] to [dest]. */
+/**
 * Copy [n] bytes from [src] to [dest].
 */
 void *Memcpy(void *dest, const void *src, uint64_t n);
 /*
 * Implementations of the functions below must be built as part of the firmware
 * and defined in lib/utility.c.
 */
-/* Implementations of the functions below must be built as part of the firmware
+/**
- * and defined in lib/utility.c */
+ * Set [n] bytes starting at [s] to [c].  Returns dest.
-
+ */
 /* Set [n] bytes starting at [s] to [c].  Returns dest. */
 void *Memset(void *dest, const uint8_t c, uint64_t n);
-/* Compare [n] bytes starting at [s1] with [s2] and return 0 if they
+/**
 * Compare [n] bytes starting at [s1] with [s2] and return 0 if they
 * match, 1 if they don't.  Returns 0 if n=0, since no bytes mismatched.
 *
 * Time taken to perform the comparison is only dependent on [n] and
 * not on the relationship of the match between [s1] and [s2].
 *
@@ -84,22 +97,27 @@ void* Memset(void* dest, const uint8_t c, uint64_t n);
 */
 int SafeMemcmp(const void *s1, const void *s2, size_t n);
-/* Buffer size required to hold the longest possible output of
+/*
- * Uint64ToString() - that is, Uint64ToString(~0, 2). */
+ * Buffer size required to hold the longest possible output of Uint64ToString()
 * - that is, Uint64ToString(~0, 2).
 */
 #define UINT64_TO_STRING_MAX 65
-/* Convert a value to a string in the specified radix (2=binary, 10=decimal,
+/**
 * Convert a value to a string in the specified radix (2=binary, 10=decimal,
 * 16=hex) and store it in <buf>, which is <bufsize> chars long.  If
 * <zero_pad_width>, left-pads the string to at least that width with '0'.
- * Returns the length of the stored string, not counting the terminating
+ * Returns the length of the stored string, not counting the terminating null.
- * null. */
+ */
 uint32_t Uint64ToString(char *buf, uint32_t bufsize, uint64_t value,
                        uint32_t radix, uint32_t zero_pad_width);
-/* Concatenate <src> onto <dest>, which has space for <destlen> characters
+/**
 * Concatenate <src> onto <dest>, which has space for <destlen> characters
 * including the terminating null.  Note that <dest> will always be
- * null-terminated if <destlen> > 0.  Returns the number of characters
+ * null-terminated if <destlen> > 0.  Returns the number of characters used in
- * used in <dest>, not counting the terminating null. */
+ * <dest>, not counting the terminating null.
 */
 uint32_t Strncat(char *dest, const char *src, uint32_t destlen);
 /* Ensure that only our stub implementations are used, not standard C */
--- a/firmware/include/vboot_api.h
+++ b/firmware/include/vboot_api.h
@@ -1,24 +1,23 @@
-/* Copyright (c) 2012 The Chromium OS Authors. All rights reserved.
+/* Copyright (c) 2013 The Chromium OS Authors. All rights reserved.
 * Use of this source code is governed by a BSD-style license that can be
 * found in the LICENSE file.
 */
-/* APIs provided by firmware to vboot_reference. */
+/* APIs provided by firmware to vboot_reference.
 /* General notes:
 *
- * All verified boot functions now start with "Vb" for namespace
+ * General notes:
 * clarity.  This fixes the problem where uboot and vboot both defined
 * assert().
 *
- * Verified boot APIs to be implemented by the calling firmware and
+ * All verified boot functions now start with "Vb" for namespace clarity.  This
- * exported to vboot_reference start with "VbEx".
+ * fixes the problem where uboot and vboot both defined assert().
 *
 * Verified boot APIs to be implemented by the calling firmware and exported to
 * vboot_reference start with "VbEx".
 *
 * TODO: split this file into a vboot_entry_points.h file which contains the
 * entry points for the firmware to call vboot_reference, and a
 * vboot_firmware_exports.h which contains the APIs to be implemented by the
 * calling firmware and exported to vboot_reference.
 */
 /* TODO: split this file into a vboot_entry_points.h file which
 * contains the entry points for the firmware to call vboot_reference,
 * and a vboot_firmware_exports.h which contains the APIs to be
 * implemented by the calling firmware and exported to
 * vboot_reference. */
 #ifndef VBOOT_REFERENCE_VBOOT_API_H_
 #define VBOOT_REFERENCE_VBOOT_API_H_
@@ -26,27 +25,29 @@
 #include "sysincludes.h"
 #include "bmpblk_header.h"
 /*****************************************************************************/
 /* Error codes */
-/* Functions which return an error all return this type.  This is a
+/*
- * 32-bit value rather than an int so it's consistent across UEFI,
+ * Functions which return an error all return this type.  This is a 32-bit
- * which is 32-bit during PEI and 64-bit during DXE/BDS. */
+ * value rather than an int so it's consistent across UEFI, which is 32-bit
 * during PEI and 64-bit during DXE/BDS.
 */
 typedef uint32_t VbError_t;
-/* Predefined error numbers. */
+/*
 * Predefined error numbers.  Success is 0.  Errors are non-zero, but differ
 * between functions.  For example, the TPM functions may pass through TPM
 * error codes, some of which may be recoverable.
 */
 enum VbErrorPredefined_t {
 	/* No error; function completed successfully. */
 	VBERROR_SUCCESS                       = 0,
-  /* Errors are non-zero, but differ between functions.  For example,
+	/*
-   * the TPM functions may pass through TPM error codes, some of which
+	 * The verified boot entry points VbInit(), VbSelectFirmware(),
-   * may be recoverable. */
+	 * VbSelectAndLoadKernel() may return the following errors.
-
+	 */
  /* The verified boot entry points VbInit(), VbSelectFirmware(),
   * VbSelectAndLoadKernel() may return the following errors. */
 	/* Unknown error */
 	VBERROR_UNKNOWN                       = 0x10000,
 	/* Unable to initialize shared data */
@@ -67,7 +68,7 @@ enum VbErrorPredefined_t {
 	VBERROR_TPM_FIRMWARE_SETUP            = 0x10008,
 	/* Unable to read kernel versions from TPM */
 	VBERROR_TPM_READ_KERNEL               = 0x10009,
-  /* Attempted to load developer-only firmware when developer switch was off */
+	/* Attempt to load developer-only firmware with developer switch off */
 	VBERROR_DEV_FIRMWARE_SWITCH_MISMATCH  = 0x1000A,
 	/* Unable to write kernel versions to TPM */
 	VBERROR_TPM_WRITE_KERNEL              = 0x1000B,
@@ -75,11 +76,11 @@ enum VbErrorPredefined_t {
 	VBERROR_TPM_LOCK_KERNEL               = 0x1000C,
 	/* Calling firmware requested shutdown via VbExIsShutdownRequested() */
 	VBERROR_SHUTDOWN_REQUESTED            = 0x1000D,
-  /* Unable to find a suitable boot device on which to look for a kernel */
+	/* Unable to find a boot device on which to look for a kernel */
 	VBERROR_NO_DISK_FOUND                 = 0x1000E,
 	/* No OS kernel found on any boot device */
 	VBERROR_NO_KERNEL_FOUND               = 0x1000F,
-  /* All OS kernels found were invalid (corrupt, improperly signed, etc.) */
+	/* All OS kernels found were invalid (corrupt, improperly signed...) */
 	VBERROR_INVALID_KERNEL_FOUND          = 0x10010,
 	/* VbSelectAndLoadKernel() requested recovery mode */
 	VBERROR_LOAD_KERNEL_RECOVERY          = 0x10011,
@@ -111,47 +112,61 @@ enum VbErrorPredefined_t {
 /*****************************************************************************/
 /* Main entry points from firmware into vboot_reference */
-/* Minimum and recommended size of shared_data_blob in bytes.  Shared
+/*
- * data blob is used to communicate data between calls to VbInit(),
+ * Minimum and recommended size of shared_data_blob in bytes.  Shared data blob
- * VbSelectFirmware(), the OS.  Minimum size is enough to hold all
+ * is used to communicate data between calls to VbInit(), VbSelectFirmware(),
- * required data for verified boot but may not be able to hold debug
+ * the OS.  Minimum size is enough to hold all required data for verified boot
- * output. */
+ * but may not be able to hold debug output.
 */
 #define VB_SHARED_DATA_MIN_SIZE 3072
 #define VB_SHARED_DATA_REC_SIZE 16384
-/* Data passed by firmware to VbInit(), VbSelectFirmware() and
+/*
- * VbSelectAndLoadKernel(). */
+ * Data passed by firmware to VbInit(), VbSelectFirmware() and
-/* Note that in UEFI, these are called by different phases in
+ * VbSelectAndLoadKernel().
- * different processor modes (VbInit() and VbSelectFirmware() = 32-bit PEI,
+ *
 * Note that in UEFI, these are called by different phases in different
 * processor modes (VbInit() and VbSelectFirmware() = 32-bit PEI,
 * VbSelectAndLoadKernel() = 64-bit BDS), so the data may be at a different
- * location between calls. */
+ * location between calls.
 */
 typedef struct VbCommonParams {
-  void* gbb_data;                /* Pointer to GBB data */
+	/* Pointer to GBB data */
-  uint32_t gbb_size;             /* Size of GBB data in bytes */
+	void *gbb_data;
 	/* Size of GBB data in bytes */
 	uint32_t gbb_size;
-  /* Shared data blob for data shared between verified boot entry
+	/*
-   * points.  This should be at least VB_SHARED_DATA_MIN_SIZE bytes
+	 * Shared data blob for data shared between verified boot entry points.
-   * long, and ideally is VB_SHARED_DATA_REC_SIZE bytes long. */
+	 * This should be at least VB_SHARED_DATA_MIN_SIZE bytes long, and
-  void* shared_data_blob;        /* Pointer to shared data blob buffer */
+	 * ideally is VB_SHARED_DATA_REC_SIZE bytes long.
-  uint32_t shared_data_size;     /* On input, set to size of shared data blob
+	 */
-                                  * buffer, in bytes.  On output, this will
+	/* Pointer to shared data blob buffer */
-                                  * contain the actual data size placed into
+	void *shared_data_blob;
-                                  * the buffer. */
+	/*
 	 * On input, set to size of shared data blob buffer, in bytes.  On
 	 * output, this will contain the actual data size placed into the
 	 * buffer.
 	 */
 	uint32_t shared_data_size;
-  /* Internal context/data for verified boot, to maintain state during
+	/*
 	 * Internal context/data for verified boot, to maintain state during
 	 * calls to other API functions such as VbExHashFirmwareBody().
-   * Allocated and freed inside the entry point; firmware should not
+	 * Allocated and freed inside the entry point; firmware should not look
-   * look at this. */
+	 * at this.
 	 */
 	void *vboot_context;
-  /* Internal context/data for firmware / VbExHashFirmwareBody().
+	/*
-   * Needed because the PEI phase of UEFI boot runs out of ROM and
+	 * Internal context/data for firmware / VbExHashFirmwareBody().  Needed
-   * thus can't modify global variables; everything needs to get
+	 * because the PEI phase of UEFI boot runs out of ROM and thus can't
-   * passed around on the stack. */
+	 * modify global variables; everything needs to get passed around on
 	 * the stack.
 	 */
 	void *caller_context;
 } VbCommonParams;
 /* Flags for VbInitParams.flags */
 /* Developer switch was on at boot time. */
 #define VB_INIT_FLAG_DEV_SWITCH_ON       0x00000001
@@ -161,17 +176,23 @@ typedef struct VbCommonParams {
 #define VB_INIT_FLAG_WP_ENABLED          0x00000004
 /* This is a S3 resume, not a normal boot. */
 #define VB_INIT_FLAG_S3_RESUME           0x00000008
-/* Previous boot attempt failed for reasons external to verified boot (RAM
+/*
- * init failure, SSD missing, etc.). */
+ * Previous boot attempt failed for reasons external to verified boot (RAM
-/* TODO: add a field to VbInitParams which holds a reason code, and report
+ * init failure, SSD missing, etc.).
- * that via VbSharedData. */
+ *
 * TODO: add a field to VbInitParams which holds a reason code, and report
 * that via VbSharedData.
 */
 #define VB_INIT_FLAG_PREVIOUS_BOOT_FAIL  0x00000010
-/* Calling firmware supports read only firmware for normal/developer
+/*
- * boot path. */
+ * Calling firmware supports read only firmware for normal/developer boot path.
 */
 #define VB_INIT_FLAG_RO_NORMAL_SUPPORT   0x00000020
-/* This platform does not have a physical dev-switch, so we must rely on a
+/*
 * This platform does not have a physical dev-switch, so we must rely on a
 * virtual switch (kept in the TPM) instead. When this flag is set,
- * VB_INIT_FLAG_DEV_SWITCH_ON is ignored. */
+ * VB_INIT_FLAG_DEV_SWITCH_ON is ignored.
 */
 #define VB_INIT_FLAG_VIRTUAL_DEV_SWITCH  0x00000040
 /* Set when the VGA Option ROM has been loaded already. */
 #define VB_INIT_FLAG_OPROM_LOADED        0x00000080
@@ -181,27 +202,35 @@ typedef struct VbCommonParams {
 #define VB_INIT_FLAG_EC_SOFTWARE_SYNC    0x00000200
 /* EC on this platform is slow to update. */
 #define VB_INIT_FLAG_EC_SLOW_UPDATE      0x00000400
-/* Software write protect was enabled at boot time. This is separate from the
+/*
- * HW write protect. Both must be set for flash write protection to work. */
+ * Software write protect was enabled at boot time. This is separate from the
 * HW write protect. Both must be set for flash write protection to work.
 */
 #define VB_INIT_FLAG_SW_WP_ENABLED       0x00000800
-/* Output flags for VbInitParams.out_flags.  Used to indicate
+/*
- * potential boot paths and configuration to the calling firmware
+ * Output flags for VbInitParams.out_flags.  Used to indicate potential boot
- * early in the boot process, so that it can properly configure itself
+ * paths and configuration to the calling firmware early in the boot process,
- * for the capabilities subsequently required by VbSelectFirmware()
+ * so that it can properly configure itself for the capabilities subsequently
- * and VbSelectAndLoadKernel(). */
+ * required by VbSelectFirmware() and VbSelectAndLoadKernel().
-/* Enable recovery path.  Do not rely on any rewritable data (cached
+ */
- * RAM timings, etc.).  Reliable operation is more important than boot
+/*
- * speed. */
+ * Enable recovery path.  Do not rely on any rewritable data (cached RAM
 * timings, etc.).  Reliable operation is more important than boot speed.
 */
 #define VB_INIT_OUT_ENABLE_RECOVERY      0x00000001
 /* RAM must be cleared before calling VbSelectFirmware(). */
 #define VB_INIT_OUT_CLEAR_RAM            0x00000002
-/* Load display drivers; VbExDisplay*() functions may be called.  If this flag
+/*
- * is not present, VbExDisplay*() functions will not be called this boot. */
+ * Load display drivers; VbExDisplay*() functions may be called.  If this flag
 * is not present, VbExDisplay*() functions will not be called this boot.
 */
 #define VB_INIT_OUT_ENABLE_DISPLAY       0x00000004
-/* Load USB storage drivers; VbExDisk*() functions may be called with the
+/*
 * Load USB storage drivers; VbExDisk*() functions may be called with the
 * VB_DISK_FLAG_REMOVABLE flag.  If this flag is not present, VbExDisk*()
- * functions will only be called for fixed disks. */
+ * functions will only be called for fixed disks.
 */
 #define VB_INIT_OUT_ENABLE_USB_STORAGE   0x00000008
 /* If this is a S3 resume, do a debug reset boot instead */
 #define VB_INIT_OUT_S3_DEBUG_BOOT        0x00000010
@@ -212,21 +241,22 @@ typedef struct VbCommonParams {
 /* Enable developer path. */
 #define VB_INIT_OUT_ENABLE_DEVELOPER     0x00000080
 /* Data only used by VbInit() */
 typedef struct VbInitParams {
 	/* Inputs to VbInit() */
-  uint32_t flags;                /* Flags (see VB_INIT_FLAG_*) */
+	/* Flags (see VB_INIT_FLAG_*) */
 	uint32_t flags;
 	/* Outputs from VbInit(); valid only if it returns success. */
-  uint32_t out_flags;            /* Output flags for firmware; see
+	/* Output flags for firmware; see VB_INIT_OUT_*) */
-                                  * VB_INIT_OUT_*) */
+	uint32_t out_flags;
 } VbInitParams;
-
+/*
-/* Firmware types for VbHashFirmwareBody() and
+ * Firmware types for VbHashFirmwareBody() and
- * VbSelectFirmwareParams.selected_firmware.  Note that we store these
+ * VbSelectFirmwareParams.selected_firmware.  Note that we store these in a
- * in a uint32_t because enum maps to int, which isn't fixed-size. */
+ * uint32_t because enum maps to int, which isn't fixed-size.
 */
 enum VbSelectFirmware_t {
 	/* Recovery mode */
 	VB_SELECT_FIRMWARE_RECOVERY = 0,
@@ -237,134 +267,163 @@ enum VbSelectFirmware_t {
 	VB_SELECT_FIRMWARE_READONLY = 3
 };
 /* Data only used by VbSelectFirmware() */
 typedef struct VbSelectFirmwareParams {
 	/* Inputs to VbSelectFirmware() */
-  void* verification_block_A;    /* Key block + preamble for firmware A */
+	/* Key block + preamble for firmware A */
-  void* verification_block_B;    /* Key block + preamble for firmware B */
+	void *verification_block_A;
-  uint32_t verification_size_A;  /* Verification block A size in bytes */
+	/* Key block + preamble for firmware B */
-  uint32_t verification_size_B;  /* Verification block B size in bytes */
+	void *verification_block_B;
 	/* Verification block A size in bytes */
 	uint32_t verification_size_A;
 	/* Verification block B size in bytes */
 	uint32_t verification_size_B;
 	/* Outputs from VbSelectFirmware(); valid only if it returns success. */
-  uint32_t selected_firmware;    /* Main firmware to run; see
+	/* Main firmware to run; see VB_SELECT_FIRMWARE_*. */
-                                  * VB_SELECT_FIRMWARE_*. */
+	uint32_t selected_firmware;
 } VbSelectFirmwareParams;
-
+/*
-/* We use disk handles rather than indices.  Using indices causes problems if
+ * We use disk handles rather than indices.  Using indices causes problems if
- * a disk is removed/inserted in the middle of processing. */
+ * a disk is removed/inserted in the middle of processing.
 */
 typedef void *VbExDiskHandle_t;
 /* Data used only by VbSelectAndLoadKernel() */
 typedef struct VbSelectAndLoadKernelParams {
 	/* Inputs to VbSelectAndLoadKernel() */
-  void* kernel_buffer;           /* Destination buffer for kernel
+	/* Destination buffer for kernel (normally at 0x100000 on x86) */
-                                  * (normally at 0x100000 on x86) */
+	void *kernel_buffer;
-  uint32_t kernel_buffer_size;   /* Size of kernel buffer in bytes */
+	/* Size of kernel buffer in bytes */
 	uint32_t kernel_buffer_size;
-  /* Outputs from VbSelectAndLoadKernel(); valid only if it returns success. */
+	/*
-  VbExDiskHandle_t disk_handle;  /* Handle of disk containing loaded kernel */
+	 * Outputs from VbSelectAndLoadKernel(); valid only if it returns
-  uint32_t partition_number;     /* Partition number on disk to boot (1...M) */
+	 * success.
-  uint64_t bootloader_address;   /* Address of bootloader image in RAM */
+	 */
-  uint32_t bootloader_size;      /* Size of bootloader image in bytes */
+	/* Handle of disk containing loaded kernel */
-  uint8_t partition_guid[16];    /* UniquePartitionGuid for boot partition */
+	VbExDiskHandle_t disk_handle;
-  /* TODO: in H2C, all that pretty much just gets passed to the bootloader
+	/* Partition number on disk to boot (1...M) */
-   * as KernelBootloaderOptions, though the disk handle is passed as an index
+	uint32_t partition_number;
-   * instead of a handle.  Is that used anymore now that we're passing
+	/* Address of bootloader image in RAM */
-   * partition_guid? */
+	uint64_t bootloader_address;
 	/* Size of bootloader image in bytes */
 	uint32_t bootloader_size;
 	/* UniquePartitionGuid for boot partition */
 	uint8_t partition_guid[16];
 	/*
 	 * TODO: in H2C, all that pretty much just gets passed to the
 	 * bootloader as KernelBootloaderOptions, though the disk handle is
 	 * passed as an index instead of a handle.  Is that used anymore now
 	 * that we're passing partition_guid?
 	 */
 } VbSelectAndLoadKernelParams;
-
+/**
-/* Initialize the verified boot library.
+ * Initialize the verified boot library.
 *
 * Returns VBERROR_SUCCESS if success, non-zero if error; on error,
- * caller should reboot. */
+ * caller should reboot.
 */
 VbError_t VbInit(VbCommonParams *cparams, VbInitParams *iparams);
-
+/**
-/* Select the main firmware.
+ * Select the main firmware.
 *
 * Returns VBERROR_SUCCESS if success, non-zero if error; on error,
- * caller should reboot. */
+ * caller should reboot.
-/* NOTE: This is now called in all modes, including recovery.
+ *
- * Previously, LoadFirmware() was not called in recovery mode, which
+ * NOTE: This is now called in all modes, including recovery.  Previously,
- * meant that LoadKernel() needed to duplicate the TPM and
+ * LoadFirmware() was not called in recovery mode, which meant that
- * VbSharedData initialization code. */
+ * LoadKernel() needed to duplicate the TPM and VbSharedData initialization
 * code.
 */
 VbError_t VbSelectFirmware(VbCommonParams *cparams,
                           VbSelectFirmwareParams *fparams);
-/* Update the data hash for the current firmware image, extending it
+/**
- * by [size] bytes stored in [*data].  This function must only be
+ * Update the data hash for the current firmware image, extending it by [size]
- * called inside VbExHashFirmwareBody(), which is in turn called by
+ * bytes stored in [*data].  This function must only be called inside
- * VbSelectFirmware().  */
+ * VbExHashFirmwareBody(), which is in turn called by VbSelectFirmware().
 */
 void VbUpdateFirmwareBodyHash(VbCommonParams *cparams,
                              uint8_t *data, uint32_t size);
-/* Select and loads the kernel.
+/**
 * Select and loads the kernel.
 *
- * Returns VBERROR_SUCCESS if success, non-zero if error; on error,
+ * Returns VBERROR_SUCCESS if success, non-zero if error; on error, caller
- * caller should reboot. */
+ * should reboot. */
 VbError_t VbSelectAndLoadKernel(VbCommonParams *cparams,
                                VbSelectAndLoadKernelParams *kparams);
 /*****************************************************************************/
 /* Debug output (from utility.h) */
-/* Output an error message and quit.  Does not return.  Supports
+/**
- * printf()-style formatting. */
+ * Output an error message and quit.  Does not return.  Supports
 * printf()-style formatting.
 */
 void VbExError(const char *format, ...);
-/* Output a debug message.  Supports printf()-style formatting. */
+/**
 * Output a debug message.  Supports printf()-style formatting.
 */
 void VbExDebug(const char *format, ...);
 /*****************************************************************************/
 /* Memory (from utility.h) */
-/* Allocate [size] bytes and return a pointer to the allocated memory. Abort
+/**
 * Allocate [size] bytes and return a pointer to the allocated memory. Abort
 * on error; this always either returns a good pointer or never returns.
 *
- * If any of the firmware API implementations require aligned data
+ * If any of the firmware API implementations require aligned data (for
- * (for example, disk access on ARM), all pointers returned by
+ * example, disk access on ARM), all pointers returned by VbExMalloc() must
- * VbExMalloc() must also be aligned.  */
+ * also be aligned.
 */
 void *VbExMalloc(size_t size);
-/* Free memory pointed to by [ptr] previously allocated by VbExMalloc(). */
+/**
 * Free memory pointed to by [ptr] previously allocated by VbExMalloc().
 */
 void VbExFree(void *ptr);
 /*****************************************************************************/
 /* Timer and delay (first two from utility.h) */
-/* Read a high-resolution timer.  Returns the current timer value in
+/**
- * arbitrary units.
+ * Read a high-resolution timer.  Returns the current timer value in arbitrary
 * units.
 *
- * This is intended for benchmarking, so this call MUST be fast.  The
+ * This is intended for benchmarking, so this call MUST be fast.  The timer
- * timer frequency must be >1 KHz (preferably >1 MHz), and the timer
+ * frequency must be >1 KHz (preferably >1 MHz), and the timer must not wrap
- * must not wrap around for at least 10 minutes.  It is preferable
+ * around for at least 10 minutes.  It is preferable (but not required) that
- * (but not required) that the timer be initialized to 0 at boot.
+ * the timer be initialized to 0 at boot.
 *
- * It is assumed that the firmware has some other way of communicating
+ * It is assumed that the firmware has some other way of communicating the
- * the timer frequency to the OS.  For example, on x86 we use TSC, and
+ * timer frequency to the OS.  For example, on x86 we use TSC, and the OS
- * the OS kernel reports the initial TSC value at kernel-start and
+ * kernel reports the initial TSC value at kernel-start and calculates the
- * calculates the frequency. */
+ * frequency. */
 uint64_t VbExGetTimer(void);
-/* Delay for at least the specified number of milliseconds.  Should be
+/**
- * accurate to within 10% (a requested delay of 1000 ms should
+ * Delay for at least the specified number of milliseconds.  Should be accurate
- * result in an actual delay of between 1000 - 1100 ms). */
+ * to within 10% (a requested delay of 1000 ms should result in an actual delay
 * of between 1000 - 1100 ms).
 */
 void VbExSleepMs(uint32_t msec);
-/* Play a beep tone of the specified frequency in Hz and duration in msec.
+/**
 * Play a beep tone of the specified frequency in Hz and duration in msec.
 * This is effectively a VbSleep() variant that makes noise.
 *
 * If the audio codec can run in the background, then:
 *   zero frequency means OFF, non-zero frequency means ON
 *   zero msec means return immediately, non-zero msec means delay (and
 *     then OFF if needed)
- * else:
+ * otherwise,
 *   non-zero msec and non-zero frequency means ON, delay, OFF, return
 *   zero msec or zero frequency means do nothing and return immediately
 *
@@ -376,65 +435,70 @@ void VbExSleepMs(uint32_t msec);
 */
 VbError_t VbExBeep(uint32_t msec, uint32_t frequency);
 /*****************************************************************************/
 /* TPM (from tlcl_stub.h) */
-/* Initialize the stub library. */
+/**
 * Initialize the stub library. */
 VbError_t VbExTpmInit(void);
-/* Close and open the device.  This is needed for running more complex commands
+/**
 * Close and open the device.  This is needed for running more complex commands
 * at user level, such as TPM_TakeOwnership, since the TPM device can be opened
- * only by one process at a time. */
+ * only by one process at a time.
 */
 VbError_t VbExTpmClose(void);
 VbError_t VbExTpmOpen(void);
-/* Send a request_length-byte request to the TPM and receive a
+/**
- * response.  On input, response_length is the size of the response
+ * Send a request_length-byte request to the TPM and receive a response.  On
- * buffer in bytes.  On exit, response_length is set to the actual
+ * input, response_length is the size of the response buffer in bytes.  On
- * received response length in bytes. */
+ * exit, response_length is set to the actual received response length in
 * bytes. */
 VbError_t VbExTpmSendReceive(const uint8_t *request, uint32_t request_length,
                             uint8_t *response, uint32_t *response_length);
 /*****************************************************************************/
 /* Non-volatile storage */
 #define VBNV_BLOCK_SIZE 16  /* Size of NV storage block in bytes */
-/* Read the VBNV_BLOCK_SIZE-byte non-volatile storage into buf. */
+/**
 * Read the VBNV_BLOCK_SIZE-byte non-volatile storage into buf.
 */
 VbError_t VbExNvStorageRead(uint8_t *buf);
-/* Write the VBNV_BLOCK_SIZE-byte non-volatile storage from buf. */
+/**
 * Write the VBNV_BLOCK_SIZE-byte non-volatile storage from buf.
 */
 VbError_t VbExNvStorageWrite(const uint8_t *buf);
 /*****************************************************************************/
 /* Firmware / EEPROM access (previously in load_firmware_fw.h) */
-/* Calculate the hash of the firmware body data for [firmware_index],
+/**
- * which is either VB_SELECT_FIRMWARE_A or VB_SELECT_FIRMWARE B.
+ * Calculate the hash of the firmware body data for [firmware_index], which is
 * either VB_SELECT_FIRMWARE_A or VB_SELECT_FIRMWARE B.
 *
- * This function must call VbUpdateFirmwareBodyHash() before
+ * This function must call VbUpdateFirmwareBodyHash() before returning, to
- * returning, to update the secure hash for the firmware image.  For
+ * update the secure hash for the firmware image.  For best performance, the
- * best performance, the implementation should call
+ * implementation should call VbUpdateFirmwareBodyHash() periodically during
- * VbUpdateFirmwareBodyHash() periodically during the read, so that
+ * the read, so that updating the hash can be pipelined with the read.  If the
- * updating the hash can be pipelined with the read.  If the reader
+ * reader cannot update the hash during the read process, it should call
- * cannot update the hash during the read process, it should call
+ * VbUpdateFirmwareBodyHash() on the entire firmware data after the read,
- * VbUpdateFirmwareBodyHash() on the entire firmware data after the
+ * before returning.
 * read, before returning.
 *
- * It is recommended that the firmware use this call to copy the
+ * It is recommended that the firmware use this call to copy the requested
- * requested firmware body from EEPROM into RAM, so that it doesn't
+ * firmware body from EEPROM into RAM, so that it doesn't need to do a second
- * need to do a second slow copy from EEPROM to RAM if this firmware
+ * slow copy from EEPROM to RAM if this firmware body is selected.
 * body is selected.
 *
- * Note this function doesn't actually pass the firmware body data to
+ * Note this function doesn't actually pass the firmware body data to verified
- * verified boot, because verified boot doesn't actually need the
+ * boot, because verified boot doesn't actually need the firmware body, just
- * firmware body, just its hash.  This is important on x86, where the
+ * its hash.  This is important on x86, where the firmware is stored
- * firmware is stored compressed.  We hash the compressed data, but
+ * compressed.  We hash the compressed data, but the BIOS decompresses it
- * the BIOS decompresses it during read.  Simply updating a hash is
+ * during read.  Simply updating a hash is compatible with the x86
- * compatible with the x86 read-and-decompress pipeline. */
+ * read-and-decompress pipeline.
 */
 VbError_t VbExHashFirmwareBody(VbCommonParams *cparams,
                               uint32_t firmware_index);
@@ -444,13 +508,17 @@ VbError_t VbExHashFirmwareBody(VbCommonParams* cparams,
 /* Flags for VbDisk APIs */
 /* Disk is removable.  Example removable disks: SD cards, USB keys.  */
 #define VB_DISK_FLAG_REMOVABLE 0x00000001
-/* Disk is fixed.  If this flag is present, disk is internal to the
+/*
- * system and not removable.  Example fixed disks: internal SATA SSD, eMMC. */
+ * Disk is fixed.  If this flag is present, disk is internal to the system and
 * not removable.  Example fixed disks: internal SATA SSD, eMMC.
 */
 #define VB_DISK_FLAG_FIXED     0x00000002
-/* Note that VB_DISK_FLAG_REMOVABLE and VB_DISK_FLAG_FIXED are
+/*
- * mutually-exclusive for a single disk.  VbExDiskGetInfo() may specify
+ * Note that VB_DISK_FLAG_REMOVABLE and VB_DISK_FLAG_FIXED are
- * both flags to request disks of both types in a single call. */
+ * mutually-exclusive for a single disk.  VbExDiskGetInfo() may specify both
-/* At some point we could specify additional flags, but we don't currently
+ * flags to request disks of both types in a single call.
 *
 * At some point we could specify additional flags, but we don't currently
 * have a way to make use of these:
 *
 * USB              Device is known to be attached to USB.  Note that the SD
@@ -461,97 +529,125 @@ VbError_t VbExHashFirmwareBody(VbCommonParams* cparams,
 *                  questionable use.
 * READ_ONLY        Device is known to be read-only.  Could be used by recovery
 *                  when processing read-only recovery image.
- **/
+ */
 /* Information on a single disk */
 typedef struct VbDiskInfo {
-  VbExDiskHandle_t handle;  /* Disk handle */
+	/* Disk handle */
-  uint64_t bytes_per_lba;   /* Size of a LBA sector in bytes */
+	VbExDiskHandle_t handle;
-  uint64_t lba_count;       /* Number of LBA sectors on the device */
+	/* Size of a LBA sector in bytes */
-  uint32_t flags;           /* Flags (see VB_DISK_FLAG_* constants) */
+	uint64_t bytes_per_lba;
-  const char* name;         /* Optional name string, for use in debugging.
+	/* Number of LBA sectors on the device */
-                             * May be empty or null if not available. */
+	uint64_t lba_count;
 	/* Flags (see VB_DISK_FLAG_* constants) */
 	uint32_t flags;
 	/*
 	 * Optional name string, for use in debugging.  May be empty or null if
 	 * not available.
 	 */
 	const char *name;
 } VbDiskInfo;
-/* Store information into [info] for all disks (storage devices)
+/**
- * attached to the system which match all of the disk_flags.
+ * Store information into [info] for all disks (storage devices) attached to
 * the system which match all of the disk_flags.
 *
- * On output, count indicates how many disks are present, and
+ * On output, count indicates how many disks are present, and [infos_ptr]
- * [infos_ptr] points to a [count]-sized array of VbDiskInfo structs
+ * points to a [count]-sized array of VbDiskInfo structs with the information
- * with the information on those disks; this pointer must be freed by
+ * on those disks; this pointer must be freed by calling VbExDiskFreeInfo().
- * calling VbExDiskFreeInfo().  If count=0, infos_ptr may point to
+ * If count=0, infos_ptr may point to NULL.  If [infos_ptr] points to NULL
- * NULL.  If [infos_ptr] points to NULL because count=0 or error, it
+ * because count=0 or error, it is not necessary to call VbExDiskFreeInfo().
 * is not necessary to call VbExDiskFreeInfo().
 *
 * A multi-function device (such as a 4-in-1 card reader) should provide
 * multiple disk handles.
 *
- * The firmware must not alter or free the list pointed to by
+ * The firmware must not alter or free the list pointed to by [infos_ptr] until
- * [infos_ptr] until VbExDiskFreeInfo() is called. */
+ * VbExDiskFreeInfo() is called.
 */
 VbError_t VbExDiskGetInfo(VbDiskInfo **infos_ptr, uint32_t *count,
                          uint32_t disk_flags);
-/* Free a disk information list [infos] previously returned by
+/**
- * VbExDiskGetInfo().  If [preserve_handle] != NULL, the firmware must
+ * Free a disk information list [infos] previously returned by
- * ensure that handle remains valid after this call; all other handles
+ * VbExDiskGetInfo().  If [preserve_handle] != NULL, the firmware must ensure
- * from the info list need not remain valid after this call. */
+ * that handle remains valid after this call; all other handles from the info
 * list need not remain valid after this call.
 */
 VbError_t VbExDiskFreeInfo(VbDiskInfo *infos,
                           VbExDiskHandle_t preserve_handle);
-/* Read lba_count LBA sectors, starting at sector lba_start, from the disk,
+/**
 * Read lba_count LBA sectors, starting at sector lba_start, from the disk,
 * into the buffer.
 *
- * If the disk handle is invalid (for example, the handle refers to a
+ * If the disk handle is invalid (for example, the handle refers to a disk
- * disk which as been removed), the function must return error but
+ * which as been removed), the function must return error but must not
- * must not crash. */
+ * crash.
 */
 VbError_t VbExDiskRead(VbExDiskHandle_t handle, uint64_t lba_start,
                       uint64_t lba_count, void *buffer);
-/* Write lba_count LBA sectors, starting at sector lba_start, to the
+/**
- * disk, from the buffer.
+ * Write lba_count LBA sectors, starting at sector lba_start, to the disk, from
 * the buffer.
 *
- * If the disk handle is invalid (for example, the handle refers to a
+ * If the disk handle is invalid (for example, the handle refers to a disk
- * disk which as been removed), the function must return error but
+ * which as been removed), the function must return error but must not
- * must not crash. */
+ * crash.
 */
 VbError_t VbExDiskWrite(VbExDiskHandle_t handle, uint64_t lba_start,
                        uint64_t lba_count, const void *buffer);
 /*****************************************************************************/
 /* Display */
 /* Predefined (default) screens for VbExDisplayScreen(). */
 enum VbScreenType_t {
-  VB_SCREEN_BLANK = 0,                 /* Blank (clear) screen */
+	/* Blank (clear) screen */
-  VB_SCREEN_DEVELOPER_WARNING = 0x101, /* Developer - warning */
+	VB_SCREEN_BLANK = 0,
-  VB_SCREEN_DEVELOPER_EGG     = 0x102, /* Developer - easter egg */
+	/* Developer - warning */
-  VB_SCREEN_RECOVERY_REMOVE   = 0x201, /* Recovery - remove inserted devices */
+	VB_SCREEN_DEVELOPER_WARNING = 0x101,
-  VB_SCREEN_RECOVERY_INSERT   = 0x202, /* Recovery - insert recovery image */
+	/* Developer - easter egg */
-  VB_SCREEN_RECOVERY_NO_GOOD  = 0x203, /* Recovery - inserted image invalid */
+	VB_SCREEN_DEVELOPER_EGG     = 0x102,
-  VB_SCREEN_RECOVERY_TO_DEV   = 0x204, /* Recovery - confirm dev mode */
+	/* Recovery - remove inserted devices */
-  VB_SCREEN_DEVELOPER_TO_NORM = 0x205, /* Developer - confirm normal mode */
+	VB_SCREEN_RECOVERY_REMOVE   = 0x201,
-  VB_SCREEN_WAIT              = 0x206, /* Please wait - programming EC */
+	/* Recovery - insert recovery image */
-  VB_SCREEN_TO_NORM_CONFIRMED = 0x207, /* Confirm after DEVELOPER_TO_NORM */
+	VB_SCREEN_RECOVERY_INSERT   = 0x202,
 	/* Recovery - inserted image invalid */
 	VB_SCREEN_RECOVERY_NO_GOOD  = 0x203,
 	/* Recovery - confirm dev mode */
 	VB_SCREEN_RECOVERY_TO_DEV   = 0x204,
 	/* Developer - confirm normal mode */
 	VB_SCREEN_DEVELOPER_TO_NORM = 0x205,
 	/* Please wait - programming EC */
 	VB_SCREEN_WAIT              = 0x206,
 	/* Confirm after DEVELOPER_TO_NORM */
 	VB_SCREEN_TO_NORM_CONFIRMED = 0x207,
 };
-/* Initialize and clear the display.  Set width and height to the screen
+/**
- * dimensions in pixels. */
+ * Initialize and clear the display.  Set width and height to the screen
 * dimensions in pixels.
 */
 VbError_t VbExDisplayInit(uint32_t *width, uint32_t *height);
-
+/**
-/* Enable (enable!=0) or disable (enable=0) the display backlight. */
+ * Enable (enable!=0) or disable (enable=0) the display backlight.
 */
 VbError_t VbExDisplayBacklight(uint8_t enable);
-
+/**
-/* Display a predefined screen; see VB_SCREEN_* for valid screens.
+ * Display a predefined screen; see VB_SCREEN_* for valid screens.
- * This is a backup method of screen display, intended for use if the
+ *
- * GBB does not contain a full set of bitmaps.  It is acceptable for
+ * This is a backup method of screen display, intended for use if the GBB does
- * the backup screen to be simple ASCII text such as "NO GOOD" or
+ * not contain a full set of bitmaps.  It is acceptable for the backup screen
- * "INSERT"; these screens should only be seen during development. */
+ * to be simple ASCII text such as "NO GOOD" or "INSERT"; these screens should
 * only be seen during development.
 */
 VbError_t VbExDisplayScreen(uint32_t screen_type);
-
+/**
-/* Write an image to the display, with the upper left corner at the specified
+ * Write an image to the display, with the upper left corner at the specified
 * pixel coordinates.  The bitmap buffer is a pointer to the platform-dependent
 * uncompressed binary blob with dimensions and format specified internally
 * (for example, a raw BMP, GIF, PNG, whatever). We pass the size just for
@@ -560,20 +656,20 @@ VbError_t VbExDisplayScreen(uint32_t screen_type);
 VbError_t VbExDisplayImage(uint32_t x, uint32_t y,
                           void *buffer, uint32_t buffersize);
-/* Display a string containing debug information on the screen,
+/**
- * rendered in a platform-dependent font.  Should be able to handle
+ * Display a string containing debug information on the screen, rendered in a
- * newlines '\n' in the string.  Firmware must support displaying at
+ * platform-dependent font.  Should be able to handle newlines '\n' in the
- * least 20 lines of text, where each line may be at least 80
+ * string.  Firmware must support displaying at least 20 lines of text, where
- * characters long.  If the firmware has its own debug state, it may
+ * each line may be at least 80 characters long.  If the firmware has its own
- * display it to the screen below this information. */
+ * debug state, it may display it to the screen below this information.
 *
 * NOTE: This is what we currently display when TAB is pressed.  Some
 * information (HWID, recovery reason) is ours; some (CMOS breadcrumbs) is
 * platform-specific.  If we decide to soft-render the HWID string
 * (chrome-os-partner:3693), we'll need to maintain our own fonts, so we'll
 * likely display it via VbExDisplayImage() above.
 */
 VbError_t VbExDisplayDebugInfo(const char *info_str);
 /* NOTE: This is what we currently display on ZGB/Alex when TAB is
 * pressed.  Some information (HWID, recovery reason) is ours; some
 * (CMOS breadcrumbs) is platform-specific.  If we decide to
 * soft-render the HWID string (chrome-os-partner:3693), we'll need to
 * maintain our own fonts, so we'll likely display it via
 * VbExDisplayImage() above. */
 /*****************************************************************************/
 /* Keyboard and switches */
@@ -587,7 +683,8 @@ enum VbKeyCode_t {
 	VB_KEY_CTRL_ENTER = 0x104,
 };
-/* Read the next keypress from the keyboard buffer.
+/**
 * Read the next keypress from the keyboard buffer.
 *
 * Returns the keypress, or zero if no keypress is pending or error.
 *
@@ -612,72 +709,91 @@ enum VbKeyCode_t {
 * sending an arrow key as the sequence of keys '\x1b', '[', '1', 'A'). */
 uint32_t VbExKeyboardRead(void);
 /*****************************************************************************/
 /* Embedded controller (EC) */
-/* This is called only if the system implements a keyboard-based (virtual)
+/**
 * This is called only if the system implements a keyboard-based (virtual)
 * developer switch. It must return true only if the system has an embedded
 * controller which is provably running in its RO firmware at the time the
- * function is called. */
+ * function is called.
 */
 int VbExTrustEC(void);
-/* Check if the EC is currently running rewritable code.
+/**
 * Check if the EC is currently running rewritable code.
 *
 * If the EC is in RO code, sets *in_rw=0.
 * If the EC is in RW code, sets *in_rw non-zero.
 * If the current EC image is unknown, returns error. */
 VbError_t VbExEcRunningRW(int *in_rw);
-/* Request the EC jump to its rewritable code.  If successful, returns
+/**
- * when the EC has booting its RW code far enough to respond to
+ * Request the EC jump to its rewritable code.  If successful, returns when the
- * subsequent commands.  Does nothing if the EC is already in its
+ * EC has booting its RW code far enough to respond to subsequent commands.
- * rewritable code. */
+ * Does nothing if the EC is already in its rewritable code.
 */
 VbError_t VbExEcJumpToRW(void);
-/* Tell the EC to stay in RO code until it reboots.  Subsequent calls to
+/**
 * Tell the EC to stay in RO code until it reboots.  Subsequent calls to
 * VbExEcJumpToRW() this boot will fail.  Fails if the EC is not currently in
- * RO code. */
+ * RO code.
 */
 VbError_t VbExEcStayInRO(void);
-/* Read the SHA-256 hash of the rewriteable EC image. */
+/**
 * Read the SHA-256 hash of the rewriteable EC image.
 */
 VbError_t VbExEcHashRW(const uint8_t **hash, int *hash_size);
-/* Get the expected contents of the EC image associated with the main firmware
+/**
- * specified by the "select" argument. */
+ * Get the expected contents of the EC image associated with the main firmware
 * specified by the "select" argument.
 */
 VbError_t VbExEcGetExpectedRW(enum VbSelectFirmware_t select,
                              const uint8_t **image, int *image_size);
-/* Update the EC rewritable image. */
+/**
 * Update the EC rewritable image.
 */
 VbError_t VbExEcUpdateRW(const uint8_t *image, int image_size);
-/* Lock the EC code to prevent updates until the EC is rebooted.
+/**
- * Subsequent calls to VbExEcUpdateRW() this boot will fail. */
+ * Lock the EC code to prevent updates until the EC is rebooted.
 * Subsequent calls to VbExEcUpdateRW() this boot will fail.
 */
 VbError_t VbExEcProtectRW(void);
 /* Args to VbExProtectFlash() */
 enum VbProtectFlash_t { VBPROTECT_RW_A, VBPROTECT_RW_B, VBPROTECT_RW_DEVKEY };
-/* Lock a section of the BIOS flash address space to prevent updates until the
+/**
 * Lock a section of the BIOS flash address space to prevent updates until the
 * host is rebooted. Subsequent attempts to erase or modify the specified BIOS
 * image will fail. If this function is called more than once each call should
- * be cumulative. */
+ * be cumulative.
 */
 VbError_t VbExProtectFlash(enum VbProtectFlash_t region);
 /*****************************************************************************/
 /* Misc */
-/* Checks if the firmware needs to shut down the system.
+/**
 * Check if the firmware needs to shut down the system.
 *
 * Returns 1 if a shutdown is being requested (for example, the user has
- * pressed the power button or closed the lid), or 0 if a shutdown is not
+ * pressed the power button or closed the lid), or 0 if a shutdown is not being
- * being requested. */
+ * requested.
-/* NOTE: When we're displaying a screen, pressing the power button
+ *
- * should shut down the computer.  We need a way to break out of our
+ * NOTE: When we're displaying a screen, pressing the power button should shut
- * control loop so this can occur cleanly. */
+ * down the computer.  We need a way to break out of our control loop so this
 * can occur cleanly.
 */
 uint32_t VbExIsShutdownRequested(void);
-/* Expose the BIOS' built-in decompression routine to the vboot wrapper. The
+/**
 * Expose the BIOS' built-in decompression routine to the vboot wrapper. The
 * caller must know how large the uncompressed data will be and must manage
 * that memory. The decompression routine just puts the uncompressed data into
 * the specified buffer. We pass in the size of the outbuf, and get back the
@@ -687,8 +803,9 @@ VbError_t VbExDecompress(void *inbuf, uint32_t in_size,
                         uint32_t compression_type,
                         void *outbuf, uint32_t *out_size);
-
+/**
-/* Execute legacy boot option */
+ * Execute legacy boot option.
 */
 int VbExLegacy(void);
 #endif  /* VBOOT_REFERENCE_VBOOT_API_H_ */
--- a/firmware/include/vboot_nvstorage.h
+++ b/firmware/include/vboot_nvstorage.h
@@ -1,10 +1,9 @@
-/* Copyright (c) 2012 The Chromium OS Authors. All rights reserved.
+/* Copyright (c) 2013 The Chromium OS Authors. All rights reserved.
 * Use of this source code is governed by a BSD-style license that can be
 * found in the LICENSE file.
 */
-/* Non-volatile storage routines for verified boot.
+/* Non-volatile storage routines for verified boot. */
 */
 #ifndef VBOOT_REFERENCE_NVSTORAGE_H_
 #define VBOOT_REFERENCE_NVSTORAGE_H_
@@ -14,36 +13,48 @@
 typedef struct VbNvContext {
 	/* Raw NV data.  Caller must fill this before calling VbNvSetup(). */
 	uint8_t raw[VBNV_BLOCK_SIZE];
-  /* Flag indicating whether raw data has changed.  Set by VbNvTeardown() if
+	/*
-   * the raw data has changed and needs to be stored to the underlying
+	 * Flag indicating whether raw data has changed.  Set by VbNvTeardown()
-   * non-volatile data store. */
+	 * if the raw data has changed and needs to be stored to the underlying
 	 * non-volatile data store.
 	 */
 	int raw_changed;
-  /* Internal data for NV storage routines.  Caller should not touch
+	/*
-   * these fields. */
+	 * Internal data for NV storage routines.  Caller should not touch
 	 * these fields.
 	 */
 	int regenerate_crc;
 } VbNvContext;
 /* Parameter type for VbNvGet(), VbNvSet(). */
 typedef enum VbNvParam {
-  /* Parameter values have been reset to defaults (flag for firmware).
+	/*
-   * 0=clear; 1=set. */
+	 * Parameter values have been reset to defaults (flag for firmware).
 	 * 0=clear; 1=set.
 	 */
 	VBNV_FIRMWARE_SETTINGS_RESET = 0,
-  /* Parameter values have been reset to defaults (flag for kernel).
+	/*
-   * 0=clear; 1=set. */
+	 * Parameter values have been reset to defaults (flag for kernel).
 	 * 0=clear; 1=set.
 	 */
 	VBNV_KERNEL_SETTINGS_RESET,
 	/* Request debug reset on next S3->S0 transition.  0=clear; 1=set. */
 	VBNV_DEBUG_RESET_MODE,
-  /* Number of times to try booting RW firmware slot B before slot A.
+	/*
-   * Valid range: 0-15. */
+	 * Number of times to try booting RW firmware slot B before slot A.
 	 * Valid range: 0-15.
 	 */
 	VBNV_TRY_B_COUNT,
-  /* Request recovery mode on next boot; see VBNB_RECOVERY_* below for
+	/*
-   * currently defined reason codes.  8-bit value. */
+	 * Request recovery mode on next boot; see VBNB_RECOVERY_* below for
 	 * currently defined reason codes.  8-bit value.
 	 */
 	VBNV_RECOVERY_REQUEST,
-  /* Localization index for screen bitmaps displayed by firmware.
+	/*
-   * 8-bit value. */
+	 * Localization index for screen bitmaps displayed by firmware.
 	 * 8-bit value.
 	 */
 	VBNV_LOCALIZATION_INDEX,
 	/* Field reserved for kernel/user-mode use; 32-bit value. */
 	VBNV_KERNEL_FIELD,
@@ -53,11 +64,17 @@ typedef enum VbNvParam {
 	VBNV_DEV_BOOT_LEGACY,
 	/* Only boot Google-signed images in developer mode.  0=no, 1=yes. */
 	VBNV_DEV_BOOT_SIGNED_ONLY,
-  /* Set by userspace to request that RO firmware disable dev-mode on the next
+	/*
-   * boot. This is likely only possible if the dev-switch is virtual. */
+	 * Set by userspace to request that RO firmware disable dev-mode on the
 	 * next boot. This is likely only possible if the dev-switch is
 	 * virtual.
 	 */
 	VBNV_DISABLE_DEV_REQUEST,
-  /* Set and cleared by vboot to request that the video Option ROM be loaded at
+	/*
-   * boot time, so that BIOS screens can be displayed. 0=no, 1=yes. */
+	 * Set and cleared by vboot to request that the video Option ROM be
 	 * loaded at boot time, so that BIOS screens can be displayed. 0=no,
 	 * 1=yes.
 	 */
 	VBNV_OPROM_NEEDED,
 	/* Request that the firmware clear the TPM owner on the next boot. */
 	VBNV_CLEAR_TPM_OWNER_REQUEST,
@@ -67,15 +84,15 @@ typedef enum VbNvParam {
 	VBNV_RECOVERY_SUBCODE,
 } VbNvParam;
 /* Recovery reason codes for VBNV_RECOVERY_REQUEST */
 /* Recovery not requested. */
 #define VBNV_RECOVERY_NOT_REQUESTED   0x00
-/* Recovery requested from legacy utility.  (Prior to the NV storage
+/*
- * spec, recovery mode was a single bitfield; this value is reserved
+ * Recovery requested from legacy utility.  (Prior to the NV storage spec,
- * so that scripts which wrote 1 to the recovery field are
+ * recovery mode was a single bitfield; this value is reserved so that scripts
- * distinguishable from scripts whch use the recovery reasons listed
+ * which wrote 1 to the recovery field are distinguishable from scripts whch
- * here. */
+ * use the recovery reasons listed here.
 */
 #define VBNV_RECOVERY_LEGACY          0x01
 /* User manually requested recovery via recovery button */
 #define VBNV_RECOVERY_RO_MANUAL       0x02
@@ -93,17 +110,23 @@ typedef enum VbNvParam {
 #define VBNV_RECOVERY_RO_TEST_LFS     0x08
 /* Test error from LoadFirmware() */
 #define VBNV_RECOVERY_RO_TEST_LF      0x09
-/* RW firmware failed signature check (neither RW firmware slot was valid).
+/*
 * RW firmware failed signature check (neither RW firmware slot was valid).
 * Recovery reason is VBNV_RECOVERY_RO_INVALID_RW_CHECK_MIN + the check value
 * for the slot which came closest to validating; see VBSD_LF_CHECK_* in
- * vboot_struct.h. */
+ * vboot_struct.h.
 */
 #define VBNV_RECOVERY_RO_INVALID_RW_CHECK_MIN  0x10
 #define VBNV_RECOVERY_RO_INVALID_RW_CHECK_MAX  0x1F
-/* Firmware boot failure outside of verified boot (RAM init, missing SSD,
+/*
- * etc.). */
+ * Firmware boot failure outside of verified boot (RAM init, missing SSD,
 * etc.).
 */
 #define VBNV_RECOVERY_RO_FIRMWARE     0x20
-/* Recovery mode TPM initialization requires a system reboot.  The system was
+/*
- * already in recovery mode for some other reason when this happened. */
+ * Recovery mode TPM initialization requires a system reboot.  The system was
 * already in recovery mode for some other reason when this happened.
 */
 #define VBNV_RECOVERY_RO_TPM_REBOOT   0x21
 /* EC software sync - other error */
 #define VBNV_RECOVERY_EC_SOFTWARE_SYNC 0x22
@@ -121,8 +144,10 @@ typedef enum VbNvParam {
 #define VBNV_RECOVERY_EC_PROTECT      0x28
 /* Unspecified/unknown error in read-only firmware */
 #define VBNV_RECOVERY_RO_UNSPECIFIED  0x3F
-/* User manually requested recovery by pressing a key at developer
+/*
- * warning screen */
+ * User manually requested recovery by pressing a key at developer
 * warning screen
 */
 #define VBNV_RECOVERY_RW_DEV_SCREEN   0x41
 /* No OS kernel detected */
 #define VBNV_RECOVERY_RW_NO_OS        0x42
@@ -175,10 +200,11 @@ typedef enum VbNvParam {
 /* Unspecified/unknown error in user-mode */
 #define VBNV_RECOVERY_US_UNSPECIFIED  0xFF
-
+/**
-/* Initialize the NV storage library.  This must be called before any
+ * Initialize the NV storage library.
- * other functions in this library.  Returns 0 if success, non-zero if
+ *
- * error.
+ * This must be called before any other functions in this library.  Returns 0
 * if success, non-zero if error.
 *
 * Proper calling procedure:
 *    1) Allocate a context struct.
@@ -187,14 +213,17 @@ typedef enum VbNvParam {
 *    3) Read underlying storage and fill in context->raw.
 *    4) Call VbNvSetup().
 *
- * If you have access to global variables, you may want to wrap all
+ * If you have access to global variables, you may want to wrap all that in
- * that in your own VbNvOpen() function.  We don't do that in here
+ * your own VbNvOpen() function.  We don't do that in here because there are no
- * because there are no global variables in UEFI BIOS during the PEI
+ * global variables in UEFI BIOS during the PEI phase (that's also why we have
- * phase (that's also why we have to pass around a context pointer). */
+ * to pass around a context pointer).
 */
 int VbNvSetup(VbNvContext *context);
-/* Clean up and flush changes back to the raw data.  This must be
+/**
- * called after other functions in this library.  Returns 0 if
+ * Clean up and flush changes back to the raw data.
 *
 * This must be called after other functions in this library.  Returns 0 if
 * success, non-zero if error.
 *
 * Proper calling procedure:
@@ -204,20 +233,26 @@ int VbNvSetup(VbNvContext* context);
 *    4) Free the context struct.
 *
 * If you have access to global variables, you may want to wrap this
- * in your own VbNvClose() function. */
+ * in your own VbNvClose() function.
 */
 int VbNvTeardown(VbNvContext *context);
-/* Read a NV storage parameter into *dest.  Returns 0 if success,
+/**
- * non-zero if error.
+ * Read a NV storage parameter into *dest.
 *
- * This may only be called between VbNvSetup() and VbNvTeardown(). */
+ * Returns 0 if success, non-zero if error.
 *
 * This may only be called between VbNvSetup() and VbNvTeardown().
 */
 int VbNvGet(VbNvContext *context, VbNvParam param, uint32_t *dest);
-/* Set a NV storage param to a new value.  Returns 0 if success,
+/**
- * non-zero if error.
+ * Set a NV storage param to a new value.
 *
- * This may only be called between VbNvSetup() and VbNvTeardown(). */
+ * Returns 0 if success, non-zero if error.
 *
 * This may only be called between VbNvSetup() and VbNvTeardown().
 */
 int VbNvSet(VbNvContext *context, VbNvParam param, uint32_t value);
 #endif  /* VBOOT_REFERENCE_NVSTORAGE_H_ */
--- a/firmware/include/vboot_struct.h
+++ b/firmware/include/vboot_struct.h
@@ -1,4 +1,4 @@
-/* Copyright (c) 2012 The Chromium OS Authors. All rights reserved.
+/* Copyright (c) 2013 The Chromium OS Authors. All rights reserved.
 * Use of this source code is governed by a BSD-style license that can be
 * found in the LICENSE file.
 *
@@ -15,27 +15,30 @@ __pragma(pack(push, 1)) /* Support packing for MSVC. */
 /* Public key data */
 typedef struct VbPublicKey {
-  uint64_t key_offset;     /* Offset of key data from start of this struct */
+	/* Offset of key data from start of this struct */
-  uint64_t key_size;       /* Size of key data in bytes (NOT strength of key
+	uint64_t key_offset;
-                           * in bits) */
+	/* Size of key data in bytes (NOT strength of key in bits) */
-  uint64_t algorithm;      /* Signature algorithm used by the key */
+	uint64_t key_size;
-  uint64_t key_version;    /* Key version */
+	/* Signature algorithm used by the key */
 	uint64_t algorithm;
 	/* Key version */
 	uint64_t key_version;
 } __attribute__((packed)) VbPublicKey;
 #define EXPECTED_VBPUBLICKEY_SIZE 32
 /* Signature data (a secure hash, possibly signed) */
 typedef struct VbSignature {
-  uint64_t sig_offset;  /* Offset of signature data from start of this
+	/* Offset of signature data from start of this struct */
-                         * struct */
+	uint64_t sig_offset;
-  uint64_t sig_size;    /* Size of signature data in bytes */
+	/* Size of signature data in bytes */
-  uint64_t data_size;   /* Size of the data block which was signed in bytes */
+	uint64_t sig_size;
 	/* Size of the data block which was signed in bytes */
 	uint64_t data_size;
 } __attribute__((packed)) VbSignature;
 #define EXPECTED_VBSIGNATURE_SIZE 24
 #define KEY_BLOCK_MAGIC "CHROMEOS"
 #define KEY_BLOCK_MAGIC_SIZE 8
@@ -49,30 +52,43 @@ typedef struct VbSignature {
 #define KEY_BLOCK_FLAG_RECOVERY_0   UINT64_C(0x04)  /* Not recovery mode */
 #define KEY_BLOCK_FLAG_RECOVERY_1   UINT64_C(0x08)  /* Recovery mode */
-/* Key block, containing the public key used to sign some other chunk
+/*
- * of data. */
+ * Key block, containing the public key used to sign some other chunk of data.
-typedef struct VbKeyBlockHeader {
+ *
-  uint8_t magic[KEY_BLOCK_MAGIC_SIZE];  /* Magic number */
+ * This should be followed by:
  uint32_t header_version_major;     /* Version of this header format */
  uint32_t header_version_minor;     /* Version of this header format */
  uint64_t key_block_size;           /* Length of this entire key block,
                                      * including keys, signatures, and
                                      * padding, in bytes */
  VbSignature key_block_signature;   /* Signature for this key block
                                      * (header + data pointed to by data_key)
                                      * For use with signed data keys*/
  VbSignature key_block_checksum;    /* SHA-512 checksum for this key block
                                      * (header + data pointed to by data_key)
                                      * For use with unsigned data keys */
  uint64_t key_block_flags;          /* Flags for key (KEY_BLOCK_FLAG_*) */
  VbPublicKey data_key;              /* Key to verify the chunk of data */
 } __attribute__((packed)) VbKeyBlockHeader;
 /* This should be followed by:
 *   1) The data_key key data, pointed to by data_key.key_offset.
 *   2) The checksum data for (VBKeyBlockHeader + data_key data), pointed to
 *      by key_block_checksum.sig_offset.
 *   3) The signature data for (VBKeyBlockHeader + data_key data), pointed to
- *      by key_block_signature.sig_offset. */
+ *      by key_block_signature.sig_offset.
 */
 typedef struct VbKeyBlockHeader {
 	/* Magic number */
 	uint8_t magic[KEY_BLOCK_MAGIC_SIZE];
 	/* Version of this header format */
 	uint32_t header_version_major;
 	/* Version of this header format */
 	uint32_t header_version_minor;
 	/*
 	 * Length of this entire key block, including keys, signatures, and
 	 * padding, in bytes
 	 */
 	uint64_t key_block_size;
 	/*
 	 * Signature for this key block (header + data pointed to by data_key)
 	 * For use with signed data keys
 	 */
 	VbSignature key_block_signature;
 	/*
 	 * SHA-512 checksum for this key block (header + data pointed to by
 	 * data_key) For use with unsigned data keys
 	 */
 	VbSignature key_block_checksum;
 	/* Flags for key (KEY_BLOCK_FLAG_*) */
 	uint64_t key_block_flags;
 	/* Key to verify the chunk of data */
 	VbPublicKey data_key;
 } __attribute__((packed)) VbKeyBlockHeader;
 #define EXPECTED_VBKEYBLOCKHEADER_SIZE 112
@@ -83,119 +99,170 @@ typedef struct VbKeyBlockHeader {
 /* Flags for VbECPreambleHeader.flags */
-/* Use the normal boot path from the read-only firmware, instead
+/*
- * of verifying the body signature. */
+ * Use the normal boot path from the read-only firmware, instead of verifying
 * the body signature.
 */
 #define VB_EC_PREAMBLE_USE_RO_NORMAL 0x00000001
-/* Premable block for EC rewritable firmware, version 1.0 */
+/*
 * Premable block for EC rewritable firmware, version 1.0.
 *
 * The firmware preamble header should be followed by:
 *   1) The signature data for the firmware body, pointed to by
 *      body_signature.sig_offset.
 *   2) The signature data for (header + body signature data), pointed
 *      to by preamble_signature.sig_offset.
 */
 typedef struct VbECPreambleHeader {
-  uint64_t preamble_size;            /* Size of this preamble, including keys,
+	/*
-                                      * signatures, and padding, in bytes */
+	 * Size of this preamble, including keys, signatures, and padding, in
-  VbSignature preamble_signature;    /* Signature for this preamble
+	 * bytes
-                                      * (header + * body signature) */
+	 */
-  uint32_t header_version_major;     /* Version of this header format */
+	uint64_t preamble_size;
-  uint32_t header_version_minor;     /* Version of this header format */
+	/* Signature for this preamble (header + * body signature) */
-
+	VbSignature preamble_signature;
-  uint64_t firmware_version;         /* Firmware version */
+	/* Version of this header format */
-  VbSignature body_digest;           /* Digest for the firmware body */
+	uint32_t header_version_major;
-
+	/* Version of this header format */
-  uint32_t flags;                    /* Flags; see VB_EC_PREAMBLE_* */
+	uint32_t header_version_minor;
-  char name[128];                    /* Human-readable ASCII, null-padded */
+	/* Firmware version */
 	uint64_t firmware_version;
 	/* Digest for the firmware body */
 	VbSignature body_digest;
 	/* Flags; see VB_EC_PREAMBLE_* */
 	uint32_t flags;
 	/* Human-readable ASCII, null-padded */
 	char name[128];
 } __attribute__((packed)) VbECPreambleHeader;
 #define EXPECTED_VB_EC_PREAMBLE_HEADER1_0_SIZE 76
 /* The firmware preamble header should be followed by:
 *   2) The signature data for the firmware body, pointed to by
 *      body_signature.sig_offset.
 *   3) The signature data for (header + body signature data), pointed
 *      to by preamble_signature.sig_offset. */
 /****************************************************************************/
 #define FIRMWARE_PREAMBLE_HEADER_VERSION_MAJOR 2
 #define FIRMWARE_PREAMBLE_HEADER_VERSION_MINOR 1
-/* Preamble block for rewritable firmware, version 2.0.  All 2.x
+/*
- * versions of this struct must start with the same data, to be
+ * Preamble block for rewritable firmware, version 2.0.  All 2.x versions of
- * compatible with version 2.0 readers. */
+ * this struct must start with the same data, to be compatible with version 2.0
 * readers.
 */
 typedef struct VbFirmwarePreambleHeader2_0 {
-  uint64_t preamble_size;            /* Size of this preamble, including keys,
+	/*
-                                      * signatures, and padding, in bytes */
+	 * Size of this preamble, including keys, signatures, and padding, in
-  VbSignature preamble_signature;    /* Signature for this preamble
+	 * bytes
-                                      * (header + kernel subkey +
+	 */
-                                      * body signature) */
+	uint64_t preamble_size;
-  uint32_t header_version_major;     /* Version of this header format (= 2) */
+	/*
-  uint32_t header_version_minor;     /* Version of this header format (= 0) */
+	 * Signature for this preamble (header + kernel subkey + body
 	 * signature)
 	 */
 	VbSignature preamble_signature;
 	/* Version of this header format (= 2) */
 	uint32_t header_version_major;
 	/* Version of this header format (= 0) */
 	uint32_t header_version_minor;
-  uint64_t firmware_version;         /* Firmware version */
+	/* Firmware version */
-  VbPublicKey kernel_subkey;         /* Key to verify kernel key block */
+	uint64_t firmware_version;
-  VbSignature body_signature;        /* Signature for the firmware body */
+	/* Key to verify kernel key block */
 	VbPublicKey kernel_subkey;
 	/* Signature for the firmware body */
 	VbSignature body_signature;
 } __attribute__((packed)) VbFirmwarePreambleHeader2_0;
 #define EXPECTED_VBFIRMWAREPREAMBLEHEADER2_0_SIZE 104
 /* Flags for VbFirmwarePreambleHeader.flags */
-/* Use the normal/dev boot path from the read-only firmware, instead
+/*
- * of verifying the body signature. */
+ * Use the normal/dev boot path from the read-only firmware, instead of
 * verifying the body signature.
 */
 #define VB_FIRMWARE_PREAMBLE_USE_RO_NORMAL 0x00000001
-/* Premable block for rewritable firmware, version 2.1 */
+/* Premable block for rewritable firmware, version 2.1.
-typedef struct VbFirmwarePreambleHeader {
+ *
-  uint64_t preamble_size;            /* Size of this preamble, including keys,
+ * The firmware preamble header should be followed by:
                                      * signatures, and padding, in bytes */
  VbSignature preamble_signature;    /* Signature for this preamble
                                      * (header + kernel subkey +
                                      * body signature) */
  uint32_t header_version_major;     /* Version of this header format */
  uint32_t header_version_minor;     /* Version of this header format */
  uint64_t firmware_version;         /* Firmware version */
  VbPublicKey kernel_subkey;         /* Key to verify kernel key block */
  VbSignature body_signature;        /* Signature for the firmware body */
  /* Fields added in header version 2.1.  You must verify the header version
   * before reading these fields! */
  uint32_t flags;                    /* Flags; see VB_FIRMWARE_PREAMBLE_*.
                                      * Readers should return 0 for header
                                      * version < 2.1. */
 } __attribute__((packed)) VbFirmwarePreambleHeader;
 #define EXPECTED_VBFIRMWAREPREAMBLEHEADER2_1_SIZE 108
 /* The firmware preamble header should be followed by:
 *   1) The kernel_subkey key data, pointed to by kernel_subkey.key_offset.
 *   2) The signature data for the firmware body, pointed to by
 *      body_signature.sig_offset.
 *   3) The signature data for (header + kernel_subkey data + body signature
- *      data), pointed to by preamble_signature.sig_offset. */
+ *      data), pointed to by preamble_signature.sig_offset.
 */
 typedef struct VbFirmwarePreambleHeader {
 	/*
 	 * Size of this preamble, including keys, signatures, and padding, in
 	 * bytes
 	 */
 	uint64_t preamble_size;
 	/*
 	 * Signature for this preamble (header + kernel subkey + body
 	 * signature)
 	 */
 	VbSignature preamble_signature;
 	/* Version of this header format */
 	uint32_t header_version_major;
 	/* Version of this header format */
 	uint32_t header_version_minor;
 	/* Firmware version */
 	uint64_t firmware_version;
 	/* Key to verify kernel key block */
 	VbPublicKey kernel_subkey;
 	/* Signature for the firmware body */
 	VbSignature body_signature;
 	/*
 	 * Fields added in header version 2.1.  You must verify the header
 	 * version before reading these fields!
 	 */
 	/*
 	 * Flags; see VB_FIRMWARE_PREAMBLE_*.  Readers should return 0 for
 	 * header version < 2.1.
 	 */
 	uint32_t flags;
 } __attribute__((packed)) VbFirmwarePreambleHeader;
 #define EXPECTED_VBFIRMWAREPREAMBLEHEADER2_1_SIZE 108
 /****************************************************************************/
 #define KERNEL_PREAMBLE_HEADER_VERSION_MAJOR 2
 #define KERNEL_PREAMBLE_HEADER_VERSION_MINOR 0
-/* Preamble block for kernel */
+/* Preamble block for kernel
-typedef struct VbKernelPreambleHeader {
+ *
-  uint64_t preamble_size;            /* Size of this preamble, including keys,
+ * This should be followed by:
-                                      * signatures, and padding, in bytes */
+ *   1) The signature data for the kernel body, pointed to by
  VbSignature preamble_signature;    /* Signature for this preamble
                                      * (header + body signature) */
  uint32_t header_version_major;     /* Version of this header format */
  uint32_t header_version_minor;     /* Version of this header format */
  uint64_t kernel_version;           /* Kernel version */
  uint64_t body_load_address;        /* Load address for kernel body */
  uint64_t bootloader_address;       /* Address of bootloader, after body is
                                      * loaded at body_load_address */
  uint64_t bootloader_size;          /* Size of bootloader in bytes */
  VbSignature body_signature;        /* Signature for the kernel body */
 } __attribute__((packed)) VbKernelPreambleHeader;
 /* This should be followed by:
 *   2) The signature data for the kernel body, pointed to by
 *      body_signature.sig_offset.
- *   3) The signature data for (VBFirmwarePreambleHeader + body signature
+ *   2) The signature data for (VBFirmwarePreambleHeader + body signature
- *      data), pointed to by preamble_signature.sig_offset. */
+ *      data), pointed to by preamble_signature.sig_offset.
 */
 typedef struct VbKernelPreambleHeader {
 	/*
 	 * Size of this preamble, including keys, signatures, and padding, in
 	 * bytes
 	 */
 	uint64_t preamble_size;
 	/* Signature for this preamble (header + body signature) */
 	VbSignature preamble_signature;
 	/* Version of this header format */
 	uint32_t header_version_major;
 	/* Version of this header format */
 	uint32_t header_version_minor;
 	/* Kernel version */
 	uint64_t kernel_version;
 	/* Load address for kernel body */
 	uint64_t body_load_address;
 	/* Address of bootloader, after body is loaded at body_load_address */
 	uint64_t bootloader_address;
 	/* Size of bootloader in bytes */
 	uint64_t bootloader_size;
 	/* Signature for the kernel body */
 	VbSignature body_signature;
 } __attribute__((packed)) VbKernelPreambleHeader;
 #define EXPECTED_VBKERNELPREAMBLEHEADER_SIZE 96
@@ -213,9 +280,11 @@ typedef struct VbKernelPreambleHeader {
 /* Flags for VbSharedDataHeader */
 /* LoadFirmware() tried firmware B because of VbNvStorage firmware B tries */
 #define VBSD_FWB_TRIED                  0x00000001
-/* LoadKernel() verified the good kernel keyblock using the kernel subkey from
+/*
 * LoadKernel() verified the good kernel keyblock using the kernel subkey from
 * the firmware.  If this flag is not present, it just used the hash of the
- * kernel keyblock. */
+ * kernel keyblock.
 */
 #define VBSD_KERNEL_KEY_VERIFIED        0x00000002
 /* LoadFirmware() was told the developer switch was on */
 #define VBSD_LF_DEV_SWITCH_ON           0x00000004
@@ -240,9 +309,11 @@ typedef struct VbKernelPreambleHeader {
 /* Firmware software write protect was enabled at boot time */
 #define VBSD_BOOT_FIRMWARE_SW_WP_ENABLED 0x00002000
-/* Supported flags by header version.  It's ok to add new flags while keeping
+/*
 * Supported flags by header version.  It's ok to add new flags while keeping
 * struct version 2 as long as flag-NOT-present is the correct value for
- * existing hardware (Stumpy/Lumpy). */
+ * existing hardware (Stumpy/Lumpy).
 */
 #define VBSD_FLAGS_VERSION_1            0x00000007  /* Alex, ZGB */
 #define VBSD_FLAGS_VERSION_2            0x00000F7F
@@ -260,8 +331,10 @@ typedef struct VbKernelPreambleHeader {
 #define VBSD_LF_CHECK_HASH_WRONG_SIZE   10
 #define VBSD_LF_CHECK_VERIFY_BODY       11
 #define VBSD_LF_CHECK_VALID             12
-/* Read-only normal path requested by firmware preamble, but
+/*
- * unsupported by firmware. */
+ * Read-only normal path requested by firmware preamble, but unsupported by
 * firmware.
 */
 #define VBSD_LF_CHECK_NO_RO_NORMAL      13
 /* Boot mode for VbSharedDataHeader.lk_boot_mode */
@@ -285,8 +358,10 @@ typedef struct VbKernelPreambleHeader {
 #define VBSD_LKP_CHECK_VERIFY_PREAMBLE    9
 #define VBSD_LKP_CHECK_KERNEL_ROLLBACK    10
 #define VBSD_LKP_CHECK_PREAMBLE_VALID     11
-/* Body load address check is omitted; this result code is deprecated and not
+/*
- * used anywhere in the codebase. */
+ * Body load address check is omitted; this result code is deprecated and not
 * used anywhere in the codebase.
 */
 #define VBSD_LKP_CHECK_BODY_ADDRESS       12
 #define VBSD_LKP_CHECK_BODY_OFFSET        13
 #define VBSD_LKP_CHECK_SELF_SIGNED        14
@@ -296,7 +371,6 @@ typedef struct VbKernelPreambleHeader {
 #define VBSD_LKP_CHECK_VERIFY_DATA        18
 #define VBSD_LKP_CHECK_KERNEL_GOOD        19
 /* Information about a single kernel partition check in LoadKernel() */
 typedef struct VbSharedDataKernelPart {
 	uint64_t sector_start;     /* Start sector of partition */
@@ -326,25 +400,35 @@ typedef struct VbSharedDataKernelPart {
 /* Information about a single call to LoadKernel() */
 typedef struct VbSharedDataKernelCall {
-  uint32_t boot_flags;                /* Bottom 32 bits of flags passed in
+	/* Bottom 32 bits of flags passed in LoadKernelParams.boot_flags */
-                                       * LoadKernelParams.boot_flags */
+	uint32_t boot_flags;
-  uint32_t flags;                     /* Debug flags; see VBSD_LK_FLAG_* */
+	/* Debug flags; see VBSD_LK_FLAG_* */
-  uint64_t sector_count;              /* Number of sectors on drive */
+	uint32_t flags;
-  uint32_t sector_size;               /* Sector size in bytes */
+	/* Number of sectors on drive */
-  uint8_t check_result;               /* Check result; see VBSD_LKC_CHECK_* */
+	uint64_t sector_count;
-  uint8_t boot_mode;                  /* Boot mode for LoadKernel(); see
+	/* Sector size in bytes */
-                                       * VBSD_LK_BOOT_MODE_* constants */
+	uint32_t sector_size;
-  uint8_t test_error_num;             /* Test error number, if non-zero */
+	/* Check result; see VBSD_LKC_CHECK_* */
-  uint8_t return_code;                /* Return code from LoadKernel() */
+	uint8_t check_result;
-  uint8_t kernel_parts_found;         /* Number of kernel partitions found */
+	/* Boot mode for LoadKernel(); see VBSD_LK_BOOT_MODE_* constants */
-  uint8_t reserved0[7];               /* Reserved for padding */
+	uint8_t boot_mode;
-  VbSharedDataKernelPart parts[VBSD_MAX_KERNEL_PARTS]; /* Data on kernels */
+	/* Test error number, if non-zero */
 	uint8_t test_error_num;
 	/* Return code from LoadKernel() */
 	uint8_t return_code;
 	/* Number of kernel partitions found */
 	uint8_t kernel_parts_found;
 	/* Reserved for padding */
 	uint8_t reserved0[7];
 	/* Data on kernels */
 	VbSharedDataKernelPart parts[VBSD_MAX_KERNEL_PARTS];
 } VbSharedDataKernelCall;
 /* Number of kernel calls to track.  Must be power of 2. */
 #define VBSD_MAX_KERNEL_CALLS 4
-/* Data shared between LoadFirmware(), LoadKernel(), and OS.
+/*
 * Data shared between LoadFirmware(), LoadKernel(), and OS.
 *
 * The boot process is:
 *   1) Caller allocates buffer, at least VB_SHARED_DATA_MIN bytes, ideally
@@ -355,25 +439,34 @@ typedef struct VbSharedDataKernelCall {
 *      LoadKernel() initializes the buffer, adding this header.  Regardless
 *      of boot type, LoadKernel() adds some data to the buffer.
 *   4) Caller makes data available to the OS in a platform-dependent manner.
- *      For example, via ACPI or ATAGs. */
+ *      For example, via ACPI or ATAGs.
 */
 typedef struct VbSharedDataHeader {
 	/* Fields present in version 1 */
-  uint32_t magic;                     /* Magic number for struct
+	/* Magic number for struct (VB_SHARED_DATA_MAGIC) */
-                                       * (VB_SHARED_DATA_MAGIC) */
+	uint32_t magic;
-  uint32_t struct_version;            /* Version of this structure */
+	/* Version of this structure */
-  uint64_t struct_size;               /* Size of this structure in bytes */
+	uint32_t struct_version;
-  uint64_t data_size;                 /* Size of shared data buffer in bytes */
+	/* Size of this structure in bytes */
-  uint64_t data_used;                 /* Amount of shared data used so far */
+	uint64_t struct_size;
-  uint32_t flags;                     /* Flags */
+	/* Size of shared data buffer in bytes */
-  uint32_t reserved0;                 /* Reserved for padding */
+	uint64_t data_size;
 	/* Amount of shared data used so far */
 	uint64_t data_used;
 	/* Flags */
 	uint32_t flags;
 	/* Reserved for padding */
 	uint32_t reserved0;
 	/* Kernel subkey, from firmware */
 	VbPublicKey kernel_subkey;
 	/* Offset of kernel subkey data from start of this struct */
 	uint64_t kernel_subkey_data_offset;
 	/* Size of kernel subkey data */
 	uint64_t kernel_subkey_data_size;
-  VbPublicKey kernel_subkey;          /* Kernel subkey, from firmware */
+	/*
-  uint64_t kernel_subkey_data_offset; /* Offset of kernel subkey data from
+	 * Timer values from VbExGetTimer().  Unused values are set to 0.  Note
-                                       * start of this struct */
+	 * that these are now the enter/exit times for the wrapper API entry
  uint64_t kernel_subkey_data_size;   /* Size of kernel subkey data */
  /* Timer values from VbExGetTimer().  Unused values are set to 0.
   * Note that these are now the enter/exit times for the wrapper API entry
 	 * points; see crosbug.com/17018. */
 	/* VbInit() enter/exit */
 	uint64_t timer_vb_init_enter;
@@ -386,55 +479,73 @@ typedef struct VbSharedDataHeader {
 	uint64_t timer_vb_select_and_load_kernel_exit;
 	/* Information stored in TPM, as retrieved by firmware */
-  uint32_t fw_version_tpm;            /* Current firmware version in TPM */
+	/* Current firmware version in TPM */
-  uint32_t kernel_version_tpm;        /* Current kernel version in TPM */
+	uint32_t fw_version_tpm;
 	/* Current kernel version in TPM */
 	uint32_t kernel_version_tpm;
 	/* Debugging information from LoadFirmware() */
-  uint8_t check_fw_a_result;          /* Result of checking RW firmware A */
+	/* Result of checking RW firmware A and B */
-  uint8_t check_fw_b_result;          /* Result of checking RW firmware B */
+	uint8_t check_fw_a_result;
-  uint8_t firmware_index;             /* Firmware index returned by
+	uint8_t check_fw_b_result;
-                                       * LoadFirmware() or 0xFF if failure */
+	/* Firmware index returned by LoadFirmware() or 0xFF if failure */
-  uint8_t reserved1;                  /* Reserved for padding */
+	uint8_t firmware_index;
-  uint32_t fw_version_tpm_start;      /* Firmware TPM version at start of
+	/* Reserved for padding */
-                                       * VbSelectFirmware() */
+	uint8_t reserved1;
-  uint32_t fw_version_lowest;         /* Firmware lowest version found */
+	/* Firmware TPM version at start of VbSelectFirmware() */
 	uint32_t fw_version_tpm_start;
 	/* Firmware lowest version found */
 	uint32_t fw_version_lowest;
 	/* Debugging information from LoadKernel() */
-  uint32_t lk_call_count;             /* Number of times LoadKernel() called */
+	/* Number of times LoadKernel() called */
-  VbSharedDataKernelCall lk_calls[VBSD_MAX_KERNEL_CALLS];  /* Info on calls */
+	uint32_t lk_call_count;
 	/* Info on calls */
 	VbSharedDataKernelCall lk_calls[VBSD_MAX_KERNEL_CALLS];
-  /* Offset and size of supplemental kernel data.  Reserve space for these
+	/*
-   * fields now, so that future LoadKernel() versions can store information
+	 * Offset and size of supplemental kernel data.  Reserve space for
-   * there without needing to shift down whatever data the original
+	 * these fields now, so that future LoadKernel() versions can store
-   * LoadFirmware() might have put immediately following its
+	 * information there without needing to shift down whatever data the
-   * VbSharedDataHeader. */
+	 * original LoadFirmware() might have put immediately following its
 	 * VbSharedDataHeader.
 	 */
 	uint64_t kernel_supplemental_offset;
 	uint64_t kernel_supplemental_size;
-  /* Fields added in version 2.  Before accessing, make sure that
+	/*
-   * struct_version >= 2*/
+	 * Fields added in version 2.  Before accessing, make sure that
-  uint8_t recovery_reason;            /* Recovery reason for current boot */
+	 * struct_version >= 2
-  uint8_t reserved2[7];               /* Reserved for padding */
+	 */
-  uint64_t fw_keyblock_flags;         /* Flags from firmware keyblock */
+	/* Recovery reason for current boot */
-  uint32_t kernel_version_tpm_start;  /* Kernel TPM version at start of
+	uint8_t recovery_reason;
-                                       * VbSelectAndLoadKernel() */
+	/* Reserved for padding */
-  uint32_t kernel_version_lowest;     /* Kernel lowest version found */
+	uint8_t reserved2[7];
 	/* Flags from firmware keyblock */
 	uint64_t fw_keyblock_flags;
 	/* Kernel TPM version at start of VbSelectAndLoadKernel() */
 	uint32_t kernel_version_tpm_start;
 	/* Kernel lowest version found */
 	uint32_t kernel_version_lowest;
-  /* After read-only firmware which uses version 2 is released, any additional
+	/*
-   * fields must be added below, and the struct version must be increased.
+	 * After read-only firmware which uses version 2 is released, any
-   * Before reading/writing those fields, make sure that the struct being
+	 * additional fields must be added below, and the struct version must
-   * accessed is at least version 3.
+	 * be increased.  Before reading/writing those fields, make sure that
 	 * the struct being accessed is at least version 3.
 	 *
-   * It's always ok for an older firmware to access a newer struct, since all
+	 * It's always ok for an older firmware to access a newer struct, since
-   * the fields it knows about are present.  Newer firmware needs to use
+	 * all the fields it knows about are present.  Newer firmware needs to
-   * reasonable defaults when accessing older structs. */
+	 * use reasonable defaults when accessing older structs.
-
+	 */
 } __attribute__((packed)) VbSharedDataHeader;
-/* Size of VbSharedDataheader for each version */
+/*
-// TODO: crossystem needs not to
+ * Size of VbSharedDataheader for each version
-// fail if called on a v1 system where sizeof(VbSharedDataHeader) was smaller
+ *
-
+ * TODO: crossystem needs not to fail if called on a v1 system where
 * sizeof(VbSharedDataHeader) was smaller
 */
 #define VB_SHARED_DATA_HEADER_SIZE_V1 1072
 #define VB_SHARED_DATA_HEADER_SIZE_V2 1096