lkenv

package
v0.0.0-...-2fb355d Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 18, 2021 License: GPL-3.0 Imports: 9 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	SNAP_BOOTSELECT_VERSION_V1 = 0x00010001
	SNAP_BOOTSELECT_VERSION_V2 = 0x00010010
)
View Source 
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

View Source 
const BOOTIMG_DEFAULT_NAME = "boot.img"

Default boot image file name to be used from kernel snap

View Source 
const SNAP_BOOTIMG_PART_NUM = 2

SNAP_BOOTIMG_PART_NUM is the number of available boot image partitions

View Source 
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)

View Source 
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)

View Source 
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.

View Source 
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
View Source 
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 

func NewEnv(path, backupPath string, version Version) *Env

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 

func (l *Env) FindFreeKernelBootPartition(kernel string) (string, error)

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 

func (l *Env) FindFreeRecoverySystemBootPartition(recoverySystem string) (string, error)

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 

func (l *Env) Get(key string) string

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 

func (l *Env) GetBootImageName() string

GetBootImageName return expected boot image file name in kernel snap. If unset, it will return the default boot.img name.

func (*Env) GetKernelBootPartition 

func (l *Env) GetKernelBootPartition(kernel string) (string, error)

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 

func (l *Env) GetRecoverySystemBootPartition(recoverySystem string) (string, error)

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 

func (l *Env) InitializeBootPartitions(bootPartLabels ...string) error

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 

func (l *Env) Load() error

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 

func (l *Env) LoadEnv(path string) error

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 

func (l *Env) RemoveKernelFromBootPartition(kernel string) error

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 

func (l *Env) RemoveRecoverySystemFromBootPartition(recoverySystem string) error

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 

func (l *Env) Save() error

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 

func (l *Env) Set(key, value string)

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 

func (l *Env) SetBootPartitionKernel(bootpart, kernel string) error

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 

func (l *Env) SetBootPartitionRecoverySystem(bootpart, recoverySystem string) error

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

	/* 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 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
}

type Version 

type Version int
const (
	V1 Version = iota
	V2Run
	V2Recovery
)

func (Version) Number 

func (v Version) Number() uint32

Number returns the Version of the lkenv version as it is encoded in the

func (Version) Signature 

func (v Version) Signature() uint32

Signature returns the Signature of the lkenv version.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.