README.md

Virtual Base System Architecture - Architecture Compliance Suite

Table of Contents

• Virtual Base System Architecture
• VBSA - Architecture Compliance Suite
• Release details
• Documentation & Guides
• VBSA build steps
  • UEFI Shell application
  • Linux application
• VBSA run steps
  • For UEFI application
  • For Linux application
• Application arguments
• VBSA coverage overview
• Limitations
• Troubleshoot guide
• Feedback, contributions, and support
• License

Virtual Base System Architecture

Virtual Base System Architecture (VBSA) defines the requirements and runtime features needed by a virtual environment to install, boot, and run an operating system. VBSA supplements the Arm BSA specification to target virtual platforms.

See the VBSA specification for the authoritative rules.

VBSA - Architecture Compliance Suite

VBSA ACS provides self-checking tests for virtual platforms. The majority of the tests run through the UEFI application, with a subset executed in a Linux guest environment to exercise OS-visible behavior.

Release details

• Code quality: EAC
• Latest release version: v1.0.0
• Release tag: v26.03_VBSA_1.0.0
• Specification coverage: VBSA v1.0
• Execution levels: Virtual platforms
• Scope: ACS is not a substitute for design verification.
• Test collateral: VBSA Test Scenario Document
• Prebuilt binaries: prebuilt_images/VBSA/v26.03_VBSA_1.0.0

GitHub branch

• Use the appropriate tag on the main branch for a released build.
• Track the main branch for the most recent fixes and features.

Documentation & Guides

• VBSA specification
• Arm VBSA Test Scenario Document
• Arm VBSA Testcase Checklist
• Common UEFI build guide
• Common Linux application guide
• Common CLI arguments

VBSA coverage overview

VBSA ACS combines firmware-level checks with guest-OS validation. Run each path below (and retain console logs) to claim full coverage for a virtual platform.

Sections covering VBSA rules

• UEFI-based tests — execute Vbsa.efi from the UEFI shell image (raw disk, VHDX, or integrated firmware) with the required rule filters.
• Linux-based tests — reuse the BSA Linux application (bsa_app) with the VBSA skip list to exercise guest-visible behavior.
• Manual verification — cross-check residual rules in the checklist and capture VE-owner evidence where ACS cannot auto-verify.

VBSA build steps

UEFI Shell application

Set up the workspace and toolchain using the Common UEFI build guide, then build the VBSA binary:

1. source ShellPkg/Application/sysarch-acs/tools/scripts/acsbuild.sh vbsa
2. Vbsa.efi is written to Build/Shell/<TOOL_CHAIN_TAG>/AARCH64/ under the edk2 tree.

Linux application

Use the Common Linux application guide to build the shared Linux artifacts. VBSA reuses bsa_acs.ko and bsa_app; run-time skip lists tailor the coverage to VBSA rules (see the Linux run steps below).

VBSA run steps

For UEFI application

1. Place Vbsa.efi and Shell.efi (renamed to \EFI\BOOT\bootaa64.efi) on a bootable image.
2. Boot the virtual environment to the UEFI shell.
3. Refresh filesystem mappings with: map -r
4. Switch to the filesystem containing Vbsa.efi (for example, fs0:)
5. Run the binary with the desired arguments (see Common CLI arguments).
6. Capture the UART console output for reporting.

Example

Shell> Vbsa.efi -v 1 -skip V_L2PE_01 -el1skiptrap cntpct -f vbsa.log

Runs at INFO level, skips rule V_L2PE_01, enables -el1skiptrap cntpct for hypervisors trapping EL1 timers, and captures logs in vbsa.log.

Use VBSA rule IDs that follow the V_L<level><module>_<nn> pattern from the VBSA checklist (for example, V_L2PE_01) with -skip/-r, and enable -el1skiptrap cntpct only when the hypervisor traps EL1 physical timer accesses; document any coverage gaps.

Creating a bootable .img (Linux host)

1. mkfs.vfat -C -n HD0 vbsa.img 1048576
2. sudo mount vbsa.img /mnt/acs
3. sudo mkdir -p /mnt/acs/EFI/BOOT
4. sudo cp Shell.efi /mnt/acs/EFI/BOOT/bootaa64.efi
5. sudo cp Vbsa.efi /mnt/acs/
6. sudo umount /mnt/acs

Creating a bootable .vhdx (Windows host)

1. Create and attach a VHDX using Hyper-V Manager or Disk Management.
2. Inside the mounted VHDX, create \EFI\BOOT.
3. Copy Shell.efi to \EFI\BOOT\bootaa64.efi.
4. Copy Vbsa.efi to the root of the volume.
5. Detach the VHDX safely.

For Linux application

VBSA uses the BSA Linux application with the VBSA skip list:

1. Load the shared kernel module:
   sudo insmod bsa_acs.ko
2. Run the Linux application with the VBSA skip list (see Common CLI arguments).
   ./bsa_app --skip B_REP_1,B_IEP_1,B_PCIe_11,B_MEM_06
3. Remove the module after the run:
   sudo rmmod bsa_acs

Inspect logs with sudo dmesg | tail -500 as needed. Adjust the skip list as the specification evolves.

Application arguments

Refer to Common CLI arguments for the complete flag list, including VBSA-specific guidance on skip lists and logging options.
That guide also documents VBSA-specific behavior such as the extended module list and the -el1skiptrap option for hypervisor scenarios.

Limitations

• VBSA tests span UEFI and Linux components; both must be executed for complete coverage.
• Exerciser-dependent PCIe rules cannot be validated in virtual environments; affected rules are marked as PASSED*(PARTIAL) or SKIPPED.
• Manual verification is required for rules that cannot be exercised on the available virtual platform.

Troubleshoot guide

• Some hypervisors trap EL1 register accesses, causing exceptions during VBSA ACS runs. Use -el1skiptrap <register list> when necessary, but document the resulting coverage gap.

Feedback, contributions and support

• Email: support-systemready-acs@arm.com
• GitHub Issues: sysarch-acs issue tracker
• Contributions: GitHub Pull Requests

License

VBSA ACS is distributed under the Apache v2.0 License.

---

Copyright (c) 2025-2026, Arm Limited and Contributors. All rights reserved.