github.com/meulengracht/snapd@v0.0.0-20210719210640-8bde69bcc84e/include/lk/snappy_boot_v2.h (about) 1 /** 2 * Copyright (C) 2020 Canonical Ltd 3 * 4 * This program is free software: you can redistribute it and/or modify 5 * it under the terms of the GNU General Public License version 3 as 6 * published by the Free Software Foundation. 7 * 8 * This program is distributed in the hope that it will be useful, 9 * but WITHOUT ANY WARRANTY; without even the implied warranty of 10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 11 * GNU General Public License for more details. 12 * 13 * You should have received a copy of the GNU General Public License 14 * along with this program. If not, see <http://www.gnu.org/licenses/>. 15 * 16 */ 17 18 #include "snappy_boot_common.h" 19 20 #ifndef _BOOTLOADER_SNAP_BOOT_V2_H 21 #define _BOOTLOADER_SNAP_BOOT_V2_H 22 23 #define SNAP_BOOTSELECT_VERSION_V2 0x00010010 24 #define SNAP_BOOTSELECT_SIGNATURE_RECOVERY ('S' | ('R' << 8) | ('s' << 16) | ('e' << 24)) 25 26 /* snappy bootselect partition format structure for run mode */ 27 typedef struct SNAP_RUN_BOOT_SELECTION { 28 /* Should always contain value of SNAP_BOOTSELECT_SIGNATURE_RUN defined in common.h */ 29 uint32_t signature; 30 /* Should always contain value of SNAP_BOOTSELECT_VERSION_V2 */ 31 uint32_t version; 32 33 /* kernel_status, one of: 'empty', "try", "trying" */ 34 char kernel_status[SNAP_NAME_MAX_LEN]; 35 /* current kernel snap revision */ 36 char snap_kernel[SNAP_NAME_MAX_LEN]; 37 /* current try kernel snap revision */ 38 char snap_try_kernel[SNAP_NAME_MAX_LEN]; 39 40 /* gadget_mode, one of: 'empty', "try", "trying" */ 41 char gadget_mode[SNAP_NAME_MAX_LEN]; 42 /* GADGET assets: current gadget assets revision */ 43 char snap_gadget[SNAP_NAME_MAX_LEN]; 44 /* GADGET assets: try gadget assets revision */ 45 char snap_try_gadget[SNAP_NAME_MAX_LEN]; 46 47 /** 48 * Matrix for mapping of run mode boot img partition to installed kernel 49 * snap revision 50 * 51 * First column represents boot image partition label (e.g. boot_a,boot_b ) 52 * value are static and should be populated at gadget built time 53 * or latest at image build time. Values are not further altered at run 54 * time. 55 * Second column represents name currently installed kernel snap 56 * e.g. pi2-kernel_123.snap 57 * initial value representing initial kernel snap revision 58 * is populated at image build time by snapd 59 * 60 * There are two rows in the matrix, representing current and previous 61 * kernel revision 62 * The following describes how this matrix should be modified at different 63 * stages: 64 * - snapd in install mode: 65 * - extracted kernel snap revision name should be filled 66 * into free slot (first row, second row) 67 * - snapd in run mode: 68 * - when new kernel snap revision is being installed, snapd cycles 69 * through matrix to find unused 'boot slot' to be used for new kernel 70 * snap revision from free slot, first column represents partition 71 * label to which kernel snap boot image should be extracted. Second 72 * column is then populated with kernel snap revision name. 73 * - kernel_status, snap_try_kernel, snap_try_core behaves same way as 74 * with u-boot 75 * - bootloader: 76 * - bootloader reads kernel_status to determine if snap_kernel or 77 * snap_try_kernel is used to get kernel snap revision name. 78 * kernel snap revision is then used to search matrix to determine 79 * partition label to be used for current boot 80 * - bootloader NEVER alters this matrix values 81 * 82 * [ <bootimg 1 part label> ] [ <kernel snap revision installed in this boot partition> ] 83 * [ <bootimg 2 part label> ] [ <kernel snap revision installed in this boot partition> ] 84 */ 85 char bootimg_matrix[SNAP_RUN_BOOTIMG_PART_NUM][2][SNAP_NAME_MAX_LEN]; 86 87 /* name of the boot image from kernel snap to be used for extraction 88 when not defined or empty, default boot.img will be used */ 89 char bootimg_file_name[SNAP_NAME_MAX_LEN]; 90 91 /** 92 * gadget assets: Matrix for mapping of gadget asset partitions 93 * Optional boot asset tracking, based on bootloader support 94 * Some boot chains support A/B boot assets for increased robustness 95 * example being A/B TrustExecutionEnvironment 96 * This matrix can be used to track current and try boot assets for 97 * robust updates 98 * Use of Gadget_asset_matrix matches use of Bootimg_matrix 99 * 100 * [ <boot assets 1 part label> ] [ <currently installed assets revision in this partition> ] 101 * [ <boot assets 2 part label> ] [ <currently installed assets revision in this partition> ] 102 */ 103 char gadget_asset_matrix[SNAP_RUN_BOOTIMG_PART_NUM][2][SNAP_NAME_MAX_LEN]; 104 105 /* unused placeholders for additional parameters to be used in the future */ 106 char unused_key_01[SNAP_NAME_MAX_LEN]; 107 char unused_key_02[SNAP_NAME_MAX_LEN]; 108 char unused_key_03[SNAP_NAME_MAX_LEN]; 109 char unused_key_04[SNAP_NAME_MAX_LEN]; 110 char unused_key_05[SNAP_NAME_MAX_LEN]; 111 char unused_key_06[SNAP_NAME_MAX_LEN]; 112 char unused_key_07[SNAP_NAME_MAX_LEN]; 113 char unused_key_08[SNAP_NAME_MAX_LEN]; 114 char unused_key_09[SNAP_NAME_MAX_LEN]; 115 char unused_key_10[SNAP_NAME_MAX_LEN]; 116 char unused_key_11[SNAP_NAME_MAX_LEN]; 117 char unused_key_12[SNAP_NAME_MAX_LEN]; 118 char unused_key_13[SNAP_NAME_MAX_LEN]; 119 char unused_key_14[SNAP_NAME_MAX_LEN]; 120 char unused_key_15[SNAP_NAME_MAX_LEN]; 121 char unused_key_16[SNAP_NAME_MAX_LEN]; 122 char unused_key_17[SNAP_NAME_MAX_LEN]; 123 char unused_key_18[SNAP_NAME_MAX_LEN]; 124 char unused_key_19[SNAP_NAME_MAX_LEN]; 125 char unused_key_20[SNAP_NAME_MAX_LEN]; 126 127 /* unused array of 10 key - value pairs */ 128 char key_value_pairs[10][2][SNAP_NAME_MAX_LEN]; 129 130 /* crc32 value for structure */ 131 uint32_t crc32; 132 } SNAP_RUN_BOOT_SELECTION_t; 133 134 /* snappy bootselect partition format structure for recovery*/ 135 typedef struct SNAP_RECOVERY_BOOT_SELECTION { 136 /* Should always contain value of SNAP_BOOTSELECT_SIGNATURE_RECOVERY defined above */ 137 uint32_t signature; 138 /* Should always contain value of SNAP_BOOTSELECT_VERSION_V2 */ 139 uint32_t version; 140 141 /** snapd_recovery_mode is what mode the system will be booted in, one of 142 * "install", "recover" or "run" 143 */ 144 char snapd_recovery_mode[SNAP_NAME_MAX_LEN]; 145 146 /** snapd_recovery_system defines the recovery system label to be used when 147 * booting the system, it must be defined to one of the values in the 148 * bootimg matrix below 149 */ 150 char snapd_recovery_system[SNAP_NAME_MAX_LEN]; 151 152 /** 153 * Matrix for mapping of recovery system boot img partition to kernel snap 154 * revisions for those recovery systems 155 * 156 * First column represents boot image partition label (e.g. recov_a, recov_a) 157 * value are static and should be populated at gadget build time 158 * or latest at image build time. Values are not further altered at run 159 * time. 160 * Second column represents the name of the currently installed recovery 161 * system label there - note that every recovery system has only one 162 * kernel for it, so this is in effect a proxy for the kernel revision 163 * 164 * The initial value representing initial single recovery system is 165 * populated at image build time by snapd 166 * 167 * There are SNAP_RECOVERY_BOOTIMG_PART_NUM rows in the matrix, representing 168 * all possible recovery systems on the image. 169 * The following describes how this matrix should be modified at different 170 * stages: 171 * - at image build time: 172 * - default recovery system label should be filled into free slot 173 * (first row, second column) 174 * - snapd: 175 * - when new recovery system is being created, snapd cycles 176 * through matrix to find unused 'boot slot' to be used for new 177 * recovery system from free slot, first column represents partition 178 * label to which kernel snap boot image should be extracted. Second 179 * column is then populated recovery system label. 180 * - snapd_recovery_mode and snapd_recovery_system are written/used 181 * normally when transitioning to/from recover/install/run modes 182 * - bootloader: 183 * - bootloader reads snapd_recovery_system to determine what label 184 * should be searched for in the matrix, then finds the corresponding 185 * partition label for the kernel snap from that recovery system. Then 186 * snapd_recovery_mode is read and both variables are put onto the 187 * kernel commandline when booting the linux kernel 188 * - bootloader NEVER alters this matrix values 189 * 190 * [ <bootimg 1 part label> ] [ <kernel snap revision installed in this boot partition> ] 191 * [ <bootimg 2 part label> ] [ <kernel snap revision installed in this boot partition> ] 192 */ 193 char bootimg_matrix[SNAP_RECOVERY_BOOTIMG_PART_NUM][2][SNAP_NAME_MAX_LEN]; 194 195 /* name of the boot image from kernel snap to be used for extraction 196 when not defined or empty, default boot.img will be used */ 197 char bootimg_file_name[SNAP_NAME_MAX_LEN]; 198 199 /** try_recovery_system contains the label of a recovery system to be 200 * tried. This entry is completely transparent to the bootloader and is 201 * only modified by snapd or snap-bootstrap. 202 */ 203 char try_recovery_system[SNAP_NAME_MAX_LEN]; 204 205 /** recovery_system_status contains the status of a tried recovery 206 * systems, which is one of "", "try", "tried". This entry is completely 207 * transparent to the bootloader and is only modified by snapd or 208 * snap-bootstrap 209 */ 210 char recovery_system_status[SNAP_NAME_MAX_LEN]; 211 212 /* unused placeholders for additional parameters to be used in the future */ 213 char unused_key_01[SNAP_NAME_MAX_LEN]; 214 char unused_key_02[SNAP_NAME_MAX_LEN]; 215 char unused_key_03[SNAP_NAME_MAX_LEN]; 216 char unused_key_04[SNAP_NAME_MAX_LEN]; 217 char unused_key_05[SNAP_NAME_MAX_LEN]; 218 char unused_key_06[SNAP_NAME_MAX_LEN]; 219 char unused_key_07[SNAP_NAME_MAX_LEN]; 220 char unused_key_08[SNAP_NAME_MAX_LEN]; 221 char unused_key_09[SNAP_NAME_MAX_LEN]; 222 char unused_key_10[SNAP_NAME_MAX_LEN]; 223 char unused_key_11[SNAP_NAME_MAX_LEN]; 224 char unused_key_12[SNAP_NAME_MAX_LEN]; 225 char unused_key_13[SNAP_NAME_MAX_LEN]; 226 char unused_key_14[SNAP_NAME_MAX_LEN]; 227 char unused_key_15[SNAP_NAME_MAX_LEN]; 228 char unused_key_16[SNAP_NAME_MAX_LEN]; 229 char unused_key_17[SNAP_NAME_MAX_LEN]; 230 char unused_key_18[SNAP_NAME_MAX_LEN]; 231 232 /* unused array of 10 key - value pairs */ 233 char key_value_pairs[10][2][SNAP_NAME_MAX_LEN]; 234 235 /* crc32 value for structure */ 236 uint32_t crc32; 237 } SNAP_RECOVERY_BOOT_SELECTION_t; 238 239 #endif // _BOOTLOADER_SNAP_BOOT_V2_H