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
- Variables
- func AddBootEntry(be *LoadOption) (int, error)
- func ClearOSIndications(i OSIndications) error
- func Delete(scope uuid.UUID, varName string) error
- func DeleteBootEntry(idx int) error
- func List(scope uuid.UUID) ([]string, error)
- func ReadLoaderDevicePartUUID() (uuid.UUID, error)
- func SetBootEntry(idx int, be *LoadOption) error
- func SetBootNext(entryIdx uint16) error
- func SetBootOrder(ord BootOrder) error
- func SetOSIndications(i OSIndications) error
- func Write(scope uuid.UUID, varName string, attrs Attribute, value []byte) error
- type Attribute
- type BootOrder
- type DevicePath
- type DevicePathElem
- type FilePath
- type HardDrivePath
- type LoadOption
- type LoadOptionCategory
- type OSIndications
- type PartitionGPT
- type PartitionMBR
- type PartitionMatch
- type PartitionUnknown
- type UnknownPath
Constants ¶
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 )
const (
Path = "/sys/firmware/efi/efivars"
)
Variables ¶
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") )
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 ¶
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 ¶
DeleteBootEntry deletes the boot entry at the given index.
func List ¶
List lists all variable names present for a given scope sorted by their names in Go's "native" string sort order.
func ReadLoaderDevicePartUUID ¶
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 ¶
SetBootNext sets the boot entry used for the next boot only. It automatically resets after the next boot.
func SetBootOrder ¶
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.
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 )
type BootOrder ¶
type BootOrder []uint16
BootOrder represents the contents of the BootOrder EFI variable.
func GetBootOrder ¶
GetBootOrder returns the current boot order of the system.
func UnmarshalBootOrder ¶
UnmarshalBootOrder loads a BootOrder from its binary representation.
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 ¶
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.