vboot_nvstorage.h revision 7adcc60e6f5f6db081b9ad6e02288335502a0d77 
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  /* Verified boot API function which should generate a test error, if
51   * error number (below) is non-zero. */
52  VBNV_TEST_ERROR_FUNC,
53  /* Verified boot API error to generate for the function, if non-zero. */
54  VBNV_TEST_ERROR_NUM,
55} VbNvParam;
56
57
58/* Recovery reason codes for VBNV_RECOVERY_REQUEST */
59/* Recovery not requested. */
60#define VBNV_RECOVERY_NOT_REQUESTED   0x00
61/* Recovery requested from legacy utility.  (Prior to the NV storage
62 * spec, recovery mode was a single bitfield; this value is reserved
63 * so that scripts which wrote 1 to the recovery field are
64 * distinguishable from scripts whch use the recovery reasons listed
65 * here. */
66#define VBNV_RECOVERY_LEGACY          0x01
67/* User manually requested recovery via recovery button */
68#define VBNV_RECOVERY_RO_MANUAL       0x02
69/* RW firmware failed signature check (neither RW firmware slot was valid) */
70#define VBNV_RECOVERY_RO_INVALID_RW   0x03
71/* S3 resume failed */
72#define VBNV_RECOVERY_RO_S3_RESUME    0x04
73/* TPM error in read-only firmware */
74#define VBNV_RECOVERY_RO_TPM_ERROR    0x05
75/* Shared data error in read-only firmware */
76#define VBNV_RECOVERY_RO_SHARED_DATA  0x06
77/* Test error from S3Resume() */
78#define VBNV_RECOVERY_RO_TEST_S3      0x07
79/* Test error from LoadFirmwareSetup() */
80#define VBNV_RECOVERY_RO_TEST_LFS     0x08
81/* Test error from LoadFirmware() */
82#define VBNV_RECOVERY_RO_TEST_LF      0x09
83/* RW firmware failed signature check (neither RW firmware slot was valid).
84 * Recovery reason is VBNV_RECOVERY_RO_INVALID_RW_CHECK_MIN + the check value
85 * for the slot which came closest to validating; see VBSD_LF_CHECK_* in
86 * vboot_struct.h. */
87#define VBNV_RECOVERY_RO_INVALID_RW_CHECK_MIN  0x10
88#define VBNV_RECOVERY_RO_INVALID_RW_CHECK_MAX  0x1F
89/* Unspecified/unknown error in read-only firmware */
90#define VBNV_RECOVERY_RO_UNSPECIFIED  0x3F
91/* User manually requested recovery by pressing a key at developer
92 * warning screen */
93#define VBNV_RECOVERY_RW_DEV_SCREEN   0x41
94/* No OS kernel detected */
95#define VBNV_RECOVERY_RW_NO_OS        0x42
96/* OS kernel failed signature check */
97#define VBNV_RECOVERY_RW_INVALID_OS   0x43
98/* TPM error in rewritable firmware */
99#define VBNV_RECOVERY_RW_TPM_ERROR    0x44
100/* RW firmware in dev mode, but dev switch is off */
101#define VBNV_RECOVERY_RW_DEV_MISMATCH 0x45
102/* Shared data error in rewritable firmware */
103#define VBNV_RECOVERY_RW_SHARED_DATA  0x46
104/* Test error from LoadKernel() */
105#define VBNV_RECOVERY_RW_TEST_LK      0x47
106/* No bootable disk found */
107#define VBNV_RECOVERY_RW_NO_DISK      0x48
108/* Unspecified/unknown error in rewritable firmware */
109#define VBNV_RECOVERY_RW_UNSPECIFIED  0x7F
110/* DM-verity error */
111#define VBNV_RECOVERY_KE_DM_VERITY    0x81
112/* Unspecified/unknown error in kernel */
113#define VBNV_RECOVERY_KE_UNSPECIFIED  0xBF
114/* Recovery mode test from user-mode */
115#define VBNV_RECOVERY_US_TEST         0xC1
116/* Unspecified/unknown error in user-mode */
117#define VBNV_RECOVERY_US_UNSPECIFIED  0xFF
118
119
120/* Function codes for VBNV_TEST_ERROR_FUNC */
121#define VBNV_TEST_ERROR_LOAD_FIRMWARE_SETUP  1
122#define VBNV_TEST_ERROR_LOAD_FIRMWARE        2
123#define VBNV_TEST_ERROR_LOAD_KERNEL          3
124#define VBNV_TEST_ERROR_S3_RESUME            4
125
126
127/* Initialize the NV storage library.  This must be called before any
128 * other functions in this library.  Returns 0 if success, non-zero if
129 * error.
130 *
131 * Proper calling procedure:
132 *    1) Allocate a context struct.
133 *    2) If multi-threaded/multi-process, acquire a lock to prevent
134 *       other processes from modifying the underlying storage.
135 *    3) Read underlying storage and fill in context->raw.
136 *    4) Call VbNvSetup().
137 *
138 * If you have access to global variables, you may want to wrap all
139 * that in your own VbNvOpen() function.  We don't do that in here
140 * because there are no global variables in UEFI BIOS during the PEI
141 * phase (that's also why we have to pass around a context pointer). */
142int VbNvSetup(VbNvContext* context);
143
144/* Clean up and flush changes back to the raw data.  This must be
145 * called after other functions in this library.  Returns 0 if
146 * success, non-zero if error.
147 *
148 * Proper calling procedure:
149 *    1) Call VbNvExit().
150 *    2) If context.raw_changed, write data back to underlying storage.
151 *    3) Release any lock you acquired before calling VbNvSetup().
152 *    4) Free the context struct.
153 *
154 * If you have access to global variables, you may want to wrap this
155 * in your own VbNvClose() function. */
156int VbNvTeardown(VbNvContext* context);
157
158/* Read a NV storage parameter into *dest.  Returns 0 if success,
159 * non-zero if error.
160 *
161 * This may only be called between VbNvSetup() and VbNvTeardown(). */
162int VbNvGet(VbNvContext* context, VbNvParam param, uint32_t* dest);
163
164/* Set a NV storage param to a new value.  Returns 0 if success,
165 * non-zero if error.
166 *
167 * This may only be called between VbNvSetup() and VbNvTeardown(). */
168int VbNvSet(VbNvContext* context, VbNvParam param, uint32_t value);
169
170
171#endif  /* VBOOT_REFERENCE_NVSTORAGE_H_ */
172