github.com/hugh712/snapd@v0.0.0-20200910133618-1a99902bd583/include/lk/snappy_boot_v1.h (about)

     1  /**
     2   * Copyright (C) 2019 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  #ifndef _BOOTLOADER_SNAP_BOOT_V1_H
    19  #define _BOOTLOADER_SNAP_BOOT_V1_H
    20  
    21  #define SNAP_BOOTSELECT_VERSION   0x00010001
    22  #define SNAP_BOOTSELECT_SIGNATURE ('S' | ('B' << 8) | ('s' << 16) | ('e' << 24))
    23  #define SNAP_NAME_MAX_LEN (256)
    24  #define HASH_LENGTH (32)
    25  #define SNAP_MODE_TRY "try"
    26  #define SNAP_MODE_TRYING "trying"
    27  #define FACTORY_RESET "factory-reset"
    28  
    29  /* partition label where boot select structure is stored */
    30  #define SNAP_BOOTSELECT_PARTITION "snapbootsel"
    31  
    32  /* number of available bootimg partitions, min 2 */
    33  #define SNAP_BOOTIMG_PART_NUM 2
    34  
    35  /* snappy bootselect partition format structure */
    36  typedef struct SNAP_BOOT_SELECTION {
    37      /* Contains value BOOTSELECT_SIGNATURE defined above */
    38      uint32_t signature;
    39      /* snappy boot select version */
    40      uint32_t version;
    41  
    42      /* snap_mode, one of: 'empty', "try", "trying" */
    43      char snap_mode[SNAP_NAME_MAX_LEN];
    44      /* current core snap revision */
    45      char snap_core[SNAP_NAME_MAX_LEN];
    46      /* try core snap revision */
    47      char snap_try_core[SNAP_NAME_MAX_LEN];
    48      /* current kernel snap revision */
    49      char snap_kernel[SNAP_NAME_MAX_LEN];
    50      /* current kernel snap revision */
    51      char snap_try_kernel[SNAP_NAME_MAX_LEN];
    52  
    53      /* gadget_mode, one of: 'empty', "try", "trying" */
    54      char gadget_mode[SNAP_NAME_MAX_LEN];
    55      /* GADGET assets: current gadget assets revision */
    56      char snap_gadget[SNAP_NAME_MAX_LEN];
    57      /* GADGET assets: try gadget assets revision */
    58      char snap_try_gadget [SNAP_NAME_MAX_LEN];
    59  
    60      /**
    61       * Reboot reason
    62       * optional parameter to signal bootloader alternative reboot reasons
    63       * e.g. recovery/factory-reset/boot asset update
    64       */
    65      char reboot_reason[SNAP_NAME_MAX_LEN];
    66  
    67      /**
    68       * Matrix for mapping of boot img partition to installed kernel snap revision
    69       *
    70       * First column represents boot image partition label (e.g. boot_a,boot_b )
    71       *   value are static and should be populated at gadget built time
    72       *   or latest at image build time. Values are not further altered at run time.
    73       * Second column represents name currently installed kernel snap
    74       *   e.g. pi2-kernel_123.snap
    75       * initial value representing initial kernel snap revision
    76       *   is pupulated at image build time by snapd
    77       *
    78       * There are two rows in the matrix, representing current and previous kernel revision
    79       * following describes how this matrix should be modified at different stages:
    80       *  - at image build time:
    81       *    - extracted kernel snap revision name should be filled
    82       *      into free slow (first row, second row)
    83       *  - snapd:
    84       *    - when new kernel snap revision is being installed, snapd cycles through
    85       *      matrix to find unused 'boot slot' to be used for new kernel snap revision
    86       *      from free slot, first column represents partition label to which kernel
    87       *      snap boot image should be extracted. Second column is then populated with
    88       *      kernel snap revision name.
    89       *    - snap_mode, snap_try_kernel, snap_try_core behaves same way as with u-boot
    90       *  - bootloader:
    91       *    - bootloader reads snap_mode to determine if snap_kernel or snap_kernel is used
    92       *      to get kernel snap revision name
    93       *      kernel snap revision is then used to search matrix to determine
    94       *      partition label to be used for current boot
    95       *    - bootloader NEVER alters this matrix values
    96       *
    97       * [ <bootimg 1 part label> ] [ <kernel snap revision installed in this boot partition> ]
    98       * [ <bootimg 2 part label> ] [ <kernel snap revision installed in this boot partition> ]
    99       */
   100      char bootimg_matrix[SNAP_BOOTIMG_PART_NUM][2][SNAP_NAME_MAX_LEN];
   101  
   102      /* name of the boot image from kernel snap to be used for extraction
   103         when not defined or empty, default boot.img will be used */
   104      char bootimg_file_name[SNAP_NAME_MAX_LEN];
   105  
   106      /**
   107       * gadget assets: Matrix for mapping of gadget asset partitions
   108       * Optional boot asset tracking, based on bootloader support
   109       * Some boot chains support A/B boot assets for increased robustness
   110       * example being A/B TrustExecutionEnvironment
   111       * This matrix can be used to track current and try boot assets for
   112       * robust updates
   113       * Use of Gadget_asset_matrix matches use of Bootimg_matrix
   114       *
   115       * [ <boot assets 1 part label> ] [ <currently installed assets revision in this partition> ]
   116       * [ <boot assets 2 part label> ] [ <currently installed assets revision in this partition> ]
   117       */
   118      char gadget_asset_matrix [SNAP_BOOTIMG_PART_NUM][2][SNAP_NAME_MAX_LEN];
   119  
   120      /* unused placeholders for additional parameters to be used  in the future */
   121      char unused_key_01 [SNAP_NAME_MAX_LEN];
   122      char unused_key_02 [SNAP_NAME_MAX_LEN];
   123      char unused_key_03 [SNAP_NAME_MAX_LEN];
   124      char unused_key_04 [SNAP_NAME_MAX_LEN];
   125      char unused_key_05 [SNAP_NAME_MAX_LEN];
   126      char unused_key_06 [SNAP_NAME_MAX_LEN];
   127      char unused_key_07 [SNAP_NAME_MAX_LEN];
   128      char unused_key_08 [SNAP_NAME_MAX_LEN];
   129      char unused_key_09 [SNAP_NAME_MAX_LEN];
   130      char unused_key_10 [SNAP_NAME_MAX_LEN];
   131      char unused_key_11 [SNAP_NAME_MAX_LEN];
   132      char unused_key_12 [SNAP_NAME_MAX_LEN];
   133      char unused_key_13 [SNAP_NAME_MAX_LEN];
   134      char unused_key_14 [SNAP_NAME_MAX_LEN];
   135      char unused_key_15 [SNAP_NAME_MAX_LEN];
   136      char unused_key_16 [SNAP_NAME_MAX_LEN];
   137      char unused_key_17 [SNAP_NAME_MAX_LEN];
   138      char unused_key_18 [SNAP_NAME_MAX_LEN];
   139      char unused_key_19 [SNAP_NAME_MAX_LEN];
   140      char unused_key_20 [SNAP_NAME_MAX_LEN];
   141  
   142      /* unused array of 10 key - value pairs */
   143      char key_value_pairs [10][2][SNAP_NAME_MAX_LEN];
   144  
   145      /* crc32 value for structure */
   146      uint32_t crc32;
   147  } SNAP_BOOT_SELECTION_t;
   148  
   149  #endif