uefi

package
v0.0.0-...-06f9e6a Latest Latest
Warning

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

 Go to latest Published: Sep 15, 2025 License: BSD-3-Clause Imports: 15 Imported by: 3

README

TamaGo - bare metal Go - UEFI x64 support

go-boot | https://github.com/usbarmory/go-boot

Copyright (c) The go-boot authors. All Rights Reserved.

TamaGo gopher

Authors

Andrea Barisani
andrea@inversepath.com

Introduction

TamaGo is a framework that enables compilation and execution of unencumbered Go applications on bare metal AMD64/ARM/RISC-V processors.

The uefi and uefi/x64 packages provides support for unikernels running under the Unified Extensible Firmware Interface UEFI on an AMD64 core.

Documentation

Go Reference

For more information about TamaGo see its repository and project wiki.

For usage of these packages in the context of an UEFI application see the go-boot unikernel project.

The package API documentation can be found on pkg.go.dev.

Compiling

Go applications are simply required to import, the relevant board package to ensure that hardware initialization and runtime support take place:

import (
	_ "github.com/usbarmory/go-boot/uefi/x64"
)

Build the TamaGo compiler (or use the latest binary release):

wget https://github.com/usbarmory/tamago-go/archive/refs/tags/latest.zip
unzip latest.zip
cd tamago-go-latest/src && ./all.bash
cd ../bin && export TAMAGO=`pwd`/go

Go applications can be compiled as usual, using the compiler built in the previous step, but with the addition of the following flags/variables:

GOOS=tamago GOARCH=amd64 ${TAMAGO} build -ldflags "-E cpuinit -T $(TEXT_START) -R 0x1000" main.go

The resulting ELF must be converted to a PE32+ executable for EFI for execution under UEFI:

objcopy \
	--strip-debug \
	--target efi-app-x86_64 \
	--subsystem=efi-app \
	--image-base 0x$(IMAGE_BASE) \
	--stack=0x10000 \
	main main.efi
printf '\x26\x02' | dd of=${APP}.efi bs=1 seek=150 count=2 conv=notrunc,fsync # adjust Characteristics

An example application, targeting the UEFI environment, is go-boot.

License

go-boot | https://github.com/usbarmory/go-boot
Copyright (c) The go-boot authors. All Rights Reserved.

These source files are distributed under the BSD-style license found in the LICENSE file.

The TamaGo logo is adapted from the Go gopher designed by Renee French and licensed under the Creative Commons 3.0 Attributions license. Go Gopher vector illustration by Hugo Arganda.

Documentation

Overview

Package uefi implements a driver for the Unified Extensible Firmware Interface (UEFI) following the specifications at: 

https://uefi.org/specs/UEFI/2.10/

This package is only meant to be used with `GOOS=tamago` as supported by the TamaGo framework for bare metal Go, see https://github.com/usbarmory/tamago.

Index

Constants

View Source 
const (
	EFI_BLACK        = 0x00
	EFI_BLUE         = 0x01
	EFI_GREEN        = 0x02
	EFI_CYAN         = 0x03
	EFI_RED          = 0x04
	EFI_MAGENTA      = 0x05
	EFI_BROWN        = 0x06
	EFI_LIGHTGRAY    = 0x07
	EFI_BRIGHT       = 0x08
	EFI_DARKGRAY     = 0x08
	EFI_LIGHTBLUE    = 0x09
	EFI_LIGHTGREEN   = 0x0a
	EFI_LIGHTCYAN    = 0x0b
	EFI_LIGHTRED     = 0x0c
	EFI_LIGHTMAGENTA = 0x0d
	EFI_YELLOW       = 0x0e
	EFI_WHITE        = 0x0f
)

EFI text attributes

View Source 
const (
	EFI_SUCCESS = iota
	EFI_LOAD_ERROR
	EFI_INVALID_PARAMETER
	EFI_UNSUPPORTED
	EFI_BAD_BUFFER_SIZE
	EFI_BUFFER_TOO_SMALL
	EFI_NOT_READY
	EFI_DEVICE_ERROR
	EFI_WRITE_PROTECTED
	EFI_OUT_OF_RESOURCES
	EFI_VOLUME_CORRUPTED
	EFI_VOLUME_FULL
	EFI_NO_MEDIA
	EFI_MEDIA_CHANGED
	EFI_NOT_FOUND
	EFI_ACCESS_DENIED
	EFI_NO_RESPONSE
	EFI_NO_MAPPING
	EFI_TIMEOUT
	EFI_NOT_STARTED
	EFI_ALREADY_STARTED
	EFI_ABORTED
	EFI_ICMP_ERROR
	EFI_TFTP_ERROR
	EFI_PROTOCOL_ERROR
	EFI_INCOMPATIBLE_VERSION
	EFI_SECURITY_VIOLATION
	EFI_CRC_ERROR
	EFI_END_OF_MEDIA
	EFI_END_OF_FILE
	EFI_INVALID_LANGUAGE
	EFI_COMPROMISED_DATA
	EFI_IP_ADDRESS_CONFLICT
	EFI_HTTP_ERROR
)

EFI Status Codes

View Source 
const (
	EFI_FILE_INFO_ID = "09576e92-6d3f-11d2-8e39-00a0c969723b"

	EFI_FILE_PROTOCOL_REVISION  = 0x00010000
	EFI_FILE_PROTOCOL_REVISION2 = 0x00020000

	EFI_FILE_MODE_READ   = 0x0000000000000001
	EFI_FILE_MODE_WRITE  = 0x0000000000000002
	EFI_FILE_MODE_CREATE = 0x8000000000000000

	EFI_FILE_DIRECTORY = 0x0000000000000010
)
View Source 
const (
	MaxFileName   = 256
	MaxDirEntries = 65536
)

EFI system partition (FAT) limits

View Source 
const (
	EFI_LOADED_IMAGE_PROTOCOL_GUID             = "5b1b31a1-9562-11d2-8e3f-00a0c969723b"
	EFI_LOADED_IMAGE_DEVICE_PATH_PROTOCOL_GUID = "09576e91-6d3f-11d2-8e39-00a0c969723b"
	EFI_SIMPLE_FILE_SYSTEM_PROTOCOL_GUID       = "964e5b22-6459-11d2-8e39-00a0c969723b"

	EFI_LOADED_IMAGE_PROTOCOL_REVISION       = 0x00001000
	EFI_SIMPLE_FILE_SYSTEM_PROTOCOL_REVISION = 0x00010000
)
View Source 
const (
	EfiBltVideoFill = iota
	EfiBltVideoToBltBuffer
	EfiBltBufferToVideo
	EfiBltVideoToVideo
	EfiGraphicsOutputBltOperationMax
)

EFI_GRAPHICS_OUTPUT_BLT_OPERATION

View Source 
const (
	AllocateAnyPages = iota
	AllocateMaxAddress
	AllocateAddress
	MaxAllocateType
)

EFI_ALLOCATE_TYPE

View Source 
const (
	EfiReservedMemoryType = iota
	EfiLoaderCode
	EfiLoaderData
	EfiBootServicesCode
	EfiBootServicesData
	EfiRuntimeServicesCode
	EfiRuntimeServicesData
	EfiConventionalMemory
	EfiUnusableMemory
	EfiACPIReclaimMemory
	EfiACPIMemoryNVS
	EfiMemoryMappedIO
	EfiMemoryMappedIOPortSpace
	EfiPalCode
	EfiPersistentMemory
	EfiUnacceptedMemoryType
	EfiMaxMemoryType
)

EFI_MEMORY_TYPE

View Source 
const (
	EfiResetCold = iota
	EfiResetWarm
	EfiResetShutdown
	EfiResetPlatformSpecific
)

EFI_RESET_SYSTEM

View Source 
const AddressRangePersistentMemory = 7

Advanced Configuration and Power Interface Specification (ACPI) Version 6.0 - Table 15-312 Address Range Types12

View Source 
const EFI_GRAPHICS_OUTPUT_PROTOCOL_GUID = "9042a9de-23dc-4a38-96fb-7aded080516a"
View Source 
const PageSize = 4096 // 4 KiB

PageSize represents the EFI page size in bytes

Variables

This section is empty.

Functions

This section is empty.

Types

type BltOperation 

type BltOperation int

type BootServices 

type BootServices struct {
	// contains filtered or unexported fields
}

BootServices represents an EFI Boot Services instance.

func (*BootServices) AllocatePages 

func (s *BootServices) AllocatePages(allocateType int, memoryType int, size int, physicalAddress uint64) error

AllocatePages calls EFI_BOOT_SERVICES.AllocatePages().

func (*BootServices) Exit 

func (s *BootServices) Exit(code int) (err error)

Exit calls EFI_BOOT_SERVICES.Exit().

func (*BootServices) ExitBootServices 

func (s *BootServices) ExitBootServices() (memoryMap *MemoryMap, err error)

ExitServices calls EFI_BOOT_SERVICES.ExitBootServices(), it is the caller responsability to avoid using any EFI Boot Service after this call is successful.

func (*BootServices) FreePages 

func (s *BootServices) FreePages(physicalAddress uint64, size int) error

FreePages calls EFI_BOOT_SERVICES.FreePages().

func (*BootServices) GetGraphicsOutput 

func (s *BootServices) GetGraphicsOutput() (gop *GraphicsOutput, err error)

GetGraphicsOutput locates and returns the EFI Graphics Output Protocol instance.

func (*BootServices) GetMemoryMap 

func (s *BootServices) GetMemoryMap() (m *MemoryMap, err error)

GetMemoryMap calls EFI_BOOT_SERVICES.GetMemoryMap().

func (*BootServices) HandleProtocol 

func (s *BootServices) HandleProtocol(handle uint64, guid GUID) (addr uint64, err error)

HandleProtocol calls EFI_BOOT_SERVICES.HandleProtocol().

func (*BootServices) LoadImage 

func (s *BootServices) LoadImage(boot int, root *FS, name string) (imageHandle uint64, err error)

LoadImage calls EFI_BOOT_SERVICES.LoadImage().

func (*BootServices) LocateProtocol 

func (s *BootServices) LocateProtocol(guid GUID) (addr uint64, err error)

LocateProtocol calls EFI_BOOT_SERVICES.LocateProtocol().

func (*BootServices) SetWatchdogTimer 

func (s *BootServices) SetWatchdogTimer(sec int) (err error)

SetWatchdogTimer calls EFI_BOOT_SERVICES.SetWatchdogTimer()

func (*BootServices) StartImage 

func (s *BootServices) StartImage(imageHandle uint64) (err error)

StartImage calls EFI_BOOT_SERVICES.StartImage().

type ConfigurationTable 

type ConfigurationTable struct {
	GUID        [16]byte
	VendorTable uint64
}

Configuration represents an EFI Configuration Table.

func (*ConfigurationTable) RegistryFormat 

func (d *ConfigurationTable) RegistryFormat() string

RegistryFormat returns the table EFI GUID in registry format.

type Console 

type Console struct {
	io.ReadWriter

	// ForceLine controls whether line feeds (LF) should be supplemented
	// with a carriage return (CR).
	ForceLine bool

	// ReplaceTabs controls whether Console I/O output should have Tab
	// characters replaced with a number of spaces.
	ReplaceTabs int

	// In should be set to the EFI SystemTable ConIn address.
	In uint64
	// Out should be set to the EFI SystemTable ConOut address.
	Out uint64
}

Console implements the io.ReadWriter interface over EFI Simple Text Input/Output protocol.

func (*Console) ClearScreen 

func (c *Console) ClearScreen() error

ClearScreen calls EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL.ClearScreen().

func (*Console) Input 

func (c *Console) Input(k *InputKey) (status uint64)

Input calls EFI_SIMPLE_TEXT_INPUT_PROTOCOL.ReadKeyStroke().

func (*Console) Output 

func (c *Console) Output(p []byte) (status uint64)

Output calls EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL.OutputString().

func (*Console) Read 

func (c *Console) Read(p []byte) (n int, err error)

Read available data to buffer from console.

func (*Console) SetAttribute 

func (c *Console) SetAttribute(attr uint64) error

SetAttribute calls EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL.SetAttribute().

func (*Console) SetMode 

func (c *Console) SetMode(mode uint64) error

SetMode calls EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL.SetMode().

func (*Console) Write 

func (c *Console) Write(p []byte) (n int, err error)

Write data from buffer to console.

type DevicePath 

type DevicePath struct {
	DevicePathNode
	Data []byte
}

DevicePath represents an EFI Device Path Protocol node.

type DevicePathNode 

type DevicePathNode struct {
	Type    uint8
	SubType uint8
	Length  uint16
}

DevicePath represents an EFI Generic Device Path Node structure.

func (*DevicePathNode) Bytes 

func (d *DevicePathNode) Bytes() []byte

Bytes converts the descriptor structure to byte array format.

type DirEntry 

type DirEntry struct {
	// contains filtered or unexported fields
}

DirEntry implements the fs.DirEntry interface for the EFI File Protocol.

func (DirEntry) Info 

func (d DirEntry) Info() (fs.FileInfo, error)

Info returns the FileInfo for the file or subdirectory described by the entry.

func (DirEntry) IsDir 

func (d DirEntry) IsDir() bool

IsDir reports whether the entry describes a directory.

func (DirEntry) Name 

func (d DirEntry) Name() string

Name returns the name of the (or subdirectory) described by the entry.

func (DirEntry) Type 

func (d DirEntry) Type() fs.FileMode

Type returns the file mode bits.

type FS 

type FS struct {
	// contains filtered or unexported fields
}

FS implements the fs.FS interface for an EFI Simple File System.

func (*FS) FilePath 

func (root *FS) FilePath(name string) (devicePath []*DevicePath, filePath *FilePath, desc []byte, err error)

FilePath returns the full EFI Device Path associated with the named file.

func (*FS) Open 

func (root *FS) Open(name string) (fs.File, error)

Open opens the named file File.Close must be called to release any associated resources.

type File 

type File struct {
	// contains filtered or unexported fields
}

File implements the fs.File interface for the EFI File Protocol.

func (*File) Close 

func (f *File) Close() (err error)

Close closes the File, rendering it unusable for I/O.

func (*File) Read 

func (f *File) Read(b []byte) (n int, err error)

Read reads up to len(b) bytes from the File and stores them in b. It returns the number of bytes read and any error encountered. At end of file, Read returns 0, io.EOF.

func (*File) ReadDir 

func (f *File) ReadDir(n int) (entries []fs.DirEntry, err error)

ReadDir reads the contents of the directory and returns a slice of up to n DirEntry values in directory order. Subsequent calls on the same file will yield further DirEntry values.

func (*File) Stat 

func (f *File) Stat() (fs.FileInfo, error)

Stat returns a FileInfo describing the named file from the file system.

type FileInfo 

type FileInfo struct {
	// contains filtered or unexported fields
}

FileInfo implements the fs.FileInfo interface for the EFI File Protocol.

func (*FileInfo) IsDir 

func (fi *FileInfo) IsDir() bool

IsDir reports whether the entry describes a directory.

func (*FileInfo) ModTime 

func (fi *FileInfo) ModTime() time.Time

ModTime returns the file modification time.

func (*FileInfo) Mode 

func (fi *FileInfo) Mode() fs.FileMode

Mode returns the file mode bits.

func (*FileInfo) Name 

func (fi *FileInfo) Name() string

Name returns the name of the file (or subdirectory) described by the entry.

func (*FileInfo) Size 

func (fi *FileInfo) Size() int64

Size returns the file length in bytes.

func (*FileInfo) Sys 

func (fi *FileInfo) Sys() any

Sys returns the underlying data source pointer.

type FilePath 

type FilePath struct {
	DevicePathNode
	PathName []byte
}

FilePath represents an EFI File Path Media Device Path instance.

func (*FilePath) Bytes 

func (d *FilePath) Bytes() []byte

Bytes converts the descriptor structure to byte array format.

type GUID 

type GUID string

GUID represents an EFI GUID (Globally Unique Identifier).

func (GUID) Bytes 

func (g GUID) Bytes() (guid []byte)

Bytes returns the GUID as byte slice.

type GraphicsOutput 

type GraphicsOutput struct {
	// contains filtered or unexported fields
}

GraphicsOutput represents an EFI Graphics Output Protocol instance.

func (*GraphicsOutput) Blt 

func (gop *GraphicsOutput) Blt(buf []byte, op BltOperation, srcX, srcY, dstX, dstY, width, height, delta uint64) (err error)

Blt calls EFI_GRAPHICS_OUTPUT_PROTCOL.Blt().

func (*GraphicsOutput) GetMode 

func (gop *GraphicsOutput) GetMode() (pm *ProtocolMode, err error)

GetMode returns the EFI Graphics Output Mode instance.

type InputKey 

type InputKey struct {
	ScanCode    uint16
	UnicodeChar [2]byte
}

InputKey represents an EFI Input Key descriptor.

type MemoryDescriptor 

type MemoryDescriptor struct {
	Type uint32

	PhysicalStart uint64
	VirtualStart  uint64
	NumberOfPages uint64
	Attribute     uint64
	// contains filtered or unexported fields
}

MemoryDescriptor represents an EFI Memory Descriptor

func (*MemoryDescriptor) E820 

func (d *MemoryDescriptor) E820() bzimage.E820Entry

E820 converts an EFI Memory Map entry to an x86 E820 one suitable for use after exiting EFI Boot Services.

func (*MemoryDescriptor) PhysicalEnd 

func (d *MemoryDescriptor) PhysicalEnd() uint64

End returns the descriptor physical end address.

func (*MemoryDescriptor) Size 

func (d *MemoryDescriptor) Size() int

Size returns the descriptor size.

type MemoryMap 

type MemoryMap struct {
	MapSize           uint64
	Descriptors       []*MemoryDescriptor
	MapKey            uint64
	DescriptorSize    uint64
	DescriptorVersion uint32
	// contains filtered or unexported fields
}

MemoryMap represents an EFI Memory Map

func (*MemoryMap) Address 

func (m *MemoryMap) Address() uint64

Address returns the EFI Memory Map pointer.

func (*MemoryMap) E820 

func (m *MemoryMap) E820() (e820 []bzimage.E820Entry)

E820 converts an EFI Memory Map to an x86 E820 one suitable for use after exiting EFI Boot Services.

type ModeInformation 

type ModeInformation struct {
	Version              uint32
	HorizontalResolution uint32
	VerticalResolution   uint32
	PixelFormat          uint32
	RedMask              uint32
	GreenMask            uint32
	BlueMask             uint32
	ReservedMask         uint32
	PixelsPerScanLine    uint32
}

ModeInformation represents an EFI Graphics Output Mode Information instance.

type ProtocolMode 

type ProtocolMode struct {
	MaxMode         uint32
	Mode            uint32
	Info            uint64
	SizeOfInfo      uint64
	FrameBufferBase uint64
	FrameBufferSize uint64
}

ProtocolMode represents an EFI Graphics Output Protocol Mode instance.

func (*ProtocolMode) GetInfo 

func (d *ProtocolMode) GetInfo() (mi *ModeInformation, err error)

GetInfo returns the EFI Graphics Output Mode information instance.

type RuntimeServices 

type RuntimeServices struct {
	// contains filtered or unexported fields
}

RuntimeServices represents an EFI Runtime Services instance.

func (*RuntimeServices) ResetSystem 

func (s *RuntimeServices) ResetSystem(resetType int) (err error)

ResetSystem calls EFI_RUNTIME_SERVICES.ResetSystem().

type Services 

type Services struct {
	// EFI System Table instance
	SystemTable *SystemTable

	// UEFI services
	Console *Console
	Boot    *BootServices
	Runtime *RuntimeServices
	// contains filtered or unexported fields
}

Services represents the UEFI services instance.

func (*Services) Address 

func (s *Services) Address() uint64

Address returns the EFI System Table pointer.

func (*Services) ImageHandle 

func (s *Services) ImageHandle() uint64

Handle returns the UEFI image handle pointer.

func (*Services) Init 

func (s *Services) Init(imageHandle uint64, systemTable uint64) (err error)

Init initializes an UEFI services instance using the argument pointers.

func (*Services) Root 

func (s *Services) Root() (root *FS, err error)

Root returns an EFI Simple File System instance for the current EFI image root volume.

type SystemTable 

type SystemTable struct {
	Header           TableHeader
	FirmwareVendor   uint64
	FirmwareRevision uint32

	ConsoleInHandle      uint64
	ConIn                uint64
	ConsoleOutHandle     uint64
	ConOut               uint64
	StandardErrorHandle  uint64
	StdErr               uint64
	RuntimeServices      uint64
	BootServices         uint64
	NumberOfTableEntries uint64
	ConfigurationTable   uint64
	// contains filtered or unexported fields
}

SystemTable represents the EFI System Table, containing pointers to the runtime and boot services tables.

func (*SystemTable) ConfigurationTables 

func (d *SystemTable) ConfigurationTables() (c []*ConfigurationTable, err error)

ConfigurationTables returns the EFI Configuration Tables.

func (*SystemTable) Revision 

func (d *SystemTable) Revision() string

Revision returns the EFI Specification revision string.

type TableHeader 

type TableHeader struct {
	Signature  uint64
	Revision   uint32
	HeaderSize uint32
	CRC32      uint32
	Reserved   uint32
}

TableHeader represents the data structure that precedes all of the standard EFI table types.

Source Files

View all Source files

Directories

Path Synopsis
Package x64 provides hardware initialization, automatically on import, for the Unified Extensible Firmware Interface (UEFI) application environment under a single x86_64 core.
 Package x64 provides hardware initialization, automatically on import, for the Unified Extensible Firmware Interface (UEFI) application environment under a single x86_64 core.

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.