> For the complete documentation index, see [llms.txt](https://docs.enclaive.cloud/sylica/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.enclaive.cloud/sylica/tutorials/understand-the-architecture.md). # Understand the architecture This document gives an overview about the CVMF architecture, components and design decisions. ## Sylica CVMF Architecture CVMF — **Confidential Virtual Machine Firmware** — is Sylica's UEFI firmware architecture for virtual machines. It provides a controlled firmware foundation for: * AMD SEV-SNP confidential virtual machines; * Intel TDX confidential virtual machines; * conventional x86 virtual machines. CVMF is based on EDK2/OVMF but uses Sylica-specific platform configurations, libraries, drivers, security settings, and build controls. The architectural objective is to provide a firmware layer that is: * small and purpose-built for virtual machines; * reproducibly built; * cryptographically identifiable; * suitable for confidential-computing measurement; * consistent across confidential and conventional VM environments; * easier to review and maintain than a general-purpose firmware configuration. ### Role in the VM architecture Every virtual machine requires firmware to initialize the virtual hardware and transfer control to the operating system. For a conventional VM: ``` Physical host │ ▼ Hypervisor │ ▼ CVMF │ ▼ UEFI boot environment │ ▼ Boot image / operating system ``` For a confidential VM, CVMF additionally becomes part of the hardware-backed trust chain: ``` CPU security technology SEV-SNP / TDX │ ▼ Confidential VM │ ▼ CVMF │ ▼ Boot workload │ ▼ Operating system │ ▼ Application ``` The CPU confidential-computing mechanism protects the VM boundary, while CVMF establishes the firmware environment inside that boundary. CVMF therefore sits between the hardware-backed confidential-computing mechanism and the guest workload. ### Trust chain For confidential computing, the firmware is security-critical because it executes before the operating system. The expected trust chain is: ``` CPU hardware │ ▼ SEV-SNP / TDX │ ▼ CVMF │ ▼ boot image │ ▼ guest operating system │ ▼ workload ``` CVMF is designed so that the firmware binary can be independently rebuilt and verified before its expected measurement is accepted by an attestation policy. This creates two related verification paths. #### Artifact verification ``` Sylica source │ ▼ Reproducible build │ ▼ CVMF.fd │ ▼ SHA-256 │ ▼ Published firmware digest ``` This establishes which source and build environment produced the firmware artifact. #### Runtime verification For a confidential VM: ``` Expected CVMF │ ▼ Expected launch state │ ▼ SEV-SNP / TDX measurement │ ▼ Hardware attestation │ ▼ Policy decision ``` Artifact reproducibility and hardware attestation solve different problems: * reproducibility establishes the relationship between source and firmware; * attestation establishes the relationship between the expected firmware and a running confidential VM. ### Architecture overview CVMF follows the standard EDK2 execution model while using Sylica-specific platform definitions. At a high level: ``` CVMF.fd │ ▼ Reset / SEC phase │ ▼ Early platform setup │ ▼ PEI / DXE transition │ ▼ DXE core │ ┌─────────────┼─────────────┐ ▼ ▼ ▼ CPU/platform devices security drivers and ACPI services │ │ │ └─────────────┼─────────────┘ ▼ BDS │ ▼ Sylica Boot Manager │ ▼ Boot image / UKI │ ▼ ExitBootServices │ ▼ Guest operating system ``` The exact early boot sequence differs between AMD SEV-SNP and Intel TDX, but both converge on the UEFI DXE and boot-management environment. ### EDK2 architecture CVMF is constructed from the EDK2 module model. The important source layers are: ``` edk2/ │ ├── MdePkg ├── MdeModulePkg ├── UefiCpuPkg ├── OvmfPkg │ └── other upstream packages │ ▼ SylicaOss/ │ ├── platform DSCs ├── firmware FDFs ├── drivers ├── libraries └── Sylica configuration │ ▼ CVMF.fd ``` Sylica does not replace EDK2 as a firmware framework. Instead, it defines a controlled EDK2 distribution and platform configuration that determines: * which modules are compiled; * which libraries satisfy EDK2 interfaces; * how firmware volumes are constructed; * which security functionality is enabled; * how the VM boot process behaves; * how the final firmware artifact is built and verified. ### Platform definitions The principal CVMF platform definitions are: ``` SylicaOss/ ├── SylicaOssSev.dsc ├── SylicaOssSev.fdf ├── SylicaOssTdx.dsc └── SylicaOssTdx.fdf ``` The DSC files define the EDK2 platform build. They select: * packages; * library instances; * drivers; * platform configuration values; * feature flags; * build options. The FDF files define how the resulting modules are arranged into firmware volumes and ultimately into `CVMF.fd`. Conceptually: ``` DSC │ │ selects modules and libraries ▼ EDK2 build │ ▼ PE/COFF firmware modules │ │ arranged according to ▼ FDF │ ▼ Firmware volumes │ ▼ CVMF.fd ``` ### Unified firmware image Sylica distributes CVMF as a single firmware image: ``` CVMF.fd ``` Rather than exposing separate CODE and VARS firmware files, the CVMF FDF configuration constructs a unified flash-device image. ``` CVMF.fd │ ┌──────────┴──────────┐ │ │ variable area firmware volumes │ ├── SEC ├── PEI / DXE └── platform modules ``` A single image provides a deterministic artifact that can be: * reproducibly built; * cryptographically hashed; * distributed as one release artifact; * referenced by attestation and policy systems; * supplied directly to supported VM runtimes. The production Sylica variants use `CVMF.fd`; upstream reference builds retain the conventional `OVMF.fd` name. ### Firmware volumes EDK2 groups firmware modules into **Firmware Volumes (FVs)**. CVMF uses different volumes for different parts of the firmware lifecycle. #### SECFV `SECFV` contains the code that executes immediately after the virtual CPU reset. Its primary responsibilities are early firmware startup and establishing the execution environment required to continue the boot process. Conceptually: ``` CPU reset │ ▼ Reset Vector │ ▼ SECFV │ ├── initial CPU state ├── confidential-computing startup └── locate/decompress later firmware ``` For AMD SEV-SNP, `SECFV` contains the standard OVMF SEC implementation together with the reset vector. For Intel TDX, the corresponding volume uses the TDX-specific EDK2 SEC implementation. This is one of the main places where the two confidential-computing architectures diverge. #### PEIFV The AMD SEV-SNP architecture contains a dedicated `PEIFV`. PEI — **Pre-EFI Initialization** — establishes enough of the platform environment to start DXE. Important modules include: ``` PEI Core │ ├── PCD services ├── platform initialization ├── CPU initialization └── DXE IPL │ ▼ DXE ``` The PEI phase performs early platform discovery and preparation while operating with a deliberately limited firmware environment. #### DXEFV `DXEFV` contains the majority of the UEFI execution environment. DXE — **Driver Execution Environment** — starts the DXE Core and loads the firmware drivers required to expose the UEFI platform to the operating system. Typical architectural functions include: ``` DXE Core │ ├── CPU services ├── PCI ├── ACPI ├── variables ├── console ├── timers ├── device paths ├── boot services ├── runtime services └── confidential-computing drivers ``` CVMF deliberately controls which modules are included in this phase because DXE normally contains much of the functionality — and therefore much of the computing base — of UEFI firmware. #### FVMAIN\_COMPACT `FVMAIN_COMPACT` is the compact firmware volume embedded in the flash image. It contains compressed firmware volumes that are expanded during early boot. For the SEV platform: ``` FVMAIN_COMPACT │ ▼ compressed container │ ├── PEIFV └── DXEFV ``` Compressing the major firmware volumes allows the flash representation to remain compact while providing larger in-memory firmware volumes during execution. #### TDX NCCFV The Intel TDX firmware architecture additionally defines `NCCFV`. `NCCFV` contains firmware components that are separated from the primary confidential DXE volume according to the TDX platform architecture. The TDX memory firmware device therefore contains separate DXE and non-confidential firmware regions: ``` TDX firmware memory │ ├── DXEFV │ │ │ └── confidential DXE environment │ └── NCCFV │ └── non-CC platform components ``` This organization reflects requirements of the TDX firmware execution model and differs from the AMD SEV-SNP layout. ### Boot phases A simplified CVMF boot sequence is: ``` Reset │ ▼ SEC │ ▼ PEI / early platform initialization │ ▼ DXE │ ▼ BDS │ ▼ Sylica Platform Boot Manager │ ▼ UEFI application / UKI │ ▼ Operating system ``` #### SEC The Security phase is the first EDK2 execution phase. It establishes the minimal environment required to continue booting and transfers control to the next firmware phase. Because this code runs at the very beginning of VM execution, it is particularly relevant to confidential-computing measurements. #### PEI PEI performs early initialization and prepares resources for DXE. SEV-SNP follows an architecture containing a conventional PEI firmware volume. TDX uses its TDX-specific early boot architecture before entering the main DXE environment. #### DXE DXE establishes the full UEFI firmware environment. It discovers platform services, initializes devices, and exposes protocols to later boot components. #### BDS BDS — **Boot Device Selection** — decides what firmware should boot. CVMF replaces parts of the generic OVMF platform boot-management behavior with Sylica's `PlatformBootManager`. The goal is to provide predictable boot behavior for VM workloads rather than emulate the broad range of boot environments expected by physical-machine firmware. ### Sylica Platform Boot Manager The Sylica-specific boot manager is located under: ``` SylicaOss/Library/PlatformBootManager/ ``` Its architecture includes: ``` PlatformBootManager │ ├── BdsPlatform │ └── boot policy │ ├── QemuKernel │ └── QEMU-provided boot image │ └── Console └── VM console configuration ``` The boot manager provides the policy layer between the generic EDK2 BDS implementation and the virtual-machine boot environment. Keeping VM-specific boot policy in a dedicated library makes the behavior explicit and avoids relying solely on generic OVMF platform policy. ### QEMU firmware interface CVMF interacts with QEMU through the QEMU firmware configuration interface, commonly known as `fw_cfg`. Architecturally: ``` QEMU │ │ fw_cfg ▼ CVMF QemuFwCfg │ ▼ QemuLoader │ ├── boot image ├── initrd ├── command line └── injected EFI files │ ▼ UEFI boot manager ``` The Sylica source tree provides dedicated components for this interface: ``` SylicaOss/ ├── Library/QemuFwCfg/ ├── Library/QemuLoadImage/ └── Driver/QemuLoader/ ``` ### QemuLoader `QemuLoader` exposes selected content supplied through QEMU to the UEFI environment. Supported loader items include: ``` kernel initrd cmdline EFI\BOOT\BOOTX64.EFI startup.nsh ``` The driver presents injected content using standard UEFI interfaces rather than requiring later boot components to understand the QEMU `fw_cfg` protocol directly. Conceptually: ``` QEMU fw_cfg │ ▼ QemuLoader │ ├── EFI Simple File System └── EFI LoadFile2 │ ▼ standard UEFI consumers ``` This separation is important architecturally: ``` QEMU-specific transport │ ▼ QemuLoader │ ▼ standard UEFI protocols │ ▼ boot components ``` The higher layers of the boot chain therefore do not need to depend directly on QEMU-specific mechanisms. ### Booting a Unified Kernel Image A typical Sylica boot architecture can use a Unified Kernel Image (UKI): ``` QEMU │ ▼ CVMF │ ▼ Sylica Platform Boot Manager │ ▼ UKI │ ├── EFI stub ├── Linux kernel ├── initrd ├── command line └── optional metadata │ ▼ Linux ``` A UKI is itself an EFI executable, allowing firmware to transfer control directly to the operating-system boot image without requiring a traditional multi-stage PC boot chain. Where Secure Boot is enabled, firmware signature verification provides a trust boundary between CVMF and the EFI boot image. ### Secure Boot CVMF can establish the UEFI Secure Boot boundary between firmware and subsequent EFI executables. Conceptually: ``` CVMF │ │ verifies signature ▼ EFI boot image / UKI │ ▼ Kernel ``` Secure Boot answers: > Is this boot image authorized by the firmware's configured signing policy? It is different from confidential-computing attestation, which answers: > What environment did the hardware establish and measure? A confidential VM may therefore combine: ``` Hardware attestation + CVMF verification + UEFI Secure Boot = measured and authenticated boot chain ``` ### AMD SEV-SNP architecture The AMD platform is built from: ``` SylicaOss/SylicaOssSev.dsc SylicaOss/SylicaOssSev.fdf ``` Its high-level architecture is: ``` AMD Secure Processor │ ▼ SEV-SNP VM launch │ ▼ Reset Vector │ ▼ SECFV │ ▼ PEIFV │ ▼ DXEFV │ ├── AmdSevDxe ├── CPU ├── PCI ├── ACPI ├── variables ├── QemuLoader └── BDS │ ▼ Sylica Boot Manager │ ▼ boot workload ``` The SEV-SNP-specific EDK2 components detect and configure the confidential guest environment. When the same underlying SEV-capable platform is used as `sylica-x86` without an SEV guest context, the SEV-specific execution paths remain inactive. This allows the architecture to serve both: ``` sylica-sev │ └── AMD confidential VM sylica-x86 │ └── conventional VM ``` ### Intel TDX architecture The Intel platform is built from: ``` SylicaOss/SylicaOssTdx.dsc SylicaOss/SylicaOssTdx.fdf ``` Its high-level architecture is: ``` Intel TDX Module │ ▼ TD launch │ ▼ TDX Reset / SEC │ ▼ TDX firmware memory │ ├── DXEFV │ ├── TdxDxe │ ├── CC measurement protocol │ ├── CPU │ ├── devices │ └── QemuLoader │ └── NCCFV └── non-CC platform components │ ▼ BDS │ ▼ Sylica Boot Manager │ ▼ boot workload ``` The architecture follows Intel TDX's firmware requirements while maintaining the same higher-level CVMF model used by the AMD platform. ### Conventional x86 architecture `sylica-x86` uses the SEV-capable CVMF platform on a conventional VM. No confidential-computing hardware feature is required. ``` x86 host │ ▼ KVM/QEMU │ ▼ sylica-x86 │ ▼ CVMF.fd │ ▼ UEFI boot │ ▼ guest OS ``` Without an SEV guest context: ``` SEV detection │ ▼ not active │ ▼ normal UEFI VM boot ``` This gives conventional virtual machines access to the same controlled firmware architecture without claiming confidential-computing isolation. The benefit of `sylica-x86` is instead a **reduced and controlled firmware computing base**. ### Reduced computing base Firmware executes with extensive privilege before the operating system assumes control. Consequently, every included firmware component contributes to: * the attack surface; * the maintenance burden; * the amount of code that requires review; * the number of dependencies that must remain secure; * the complexity of reasoning about the boot process. CVMF is designed for virtual machines rather than physical PCs and can therefore avoid functionality that is not required by the supported virtual environment. The architectural objective is: ``` General-purpose firmware │ ▼ large compatibility surface │ ▼ large computing base ``` versus: ``` CVMF │ ▼ VM-focused functionality │ ▼ reduced computing base │ ├── smaller review surface ├── fewer unnecessary components ├── simpler lifecycle management └── clearer trust boundary ``` The reduced computing base is beneficial for both confidential and conventional virtual machines. Confidential computing adds a hardware trust boundary; it does not remove the need to minimize the firmware that runs inside that boundary. ### Sylica-specific components The Sylica platform package contains a deliberately small set of Sylica-specific architectural components: ``` SylicaOss/ │ ├── Driver/ │ └── QemuLoader/ │ ├── Library/ │ ├── BlobVerifier/ │ ├── PlatformBootManager/ │ ├── QemuFwCfg/ │ ├── QemuLoadImage/ │ └── Tdx/ │ ├── Include/ │ ├── SylicaOss.dec │ ├── SylicaOssSev.dsc ├── SylicaOssSev.fdf ├── SylicaOssTdx.dsc └── SylicaOssTdx.fdf ``` Each layer has a distinct responsibility. | Component | Architectural responsibility | | --------------------- | --------------------------------------------------------- | | Platform DSC | Select firmware components and library implementations | | Platform FDF | Define firmware image and firmware-volume layout | | `PlatformBootManager` | Define VM boot policy | | `QemuFwCfg` | Access host-supplied QEMU firmware configuration | | `QemuLoader` | Expose host-provided boot blobs through UEFI protocols | | `QemuLoadImage` | Integrate QEMU-provided images into the boot path | | `BlobVerifier` | Verification support for externally supplied boot content | | TDX libraries | TDX-specific platform integration | This keeps Sylica-specific behavior separated from the upstream EDK2 framework. ### Build architecture The firmware architecture is complemented by a reproducible build architecture. Both development and release builds ultimately invoke: ``` reproduce/build.sh ``` The build flow is: ``` platforms/.json │ ▼ reproduce/build.sh │ ▼ platform DSC │ ▼ EDK2 build │ ▼ platform FDF │ ▼ CVMF.fd │ ├── sha256sums └── b2sums ``` For releases, this process runs inside the pinned and network-isolated container build environment. See [Building Sylica Firmware](/sylica/tutorials/building-sylica-firmware.md) and [Reproducible Builds](/sylica/tutorials/reproducing-builds.md). ### Security architecture CVMF's security architecture combines several independent controls. ``` Source control │ ▼ pinned EDK2 │ ▼ reproducible build │ ▼ CVMF.fd │ ┌───────────┴───────────┐ ▼ ▼ artifact verification reduced computing base │ │ └───────────┬───────────┘ ▼ VM initialization │ ┌───────────┴────────────┐ ▼ ▼ SEV-SNP / TDX Secure Boot attestation │ │ ▼ │ authorized UKI └───────────┬────────────┘ ▼ workload ``` These mechanisms should not be conflated. | Mechanism | Protects against / establishes | | ------------------------- | --------------------------------------------------- | | Reduced computing base | Limits firmware functionality that must be trusted | | Reproducible builds | Links published binary to source and build inputs | | Firmware hash | Identifies an exact `CVMF.fd` artifact | | SEV-SNP / TDX measurement | Identifies hardware-established VM launch state | | Hardware attestation | Cryptographically reports the confidential VM state | | Secure Boot | Authorizes subsequent EFI executables | | Controlled boot policy | Limits and defines supported boot paths | Together they provide a layered firmware security model. ### Runtime boundary CVMF owns the VM from virtual CPU reset until control is transferred to the boot workload. ``` VM creation │ ▼ ┌──────────────────────────────┐ │ CVMF │ │ │ │ Reset │ │ SEC │ │ PEI / early initialization │ │ DXE │ │ BDS │ │ Secure Boot │ │ Boot Manager │ └──────────────┬───────────────┘ │ │ transfer control ▼ ┌──────────────────────────────┐ │ Guest workload │ │ │ │ UKI / bootloader │ │ Kernel │ │ Initrd │ │ Operating system │ └──────────────────────────────┘ ``` After `ExitBootServices()`, the operating system owns most resources previously managed by UEFI. Only UEFI Runtime Services intentionally exposed by the firmware remain available to the guest. ### Design principles CVMF follows five architectural principles. #### 1. Minimize the firmware computing base Only functionality required by the supported VM environments should be included. #### 2. Keep platform differences explicit AMD SEV-SNP and Intel TDX have different early-boot and measurement architectures. CVMF keeps those differences in platform definitions and technology-specific components while sharing higher-level UEFI behavior. #### 3. Use standard UEFI interfaces above platform-specific mechanisms For example, QEMU-specific boot blobs are translated into standard UEFI protocols before being consumed by higher boot layers. #### 4. Make the firmware artifact independently verifiable The resulting `CVMF.fd` is deterministic and can be reproduced and compared with published release hashes. #### 5. Separate build trust from runtime trust Reproducibility establishes how the firmware was built. Hardware attestation establishes what confidential VM was launched. Secure Boot establishes which subsequent EFI executable is authorized. These controls form separate but complementary parts of the trust chain. ### Architecture summary CVMF can be summarized as: ``` Sylica CVMF │ ┌─────────────────┼─────────────────┐ │ │ │ ▼ ▼ ▼ AMD SEV-SNP Intel TDX Conventional x86 │ │ │ └─────────────────┼─────────────────┘ │ ▼ controlled EDK2 platform │ ▼ reduced firmware computing base │ ▼ CVMF.fd │ ┌───────────────┼───────────────┐ ▼ ▼ ▼ reproducibility attestation Secure Boot │ │ │ └───────────────┼───────────────┘ ▼ trusted boot workload ``` CVMF is therefore not only a replacement firmware binary. It is the firmware layer that connects Sylica's **minimal computing base**, **reproducible software supply chain**, **UEFI boot policy**, and **confidential-computing attestation model** into a single VM architecture.