Index: firmware/include/vboot_nvstorage.h |
diff --git a/firmware/include/vboot_nvstorage.h b/firmware/include/vboot_nvstorage.h |
index cd4f89dd6af8bc66b868a01d7b0e240af107fdeb..31bc539ed9be6d9e1ad43b3fde232a3516cff763 100644 |
--- a/firmware/include/vboot_nvstorage.h |
+++ b/firmware/include/vboot_nvstorage.h |
@@ -3,17 +3,17 @@ |
* found in the LICENSE file. |
*/ |
-/* Non-volatile storage routines. |
+/* Non-volatile storage routines for verified boot. |
*/ |
#ifndef VBOOT_REFERENCE_NVSTORAGE_H_ |
#define VBOOT_REFERENCE_NVSTORAGE_H_ |
-#define NV_BLOCK_SIZE 16 /* Size of NV storage block in bytes */ |
+#define VBNV_BLOCK_SIZE 16 /* Size of NV storage block in bytes */ |
typedef struct VbNvContext { |
/* Raw NV data. Caller must fill this before calling VbNvSetup(). */ |
- uint8_t raw[NV_BLOCK_SIZE]; |
+ 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 |
* non-volatile data store. */ |
@@ -28,45 +28,109 @@ typedef struct VbNvContext { |
/* Parameter type for VbNvGet(), VbNvSet(). */ |
typedef enum VbNvParam { |
+ /* 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. */ |
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. */ |
VBNV_TRY_B_COUNT, |
+ /* 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. */ |
VBNV_LOCALIZATION_INDEX, |
+ /* Field reserved for kernel/user-mode use; 32-bit value. */ |
VBNV_KERNEL_FIELD, |
} 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 |
+ * so that scripts which wrote 1 to the recovery field are |
+ * distinguishable from scripts whch use the recovery reasons listed |
+ * here. */ |
+#define VBNV_RECOVERY_LEGACY 0x01 |
+/* User manually requested recovery via recovery button */ |
+#define VBNV_RECOVERY_RO_MANUAL 0x02 |
+/* RW firmware failed signature check (neither RW firmware slot was valid) */ |
+#define VBNV_RECOVERY_RO_INVALID_RW 0x03 |
+/* S3 resume failed */ |
+#define VBNV_RECOVERY_RO_S3_RESUME 0x04 |
+/* TPM error in read-only firmware */ |
+#define VBNV_RECOVERY_RO_TPM_ERROR 0x05 |
+/* 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 */ |
+#define VBNV_RECOVERY_RW_DEV_SCREEN 0x41 |
+/* No OS kernel detected */ |
+#define VBNV_RECOVERY_RW_NO_OS 0x42 |
+/* OS kernel failed signature check */ |
+#define VBNV_RECOVERY_RW_INVALID_OS 0x43 |
+/* TPM error in rewritable firmware */ |
+#define VBNV_RECOVERY_RW_TPM_ERROR 0x44 |
+/* Unspecified/unknown error in rewritable firmware */ |
+#define VBNV_RECOVERY_RW_UNSPECIFIED 0x7F |
+/* DM-verity error */ |
+#define VBNV_RECOVERY_KE_DM_VERITY 0x81 |
+/* Unspecified/unknown error in kernel */ |
+#define VBNV_RECOVERY_KE_UNSPECIFIED 0xBF |
+/* Recovery mode test from user-mode */ |
+#define VBNV_RECOVERY_US_TEST 0xC1 |
+/* Unspecified/unknown error in user-mode */ |
+#define VBNV_RECOVERY_US_UNSPECIFIED 0xFF |
+ |
+ |
/* Initialize the NV storage library. This must be called before any |
- * other functions in this library. Returns 0 if success, non-zero if |
+ * other functions in this library. Returns 0 if success, non-zero if |
* error. |
* |
- * If you have access to global variables, you may want to wrap this |
- * in your own VbNvOpen() function which allocates a context, acquires |
- * a lock to prevent race conditions accessing the underlying storage, |
- * reads the raw data from underlying storage, and calls VbNvSetup(). |
- * We don't do that in here because there are no global variables in |
- * UEFI BIOS during PEI phase. */ |
+ * Proper calling procedure: |
+ * 1) Allocate a context struct. |
+ * 2) If multi-threaded/multi-process, acquire a lock to prevent |
+ * other processes from modifying the underlying storage. |
+ * 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 |
+ * that in your own VbNvOpen() function. We don't do that in here |
+ * because there are no global variables in UEFI BIOS during the PEI |
+ * phase (that's also why we have 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. Caller must check |
- * context.raw_changed after calling this function. Returns 0 if |
+ * called after other functions in this library. Returns 0 if |
* success, non-zero if error. |
* |
+ * Proper calling procedure: |
+ * 1) Call VbNvExit(). |
+ * 2) If context.raw_changed, write data back to underlying storage. |
+ * 3) Release any lock you acquired before calling VbNvSetup(). |
+ * 4) Free the context struct. |
+ * |
* If you have access to global variables, you may want to wrap this |
- * in your own VbNvClose() function which calls VbNvTeardown(), writes |
- * the underlying storage if context.raw_changed, releases the lock |
- * acquired in VbNvOpen, and frees the context. */ |
+ * in your own VbNvClose() function. */ |
int VbNvTeardown(VbNvContext* context); |
/* Read a NV storage parameter into *dest. Returns 0 if success, |
- * non-zero if error. */ |
+ * 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. */ |
+ * non-zero if error. |
+ * |
+ * This may only be called between VbNvSetup() and VbNvTeardown(). */ |
int VbNvSet(VbNvContext* context, VbNvParam param, uint32_t value); |