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