efivarfs

package
v0.0.0-...-8d377ce Latest Latest
Warning

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

Go to latest
Published: Mar 29, 2024 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Overview

Package efivarfs provides functions to read and manipulate UEFI runtime variables. It uses Linux's efivarfs [1] to access the variables and all functions generally require that this is mounted at "/sys/firmware/efi/efivars".

[1] https://www.kernel.org/doc/html/latest/filesystems/efivarfs.html

Index

Constants

View Source
const (
	Path = "/sys/firmware/efi/efivars"
)

Variables

View Source
var (
	// ScopeGlobal is the scope of variables defined by the EFI specification
	// itself.
	ScopeGlobal = uuid.MustParse("8be4df61-93ca-11d2-aa0d-00e098032b8c")
	// ScopeSystemd is the scope of variables defined by Systemd/bootspec.
	ScopeSystemd = uuid.MustParse("4a67b082-0a4c-41cf-b6c7-440b29bb8c4f")
)

Encoding defines the Unicode encoding used by UEFI, which is UCS-2 Little Endian. For BMP characters UTF-16 is equivalent to UCS-2. See the UEFI Spec 2.9, Sections 33.2.6 and 1.8.1.

Functions

func AddBootEntry

func AddBootEntry(be *LoadOption) (int, error)

AddBootEntry creates an new EFI boot entry variable and returns its non-negative index on success.

func Delete

func Delete(scope uuid.UUID, varName string) error

Delete deletes the given variable name in the given scope. Use with care, some firmware fails to boot if variables it uses are deleted.

func DeleteBootEntry

func DeleteBootEntry(idx int) error

DeleteBootEntry deletes the boot entry at the given index.

func List

func List(scope uuid.UUID) ([]string, error)

List lists all variable names present for a given scope sorted by their names in Go's "native" string sort order.

func ReadLoaderDevicePartUUID

func ReadLoaderDevicePartUUID() (uuid.UUID, error)

ReadLoaderDevicePartUUID reads the ESP UUID from an EFI variable.

func SetBootEntry

func SetBootEntry(idx int, be *LoadOption) error

SetBootEntry writes the given boot entry to the given index.

func SetBootNext

func SetBootNext(entryIdx uint16) error

SetBootNext sets the boot entry used for the next boot only. It automatically resets after the next boot.

func SetBootOrder

func SetBootOrder(ord BootOrder) error

SetBootOrder replaces contents of the boot order variable with the order specified in ord.

func Write

func Write(scope uuid.UUID, varName string, attrs Attribute, value []byte) error

Write writes the value of the named variable in the given scope.

Types

type Attribute

type Attribute uint32

Attribute contains a bitset of EFI variable attributes.

const (
	// If set the value of the variable is is persistent across resets and
	// power cycles. Variables without this set cannot be created or modified
	// after UEFI boot services are terminated.
	AttrNonVolatile Attribute = 1 << iota
	// If set allows access to this variable from UEFI boot services.
	AttrBootserviceAccess
	// If set allows access to this variable from an operating system after
	// UEFI boot services are terminated. Variables setting this must also
	// set AttrBootserviceAccess. This is automatically taken care of by Write
	// in this package.
	AttrRuntimeAccess
	// Marks a variable as being a hardware error record. See UEFI 2.10 section
	// 8.2.8 for more information about this.
	AttrHardwareErrorRecord
	// Deprecated, should not be used for new variables.
	AttrAuthenticatedWriteAccess
	// Variable requires special authentication to write. These variables
	// cannot be written with this package.
	AttrTimeBasedAuthenticatedWriteAccess
	// If set in a Write() call, tries to append the data instead of replacing
	// it completely.
	AttrAppendWrite
	// Variable requires special authentication to access and write. These
	// variables cannot be accessed with this package.
	AttrEnhancedAuthenticatedAccess
)

func Read

func Read(scope uuid.UUID, varName string) ([]byte, Attribute, error)

Read reads the value of the named variable in the given scope.

type BootOrder

type BootOrder []uint16

BootOrder represents the contents of the BootOrder EFI variable.

func GetBootOrder

func GetBootOrder() (BootOrder, error)

GetBootOrder returns the current boot order of the system.

func UnmarshalBootOrder

func UnmarshalBootOrder(d []byte) (BootOrder, error)

UnmarshalBootOrder loads a BootOrder from its binary representation.

func (*BootOrder) Marshal

func (t *BootOrder) Marshal() []byte

Marshal generates the binary representation of a BootOrder.

type DevicePath

type DevicePath []DevicePathElem

DevicePath represents a path consisting of one or more elements to an entity implementing an EFI protocol. It's very broadly used inside EFI for representing all sorts of abstract paths. In the context of this package it is used to represent paths to EFI loaders. See https://uefi.org/specs/UEFI/2.10/10_Protocols_Device_Path_Protocol.html for more information.

func UnmarshalDevicePath

func UnmarshalDevicePath(data []byte) (DevicePath, []byte, error)

UnmarshalDevicePath parses a binary device path until it encounters an end device path structure. It returns that device path (excluding the final end device path marker) as well as all all data following the end marker.

func (DevicePath) Marshal

func (d DevicePath) Marshal() ([]byte, error)

Marshal encodes the device path in binary form.

type DevicePathElem

type DevicePathElem interface {
	// contains filtered or unexported methods
}

DevicePathElem is a common interface for all UEFI device path elements.

type FilePath

type FilePath string

FilePath contains a backslash-separated path or part of a path to a file on a filesystem.

type HardDrivePath

type HardDrivePath struct {
	// Partition number, starting at 1. If zero or unset, the whole drive is
	// selected.
	PartitionNumber uint32
	// Block address at which the partition starts. Not used for matching
	// partitions in EDK2.
	PartitionStartBlock uint64
	// Number of blocks occupied by the partition starting from the
	// PartitionStartBlock. Not used for matching partitions in EDK2.
	PartitionSizeBlocks uint64
	// PartitionMatch is used to match drive or partition signatures.
	// Use PartitionMBR and PartitionGPT types here.
	PartitionMatch PartitionMatch
}

HardDrivePath matches whole drives or partitions on GPT/MBR formatted drives.

type LoadOption

type LoadOption struct {
	// Human-readable description of what this load option loads.
	// This is what's being shown by the firmware when selecting a boot option.
	Description string
	// If set, firmware will skip this load option when it is in BootOrder.
	// It is unspecificed whether this prevents the user from booting the entry
	// manually.
	Inactive bool
	// If set, this load option will not be shown in any menu for load option
	// selection. This does not affect other functionality.
	Hidden bool
	// Category contains the category of the load entry. The selected category
	// affects various firmware behaviors, see the individual value
	// descriptions for more information.
	Category LoadOptionCategory
	// Path to the UEFI PE executable to execute when this load option is being
	// loaded.
	FilePath DevicePath
	// ExtraPaths contains additional device paths with vendor-specific
	// behavior. Can generally be left empty.
	ExtraPaths []DevicePath
	// OptionalData gets passed as an argument to the executed PE executable.
	// If zero-length a NULL value is passed to the executable.
	OptionalData []byte
}

LoadOption contains information on a payload to be loaded by EFI.

func GetBootEntry

func GetBootEntry(idx int) (*LoadOption, error)

GetBootEntry returns the boot entry at the given index.

func UnmarshalLoadOption

func UnmarshalLoadOption(data []byte) (*LoadOption, error)

UnmarshalLoadOption decodes a binary EFI_LOAD_OPTION into a LoadOption.

func (*LoadOption) Marshal

func (e *LoadOption) Marshal() ([]byte, error)

Marshal encodes a LoadOption into a binary EFI_LOAD_OPTION.

type LoadOptionCategory

type LoadOptionCategory uint8
const (
	// Boot entries belonging to the Boot category are normal boot entries.
	LoadOptionCategoryBoot LoadOptionCategory = 0x0
	// Boot entries belonging to the App category are not booted as part of
	// the normal boot order, but are only launched via menu or hotkey.
	// This category is optional for bootloaders to support, before creating
	// new boot entries of this category firmware support needs to be
	// confirmed.
	LoadOptionCategoryApp LoadOptionCategory = 0x1
)

type PartitionGPT

type PartitionGPT struct {
	// UUID of the partition to be matched. Conversion into mixed-endian format
	// is taken care of, a standard big-endian UUID can be put in here.
	PartitionUUID uuid.UUID
}

PartitionGPT matches a partition on a drive formatted with GPT.

type PartitionMBR

type PartitionMBR struct {
	// DiskSignature contains a 4-byte signature identifying the drive, located
	// just after the 440 bytes of boot sector loading code.
	// Note that since MBR does not have per-partition signatures, this is
	// combined with PartitionNumber to select a partition.
	DiskSignature [4]byte
}

PartitionMBR matches a drive or partition formatted with legacy MBR (Master Boot Record).

type PartitionMatch

type PartitionMatch interface {
	// contains filtered or unexported methods
}

type PartitionUnknown

type PartitionUnknown struct {
	PartitionSignature [16]byte
	PartitionFormat    uint8
	SignatureType      uint8
}

PartitionUnknown is being used to represent unknown partitioning schemas or combinations of PartitionFormat/SignatureType. It contains raw uninterpreted data.

type UnknownPath

type UnknownPath struct {
	TypeVal    uint8
	SubTypeVal uint8
	DataVal    []byte
}

UnknownPath is a generic structure for all types of path elements not understood by this library. The UEFI-specified set of path element types is vast and mostly unused, this generic type allows for parsing as well as pass-through of not-understood path elements.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL