vboot_nvstorage.h revision 640fb51d866e7ac8a92f61a2f69145bfe6b13699 
1/* Copyright (c) 2011 The Chromium OS Authors. All rights reserved.
2 * Use of this source code is governed by a BSD-style license that can be
3 * found in the LICENSE file.
4 */
5
6/* Non-volatile storage routines for verified boot.
7 */
8
9#ifndef VBOOT_REFERENCE_NVSTORAGE_H_
10#define VBOOT_REFERENCE_NVSTORAGE_H_
11
12#define VBNV_BLOCK_SIZE 16  /* Size of NV storage block in bytes */
13
14typedef struct VbNvContext {
15  /* Raw NV data.  Caller must fill this before calling VbNvSetup(). */
16  uint8_t raw[VBNV_BLOCK_SIZE];
17  /* Flag indicating whether raw data has changed.  Set by VbNvTeardown() if
18   * the raw data has changed and needs to be stored to the underlying
19   * non-volatile data store. */
20  int raw_changed;
21
22  /* Internal data for NV storage routines.  Caller should not touch
23   * these fields. */
24  int regenerate_crc;
25
26} VbNvContext;
27
28
29/* Parameter type for VbNvGet(), VbNvSet(). */
30typedef enum VbNvParam {
31  /* Parameter values have been reset to defaults (flag for firmware).
32   * 0=clear; 1=set. */
33  VBNV_FIRMWARE_SETTINGS_RESET = 0,
34  /* Parameter values have been reset to defaults (flag for kernel).
35   * 0=clear; 1=set. */
36  VBNV_KERNEL_SETTINGS_RESET,
37  /* Request debug reset on next S3->S0 transition.  0=clear; 1=set. */
38  VBNV_DEBUG_RESET_MODE,
39  /* Number of times to try booting RW firmware slot B before slot A.
40   * Valid range: 0-15. */
41  VBNV_TRY_B_COUNT,
42  /* Request recovery mode on next boot; see VBNB_RECOVERY_* below for
43   * currently defined reason codes.  8-bit value. */
44  VBNV_RECOVERY_REQUEST,
45  /* Localization index for screen bitmaps displayed by firmware.
46   * 8-bit value. */
47  VBNV_LOCALIZATION_INDEX,
48  /* Field reserved for kernel/user-mode use; 32-bit value. */
49  VBNV_KERNEL_FIELD,
50  /* Firmware checked RW slot B before slot A on the current boot because
51   * VBNV_TRY_B_COUNT was non-zero at that time.  0=no; 1=yes. */
52  VBNV_TRIED_FIRMWARE_B,
53  /* Firmware verified the kernel key block signature using the key stored
54   * in the firmware.  0=no, just used the key block hash; 1=yes, used the
55   * key block signature. */
56  VBNV_FW_VERIFIED_KERNEL_KEY,
57} VbNvParam;
58
59
60/* Recovery reason codes for VBNV_RECOVERY_REQUEST */
61/* Recovery not requested. */
62#define VBNV_RECOVERY_NOT_REQUESTED   0x00
63/* Recovery requested from legacy utility.  (Prior to the NV storage
64 * spec, recovery mode was a single bitfield; this value is reserved
65 * so that scripts which wrote 1 to the recovery field are
66 * distinguishable from scripts whch use the recovery reasons listed
67 * here. */
68#define VBNV_RECOVERY_LEGACY          0x01
69/* User manually requested recovery via recovery button */
70#define VBNV_RECOVERY_RO_MANUAL       0x02
71/* RW firmware failed signature check (neither RW firmware slot was valid) */
72#define VBNV_RECOVERY_RO_INVALID_RW   0x03
73/* S3 resume failed */
74#define VBNV_RECOVERY_RO_S3_RESUME    0x04
75/* TPM error in read-only firmware */
76#define VBNV_RECOVERY_RO_TPM_ERROR    0x05
77/* Unspecified/unknown error in read-only firmware */
78#define VBNV_RECOVERY_RO_UNSPECIFIED  0x3F
79/* User manually requested recovery by pressing a key at developer
80 * warning screen */
81#define VBNV_RECOVERY_RW_DEV_SCREEN   0x41
82/* No OS kernel detected */
83#define VBNV_RECOVERY_RW_NO_OS        0x42
84/* OS kernel failed signature check */
85#define VBNV_RECOVERY_RW_INVALID_OS   0x43
86/* TPM error in rewritable firmware */
87#define VBNV_RECOVERY_RW_TPM_ERROR    0x44
88/* RW firmware in dev mode, but dev switch is off */
89#define VBNV_RECOVERY_RW_DEV_MISMATCH 0x45
90/* Unspecified/unknown error in rewritable firmware */
91#define VBNV_RECOVERY_RW_UNSPECIFIED  0x7F
92/* DM-verity error */
93#define VBNV_RECOVERY_KE_DM_VERITY    0x81
94/* Unspecified/unknown error in kernel */
95#define VBNV_RECOVERY_KE_UNSPECIFIED  0xBF
96/* Recovery mode test from user-mode */
97#define VBNV_RECOVERY_US_TEST         0xC1
98/* Unspecified/unknown error in user-mode */
99#define VBNV_RECOVERY_US_UNSPECIFIED  0xFF
100
101
102/* Initialize the NV storage library.  This must be called before any
103 * other functions in this library.  Returns 0 if success, non-zero if
104 * error.
105 *
106 * Proper calling procedure:
107 *    1) Allocate a context struct.
108 *    2) If multi-threaded/multi-process, acquire a lock to prevent
109 *       other processes from modifying the underlying storage.
110 *    3) Read underlying storage and fill in context->raw.
111 *    4) Call VbNvSetup().
112 *
113 * If you have access to global variables, you may want to wrap all
114 * that in your own VbNvOpen() function.  We don't do that in here
115 * because there are no global variables in UEFI BIOS during the PEI
116 * phase (that's also why we have to pass around a context pointer). */
117int VbNvSetup(VbNvContext* context);
118
119/* Clean up and flush changes back to the raw data.  This must be
120 * called after other functions in this library.  Returns 0 if
121 * success, non-zero if error.
122 *
123 * Proper calling procedure:
124 *    1) Call VbNvExit().
125 *    2) If context.raw_changed, write data back to underlying storage.
126 *    3) Release any lock you acquired before calling VbNvSetup().
127 *    4) Free the context struct.
128 *
129 * If you have access to global variables, you may want to wrap this
130 * in your own VbNvClose() function. */
131int VbNvTeardown(VbNvContext* context);
132
133/* Read a NV storage parameter into *dest.  Returns 0 if success,
134 * non-zero if error.
135 *
136 * This may only be called between VbNvSetup() and VbNvTeardown(). */
137int VbNvGet(VbNvContext* context, VbNvParam param, uint32_t* dest);
138
139/* Set a NV storage param to a new value.  Returns 0 if success,
140 * non-zero if error.
141 *
142 * This may only be called between VbNvSetup() and VbNvTeardown(). */
143int VbNvSet(VbNvContext* context, VbNvParam param, uint32_t value);
144
145
146#endif  /* VBOOT_REFERENCE_NVSTORAGE_H_ */
147