Documentation
¶
Index ¶
- Constants
- Variables
- func Align(val uint64, base uint64) uint64
- func Align4(val uint64) uint64
- func Align8(val uint64) uint64
- func Checksum16(buf []byte) (uint16, error)
- func Checksum8(buf []byte) uint8
- func ExtractBinary(buf []byte, dirPath string, filename string) (string, error)
- func FindFirmwareVolumeOffset(data []byte) int64
- func FindSignature(buf []byte) (int, error)
- func MarshalFirmware(f Firmware) ([]byte, error)
- func Read3Size(size [3]uint8) uint64
- func Write3Size(size uint64) [3]uint8
- type BIOSRegion
- type Block
- type FVFileType
- type File
- type FileHeader
- type FileHeaderExtended
- type Firmware
- type FirmwareVolume
- type FirmwareVolumeExtHeader
- type FirmwareVolumeFixedHeader
- type FlashDescriptor
- type FlashDescriptorMap
- type FlashFrequency
- type FlashImage
- type FlashMasterSection
- type FlashParams
- func (p *FlashParams) DualOutputFastReadSupported() uint
- func (p *FlashParams) FastReadEnabled() uint
- func (p *FlashParams) FastReadFrequency() FlashFrequency
- func (p *FlashParams) FirstChipDensity() uint
- func (p *FlashParams) FlashReadStatusFrequency() FlashFrequency
- func (p *FlashParams) FlashWriteFrequency() FlashFrequency
- func (p *FlashParams) ReadClockFrequency() FlashFrequency
- func (p *FlashParams) SecondChipDensity() uint
- func (p *FlashParams) String() string
- type FlashRegionSection
- type GBERegion
- type GUIDEDSectionAttribute
- type IntegrityCheck
- type MERegion
- type PDRegion
- type ROMAttributes
- type Region
- type RegionPermissions
- type Section
- type SectionExtHeader
- type SectionGUIDDefined
- type SectionHeader
- type SectionType
- type TypedFirmware
Constants ¶
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 )
const ( FirmwareVolumeFixedHeaderSize = 56 FirmwareVolumeMinSize = FirmwareVolumeFixedHeaderSize + 8 // +8 for the null block that terminates the block list FirmwareVolumeExtHeaderMinSize = 20 )
FirmwareVolume constants
const ( // FlashDescriptorLength represents the size of the descriptor region. FlashDescriptorLength = 0x1000 // FlashSignatureLength represents the size of the flash signature FlashSignatureLength = 4 )
const ( // FlashDescriptorMapSize is the size in bytes of the Intel flash descriptor FlashDescriptorMapSize = 0x1000 // FlashDescriptorMapMaxBase is the maximum base address for a flash descriptor // region FlashDescriptorMapMaxBase = 0xe0 )
const FlashMasterSectionSize = 12
FlashMasterSectionSize is the size in bytes of the FlashMaster section
const (
// FlashParamsSize is the size of a FlashParams struct
FlashParamsSize = 4
)
const FlashRegionSectionSize = 36
FlashRegionSectionSize is the size of the Region descriptor. It is made up by 18 fields, each 16-bits large.
const (
// RegionBlockSize assumes the region struct values correspond to blocks of 0x1000 in size
RegionBlockSize = 0x1000
)
const (
// SectionMinLength is the minimum length of a file section header.
SectionMinLength = 0x08
)
Variables ¶
var ( ZeroGUID = uuid.MustParse("00000000-0000-0000-0000-000000000000") FFGUID = uuid.MustParse("FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF") )
Stock GUIDS
var ( FFS1 *uuid.UUID FFS2 *uuid.UUID FFS3 *uuid.UUID EVSA *uuid.UUID NVAR *uuid.UUID EVSA2 *uuid.UUID AppleBoot *uuid.UUID PFH1 *uuid.UUID PFH2 *uuid.UUID )
Valid FV GUIDs
var FVGUIDs map[uuid.UUID]string
FVGUIDs holds common FV type names
var FlashFrequencyStringMap = map[FlashFrequency]string{ Freq20MHz: "20MHz", Freq33MHz: "33MHz", Freq48MHz: "48MHz", Freq50MHz30MHz: "50Mhz30MHz", Freq17MHz: "17MHz", }
FlashFrequencyStringMap maps frequency constants to strings
var (
FlashSignature = []byte{0x5a, 0xa5, 0xf0, 0x0f}
)
FlashSignature is the sequence of bytes that a Flash image is expected to start with.
Functions ¶
func Checksum16 ¶
Checksum16 does a 16 bit checksum of the byte slice passed in.
func ExtractBinary ¶
ExtractBinary simply dumps the binary to a specified directory and filename. It creates the directory if it doesn't already exist, and dumps the buffer to it. It returns the filepath of the binary, and an error if it exists. This is meant as a helper function for other Extract functions.
func FindFirmwareVolumeOffset ¶
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 FindSignature ¶
FindSignature searches for an Intel flash signature.
func MarshalFirmware ¶
MarshalFirmware marshals the firmware element to JSON, including the type information at the top.
func Write3Size ¶
Write3Size writes a size into a 3-byte array
Types ¶
type BIOSRegion ¶
type BIOSRegion struct {
FirmwareVolumes []*FirmwareVolume
//Metadata for extraction and recovery
ExtractPath string
// This is a pointer to the Region struct laid out in the ifd
Position *Region `json:",omitempty"`
// contains filtered or unexported fields
}
BIOSRegion represents the Bios Region in the firmware. It holds all the FVs as well as padding TODO(ganshun): handle padding
func NewBIOSRegion ¶
func NewBIOSRegion(buf []byte, r *Region) (*BIOSRegion, error)
NewBIOSRegion parses a sequence of bytes and returns a BIOSRegion object, if a valid one is passed, or an error. It also points to the Region struct uncovered in the ifd.
func (*BIOSRegion) Assemble ¶
func (br *BIOSRegion) Assemble() ([]byte, error)
Assemble assembles the Bios Region from the binary file.
func (*BIOSRegion) Extract ¶
func (br *BIOSRegion) Extract(parentPath string) error
Extract extracts the Bios Region to the directory passed in.
type FVFileType ¶
type FVFileType uint8
FVFileType represents the different types possible in an EFI file.
type File ¶
type File struct {
Header FileHeaderExtended
Sections []*Section `json:",omitempty"`
ExtractPath string
DataOffset uint64
// contains filtered or unexported fields
}
File represents an EFI File.
func CreatePadFile ¶
CreatePadFile creates an empty pad file in order to align the next file.
func NewFile ¶
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.
type FileHeader ¶
type FileHeader struct {
UUID uuid.UUID // This is the GUID of the file.
Checksum IntegrityCheck `json:"-"`
Type FVFileType
Attributes fileAttr
Size [3]uint8 `json:"-"`
State uint8 `json:"-"`
}
FileHeader represents an EFI File header.
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 Firmware ¶
type Firmware interface {
Validate() []error
Extract(dirpath string) error
Assemble() ([]byte, error)
}
Firmware is an interface to describe generic firmware types. The implementations (e.g. Flash image, or FirmwareVolume) must implement this interface.
func Parse ¶
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 ¶
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
FVOffset uint64 // Byte offset from start of BIOS region.
ExtractPath string
// 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) (*FirmwareVolume, error)
NewFirmwareVolume parses a sequence of bytes and returns a FirmwareVolume object, if a valid one is passed, or an error
func (*FirmwareVolume) Assemble ¶
func (fv *FirmwareVolume) Assemble() ([]byte, error)
Assemble assembles the Firmware Volume from the binary file. TODO: HANDLE HEADER CHANGES. We assume the FV length hasn't changed, and we assume the FV offset is the same as specified in the JSON. We also don't check that the extended header or data offset is the same. This is not something that's expected to change easily.
func (*FirmwareVolume) Extract ¶
func (fv *FirmwareVolume) Extract(parentPath string) error
Extract extracts the Firmware Volume to the directory passed in.
func (*FirmwareVolume) GetErasePolarity ¶
func (fv *FirmwareVolume) GetErasePolarity() uint8
GetErasePolarity gets the erase polarity
func (*FirmwareVolume) Validate ¶
func (fv *FirmwareVolume) Validate() []error
Validate Firmware Volume
type FirmwareVolumeExtHeader ¶
FirmwareVolumeExtHeader contains the fields of an extended firmware volume header
type FirmwareVolumeFixedHeader ¶
type FirmwareVolumeFixedHeader struct {
FileSystemGUID uuid.UUID
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) Assemble ¶
func (fd *FlashDescriptor) Assemble() ([]byte, error)
Assemble assembles the flash descriptor using the binary pointed to in ExtractPath.
func (*FlashDescriptor) Extract ¶
func (fd *FlashDescriptor) Extract(parentPath string) error
Extract extracts the flash descriptor region to the directory passed in.
func (*FlashDescriptor) ParseFlashDescriptor ¶
func (fd *FlashDescriptor) ParseFlashDescriptor() error
ParseFlashDescriptor parses the ifd from the buffer
func (*FlashDescriptor) Validate ¶
func (fd *FlashDescriptor) Validate() []error
Validate the descriptor region
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
func (*FlashDescriptorMap) Validate ¶
func (d *FlashDescriptorMap) Validate() []error
Validate runs a set of checks on the flash descriptor and returns a list of errors specifying what is wrong.
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
BIOS *BIOSRegion `json:",omitempty"`
ME *MERegion `json:",omitempty"`
GBE *GBERegion `json:",omitempty"`
PD *PDRegion `json:",omitempty"`
// Metadata for extraction and recovery
ExtractPath string
// 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) Assemble ¶
func (f *FlashImage) Assemble() ([]byte, error)
Assemble assembles the FlashImage starting from the bottom up.
func (*FlashImage) Extract ¶
func (f *FlashImage) Extract(dirPath string) error
Extract extracts the flash image to the directory passed in.
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) String ¶
func (f *FlashImage) String() string
func (*FlashImage) Validate ¶
func (f *FlashImage) Validate() []error
Validate runs a set of checks on the flash image and returns a list of errors specifying what is wrong.
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 FlashRegionSection ¶
type FlashRegionSection struct {
FlashBlockEraseSize uint16
BIOS Region
ME Region
GBE Region
PD Region
// 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 GBERegion ¶
type GBERegion struct {
//Metadata for extraction and recovery
ExtractPath string
// This is a pointer to the Region struct laid out in the ifd
Position *Region
// contains filtered or unexported fields
}
GBERegion represents the GBE Region in the firmware.
func NewGBERegion ¶
NewGBERegion parses a sequence of bytes and returns a GBERegion object, if a valid one is passed, or an error. It also points to the Region struct uncovered in the ifd.
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 ¶
IntegrityCheck holds the two 8 bit checksums for the file header and body separately.
type MERegion ¶
type MERegion struct {
//Metadata for extraction and recovery
ExtractPath string
// This is a pointer to the Region struct laid out in the ifd
Position *Region
// contains filtered or unexported fields
}
MERegion represents the ME Region in the firmware.
func NewMERegion ¶
NewMERegion parses a sequence of bytes and returns a MERegion object, if a valid one is passed, or an error. It also points to the Region struct uncovered in the ifd.
type PDRegion ¶
type PDRegion struct {
//Metadata for extraction and recovery
ExtractPath string
// This is a pointer to the Region struct laid out in the ifd
Position *Region
// contains filtered or unexported fields
}
PDRegion represents the PD Region in the firmware.
func NewPDRegion ¶
NewPDRegion parses a sequence of bytes and returns a PDRegion object, if a valid one is passed, or an error. It also points to the Region struct uncovered in the ifd.
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.
var Attributes ROMAttributes
Attributes holds the global attributes
type Region ¶
Region holds the base and limit of every type of region. Each region such as the bios region should point back to it.
func (*Region) BaseOffset ¶
BaseOffset calculates the offset into the flash image where the Region begins
type RegionPermissions ¶
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
// Type specific fields
TypeSpecific interface{} `json:",omitempty"`
// For EFI_SECTION_USER_INTERFACE
Name string `json:",omitempty"`
// Encapsulated firmware
Encapsulated *TypedFirmware `json:",omitempty"`
// contains filtered or unexported fields
}
Section represents a Firmware File Section
func NewSection ¶
NewSection parses a sequence of bytes and returns a Section object, if a valid one is passed, or an error.
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 ¶
SectionGUIDDefined contains the fields for a EFI_SECTION_GUID_DEFINED section.
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
type TypedFirmware ¶
TypedFirmware includes the Firmware interface's type when exporting it to JSON. The type is required when unmarshalling.
func (TypedFirmware) UnmarshalJSON ¶
func (f TypedFirmware) UnmarshalJSON(b []byte) error
UnmarshalJSON unmarshals a TypedFirmware struct and correctly deduces the type of the interface.