uefi

package
v1.2.0 Latest Latest
Warning

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

 Go to latest Published: May 11, 2023 License: BSD-3-Clause Imports: 16 Imported by: 41

Documentation

Overview

Package uefi contents data types for the components found in UEFI and an Parse function for reading an image.

Index

Constants

View Source 
const (
	// FileHeaderMinLength is the minimum length of a firmware file header.
	FileHeaderMinLength = 0x18
	// FileHeaderExtMinLength is the minimum length of an extended firmware file header.
	FileHeaderExtMinLength = 0x20
	// EmptyBodyChecksum is the value placed in the File IntegrityCheck field if the body checksum bit isn't set.
	EmptyBodyChecksum uint8 = 0xAA
)
View Source 
const (
	FirmwareVolumeFixedHeaderSize  = 56
	FirmwareVolumeMinSize          = FirmwareVolumeFixedHeaderSize + 8 // +8 for the null block that terminates the block list
	FirmwareVolumeExtHeaderMinSize = 20
)

FirmwareVolume constants

View Source 
const (
	// FlashDescriptorMapMaxBase is the maximum base address for a flash descriptor
	// region
	FlashDescriptorMapMaxBase = 0xe0

	// FlashDescriptorMapSize is the size in byte of the FlashDescriptorMap
	FlashDescriptorMapSize = 16
)
View Source 
const (
	// MEPartitionDescriptorMinLength is the min size of the descriptor
	MEPartitionDescriptorMinLength = 28
	// MEPartitionTableEntryLength is the size of a partition table entry
	MEPartitionTableEntryLength = 32
)
View Source 
const (
	// SectionMinLength is the minimum length of a file section header.
	SectionMinLength = 0x04
	// SectionExtMinLength is the minimum length of an extended file section header.
	SectionExtMinLength = 0x08
)
View Source 
const (
	// FlashDescriptorLength represents the size of the descriptor region.
	FlashDescriptorLength = 0x1000
)
View Source 
const FlashMasterSectionSize = 12

FlashMasterSectionSize is the size in bytes of the FlashMaster section

View Source 
const (
	// FlashParamsSize is the size of a FlashParams struct
	FlashParamsSize = 4
)
View Source 
const FlashRegionSectionSize = 64

FlashRegionSectionSize is the size of the Region descriptor. It is made up by 16 fields, each 2x16-bits large.

View Source 
const NVarEntrySignature uint32 = 0x5241564E

NVarEntrySignature value for 'NVAR' signature

View Source 
const (
	// RegionBlockSize assumes the region struct values correspond to blocks of 0x1000 in size
	RegionBlockSize = 0x1000
)

Variables

View Source 
var (
	ZeroGUID = guid.MustParse("00000000-0000-0000-0000-000000000000")
	FFGUID   = guid.MustParse("FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF")
)

Stock GUIDS

View Source 
var (
	FFS1      = guid.MustParse("7a9354d9-0468-444a-81ce-0bf617d890df")
	FFS2      = guid.MustParse("8c8ce578-8a3d-4f1c-9935-896185c32dd3")
	FFS3      = guid.MustParse("5473c07a-3dcb-4dca-bd6f-1e9689e7349a")
	EVSA      = guid.MustParse("fff12b8d-7696-4c8b-a985-2747075b4f50")
	NVAR      = guid.MustParse("cef5b9a3-476d-497f-9fdc-e98143e0422c")
	EVSA2     = guid.MustParse("00504624-8a59-4eeb-bd0f-6b36e96128e0")
	AppleBoot = guid.MustParse("04adeead-61ff-4d31-b6ba-64f8bf901f5a")
	PFH1      = guid.MustParse("16b45da2-7d70-4aea-a58d-760e9ecb841d")
	PFH2      = guid.MustParse("e360bdba-c3ce-46be-8f37-b231e5cb9f35")
)

Valid FV GUIDs

View Source 
var (
	// ReadOnly breaks firmware modification operations, but optimizes
	// memory and CPU consumption for read-only operations.
	//
	// DO NOT USE THIS OPTION UNLESS YOU KNOW WHAT ARE YOU DOING. IF YOU
	// WILL MODIFY A FIRMWARE WITH THIS OPTION BEING ENABLED, THIS FIRMWARE
	// MIGHT BRICK YOUR DEVICE.
	ReadOnly = false

	// DisableDecompression disables section decompression.
	//
	// DO NOT USE THIS OPTION UNLESS YOU KNOW WHAT ARE YOU DOING. IF YOU
	// WILL MODIFY A FIRMWARE WITH THIS OPTION BEING ENABLED, THIS FIRMWARE
	// MIGHT BRICK YOUR DEVICE.
	DisableDecompression = false
)
View Source 
var Attributes = ROMAttributes{ErasePolarity: poisonedPolarity}

Attributes holds the global attributes

View Source 
var DepExNamesToOpCodes = map[DepExOpCode]byte{}

DepExNamesToOpCodes maps the operation back to the code.

View Source 
var DepExOpCodes = map[byte]DepExOpCode{
	0x0: "BEFORE",
	0x1: "AFTER",
	0x2: "PUSH",
	0x3: "AND",
	0x4: "OR",
	0x5: "NOT",
	0x6: "TRUE",
	0x7: "FALSE",
	0x8: "END",
	0x9: "SOR",
}

DepExOpCodes maps the numeric code to the string.

View Source 
var FVGUIDs = map[guid.GUID]string{
	*FFS1:      "FFS1",
	*FFS2:      "FFS2",
	*FFS3:      "FFS3",
	*EVSA:      "NVRAM_EVSA",
	*NVAR:      "NVRAM_NVAR",
	*EVSA2:     "NVRAM_EVSA2",
	*AppleBoot: "APPLE_BOOT",
	*PFH1:      "PFH1",
	*PFH2:      "PFH2",
}

FVGUIDs holds common FV type names

View Source 
var FlashFrequencyStringMap = map[FlashFrequency]string{
	Freq20MHz:      "20MHz",
	Freq33MHz:      "33MHz",
	Freq48MHz:      "48MHz",
	Freq50MHz30MHz: "50Mhz30MHz",
	Freq17MHz:      "17MHz",
}

FlashFrequencyStringMap maps frequency constants to strings

View Source 
var (
	FlashSignature = []byte{0x5a, 0xa5, 0xf0, 0x0f}
)

FlashSignature is the sequence of bytes that a Flash image is expected to start with.

View Source 
var (
	MEFTPSignature = []byte{0x24, 0x46, 0x50, 0x54}
)

MEFTPSignature is the sequence of bytes that an ME Flash Partition Table is expected to start with ie "$FPT".

View Source 
var NamesToFileType map[string]FVFileType

NamesToFileType maps from common file type strings to the actual type.

View Source 
var SupportedFiles = map[FVFileType]bool{

	FVFileTypeRaw:      false,
	FVFileTypeFreeForm: true,
	FVFileTypeSECCore:  true,
	FVFileTypePEICore:  true,
	FVFileTypeDXECore:  true,

	FVFileTypeDriver:             true,
	FVFileTypeCombinedPEIMDriver: true,
	FVFileTypeApplication:        true,
	FVFileTypeSMM:                true,
	FVFileTypeVolumeImage:        true,
	FVFileTypeCombinedSMMDXE:     true,
	FVFileTypeSMMCore:            true,
	FVFileTypeSMMStandalone:      true,
	FVFileTypeSMMCoreStandalone:  true,
}

SupportedFiles is a list of files types which will be parsed. File types not on this list are treated as opaque binary blobs.

View Source 
var SuppressErasePolarityError = false

SuppressErasePolarityError forces to ignore the "conflicting erase polarities" error.

See also: https://github.com/linuxboot/fiano/issues/329

Functions

func Align 

func Align(val uint64, base uint64) uint64

Align aligns an address

func Align4 

func Align4(val uint64) uint64

Align4 aligns an address to 4 bytes

func Align8 

func Align8(val uint64) uint64

Align8 aligns an address to 8 bytes

func Checksum16 

func Checksum16(buf []byte) (uint16, error)

Checksum16 does a 16 bit checksum of the byte slice passed in.

func Checksum8 

func Checksum8(buf []byte) uint8

Checksum8 does a 8 bit checksum of the slice passed in.

func Erase 

func Erase(buf []byte, polarity byte)

Erase sets the buffer to be ErasePolarity

func FindFirmwareVolumeOffset 

func FindFirmwareVolumeOffset(data []byte) int64

FindFirmwareVolumeOffset searches for a firmware volume signature, "_FVH" using 8-byte alignment. If found, returns the offset from the start of the bios region, otherwise returns -1.

func FindMEDescriptor 

func FindMEDescriptor(buf []byte) (int, error)

FindMEDescriptor searches for an Intel ME FTP signature

func FindSignature 

func FindSignature(buf []byte) (int, error)

FindSignature searches for an Intel flash signature.

func IsErased 

func IsErased(buf []byte, polarity byte) bool

IsErased check if the buffer is ErasePolarity

func MarshalFirmware 

func MarshalFirmware(f Firmware) ([]byte, error)

MarshalFirmware marshals the firmware element to JSON, including the type information at the top.

func Read3Size 

func Read3Size(size [3]uint8) uint64

Read3Size reads a 3-byte size and returns it as a uint64

func SetErasePolarity 

func SetErasePolarity(ep byte) error

SetErasePolarity sets the Erase Polarity for the flash image. It checks to see if there are conflicting Erase Polarities.

func Write3Size 

func Write3Size(size uint64) [3]uint8

Write3Size writes a size into a 3-byte array

Types

type BIOSPadding 

type BIOSPadding struct {
	Offset uint64

	// Metadata
	ExtractPath string
	// contains filtered or unexported fields
}

BIOSPadding holds the padding in between firmware volumes This may sometimes hold data, even though it shouldn't. We need to preserve it though.

func NewBIOSPadding 

func NewBIOSPadding(buf []byte, offset uint64) (*BIOSPadding, error)

NewBIOSPadding parses a sequence of bytes and returns a BIOSPadding object.

func (*BIOSPadding) Apply 

func (bp *BIOSPadding) Apply(v Visitor) error

Apply a visitor to the BIOSPadding.

func (*BIOSPadding) ApplyChildren 

func (bp *BIOSPadding) ApplyChildren(v Visitor) error

ApplyChildren applies a visitor to all the direct children of the BIOSPadding

func (*BIOSPadding) Buf 

func (bp *BIOSPadding) Buf() []byte

Buf returns the buffer

func (*BIOSPadding) SetBuf 

func (bp *BIOSPadding) SetBuf(buf []byte)

SetBuf sets the buffer

type BIOSRegion 

type BIOSRegion struct {
	Elements []*TypedFirmware `json:",omitempty"`

	// Metadata for extraction and recovery
	ExtractPath string
	Length      uint64
	// This is a pointer to the FlashRegion struct laid out in the ifd.
	FRegion    *FlashRegion
	RegionType FlashRegionType
	// contains filtered or unexported fields
}

BIOSRegion represents the Bios Region in the firmware. It holds all the FVs as well as padding

func (*BIOSRegion) Apply 

func (br *BIOSRegion) Apply(v Visitor) error

Apply calls the visitor on the BIOSRegion.

func (*BIOSRegion) ApplyChildren 

func (br *BIOSRegion) ApplyChildren(v Visitor) error

ApplyChildren calls the visitor on each child node of BIOSRegion.

func (*BIOSRegion) Buf 

func (br *BIOSRegion) Buf() []byte

Buf returns the buffer. Used mostly for things interacting with the Firmware interface.

func (*BIOSRegion) FirstFV 

func (br *BIOSRegion) FirstFV() (*FirmwareVolume, error)

FirstFV finds the first firmware volume in the BIOSRegion.

func (*BIOSRegion) FlashRegion 

func (br *BIOSRegion) FlashRegion() (fr *FlashRegion)

FlashRegion gets the Flash Region.

func (*BIOSRegion) SetBuf 

func (br *BIOSRegion) SetBuf(buf []byte)

SetBuf sets the buffer. Used mostly for things interacting with the Firmware interface.

func (*BIOSRegion) SetFlashRegion 

func (br *BIOSRegion) SetFlashRegion(fr *FlashRegion)

SetFlashRegion sets the Flash Region.

func (*BIOSRegion) Type 

func (br *BIOSRegion) Type() FlashRegionType

Type returns the flash region type.

type Block 

type Block struct {
	Count uint32
	Size  uint32
}

Block describes number and size of the firmware volume blocks

type DepExOp 

type DepExOp struct {
	OpCode DepExOpCode
	GUID   *guid.GUID `json:",omitempty"`
}

DepExOp contains one operation for the dependency expression.

type DepExOpCode 

type DepExOpCode string

DepExOpCode is one opcode for the dependency expression section.

type FVFileType 

type FVFileType uint8

FVFileType represents the different types possible in an EFI file. 

const (
	FVFileTypeAll FVFileType = iota
	FVFileTypeRaw
	FVFileTypeFreeForm
	FVFileTypeSECCore
	FVFileTypePEICore
	FVFileTypeDXECore
	FVFileTypePEIM
	FVFileTypeDriver
	FVFileTypeCombinedPEIMDriver
	FVFileTypeApplication
	FVFileTypeSMM
	FVFileTypeVolumeImage
	FVFileTypeCombinedSMMDXE
	FVFileTypeSMMCore
	FVFileTypeSMMStandalone
	FVFileTypeSMMCoreStandalone
	FVFileTypeOEMMin   FVFileType = 0xC0
	FVFileTypeOEMMax   FVFileType = 0xDF
	FVFileTypeDebugMin FVFileType = 0xE0
	FVFileTypeDebugMax FVFileType = 0xEF
	FVFileTypePad      FVFileType = 0xF0
	FVFileTypeFFSMin   FVFileType = 0xF0
	FVFileTypeFFSMax   FVFileType = 0xFF
)

UEFI FV File types.

func (FVFileType) String 

func (f FVFileType) String() string

String creates a string representation for the file type.

type File 

type File struct {
	Header FileHeaderExtended
	Type   string

	// a File can contain either Sections or an NVarStore but not both
	Sections  []*Section `json:",omitempty"`
	NVarStore *NVarStore `json:",omitempty"`

	ExtractPath string
	DataOffset  uint64
	// contains filtered or unexported fields
}

File represents an EFI File.

func CreatePadFile 

func CreatePadFile(size uint64) (*File, error)

CreatePadFile creates an empty pad file in order to align the next file.

func NewFile 

func NewFile(buf []byte) (*File, error)

NewFile parses a sequence of bytes and returns a File object, if a valid one is passed, or an error. If no error is returned and the File pointer is nil, it means we've reached the volume free space at the end of the FV.

func (*File) Apply 

func (f *File) Apply(v Visitor) error

Apply calls the visitor on the File.

func (*File) ApplyChildren 

func (f *File) ApplyChildren(v Visitor) error

ApplyChildren calls the visitor on each child node of File.

func (*File) Buf 

func (f *File) Buf() []byte

Buf returns the buffer. Used mostly for things interacting with the Firmware interface.

func (*File) ChecksumAndAssemble 

func (f *File) ChecksumAndAssemble(fileData []byte) error

ChecksumAndAssemble takes in the fileData and assembles the file binary

func (*File) ChecksumHeader 

func (f *File) ChecksumHeader() uint8

ChecksumHeader returns a checksum of the header.

func (*File) HeaderLen 

func (f *File) HeaderLen() uint64

HeaderLen returns the length of the file header depending on the file size.

func (*File) SetBuf 

func (f *File) SetBuf(buf []byte)

SetBuf sets the buffer. Used mostly for things interacting with the Firmware interface.

func (*File) SetSize 

func (f *File) SetSize(size uint64, resizeFile bool)

SetSize sets the size into the File struct. If resizeFile is true, if the file is too large the file will be enlarged to make space for the ExtendedHeader

type FileHeader 

type FileHeader struct {
	GUID       guid.GUID      // This is the GUID of the file.
	Checksum   IntegrityCheck `json:"-"`
	Type       FVFileType
	Attributes fileAttr
	Size       ThreeUint8
	State      FileState
}

FileHeader represents an EFI File header.

func (*FileHeader) SetState 

func (fh *FileHeader) SetState(s FileState)

SetState sets file state respecting erase polarity

type FileHeaderExtended 

type FileHeaderExtended struct {
	FileHeader
	ExtendedSize uint64 `json:"-"`
}

FileHeaderExtended represents an EFI File header with the large file attribute set. We also use this as the generic header for all EFI files, regardless of whether they are actually large. This makes it easier for us to just return one type All sizes are also copied into the ExtendedSize field so we only have to check once

type FileState 

type FileState uint8

FileState (needs to be xored with Attributes.ErasePolarity) 

const (
	FileStateHeaderConstruction FileState = 0x01
	FileStateHeaderValid        FileState = 0x02
	FileStateDataValid          FileState = 0x04
	FileStateMarkeForUpdate     FileState = 0x08
	FileStateDeleted            FileState = 0x10
	FileStateHeaderInvalid      FileState = 0x20

	FileStateValid FileState = FileStateHeaderConstruction | FileStateHeaderValid | FileStateDataValid
)

File State Bits

type Firmware 

type Firmware interface {
	Buf() []byte
	SetBuf(buf []byte)

	// Apply a visitor to the Firmware.
	Apply(v Visitor) error

	// Apply a visitor to all the direct children of the Firmware
	// (excluding the Firmware itself).
	ApplyChildren(v Visitor) error
}

Firmware is an interface to describe generic firmware types. When the firmware is parsed, all the Firmware objects are laid out in a tree (similar to an AST). This interface represents one node in said tree. The implementations (e.g. Flash image, or FirmwareVolume) must implement this interface.

func Parse 

func Parse(buf []byte) (Firmware, error)

Parse exposes a high-level parser for generic firmware types. It does not implement any parser itself, but it calls known parsers that implement the Firmware interface.

func UnmarshalFirmware 

func UnmarshalFirmware(b []byte) (Firmware, error)

UnmarshalFirmware unmarshals the firmware element from JSON, using the type information at the top.

type FirmwareVolume 

type FirmwareVolume struct {
	FirmwareVolumeFixedHeader
	// there must be at least one that is zeroed and indicates the end of the
	// block list
	// We don't really have to care about blocks because we just read everything in.
	Blocks []Block
	FirmwareVolumeExtHeader
	Files []*File `json:",omitempty"`

	// Variables not in the binary for us to keep track of stuff/print
	DataOffset uint64
	FVType     string `json:"-"`

	FVOffset    uint64 // Byte offset from start of BIOS region.
	ExtractPath string
	Resizable   bool   // Determines if this FV is resizable.
	FreeSpace   uint64 `json:"-"`
	// contains filtered or unexported fields
}

FirmwareVolume represents a firmware volume. It combines the fixed header and a variable list of blocks

func NewFirmwareVolume 

func NewFirmwareVolume(data []byte, fvOffset uint64, resizable bool) (*FirmwareVolume, error)

NewFirmwareVolume parses a sequence of bytes and returns a FirmwareVolume object, if a valid one is passed, or an error

func (*FirmwareVolume) Apply 

func (fv *FirmwareVolume) Apply(v Visitor) error

Apply calls the visitor on the FirmwareVolume.

func (*FirmwareVolume) ApplyChildren 

func (fv *FirmwareVolume) ApplyChildren(v Visitor) error

ApplyChildren calls the visitor on each child node of FirmwareVolume.

func (*FirmwareVolume) Buf 

func (fv *FirmwareVolume) Buf() []byte

Buf returns the buffer. Used mostly for things interacting with the Firmware interface.

func (*FirmwareVolume) GetErasePolarity 

func (fv *FirmwareVolume) GetErasePolarity() uint8

GetErasePolarity gets the erase polarity

func (*FirmwareVolume) InsertFile 

func (fv *FirmwareVolume) InsertFile(alignedOffset uint64, fBuf []byte) error

InsertFile appends the file to the end of the buffer according to alignment requirements.

func (*FirmwareVolume) SetBuf 

func (fv *FirmwareVolume) SetBuf(buf []byte)

SetBuf sets the buffer. Used mostly for things interacting with the Firmware interface.

func (FirmwareVolume) String 

func (fv FirmwareVolume) String() string

String creates a string representation for the firmware volume.

type FirmwareVolumeExtHeader 

type FirmwareVolumeExtHeader struct {
	FVName        guid.GUID
	ExtHeaderSize uint32
}

FirmwareVolumeExtHeader contains the fields of an extended firmware volume header

type FirmwareVolumeFixedHeader 

type FirmwareVolumeFixedHeader struct {
	FileSystemGUID  guid.GUID
	Length          uint64
	Signature       uint32
	Attributes      uint32 // UEFI PI spec volume 3.2.1 EFI_FIRMWARE_VOLUME_HEADER
	HeaderLen       uint16
	Checksum        uint16
	ExtHeaderOffset uint16
	Reserved        uint8 `json:"-"`
	Revision        uint8
	// contains filtered or unexported fields
}

FirmwareVolumeFixedHeader contains the fixed fields of a firmware volume header

type FlashDescriptor 

type FlashDescriptor struct {
	DescriptorMapStart uint
	RegionStart        uint
	MasterStart        uint
	DescriptorMap      *FlashDescriptorMap
	Region             *FlashRegionSection
	Master             *FlashMasterSection

	//Metadata for extraction and recovery
	ExtractPath string
	// contains filtered or unexported fields
}

FlashDescriptor is the main structure that represents an Intel Flash Descriptor.

func (*FlashDescriptor) Apply 

func (fd *FlashDescriptor) Apply(v Visitor) error

Apply calls the visitor on the FlashDescriptor.

func (*FlashDescriptor) ApplyChildren 

func (fd *FlashDescriptor) ApplyChildren(v Visitor) error

ApplyChildren calls the visitor on each child node of FlashDescriptor.

func (*FlashDescriptor) Buf 

func (fd *FlashDescriptor) Buf() []byte

Buf returns the buffer. Used mostly for things interacting with the Firmware interface.

func (*FlashDescriptor) ParseFlashDescriptor 

func (fd *FlashDescriptor) ParseFlashDescriptor() error

ParseFlashDescriptor parses the ifd from the buffer

func (*FlashDescriptor) SetBuf 

func (fd *FlashDescriptor) SetBuf(buf []byte)

SetBuf sets the buffer. Used mostly for things interacting with the Firmware interface.

type FlashDescriptorMap 

type FlashDescriptorMap struct {
	// FLMAP0
	ComponentBase      uint8
	NumberOfFlashChips uint8
	RegionBase         uint8
	NumberOfRegions    uint8
	// FLMAP1
	MasterBase        uint8
	NumberOfMasters   uint8
	PchStrapsBase     uint8
	NumberOfPchStraps uint8
	// FLMAP2
	ProcStrapsBase          uint8
	NumberOfProcStraps      uint8
	IccTableBase            uint8
	NumberOfIccTableEntries uint8
	// FLMAP3
	DmiTableBase            uint8
	NumberOfDmiTableEntries uint8
	Reserved0               uint8
	Reserved1               uint8
}

FlashDescriptorMap represent an Intel flash descriptor. This object provides accessors to the various descriptor fields.

func NewFlashDescriptorMap 

func NewFlashDescriptorMap(buf []byte) (*FlashDescriptorMap, error)

NewFlashDescriptorMap initializes a FlashDescriptor from a slice of bytes.

func (*FlashDescriptorMap) String 

func (d *FlashDescriptorMap) String() string

type FlashFrequency 

type FlashFrequency uint

FlashFrequency is the type used for Frequency fields 

const (
	Freq20MHz      FlashFrequency = 0
	Freq33MHz      FlashFrequency = 1
	Freq48MHz      FlashFrequency = 2
	Freq50MHz30MHz FlashFrequency = 4
	Freq17MHz      FlashFrequency = 6
)

Flash frequency constants

type FlashImage 

type FlashImage struct {

	// Holds the Flash Descriptor
	IFD FlashDescriptor
	// Actual regions
	Regions []*TypedFirmware `json:",omitempty"`

	// Metadata for extraction and recovery
	ExtractPath string
	FlashSize   uint64
	// contains filtered or unexported fields
}

FlashImage is the main structure that represents an Intel Flash image. It implements the Firmware interface.

func NewFlashImage 

func NewFlashImage(buf []byte) (*FlashImage, error)

NewFlashImage tries to create a FlashImage structure, and returns a FlashImage and an error if any. This only works with images that operate in Descriptor mode.

func (*FlashImage) Apply 

func (f *FlashImage) Apply(v Visitor) error

Apply calls the visitor on the FlashImage.

func (*FlashImage) ApplyChildren 

func (f *FlashImage) ApplyChildren(v Visitor) error

ApplyChildren calls the visitor on each child node of FlashImage.

func (*FlashImage) Buf 

func (f *FlashImage) Buf() []byte

Buf returns the buffer. Used mostly for things interacting with the Firmware interface.

func (*FlashImage) FindSignature 

func (f *FlashImage) FindSignature() (int, error)

FindSignature looks for the Intel flash signature, and returns its offset from the start of the image. The PCH images are located at offset 16, while in ICH8/9/10 they start at 0. If no signature is found, it returns -1.

func (*FlashImage) IsPCH 

func (f *FlashImage) IsPCH() bool

IsPCH returns whether the flash image has the more recent PCH format, or not. PCH images have the first 16 bytes reserved, and the 4-bytes signature starts immediately after. Older images (ICH8/9/10) have the signature at the beginning. TODO: Check this. What if we have the signature in both places? I feel like the check should be IsICH because I expect the ICH to override PCH if the signature exists in 0:4 since in that case 16:20 should be data. If that's the case, FindSignature needs to be fixed as well

func (*FlashImage) SetBuf 

func (f *FlashImage) SetBuf(buf []byte)

SetBuf sets the buffer. Used mostly for things interacting with the Firmware interface.

func (*FlashImage) String 

func (f *FlashImage) String() string

type FlashMasterSection 

type FlashMasterSection struct {
	BIOS RegionPermissions
	ME   RegionPermissions
	GBE  RegionPermissions
}

FlashMasterSection holds all the IDs and read/write permissions for other regions This controls whether the bios region can read/write to the ME for example.

func NewFlashMasterSection 

func NewFlashMasterSection(buf []byte) (*FlashMasterSection, error)

NewFlashMasterSection parses a sequence of bytes and returns a FlashMasterSection object, if a valid one is passed, or an error

func (*FlashMasterSection) String 

func (m *FlashMasterSection) String() string

type FlashParams 

type FlashParams [4]byte

FlashParams is a 4-byte object that holds the flash parameters information.

func NewFlashParams 

func NewFlashParams(buf []byte) (*FlashParams, error)

NewFlashParams initializes a FlashParam struct from a slice of bytes

func (*FlashParams) DualOutputFastReadSupported 

func (p *FlashParams) DualOutputFastReadSupported() uint

DualOutputFastReadSupported returns if Dual Output Fast Read is supported.

func (*FlashParams) FastReadEnabled 

func (p *FlashParams) FastReadEnabled() uint

FastReadEnabled returns if FastRead is enabled.

func (*FlashParams) FastReadFrequency 

func (p *FlashParams) FastReadFrequency() FlashFrequency

FastReadFrequency returns the frequency under FastRead.

func (*FlashParams) FirstChipDensity 

func (p *FlashParams) FirstChipDensity() uint

FirstChipDensity returns the size of the first chip.

func (*FlashParams) FlashReadStatusFrequency 

func (p *FlashParams) FlashReadStatusFrequency() FlashFrequency

FlashReadStatusFrequency returns the chip frequency while reading the flash status.

func (*FlashParams) FlashWriteFrequency 

func (p *FlashParams) FlashWriteFrequency() FlashFrequency

FlashWriteFrequency returns the chip frequency for writing.

func (*FlashParams) ReadClockFrequency 

func (p *FlashParams) ReadClockFrequency() FlashFrequency

ReadClockFrequency returns the chip frequency while reading from the flash.

func (*FlashParams) SecondChipDensity 

func (p *FlashParams) SecondChipDensity() uint

SecondChipDensity returns the size of the second chip.

func (*FlashParams) String 

func (p *FlashParams) String() string

type FlashRegion 

type FlashRegion struct {
	Base  uint16 // Index of first 4KiB block
	Limit uint16 // Index of last block
}

FlashRegion holds the base and limit of every type of region. Each region such as the bios region should point back to it. TODO: figure out of block sizes are read from some location on flash or fixed. Right now we assume they're fixed to 4KiB

func (*FlashRegion) BaseOffset 

func (r *FlashRegion) BaseOffset() uint32

BaseOffset calculates the offset into the flash image where the Region begins

func (*FlashRegion) EndOffset 

func (r *FlashRegion) EndOffset() uint32

EndOffset calculates the offset into the flash image where the Region ends

func (*FlashRegion) String 

func (r *FlashRegion) String() string

func (*FlashRegion) Valid 

func (r *FlashRegion) Valid() bool

Valid checks to see if a region is valid

type FlashRegionSection 

type FlashRegionSection struct {
	FlashBlockEraseSize uint16

	// This isn't documented anywhere, but I've only seen images with 16 slots for FlashRegion entries, with the
	// FlashMasterSection coming immediately after, so I'm assuming that's the max for now.
	FlashRegions [15]FlashRegion
	// contains filtered or unexported fields
}

FlashRegionSection holds the metadata of all the different flash regions like PDR, Gbe and the Bios region.

func NewFlashRegionSection 

func NewFlashRegionSection(data []byte) (*FlashRegionSection, error)

NewFlashRegionSection initializes a FlashRegionSection from a slice of bytes

func (*FlashRegionSection) String 

func (f *FlashRegionSection) String() string

func (*FlashRegionSection) ValidRegions 

func (f *FlashRegionSection) ValidRegions() []string

ValidRegions returns a list of names of the regions with non-zero size.

type FlashRegionType 

type FlashRegionType int

FlashRegionType represents the different types possible in a flash region. 

const (
	RegionTypeBIOS FlashRegionType = iota
	RegionTypeME
	RegionTypeGBE
	RegionTypePD
	RegionTypeDevExp1
	RegionTypeBIOS2
	RegionTypeMicrocode
	RegionTypeEC
	RegionTypeDevExp2
	RegionTypeIE
	RegionTypeTGBE1
	RegionTypeTGBE2
	RegionTypeReserved1
	RegionTypeReserved2
	RegionTypePTT

	RegionTypeUnknown FlashRegionType = -1
)

IFD Region types. This also corresponds to their index in the flash region section. Referenced from github.com/LongSoft/UEFITool, common/descriptor.h.

func (FlashRegionType) String 

func (rt FlashRegionType) String() string

type GUIDEDSectionAttribute 

type GUIDEDSectionAttribute uint16

GUIDEDSectionAttribute holds a GUIDED section attribute bitfield 

const (
	GUIDEDSectionProcessingRequired GUIDEDSectionAttribute = 0x01
	GUIDEDSectionAuthStatusValid    GUIDEDSectionAttribute = 0x02
)

UEFI GUIDED Section Attributes

type IntegrityCheck 

type IntegrityCheck struct {
	Header uint8
	File   uint8
}

IntegrityCheck holds the two 8 bit checksums for the file header and body separately.

type MEFPT 

type MEFPT struct {
	PartitionCount    uint32
	PartitionMapStart int
	Entries           []MEPartitionEntry
	// Metadata for extraction and recovery
	ExtractPath string
	// contains filtered or unexported fields
}

MEFPT is the main structure that represents an ME Flash Partition Table.

func NewMEFPT 

func NewMEFPT(buf []byte) (*MEFPT, error)

NewMEFPT tries to create a MEFPT

func (*MEFPT) Apply 

func (fp *MEFPT) Apply(v Visitor) error

Apply calls the visitor on the MEFPT.

func (*MEFPT) ApplyChildren 

func (fp *MEFPT) ApplyChildren(v Visitor) error

ApplyChildren calls the visitor on each child node of MEFPT.

func (*MEFPT) Buf 

func (fp *MEFPT) Buf() []byte

Buf returns the buffer. Used mostly for things interacting with the Firmware interface.

func (*MEFPT) SetBuf 

func (fp *MEFPT) SetBuf(buf []byte)

SetBuf sets the buffer. Used mostly for things interacting with the Firmware interface.

type MEName 

type MEName [4]byte

MEName represent 4 bytes with JSON string support

func (MEName) MarshalText 

func (n MEName) MarshalText() ([]byte, error)

MarshalText converts MEName to a byte range (for JSON)

func (MEName) String 

func (n MEName) String() string

func (*MEName) UnmarshalText 

func (n *MEName) UnmarshalText(b []byte) error

UnmarshalText converts a byte range to MEName (for JSON)

type MEPartitionEntry 

type MEPartitionEntry struct {
	Name     MEName
	Owner    [4]byte
	Offset   uint32
	Length   uint32
	Reserved [3]uint32
	Flags    uint32
}

MEPartitionEntry is an entry in FTP

func (MEPartitionEntry) OffsetIsValid 

func (e MEPartitionEntry) OffsetIsValid() bool

OffsetIsValid returns true if the entry has a valid offset

func (MEPartitionEntry) Type 

func (e MEPartitionEntry) Type() string

Type returns the type of the entry

type MERegion 

type MERegion struct {
	FPT *MEFPT

	// Metadata for extraction and recovery
	ExtractPath string
	// This is a pointer to the FlashRegion struct laid out in the ifd.
	FRegion *FlashRegion
	// Region Type as per the IFD
	RegionType FlashRegionType
	// Computed free space after parsing the partition table
	FreeSpaceOffset uint64
	// contains filtered or unexported fields
}

MERegion implements Region for a raw chunk of bytes in the firmware image.

func (*MERegion) Apply 

func (rr *MERegion) Apply(v Visitor) error

Apply calls the visitor on the MERegion.

func (*MERegion) ApplyChildren 

func (rr *MERegion) ApplyChildren(v Visitor) error

ApplyChildren calls the visitor on each child node of MERegion.

func (*MERegion) Buf 

func (rr *MERegion) Buf() []byte

Buf returns the buffer. Used mostly for things interacting with the Firmware interface.

func (*MERegion) FlashRegion 

func (rr *MERegion) FlashRegion() (fr *FlashRegion)

FlashRegion gets the flash region.

func (*MERegion) SetBuf 

func (rr *MERegion) SetBuf(buf []byte)

SetBuf sets the buffer. Used mostly for things interacting with the Firmware interface.

func (*MERegion) SetFlashRegion 

func (rr *MERegion) SetFlashRegion(fr *FlashRegion)

SetFlashRegion sets the flash region.

func (*MERegion) Type 

func (rr *MERegion) Type() FlashRegionType

Type returns the flash region type.

type NVar 

type NVar struct {
	Header    NVarHeader
	GUID      guid.GUID
	GUIDIndex *uint8 `json:",omitempty"`
	Name      string

	NVarStore *NVarStore `json:",omitempty"`

	//Decoded data
	Type       NVarEntryType
	Offset     uint64
	NextOffset uint64

	//Extended Header
	ExtAttributes               *NVarExtAttribute `json:",omitempty"`
	Checksum                    *uint8            `json:",omitempty"`
	ExpectedChecksum            *uint8            `json:",omitempty"`
	TimeStamp                   *uint64           `json:",omitempty"`
	Hash                        []byte            `json:",omitempty"`
	UnknownExtendedHeaderFormat bool              `json:",omitempty"`

	ExtractPath string
	DataOffset  int64
	ExtOffset   int64 `json:",omitempty"`
	// contains filtered or unexported fields
}

NVar represent an NVAR entry

func (*NVar) Apply 

func (v *NVar) Apply(vr Visitor) error

Apply calls the visitor on the NVar.

func (*NVar) ApplyChildren 

func (v *NVar) ApplyChildren(vr Visitor) error

ApplyChildren calls the visitor on each child node of NVar.

func (*NVar) Assemble 

func (v *NVar) Assemble(content []byte, checkOnly bool) error

Assemble takes in the content and assembles the NVAR binary Warning: when checkOnly is false the resulting NVar must be Assembled again to fix the header content

func (*NVar) Buf 

func (v *NVar) Buf() []byte

Buf returns the buffer. Used mostly for things interacting with the Firmware interface.

func (*NVar) IsValid 

func (v *NVar) IsValid() bool

IsValid tells whether an entry is valid

func (*NVar) SetBuf 

func (v *NVar) SetBuf(buf []byte)

SetBuf sets the buffer. Used mostly for things interacting with the Firmware interface.

func (*NVar) String 

func (v *NVar) String() string

String returns the String value of the NVAR: Type and Name if valid

type NVarAttribute 

type NVarAttribute uint8

NVarAttribute represent Attributes 

const (
	NVarEntryRuntime       NVarAttribute = 0x01
	NVarEntryASCIIName     NVarAttribute = 0x02
	NVarEntryGUID          NVarAttribute = 0x04
	NVarEntryDataOnly      NVarAttribute = 0x08
	NVarEntryExtHeader     NVarAttribute = 0x10
	NVarEntryHWErrorRecord NVarAttribute = 0x20
	NVarEntryAuthWrite     NVarAttribute = 0x40
	NVarEntryValid         NVarAttribute = 0x80
)

Attributes

func (NVarAttribute) IsValid 

func (a NVarAttribute) IsValid() bool

IsValid returns the Valid attribute as boolean

type NVarEntryType 

type NVarEntryType uint8

NVarEntryType represent the computed type of an NVAR entry 

const (
	InvalidNVarEntry NVarEntryType = iota
	InvalidLinkNVarEntry
	LinkNVarEntry
	DataNVarEntry
	FullNVarEntry
)

Types

func (NVarEntryType) String 

func (t NVarEntryType) String() string

type NVarExtAttribute 

type NVarExtAttribute uint8

NVarExtAttribute represent extended attributes 

const (
	NVarEntryExtChecksum    NVarExtAttribute = 0x01
	NVarEntryExtAuthWrite   NVarExtAttribute = 0x10
	NVarEntryExtTimeBased   NVarExtAttribute = 0x20
	NVarEntryExtUnknownMask NVarExtAttribute = 0xCE
)

Extended attributes values

type NVarHeader 

type NVarHeader struct {
	Signature  uint32 `json:"-"`
	Size       uint16
	Next       [3]uint8 `json:"-"`
	Attributes NVarAttribute
}

NVarHeader represents an NVAR entry header

type NVarStore 

type NVarStore struct {
	Entries   []*NVar
	GUIDStore []guid.GUID `json:",omitempty"`

	FreeSpaceOffset uint64
	GUIDStoreOffset uint64
	Length          uint64
	// contains filtered or unexported fields
}

NVarStore represent an NVAR store

func NewNVarStore 

func NewNVarStore(buf []byte) (*NVarStore, error)

NewNVarStore parses a sequence of bytes and returns an NVarStore object, if a valid one is passed, or an error.

func (*NVarStore) Apply 

func (s *NVarStore) Apply(v Visitor) error

Apply calls the visitor on the NVarStore.

func (*NVarStore) ApplyChildren 

func (s *NVarStore) ApplyChildren(v Visitor) error

ApplyChildren calls the visitor on each child node of NVarStore.

func (*NVarStore) Buf 

func (s *NVarStore) Buf() []byte

Buf returns the buffer. Used mostly for things interacting with the Firmware interface.

func (*NVarStore) GetGUIDStoreBuf 

func (s *NVarStore) GetGUIDStoreBuf() ([]byte, error)

GetGUIDStoreBuf returns the binary representation of the GUIDStore

func (*NVarStore) SetBuf 

func (s *NVarStore) SetBuf(buf []byte)

SetBuf sets the buffer. Used mostly for things interacting with the Firmware interface.

type ROMAttributes 

type ROMAttributes struct {
	ErasePolarity byte // Either 0xFF or 0
}

ROMAttributes is used to hold global variables that apply across the whole image. We have to do this to avoid passing too many things down each time.

type RawRegion 

type RawRegion struct {

	// Metadata for extraction and recovery
	ExtractPath string
	// This is a pointer to the FlashRegion struct laid out in the ifd.
	FRegion *FlashRegion
	// Region Type as per the IFD
	RegionType FlashRegionType
	// contains filtered or unexported fields
}

RawRegion implements Region for a raw chunk of bytes in the firmware image.

func (*RawRegion) Apply 

func (rr *RawRegion) Apply(v Visitor) error

Apply calls the visitor on the RawRegion.

func (*RawRegion) ApplyChildren 

func (rr *RawRegion) ApplyChildren(v Visitor) error

ApplyChildren calls the visitor on each child node of RawRegion.

func (*RawRegion) Buf 

func (rr *RawRegion) Buf() []byte

Buf returns the buffer. Used mostly for things interacting with the Firmware interface.

func (*RawRegion) FlashRegion 

func (rr *RawRegion) FlashRegion() (fr *FlashRegion)

FlashRegion gets the flash region.

func (*RawRegion) SetBuf 

func (rr *RawRegion) SetBuf(buf []byte)

SetBuf sets the buffer. Used mostly for things interacting with the Firmware interface.

func (*RawRegion) SetFlashRegion 

func (rr *RawRegion) SetFlashRegion(fr *FlashRegion)

SetFlashRegion sets the flash region.

func (*RawRegion) Type 

func (rr *RawRegion) Type() FlashRegionType

Type returns the flash region type.

type Region 

type Region interface {
	Firmware
	Type() FlashRegionType
	FlashRegion() *FlashRegion
	SetFlashRegion(fr *FlashRegion)
}

Region contains the start and end of a region in flash. This can be a BIOS, ME, PDR or GBE region.

func NewBIOSRegion 

func NewBIOSRegion(buf []byte, r *FlashRegion, _ FlashRegionType) (Region, error)

NewBIOSRegion parses a sequence of bytes and returns a Region object, if a valid one is passed, or an error. It also points to the Region struct uncovered in the ifd.

func NewMERegion 

func NewMERegion(buf []byte, r *FlashRegion, rt FlashRegionType) (Region, error)

NewMERegion creates a new region.

func NewRawRegion 

func NewRawRegion(buf []byte, r *FlashRegion, rt FlashRegionType) (Region, error)

NewRawRegion creates a new region.

type RegionPermissions 

type RegionPermissions struct {
	ID    uint16
	Read  uint8
	Write uint8
}

RegionPermissions holds the read/write permissions for other regions.

func (*RegionPermissions) String 

func (r *RegionPermissions) String() string

type Section 

type Section struct {
	Header SectionExtHeader
	Type   string

	// Metadata for extraction and recovery
	ExtractPath string
	FileOrder   int `json:"-"`

	// Type specific fields
	// TODO: It will be simpler if this was not an interface
	TypeSpecific *TypeSpecificHeader `json:",omitempty"`

	// For EFI_SECTION_USER_INTERFACE
	Name string `json:",omitempty"`

	// For EFI_SECTION_VERSION
	BuildNumber uint16 `json:",omitempty"`
	Version     string `json:",omitempty"`

	// For EFI_SECTION_DXE_DEPEX, EFI_SECTION_PEI_DEPEX, and EFI_SECTION_MM_DEPEX
	DepEx []DepExOp `json:",omitempty"`

	// Encapsulated firmware
	Encapsulated []*TypedFirmware `json:",omitempty"`
	// contains filtered or unexported fields
}

Section represents a Firmware File Section

func CreateSection 

func CreateSection(t SectionType, buf []byte, encap []Firmware, g *guid.GUID) (*Section, error)

CreateSection creates a new section from minimal components. The guid is only used in the case of a GUID Defined section type.

func NewSection 

func NewSection(buf []byte, fileOrder int) (*Section, error)

NewSection parses a sequence of bytes and returns a Section object, if a valid one is passed, or an error.

func (*Section) Apply 

func (s *Section) Apply(v Visitor) error

Apply calls the visitor on the Section.

func (*Section) ApplyChildren 

func (s *Section) ApplyChildren(v Visitor) error

ApplyChildren calls the visitor on each child node of Section.

func (*Section) Buf 

func (s *Section) Buf() []byte

Buf returns the buffer. Used mostly for things interacting with the Firmware interface.

func (*Section) GenSecHeader 

func (s *Section) GenSecHeader() error

GenSecHeader generates a full binary header for the section data. It assumes that the passed in section struct already contains section data in the buffer, the section type in the Type field, and the type specific header in the TypeSpecific field. It modifies the calling Section.

func (*Section) SetBuf 

func (s *Section) SetBuf(buf []byte)

SetBuf sets the buffer. Used mostly for things interacting with the Firmware interface.

func (*Section) SetType 

func (s *Section) SetType(t SectionType)

SetType sets the section type in the header and updates the string name.

func (*Section) String 

func (s *Section) String() string

String returns the String value of the section if it makes sense, such as the name or the version string.

type SectionExtHeader 

type SectionExtHeader struct {
	SectionHeader
	ExtendedSize uint32 `json:"-"`
}

SectionExtHeader represents an EFI_COMMON_SECTION_HEADER2 as specified in UEFI PI Spec 3.2.4 Firmware File Section

type SectionGUIDDefined 

type SectionGUIDDefined struct {
	SectionGUIDDefinedHeader

	// Metadata
	Compression string
}

SectionGUIDDefined contains the type specific fields for a EFI_SECTION_GUID_DEFINED section.

func (*SectionGUIDDefined) GetBinHeaderLen 

func (s *SectionGUIDDefined) GetBinHeaderLen() uint32

GetBinHeaderLen returns the length of the binary typ specific header

type SectionGUIDDefinedHeader 

type SectionGUIDDefinedHeader struct {
	GUID       guid.GUID
	DataOffset uint16
	Attributes uint16
}

SectionGUIDDefinedHeader contains the fields for a EFI_SECTION_GUID_DEFINED encapsulated section header.

type SectionHeader 

type SectionHeader struct {
	Size [3]uint8 `json:"-"`
	Type SectionType
}

SectionHeader represents an EFI_COMMON_SECTION_HEADER as specified in UEFI PI Spec 3.2.4 Firmware File Section

type SectionType 

type SectionType uint8

SectionType holds a section type value 

const (
	SectionTypeAll                 SectionType = 0x00
	SectionTypeCompression         SectionType = 0x01
	SectionTypeGUIDDefined         SectionType = 0x02
	SectionTypeDisposable          SectionType = 0x03
	SectionTypePE32                SectionType = 0x10
	SectionTypePIC                 SectionType = 0x11
	SectionTypeTE                  SectionType = 0x12
	SectionTypeDXEDepEx            SectionType = 0x13
	SectionTypeVersion             SectionType = 0x14
	SectionTypeUserInterface       SectionType = 0x15
	SectionTypeCompatibility16     SectionType = 0x16
	SectionTypeFirmwareVolumeImage SectionType = 0x17
	SectionTypeFreeformSubtypeGUID SectionType = 0x18
	SectionTypeRaw                 SectionType = 0x19
	SectionTypePEIDepEx            SectionType = 0x1b
	SectionMMDepEx                 SectionType = 0x1c
)

UEFI Section types

func (SectionType) String 

func (s SectionType) String() string

String creates a string representation for the section type.

type ThreeUint8 added in v1.1.1 

type ThreeUint8 [3]uint8

func (*ThreeUint8) MarshalJSON added in v1.1.1 

func (t *ThreeUint8) MarshalJSON() ([]byte, error)

func (*ThreeUint8) UnmarshalJSON added in v1.1.1 

func (t *ThreeUint8) UnmarshalJSON(b []byte) error

type TypeHeader 

type TypeHeader interface {
	GetBinHeaderLen() uint32
}

TypeHeader interface forces type specific headers to report their length

type TypeSpecificHeader 

type TypeSpecificHeader struct {
	Type   SectionType
	Header TypeHeader
}

TypeSpecificHeader is used for marshalling and unmarshalling from JSON

func (*TypeSpecificHeader) UnmarshalJSON 

func (t *TypeSpecificHeader) UnmarshalJSON(b []byte) error

UnmarshalJSON unmarshals a TypeSpecificHeader struct and correctly deduces the type of the interface.

type TypedFirmware 

type TypedFirmware struct {
	Type  string
	Value Firmware
}

TypedFirmware includes the Firmware interface's type when exporting it to JSON. The type is required when unmarshalling.

func MakeTyped 

func MakeTyped(f Firmware) *TypedFirmware

MakeTyped takes a Firmware interface and makes a (type, value) pair.

func (*TypedFirmware) UnmarshalJSON 

func (f *TypedFirmware) UnmarshalJSON(b []byte) error

UnmarshalJSON unmarshals a TypedFirmware struct and correctly deduces the type of the interface.

type Visitor 

type Visitor interface {
	// Run wraps Visit. Additionally, it performs some setup and teardown
	// tasks. As a consumer of the visitor, Run is typically the function
	// you should call.
	Run(Firmware) error

	// Visit applies the visitor to the Firmware and (usually) recurses
	// over the children.
	Visit(Firmware) error
}

Visitor represents an operation which can be applied to the Firmware. Typically, the Visit function contains a type switch for the different firmware types and a default case. For example: 

func (v *Example) Visit(f uefi.Firmware) error {
    switch f := f.(type) {

    case *uefi.File:
        fmt.Println("f is a file")
        return f.ApplyChildren(v) // Children are recursed over

    case *uefi.Section:
        fmt.Println("f is a section")
        return nil // Children are not visited

    default:
        // The default action is to recurse over children.
        return f.ApplyChildren(v)
    }
}

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.