efivarfs

package
v0.0.0-...-5fb8a3f Latest Latest
Warning

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

 Go to latest Published: Sep 30, 2024 License: Apache-2.0 Imports: 14 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 (
	// Indicates that on next boot firmware should boot to a firmware-provided
	// UI instead of the normal boot order.
	BootToFirmwareUI = OSIndications(1 << iota)
	// Indicates that firmware supports timestamp-based revocation and the
	// "dbt" authorized timestamp database variable.
	TimestampRevocationSupported
	// Indicates that on next boot firmware should look for an EFI update
	// capsule on an EFI system partition and try to install it.
	FileCapsuleDelivery
	// Indicates that firmware supports UEFI FMP update capsules.
	FirmwareManagementProtocolCapsuleSupported
	// Indicates that firmware supports reporting results of deferred (i.e.
	// processed on next boot) capsule installs via variables.
	CapsuleResultVarSupported
	// Indicates that firmware should skip Boot# processing on next boot
	// and instead use OsRecovery# for selecting a load option.
	StartOSRecovery
	// Indicates that firmware should skip Boot# processing on next boot
	// and instead use PlatformRecovery# for selecting a load option.
	StartPlatformRecovery
	// Indicates that firmware should collect the current config and report
	// the data to the EFI system configuration table on next boot.
	JSONConfigDataRefresh
)
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")
)
View Source 
var Encoding = unicode.UTF16(unicode.LittleEndian, unicode.IgnoreBOM)

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 ClearOSIndications 

func ClearOSIndications(i OSIndications) error

ClearOSIndications clears all OS indication bits set in i in firmware. Note that this effectively inverts i, bits set in i will be cleared.

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 SetOSIndications 

func SetOSIndications(i OSIndications) error

SetOSIndications sets all OS indication bits set in i in firmware. It does not clear any already-set bits, use ClearOSIndications for that.

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 OSIndications 

type OSIndications uint64

OSIndications is a bitset used to indicate firmware support for various features as well as to trigger some of these features. If a constant ends in Supported, it cannot be triggered, the others can be.

func OSIndicationsSupported 

func OSIndicationsSupported() (OSIndications, error)

OSIndicationsSupported indicates which of the OS indication features and actions that the firmware supports.

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.

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.