Skip to content

os-windows.md

Latest commit

 

History

History
59 lines (44 loc) · 3.47 KB

os-windows.md

File metadata and controls

59 lines (44 loc) · 3.47 KB
Raw

OS Windows family — Windows, UEFI, DOS

Goal

Emulate API-call-driven (rather than syscall-driven) environments. Windows: Win32/NT API emulation with handles, registry, and PE process structures. UEFI: boot/runtime/SMM services and protocol database for DXE/SMM modules. DOS: BIOS/DOS interrupt services for COM/EXE/MBR targets. Mature released infrastructure; maturity-based status.

Status

done — Windows PE suite runs in CI on a Windows host; UEFI and DOS suites run on Linux. Windows tests are platform-gated locally (need collected DLLs).

Code Structure

File Role
qiling/os/windows/windows.py QlOsWindows: component setup (handles, registry, clipboard, fiber), run loop
qiling/os/windows/dlls/ Win32 API implementations per DLL (kernel32/, ntdll.py, msvcrt.py, advapi32.py, …)
qiling/os/windows/fncc.py, api.py Decorators declaring API signatures/calling conventions
qiling/os/windows/handle.py, registry.py, clipboard.py, fiber.py, thread.py, structs.py Windows kernel-object emulation
qiling/os/uefi/uefi.py QlOsUefi run loop
qiling/os/uefi/bs.py, rt.py, ds.py, smm.py, protocols/ Boot/runtime/DXE/SMM services and protocol implementations
qiling/os/uefi/context.py UEFI execution contexts populated by the loader
qiling/os/dos/dos.py QlOsDos run loop
qiling/os/dos/interrupts/ INT 10h/13h/15h/16h/21h… service handlers

Key Types and Entry Points

  • qiling/os/windows/windows.py:33 - QlOsWindows(QlOs) - __setup_components (:156) builds handle manager/registry/clipboard/fiber; run() (:201).
  • qiling/os/windows/fncc.py - @winsdkapi decorator - declares an API's calling convention and typed params; implementations live in dlls/.
  • API dispatch is address-based: IAT addresses recorded by the PE loader are hooked and marshalled through QlFunctionCall — user overrides via QlOs.set_api (qiling/os/os.py:225).
  • qiling/os/uefi/uefi.py:22 - QlOsUefi(QlOs) - executes DXE/SMM modules; services in bs.py/rt.py/smm.py are installed as callable tables.
  • qiling/os/dos/dos.py:33 - QlOsDos(QlOs) - dispatches BIOS/DOS interrupts from interrupts/.

Interactions

  • All three subclass os-base.md QlOs and allocate from QlMemoryHeap.
  • loader.md: QlLoaderPE builds PEB/TEB and records IAT hook addresses; QlLoaderPE_UEFI installs protocols into qiling/os/uefi/context.py; QlLoaderDOS sets real-mode state.
  • Argument marshalling uses QlFunctionCall + qiling/cc/intel.py conventions (arch.md).
  • The registry emulation reads hive files from the rootfs via os-base.md path services.
  • examples/uefi_sanitized_heap.py pairs UEFI with the heap sanitizer from extensions.md.

How to Test

cd tests && python3 test_uefi.py   # pass = unittest "OK", exit 0 (Linux-runnable)
  • Windows host only: cd tests && cmd.exe /C test_pe.bat after running examples/scripts/dllscollector.bat (CI does this in .github/workflows/build-ci.yml).
  • DOS: cd tests && python3 test_dos.py (uses scripted keyboard input).

Open Gaps / Roadmap

  • Windows tests require a Windows host: system DLLs/registry hives are not redistributable and must be collected locally.
  • Win32 API surface is demand-driven; unimplemented APIs raise QlErrorSyscallNotFound-style errors and are added as samples need them.
  • SMM emulation covers common protocols only (see qiling/os/uefi/smm.py).