1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
|
/*
* Copyright (C) 2016 The Android Open Source Project
*
* Permission is hereby granted, free of charge, to any person
* obtaining a copy of this software and associated documentation
* files (the "Software"), to deal in the Software without
* restriction, including without limitation the rights to use, copy,
* modify, merge, publish, distribute, sublicense, and/or sell copies
* of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be
* included in all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
* BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
* ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*/
#if !defined(AVB_INSIDE_LIBAVB_AB_H) && !defined(AVB_COMPILATION)
#error "Never include this file directly, include libavb/libavb_ab.h instead."
#endif
#ifndef AVB_AB_FLOW_H_
#define AVB_AB_FLOW_H_
#include "avb_ab_ops.h"
#ifdef __cplusplus
extern "C" {
#endif
/* Magic for the A/B struct when serialized. */
#define AVB_AB_MAGIC "\0AB0"
#define AVB_AB_MAGIC_LEN 4
/* Versioning for the on-disk A/B metadata - keep in sync with avbtool. */
#define AVB_AB_MAJOR_VERSION 1
#define AVB_AB_MINOR_VERSION 0
/* Size of AvbABData struct. */
#define AVB_AB_DATA_SIZE 32
/* Maximum values for slot data */
#define AVB_AB_MAX_PRIORITY 15
#define AVB_AB_MAX_TRIES_REMAINING 7
/* Struct used for recording per-slot metadata.
*
* When serialized, data is stored in network byte-order.
*/
typedef struct AvbABSlotData {
/* Slot priority. Valid values range from 0 to AVB_AB_MAX_PRIORITY,
* both inclusive with 1 being the lowest and AVB_AB_MAX_PRIORITY
* being the highest. The special value 0 is used to indicate the
* slot is unbootable.
*/
uint8_t priority;
/* Number of times left attempting to boot this slot ranging from 0
* to AVB_AB_MAX_TRIES_REMAINING.
*/
uint8_t tries_remaining;
/* Non-zero if this slot has booted successfully, 0 otherwise. */
uint8_t successful_boot;
/* Reserved for future use. */
uint8_t reserved[1];
} AVB_ATTR_PACKED AvbABSlotData;
/* Struct used for recording A/B metadata.
*
* When serialized, data is stored in network byte-order.
*/
typedef struct AvbABData {
/* Magic number used for identification - see AVB_AB_MAGIC. */
uint8_t magic[AVB_AB_MAGIC_LEN];
/* Version of on-disk struct - see AVB_AB_{MAJOR,MINOR}_VERSION. */
uint8_t version_major;
uint8_t version_minor;
/* Padding to ensure |slots| field start eight bytes in. */
uint8_t reserved1[2];
/* Per-slot metadata. */
AvbABSlotData slots[2];
/* Reserved for future use. */
uint8_t reserved2[12];
/* CRC32 of all 28 bytes preceding this field. */
uint32_t crc32;
} AVB_ATTR_PACKED AvbABData;
/* Copies |src| to |dest|, byte-swapping fields in the
* process. Returns false if the data is invalid (e.g. wrong magic,
* wrong CRC32 etc.), true otherwise.
*/
bool avb_ab_data_verify_and_byteswap(const AvbABData* src, AvbABData* dest);
/* Copies |src| to |dest|, byte-swapping fields in the process. Also
* updates the |crc32| field in |dest|.
*/
void avb_ab_data_update_crc_and_byteswap(const AvbABData* src, AvbABData* dest);
/* Initializes |data| such that it has two slots and both slots have
* maximum tries remaining. The CRC is not set.
*/
void avb_ab_data_init(AvbABData* data);
/* Reads A/B metadata from the 'misc' partition using |ops|. Returned
* data is properly byteswapped. Returns AVB_IO_RESULT_OK on
* success, error code otherwise.
*
* If the data read from disk is invalid (e.g. wrong magic or CRC
* checksum failure), the metadata will be reset using
* avb_ab_data_init() and then written to disk.
*/
AvbIOResult avb_ab_data_read(AvbABOps* ab_ops, AvbABData* data);
/* Writes A/B metadata to the 'misc' partition using |ops|. This will
* byteswap and update the CRC as needed. Returns AVB_IO_RESULT_OK on
* success, error code otherwise.
*/
AvbIOResult avb_ab_data_write(AvbABOps* ab_ops, const AvbABData* data);
/* Return codes used in avb_ab_flow(), see that function for
* documentation of each value.
*/
typedef enum {
AVB_AB_FLOW_RESULT_OK,
AVB_AB_FLOW_RESULT_ERROR_OOM,
AVB_AB_FLOW_RESULT_ERROR_IO,
AVB_AB_FLOW_RESULT_ERROR_NO_BOOTABLE_SLOTS
} AvbABFlowResult;
/* High-level function to select a slot to boot. The following
* algorithm is used:
*
* 1. A/B metadata is loaded and validated using the
* read_ab_metadata() operation. Typically this means it's read from
* the 'misc' partition and if it's invalid then it's reset using
* avb_ab_data_init() and this reset metadata is returned.
*
* 2. All bootable slots listed in the A/B metadata are verified using
* avb_slot_verify(). If a slot fails verification, it will be marked
* as unbootable in the A/B metadata and the metadata will be saved to
* disk before returning.
*
* 3. If there are no bootable slots, the value
* AVB_AB_FLOW_RESULT_ERROR_NO_BOOTABLE_SLOTS is returned.
*
* 4. For each bootable slot, the Stored Rollback Indexes are updated
* such that for each rollback index slot, the Stored Rollback Index
* is the largest number smaller than or equal to the Rollback Index
* of each slot.
*
* 5. The bootable slot with the highest priority is selected and
* returned in |out_data|. If this slot is already marked as
* successful, the A/B metadata is not modified. However, if the slot
* is not marked as bootable its |tries_remaining| count is
* decremented and the A/B metadata is saved to disk before returning.
* In either case the value AVB_AB_FLOW_RESULT_OK is returning.
*
* The partitions to load is given in |requested_partitions| as a
* NULL-terminated array of NUL-terminated strings. Typically the
* |requested_partitions| array only contains a single item for the
* boot partition, 'boot'.
*
* If an I/O operation - such as loading/saving metadata or checking
* rollback indexes - fail, the value AVB_AB_FLOW_RESULT_ERROR_IO is
* returned.
*
* If memory allocation fails, AVB_AB_FLOW_RESULT_ERROR_OOM is
* returned.
*
* Reasonable behavior for handling AVB_AB_FLOW_RESULT_ERROR_NO_BOOTABLE_SLOTS
* is to initiate device recovery (which is device-dependent).
*/
AvbABFlowResult avb_ab_flow(AvbABOps* ab_ops,
const char* const* requested_partitions,
AvbSlotVerifyData** out_data);
/* Marks the slot with the given slot number as active. Returns
* AVB_IO_RESULT_OK on success, error code otherwise.
*
* This function is typically used by the OS updater when completing
* an update. It can also used by the firmware for implementing the
* "set_active" command.
*/
AvbIOResult avb_ab_mark_slot_active(AvbABOps* ab_ops, unsigned int slot_number);
/* Marks the slot with the given slot number as unbootable. Returns
* AVB_IO_RESULT_OK on success, error code otherwise.
*
* This function is typically used by the OS updater before writing to
* a slot.
*/
AvbIOResult avb_ab_mark_slot_unbootable(AvbABOps* ab_ops,
unsigned int slot_number);
/* Marks the slot with the given slot number as having booted
* successfully. Returns AVB_IO_RESULT_OK on success, error code
* otherwise.
*
* Calling this on an unbootable slot is an error - AVB_IO_RESULT_OK
* will be returned yet the function will have no side-effects.
*
* This function is typically used by the OS updater after having
* confirmed that the slot works as intended.
*/
AvbIOResult avb_ab_mark_slot_successful(AvbABOps* ab_ops,
unsigned int slot_number);
#ifdef __cplusplus
}
#endif
#endif /* AVB_AB_FLOW_H_ */
|
