qiling/ARCHITECTURE/modules/uefi.md

eatmycode_version

eatmycode_version
2.1.0

UEFI Services

Owner: Project architecture

Read when: changing qiling/os/uefi/, DXE/SMM service tables, protocols, events or UEFI module execution.

Responsibility and Status

Owns UEFI service/API behavior, protocol definitions, DXE/SMM contexts and firmware events/callbacks. In progress: two direct UEFI integration tests pass; they do not establish complete firmware or SMM conformance. The UEFI PE loader owns mapping, service-table installation and module queues.

Code Map

Path / symbol	Role
uefi.py: QlOsUefi	Calls, module callbacks, execution and selected OS state
fncc.py: dxeapi	Typed service hooks and interception
context.py: DxeContext, SmmContext	Context-owned heaps, protocols and configuration state
bs.py, rt.py, ds.py, smst.py, smm.py, protocols/	Service tables, SMM environment and protocol hooks
UefiSpec.py, ProcessorBind.py, guids.csv, __init__.py	ABI types and GUID names
test_uefi.py, qiling/profiles/uefi.ql	API interception and sanitized heap integration

Local Conventions

The root baseline applies; retain specification casing and ordered ctypes fields. Service handlers use dxeapi and explicit parameter types. type64.py is reference-only and raises on import; do not use it as runtime definitions. No reproducible regeneration pipeline for that reference file is established; runtime layout changes belong in the actual spec/bindings/protocol definitions.

Contracts and Invariants

• Function calls use cdecl for 32-bit and ms64 for 64-bit state. Service hooks resolve by function name; set_api adapts user targets, and the decorator applies CALL/ENTER/EXIT hooks (uefi.py, fncc.py).
• Context protocols and heaps are initialized with the PE/UEFI loader. Preserve DXE versus SMM context selection, GUID identity, native-width fields and protocol callback signatures.
• Module-enter/module-exit callbacks can thwart subsequent execution; queue/event/notification state and saved heap state live partly in the loader. QlOsUefi.save() only extends base state with its entry point.
• Guest structure addresses and buffer lengths must be validated before shared memory/heap access. A handler stub returning success is not proof of specification conformance.

Dependencies and Boundaries

Read loaders for image queues/context installation/snapshots, OS base for struct/fcall/heap changes, arch for ABI width, and extensions when sanitizer/coverage hooks change. UEFI shares PE parsing infrastructure, not Windows API semantics.

Change Guide

Change trigger	Inspect / extend	Required docs / checks
Service/protocol	Descriptor layout, decorator, GUID and context	Direct UEFI script plus target service assertions
Event/module scheduling	Queue notifications, loader context callbacks	Read loader; module order/interception regression
SMM or snapshot	OS/loader state split and context memory	Read loader and OS base; explicit restoration/state evidence

Verification

From tests/: python test_uefi.py with root dependencies and examples/rootfs/x8664_efi fixtures. Both tests passed during the latest refresh; they exercise interception and sanitized heap behavior. Do not substitute python -m unittest test_uefi: actual bodies are guarded by __main__. For package/coverage output changes also use the CLI coverage test through extensions.

Known Gaps

Coverage is narrow relative to the service/protocol surface. Full SMM, 32-bit firmware and complete state restoration were not verified. type64.py is an intentionally unusable reference artifact, not a second supported runtime ABI. Keep unimplemented service behavior explicit.