.. _os-virtual-platforms:

#################
Virtual Platforms
#################

Both virtual configurations use ``MACHINE = "qemuarm64"`` and
``orchestraos-image-minimal`` with RAUC. A BSP include selects the firmware and
boot integration. Their disk files and firmware are not interchangeable.

.. list-table:: Virtual platform configurations
   :header-rows: 1

   * - Configuration
     - Manifest under ``ci/orcos/``
     - Firmware and outputs
   * - U-Boot
     - ``orcos-cmdline-rauc-qemuarm64-uboot-release.yml``
     - WIC/QCOW2 disk image, ``u-boot.bin``, and ``bootenv.img``. No installer ISO.
   * - UEFI
     - ``orcos-cmdline-rauc-qemuarm64-uefi-release.yml``
     - WIC/QCOW2 disk image, installer ISO, and ``QEMU_EFI.fd``.

The corresponding manifests without ``-release`` follow development layer
branches. Build with the access setup from :ref:`orchestra-os-quickstart`:

.. code-block:: sh

   kas-container ${REPO_ACCESS} build ci/orcos/orcos-cmdline-rauc-qemuarm64-uefi-release.yml

With the standard local working directory, outputs are under
``build/tmp/deploy/images/qemuarm64/``. The QEMU fragment adds ``wic.qcow2`` and
its checksum. Firmware is a separate deployed artifact; RAUC does not update
the VM's external firmware through an on-disk bootloader slot.

Firmware Configuration
======================

The BSP provides two includes for Poky's ``qemuarm64`` machine:

.. list-table:: Virtual platform integration
   :header-rows: 1

   * - Include
     - Boot firmware
     - Boot slot filesystem
   * - ``conf/machine/include/qemuarm64-orcos.inc``
     - U-Boot with persistent ``bootenv.img``.
     - ext4.
   * - ``conf/machine/include/qemuarm64-uefi-orcos.inc``
     - EDK2 / ``QEMU_EFI.fd`` with a writable EFI variable store.
     - FAT EFI system partitions.

Both use ``MACHINE = "qemuarm64"`` and ``/dev/vda``. Only the UEFI include
enables ISO installation support. EIG secure-boot fuses and encryption backends
are hardware-specific and do not apply to these virtual configurations.

Disk and Guest Integration
==========================

The target disk is the first virtio disk, ``/dev/vda``. Rootfs A/B,
application A/B, and data use the normal LVM provisioning flow. The initial
LVM partition is 6144 MiB and grows on first boot; allow sufficient final disk
capacity as described in :ref:`os-partition-layout`.

Both final virtual images include ``qemu-guest-agent``. The UEFI installer
initramfs also includes it and starts it when the hypervisor exposes the
``org.qemu.guest_agent.0`` virtio-serial port. The final OS uses the regular
service. In Proxmox, enable the VM's QEMU Guest Agent option and expose the
corresponding port.

For U-Boot, retain the writable ``bootenv.img`` with the VM and use it with
the matching firmware and disk image. The BSP's QEMU boot configuration
describes its pflash attachment. The following ISO procedure applies only to
UEFI.

UEFI Installer Behavior
=======================

The ISO reuses the normal OrchestraOS initramfs and activates its installer
module with ``orcos_install=1``. There is no separate installer image recipe.
Attach the ISO as a virtual CD/DVD; raw-disk and USB boot are outside this
installer configuration.

The installer checks the SHA-256 manifest for ``disk.wic.zst`` and
``disk.wic.bmap`` and copies them to the configured target with
``bmaptool copy``. Copying streams decompression and writes mapped blocks,
without staging a full uncompressed WIC in RAM. Progress appears on the
console. The installer then syncs the target and powers off.

It refuses targets with recognized partitions or signatures, mounts, holders,
or insufficient space. These guards do not detect arbitrary existing bytes
and skipped image regions are not zeroed. Use a new, zero-initialized VM disk.
The checksum detects payload corruption; it does not authenticate the ISO.

Copying does not populate LVM, write provisioning markers, or create EFI slot
entries. After removing the ISO, first disk boot runs the regular provisioning
flow described in :ref:`os-rauc-update-flow` and the architecture chapter.
An interrupted copy can leave a partial installation that the next ISO boot
refuses. Replace the target with a new unused disk before retrying.

UEFI Installation Example
=========================

Create a new 16 GiB target and two 64 MiB pflash images. Run this setup once
for a new VM, using new firmware-variable files:

.. code-block:: sh

   qemu-img create -f qcow2 orchestraos-installed.qcow2 16G
   cp build/tmp/deploy/images/qemuarm64/QEMU_EFI.fd code.fd
   truncate -s 64M code.fd
   truncate -s 64M vars.fd

The ARM ``virt`` machine uses separate flash banks for firmware code and
variables. Attach unit 0 read-only and unit 1 writable. A ``-bios`` attachment
alone does not provide the persistent variable store used here.

.. code-block:: sh

   qemu-system-aarch64 -machine virt -cpu cortex-a57 -m 2048 \
     -drive if=pflash,format=raw,unit=0,file=code.fd,readonly=on \
     -drive if=pflash,format=raw,unit=1,file=vars.fd \
     -device virtio-serial-pci \
     -chardev socket,path=qemu-ga.sock,server=on,wait=off,id=qga \
     -device virtserialport,chardev=qga,name=org.qemu.guest_agent.0 \
     -device virtio-scsi-pci,id=scsi \
     -drive if=none,id=target,format=qcow2,file=orchestraos-installed.qcow2 \
     -device virtio-blk-pci,drive=target,bootindex=1 \
     -drive if=none,id=cdrom,media=cdrom,format=raw,readonly=on,file=build/tmp/deploy/images/qemuarm64/orchestraos-image-minimal-qemuarm64.rootfs.iso \
     -device scsi-cd,drive=cdrom,bus=scsi.0,bootindex=2 -nographic

Once the installer powers off, remove the two CD/DVD attachment arguments
(``-drive ... id=cdrom`` and ``-device scsi-cd ...``), retain the target disk
and both pflash attachments, and boot again. Provisioning can reboot the guest
before normal login is available.

Keep the same ``vars.fd`` for subsequent boots. Each VM needs its own variable
store; recreating it loses EFI slot entries and BootOrder. The hypervisor owns
the QCOW2 or VDI container, while the installer writes the virtual block device
inside the guest.