Documentation ¶
Index ¶
- Constants
- type Env
- func (l *Env) FindFreeKernelBootPartition(kernel string) (string, error)
- func (l *Env) FindFreeRecoverySystemBootPartition(recoverySystem string) (string, error)
- func (l *Env) Get(key string) string
- func (l *Env) GetBootImageName() string
- func (l *Env) GetKernelBootPartition(kernel string) (string, error)
- func (l *Env) GetRecoverySystemBootPartition(recoverySystem string) (string, error)
- func (l *Env) InitializeBootPartitions(bootPartLabels ...string) error
- func (l *Env) Load() error
- func (l *Env) LoadEnv(path string) error
- func (l *Env) RemoveKernelFromBootPartition(kernel string) error
- func (l *Env) RemoveRecoverySystemFromBootPartition(recoverySystem string) error
- func (l *Env) Save() error
- func (l *Env) Set(key, value string)
- func (l *Env) SetBootPartitionKernel(bootpart, kernel string) error
- func (l *Env) SetBootPartitionRecoverySystem(bootpart, recoverySystem string) error
- type SnapBootSelect_v1
- type SnapBootSelect_v2_recovery
- type SnapBootSelect_v2_run
- type Version
Constants ¶
const ( SNAP_BOOTSELECT_VERSION_V1 = 0x00010001 SNAP_BOOTSELECT_VERSION_V2 = 0x00010010 )
const ( // the boot image partition label itself MATRIX_ROW_PARTITION = 0 // the value of the boot image partition label mapping (i.e. the kernel // revision or the recovery system label, depending on which specific // matrix is being operated on) MATRIX_ROW_VALUE = 1 )
for accessing the Bootimg_matrix
const BOOTIMG_DEFAULT_NAME = "boot.img"
Default boot image file name to be used from kernel snap
const SNAP_BOOTIMG_PART_NUM = 2
SNAP_BOOTIMG_PART_NUM is the number of available boot image partitions
const SNAP_BOOTSELECT_RECOVERY_SIGNATURE = 0x53 | 0x52<<8 | 0x73<<16 | 0x65<<24
const SNAP_BOOTSELECT_RECOVERY_SIGNATURE ('S' | ('R' << 8) | ('s' << 16) | ('e' << 24)) value comes from S(Snap)R(Recovery)se(select)
const SNAP_BOOTSELECT_SIGNATURE = 0x53 | 0x42<<8 | 0x73<<16 | 0x65<<24
const SNAP_BOOTSELECT_SIGNATURE ('S' | ('B' << 8) | ('s' << 16) | ('e' << 24)) value comes from S(Snap)B(Boot)se(select)
const SNAP_FILE_NAME_MAX_LEN = 256
SNAP_FILE_NAME_MAX_LEN is the maximum size of a C string representing a snap name, such as for a kernel snap revision.
const SNAP_RECOVERY_BOOTIMG_PART_NUM = 10
* maximum number of available bootimg partitions for recovery systems, min 5
- NOTE: the number of actual bootimg partitions usable is determined by the
- gadget, this just sets the upper bound of maximum number of recovery systems
- a gadget could define without needing changes here
const SNAP_RUN_BOOTIMG_PART_NUM = 2
SNAP_RUN_BOOTIMG_PART_NUM is the number of available boot image partitions for uc20 for kernel/try-kernel in run mode
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Env ¶
type Env struct {
// contains filtered or unexported fields
}
Env contains the data of the little kernel environment
func NewEnv ¶
NewEnv creates a new lkenv object referencing the primary bootloader environment file at path with the specified version. If the specified filed is expected to be a valid lkenv object, then the object should be loaded with the Load() method, otherwise the lkenv object can be manipulated in memory and later written to disk with Save().
func (*Env) FindFreeKernelBootPartition ¶
FindFreeKernelBootPartition finds a free boot image partition to be used for a new kernel revision. It ignores the currently installed boot image partition used for the active kernel
func (*Env) FindFreeRecoverySystemBootPartition ¶
FindFreeRecoverySystemBootPartition finds a free recovery system boot image partition to be used for the recovery kernel from the recovery system. It only considers boot image partitions that are currently not set to a recovery system to be free.
func (*Env) Get ¶
Get returns the value of the key from the environment. If the key specified is not supported for the environment, the empty string is returned.
func (*Env) GetBootImageName ¶
GetBootImageName return expected boot image file name in kernel snap. If unset, it will return the default boot.img name.
func (*Env) GetKernelBootPartition ¶
GetKernelBootPartition returns the first found boot image partition label that contains a reference to the given kernel revision. If the revision was not found, a non-nil error is returned.
func (*Env) GetRecoverySystemBootPartition ¶
GetRecoverySystemBootPartition returns the first found boot image partition label that contains a reference to the given recovery system. If the recovery system was not found, a non-nil error is returned.
func (*Env) InitializeBootPartitions ¶
InitializeBootPartitions sets the boot image partition label names. This function should not be used at run time! It should be used only at image build time, if partition labels are not pre-filled by gadget built, currently it is only used inside snapd for tests.
func (*Env) Load ¶
Load will load the lk bootloader environment from it's configured primary environment file, and if that fails it will fallback to trying the backup environment file.
func (*Env) LoadEnv ¶
LoadEnv loads the lk bootloader environment from the specified file. The bootloader environment in the referenced file must be of the same version that the Env object was created with using NewEnv. The returned error may wrap os.ErrNotExist, so instead of using os.IsNotExist, callers should use xerrors.Is(err,os.ErrNotExist) instead.
func (*Env) RemoveKernelFromBootPartition ¶
RemoveKernelFromBootPartition removes from the boot image matrix the first found boot image partition that contains a reference to the given kernel revision. If the referenced kernel revision was not found, a non-nil err is returned, otherwise the reference is removed and nil is returned.
func (*Env) RemoveRecoverySystemFromBootPartition ¶
RemoveRecoverySystemFromBootPartition removes from the boot image matrix the first found boot partition that contains a reference to the given recovery system. If the referenced recovery system was not found, a non-nil err is returned, otherwise the reference is removed and nil is returned.
func (*Env) Save ¶
Save saves the lk bootloader environment to the configured primary environment file, and if the backup environment file exists, the backup too. Save will also update the CRC32 of the environment when writing the file(s).
func (*Env) Set ¶
Set assigns the value to the key in the environment. If the key specified is not supported for the environment, nothing happens.
func (*Env) SetBootPartitionKernel ¶
SetBootPartitionKernel sets the kernel revision reference for the provided boot image partition label. It returns a non-nil err if the provided boot image partition label was not found.
func (*Env) SetBootPartitionRecoverySystem ¶
SetBootPartitionRecoverySystem sets the recovery system reference for the provided boot image partition. It returns a non-nil err if the provided boot partition reference was not found.
type SnapBootSelect_v1 ¶
type SnapBootSelect_v1 struct { /* Contains value BOOTSELECT_SIGNATURE defined above */ Signature uint32 /* snappy boot select version */ Version uint32 /* snap_mode, one of: 'empty', "try", "trying" */ Snap_mode [SNAP_FILE_NAME_MAX_LEN]byte /* current core snap revision */ Snap_core [SNAP_FILE_NAME_MAX_LEN]byte /* try core snap revision */ Snap_try_core [SNAP_FILE_NAME_MAX_LEN]byte /* current kernel snap revision */ Snap_kernel [SNAP_FILE_NAME_MAX_LEN]byte /* current kernel snap revision */ Snap_try_kernel [SNAP_FILE_NAME_MAX_LEN]byte /* gadget_mode, one of: 'empty', "try", "trying" */ Gadget_mode [SNAP_FILE_NAME_MAX_LEN]byte /* GADGET assets: current gadget assets revision */ Snap_gadget [SNAP_FILE_NAME_MAX_LEN]byte /* GADGET assets: try gadget assets revision */ Snap_try_gadget [SNAP_FILE_NAME_MAX_LEN]byte /** * Reboot reason * optional parameter to signal bootloader alternative reboot reasons * e.g. recovery/factory-reset/boot asset update */ Reboot_reason [SNAP_FILE_NAME_MAX_LEN]byte /** * Matrix for mapping of boot img partition to installed kernel snap revision * * First column represents boot image partition label (e.g. boot_a,boot_b ) * value are static and should be populated at gadget built time * or latest at image build time. Values are not further altered at run time. * Second column represents name currently installed kernel snap * e.g. pi2-kernel_123.snap * initial value representing initial kernel snap revision * is populated at image build time by snapd * * There are two rows in the matrix, representing current and previous kernel revision * following describes how this matrix should be modified at different stages: * - at image build time: * - extracted kernel snap revision name should be filled * into free slot (first row, second column) * - snapd: * - when new kernel snap revision is being installed, snapd cycles through * matrix to find unused 'boot slot' to be used for new kernel snap revision * from free slot, first column represents partition label to which kernel * snap boot image should be extracted. Second column is then populated with * kernel snap revision name. * - snap_mode, snap_try_kernel, snap_try_core behaves same way as with u-boot * - bootloader: * - bootloader reads snap_mode to determine if snap_kernel or snap_try_kernel is used * to get kernel snap revision name * kernel snap revision is then used to search matrix to determine * partition label to be used for current boot * - bootloader NEVER alters this matrix values * * [ <bootimg 1 part label> ] [ <kernel snap revision installed in this boot partition> ] * [ <bootimg 2 part label> ] [ <kernel snap revision installed in this boot partition> ] */ Bootimg_matrix [SNAP_BOOTIMG_PART_NUM][2][SNAP_FILE_NAME_MAX_LEN]byte /** * name of the boot image from kernel snap to be used for extraction * when not defined or empty, default boot.img will be used */ Bootimg_file_name [SNAP_FILE_NAME_MAX_LEN]byte /** * gadget assets: Matrix for mapping of gadget asset partitions * Optional boot asset tracking, based on bootloader support * Some boot chains support A/B boot assets for increased robustness * example being A/B TrustExecutionEnvironment * This matrix can be used to track current and try boot assets for * robust updates * Use of Gadget_asset_matrix matches use of Bootimg_matrix * * [ <boot assets 1 part label> ] [ <currently installed assets revision in this partition> ] * [ <boot assets 2 part label> ] [ <currently installed assets revision in this partition> ] */ Gadget_asset_matrix [SNAP_BOOTIMG_PART_NUM][2][SNAP_FILE_NAME_MAX_LEN]byte /* unused placeholders for additional parameters in the future */ Unused_key_01 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_02 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_03 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_04 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_05 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_06 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_07 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_08 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_09 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_10 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_11 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_12 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_13 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_14 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_15 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_16 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_17 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_18 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_19 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_20 [SNAP_FILE_NAME_MAX_LEN]byte /* unused array of 10 key value pairs */ Key_value_pairs [10][2][SNAP_FILE_NAME_MAX_LEN]byte /* crc32 value for structure */ Crc32 uint32 }
*
Following structure has to be kept in sync with c structure defined by
include/lk/snappy-boot_v1.h
c headerfile is used by bootloader, this ensures sync of the environment
between snapd and bootloader
when this structure needs to be updated,
new version should be introduced instead together with c header file,
which is to be adopted by bootloader *
!!! Support for old version has to be maintained, as it is not guaranteed
all existing bootloader would adopt new version!
type SnapBootSelect_v2_recovery ¶
type SnapBootSelect_v2_recovery struct { /* Contains value BOOTSELECT_SIGNATURE defined above */ Signature uint32 /* snappy boot select version */ Version uint32 /** snapd_recovery_mode is what mode the system will be booted in, one of * "install", "recover" or "run" */ Snapd_recovery_mode [SNAP_FILE_NAME_MAX_LEN]byte /** snapd_recovery_system defines the recovery system label to be used when * booting the system, it must be defined to one of the values in the * bootimg matrix below */ Snapd_recovery_system [SNAP_FILE_NAME_MAX_LEN]byte /** * Matrix for mapping of recovery system boot img partition to kernel snap * revisions for those recovery systems * * First column represents boot image partition label (e.g. recov_a, recov_a) * value are static and should be populated at gadget build time * or latest at image build time. Values are not further altered at run * time. * Second column represents the name of the currently installed recovery * system label there - note that every recovery system has only one * kernel for it, so this is in effect a proxy for the kernel revision * * The initial value representing initial single recovery system is * populated at image build time by snapd * * There are SNAP_RECOVERY_BOOTIMG_PART_NUM rows in the matrix, representing * all possible recovery systems on the image. * The following describes how this matrix should be modified at different * stages: * - at image build time: * - default recovery system label should be filled into free slot * (first row, second column) * - snapd: * - when new recovery system is being created, snapd cycles * through matrix to find unused 'boot slot' to be used for new * recovery system from free slot, first column represents partition * label to which kernel snap boot image should be extracted. Second * column is then populated recovery system label. * - snapd_recovery_mode and snapd_recovery_system are written/used * normally when transitioning to/from recover/install/run modes * - bootloader: * - bootloader reads snapd_recovery_system to determine what label * should be searched for in the matrix, then finds the corresponding * partition label for the kernel snap from that recovery system. Then * snapd_recovery_mode is read and both variables are put onto the * kernel commandline when booting the linux kernel * - bootloader NEVER alters this matrix values * * [ <bootimg 1 part label> ] [ <kernel snap revision installed in this boot partition> ] * [ <bootimg 2 part label> ] [ <kernel snap revision installed in this boot partition> ] */ Bootimg_matrix [SNAP_RECOVERY_BOOTIMG_PART_NUM][2][SNAP_FILE_NAME_MAX_LEN]byte /* name of the boot image from kernel snap to be used for extraction when not defined or empty, default boot.img will be used */ Bootimg_file_name [SNAP_FILE_NAME_MAX_LEN]byte /** try_recovery_system contains the label of a recovery system to be * tried. This entry is completely transparent to the bootloader and is * only modified by snapd or snap-bootstrap. */ Try_recovery_system [SNAP_FILE_NAME_MAX_LEN]byte /** recovery_system_status contains the status of a tried recovery * systems, which is one of "", "try", "tried". This entry is completely * transparent to the bootloader and is only modified by snapd or * snap-bootstrap */ Recovery_system_status [SNAP_FILE_NAME_MAX_LEN]byte /** device_lock_state contains the lock state of the device. It is used by the * bootloader to track device lock changes. When lock state changes, device goes * automatically to install mode. This entry is completely transparent * to the snapd and is only modified by bootloader. * Only first char in the array is used (device_lock_state[0]) * Permitted values: * 0: DEVICE_STATE_UNKNOWN: initial value at first boot. * This is changed by the bootloader to reflect actual device state. * 1: DEVICE_STATE_UNLOCKED: unlocked device * 2: DEVICE_STATE_LOCKED: locked device */ Device_lock_state [SNAP_FILE_NAME_MAX_LEN]byte /* unused placeholders for additional parameters in the future */ Unused_key_01 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_02 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_03 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_04 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_05 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_06 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_07 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_08 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_09 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_10 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_11 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_12 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_13 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_14 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_15 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_16 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_17 [SNAP_FILE_NAME_MAX_LEN]byte /* unused array of 10 key value pairs */ Key_value_pairs [10][2][SNAP_FILE_NAME_MAX_LEN]byte /* crc32 value for structure */ Crc32 uint32 }
type SnapBootSelect_v2_run ¶
type SnapBootSelect_v2_run struct { /* Contains value BOOTSELECT_SIGNATURE defined above */ Signature uint32 /* snappy boot select version */ Version uint32 /* kernel_status, one of: 'empty', "try", "trying" */ Kernel_status [SNAP_FILE_NAME_MAX_LEN]byte /* current kernel snap revision */ Snap_kernel [SNAP_FILE_NAME_MAX_LEN]byte /* current try kernel snap revision */ Snap_try_kernel [SNAP_FILE_NAME_MAX_LEN]byte /* gadget_mode, one of: 'empty', "try", "trying" */ Gadget_mode [SNAP_FILE_NAME_MAX_LEN]byte /* GADGET assets: current gadget assets revision */ Snap_gadget [SNAP_FILE_NAME_MAX_LEN]byte /* GADGET assets: try gadget assets revision */ Snap_try_gadget [SNAP_FILE_NAME_MAX_LEN]byte /** * Matrix for mapping of run mode boot img partition to installed kernel * snap revision * * First column represents boot image partition label (e.g. boot_a,boot_b ) * value are static and should be populated at gadget built time * or latest at image build time. Values are not further altered at run * time. * Second column represents name currently installed kernel snap * e.g. pi2-kernel_123.snap * initial value representing initial kernel snap revision * is populated at image build time by snapd * * There are two rows in the matrix, representing current and previous * kernel revision * The following describes how this matrix should be modified at different * stages: * - snapd in install mode: * - extracted kernel snap revision name should be filled * into free slot (first row, second row) * - snapd in run mode: * - when new kernel snap revision is being installed, snapd cycles * through matrix to find unused 'boot slot' to be used for new kernel * snap revision from free slot, first column represents partition * label to which kernel snap boot image should be extracted. Second * column is then populated with kernel snap revision name. * - kernel_status, snap_try_kernel, snap_try_core behaves same way as * with u-boot * - bootloader: * - bootloader reads kernel_status to determine if snap_kernel or * snap_try_kernel is used to get kernel snap revision name. * kernel snap revision is then used to search matrix to determine * partition label to be used for current boot * - bootloader NEVER alters this matrix values * * [ <bootimg 1 part label> ] [ <kernel snap revision installed in this boot partition> ] * [ <bootimg 2 part label> ] [ <kernel snap revision installed in this boot partition> ] */ Bootimg_matrix [SNAP_RUN_BOOTIMG_PART_NUM][2][SNAP_FILE_NAME_MAX_LEN]byte /* name of the boot image from kernel snap to be used for extraction when not defined or empty, default boot.img will be used */ Bootimg_file_name [SNAP_FILE_NAME_MAX_LEN]byte /** * gadget assets: Matrix for mapping of gadget asset partitions * Optional boot asset tracking, based on bootloader support * Some boot chains support A/B boot assets for increased robustness * example being A/B TrustExecutionEnvironment * This matrix can be used to track current and try boot assets for * robust updates * Use of Gadget_asset_matrix matches use of Bootimg_matrix * * [ <boot assets 1 part label> ] [ <currently installed assets revision in this partition> ] * [ <boot assets 2 part label> ] [ <currently installed assets revision in this partition> ] */ Gadget_asset_matrix [SNAP_RUN_BOOTIMG_PART_NUM][2][SNAP_FILE_NAME_MAX_LEN]byte /* unused placeholders for additional parameters in the future */ Unused_key_01 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_02 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_03 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_04 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_05 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_06 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_07 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_08 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_09 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_10 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_11 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_12 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_13 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_14 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_15 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_16 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_17 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_18 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_19 [SNAP_FILE_NAME_MAX_LEN]byte Unused_key_20 [SNAP_FILE_NAME_MAX_LEN]byte /* unused array of 10 key value pairs */ Key_value_pairs [10][2][SNAP_FILE_NAME_MAX_LEN]byte /* crc32 value for structure */ Crc32 uint32 }