Server Base System Architecture - Architecture Compliance Suite

Server Base System Architecture

Server Base System Architecture (SBSA) specification specifies a hardware system architecture based on the Arm 64-bit architecture. Server system software such as operating systems, hypervisors, and firmware rely on this. It addresses processing element features and key aspects of system architecture.

For more information, download the SBSA specification

SBSA - Architecture Compliance Suite

SBSA Architecture Compliance Suite (ACS) is a collection of self-checking, portable C-based tests. This suite includes a set of examples of the invariant behaviors that are provided by the SBSA specification, so that implementers can verify if these behaviours have been interpreted correctly. Most of the tests are executed from UEFI Shell by executing the SBSA UEFI shell application. A few tests are executed by running the SBSA ACS Linux application which in turn depends on the SBSA ACS Linux kernel module.

Release details

Code Quality: REL v3.2
The tests are written for version 6.0 of the SBSA specification.
PCIe RCiEP tests for Appendix E of SBSA 6.0 specification are also included.
The compliance suite is not a substitute for design verification.
To review the SBSA ACS logs, Arm licensees can contact Arm directly through their partner managers.
To know about the gaps in the test coverage, see Testcase checklist.

GitHub branch

To pick up the release version of the code, checkout the release branch.
To get the latest version of the code with bug fixes and new features, use the master branch.

Additional reading

For details on the SBSA ACS UEFI Shell Application, see Arm SBSA ACS User Guide.
For details on the Design of the SBSA ACS, see Arm SBSA Validation Methodology Document.
For information about the test coverage scenarios that are implemented in the current release of ACS and the scenarios that are planned for the future releases, see Testcase checklist.

SBSA ACS Baremetal Reference Code

Baremetal reference code is added as part of this release. For more information, see

Baremetal User Guide.
Baremetal Code.
Note: The Baremetal PCIe enumeration code provided as part of the SBSA ACS should be used and should not be replaced. This code is vital in analyzing the test result.

SBSA ACS Linux kernel module

To enable the export of a few kernel APIs that are necessary for PCIe and IOMMU tests, Linux kernel module and a kernel patch file are required. These files are available at linux-acs.

Target platforms

Any AARCH64 Enterprise Platform that boots UEFI and Linux OS.

ACS build steps - UEFI Shell application

Prebuilt images

Prebuilt images for each release are available in the prebuilt_images folder of the release branch. You can choose to use these images or build your own image by following the steps below. If you choose to use the prebuilt image, jump to the test suite execution section below for details on how to run the application.

Prerequisites

Before starting the ACS build, ensure that the following requirements are met.

Any mainstream Linux based OS distribution running on a x86 or aarch64 machine.
git clone the edk2-stable202008 tag of EDK2 tree.
git clone the EDK2 port of libc SHA: 61687168fe02ac4d933a36c9145fdd242ac424d1.
Install GCC 5.3 or later toolchain for Linux from here.
Install the build prerequisite packages to build EDK2. Note: The details of the packages are beyond the scope of this document.

To start the ACS build, perform the following steps:

cd local_edk2_path
git clone https://github.com/tianocore/edk2-libc
git submodule update --init --recursive
git clone https://github.com/ARM-software/sbsa-acs ShellPkg/Application/sbsa-acs
Add the following to the [LibraryClasses.common] section in ShellPkg/ShellPkg.dsc

Add SbsaValLib|ShellPkg/Application/sbsa-acs/val/SbsaValLib.inf
Add SbsaPalLib|ShellPkg/Application/sbsa-acs/platform/pal_uefi/SbsaPalLib.inf

Add ShellPkg/Application/sbsa-acs/uefi_app/SbsaAvs.inf in the [components] section of ShellPkg/ShellPkg.dsc

Linux build environment

If the build environment is Linux, perform the following steps:

export GCC49_AARCH64_PREFIX= GCC5.3 toolchain path pointing to /bin/aarch64-linux-gnu- in case of x86 machine. For aarch64 build it should point to /usr/bin/
export PACKAGES_PATH= path pointing to edk2-libc
source edksetup.sh
make -C BaseTools/Source/C
source ShellPkg/Application/sbsa-acs/tools/scripts/avsbuild.sh

Windows build environment

If the build environment is Windows, perform the following steps:

Set the toolchain path to GCC53 or above.
Setup the environment for AARCH64 EDK2 build.
Setup the environment for PACKAGES_PATH.
Build the SBSA shell application. For example, build -a AARCH64 -t GCC49 -p ShellPkg/ShellPkg.dsc -m ShellPkg/Application/sbsa-acs/uefi_app/SbsaAvs.inf

Note: To build the ACS with NIST Statistical Test Suite, see SBSA_NIST_User_Guide

Build output

The EFI executable file is generated at <edk2_path>/Build/Shell/DEBUG_GCC49/AARCH64/Sbsa.efi

Test suite execution

The execution of the compliance suite varies depending on the test environment. These steps assume that the test suite is invoked through the ACS UEFI shell application.

For details about the SBSA ACS UEFI Shell application, see SBSA ACS USER Guide

Prerequisites

If the system supports LPI’s (Interrupt ID > 8192) then Firmware should have support for installing handler for LPI interrupts.
- If you are using edk2, change the ArmGic driver in the ArmPkg to have support for installing handler for LPI’s.
- Add the following in edk2/ArmPkg/Drivers/ArmGic/GicV3/ArmGicV3Dxe.c

   - After [#define ARM_GIC_DEFAULT_PRIORITY  0x80]
     +#define ARM_GIC_MAX_NUM_INTERRUPT 16384
   - Change this in GicV3DxeInitialize Function.
     -mGicNumInterrupts      = ArmGicGetMaxNumInterrupts (mGicDistributorBase);
     +mGicNumInterrupts      = ARM_GIC_MAX_NUM_INTERRUPT;

Post-Silicon

On a system where a USB port is available and functional, perform the following steps:

Copy 'Sbsa.efi' to a USB Flash drive.
Plug in the USB Flash drive to one of the functional USB ports on the system.
Boot the system to UEFI shell.
To determine the file system number of the plugged in USB drive, execute 'map -r' command.
Type 'fsx' where 'x' is replaced by the number determined in step 4.
To start the compliance tests, run the executable Sbsa.efi with the appropriate parameters. For details on the parameters, refer to SBSA ACS User Guide
Copy the UART console output to a log file for analysis and certification.

Emulation environment with secondary storage

On an emulation environment with secondary storage, perform the following steps:

Create an image file which contains the 'Sbsa.efi' file. For Example:

mkfs.vfat -C -n HD0 hda.img 2097152
sudo mount -o rw,loop=/dev/loop0,uid=whoami,gid=whoami hda.img /mnt/sbsa. If loop0 is busy, specify the loop that is free
cp "/Sbsa.efi" /mnt/sbsa/
sudo umount /mnt/sbsa

Load the image file to the secondary storage using a backdoor. The steps followed to load the image file are Emulation environment specific and beyond the scope of this document.
Boot the system to UEFI shell.
To determine the file system number of the secondary storage, execute 'map -r' command.
Type 'fsx' where 'x' is replaced by the number determined in step 4.
To start the compliance tests, run the executable Sbsa.efi with the appropriate parameters. For details on the parameters, see the Arm SBSA ACS User Guide
Copy the UART console output to a log file for analysis and certification.

Emulation environment without secondary storage

On an emulation platform where secondary storage is not available, perform the following steps:

Add the path to 'Sbsa.efi' file in the UEFI FD file.
Build UEFI image including the UEFI Shell.
Boot the system to UEFI shell.
Run the executable 'Sbsa.efi' to start the compliance tests. For details about the parameters, see the SBSA ACS User Guide.
Copy the UART console output to a log file for analysis and certification.

Linux OS-based tests

Certain PCIe and IOMMU tests require Linux operating system with kernel version 4.10 or above. The procedure to build and run these tests is described in SBSA ACS User Guide.

Security implication

Arm Enterprise ACS test suite may run at higher privilege level. An attacker may utilize these tests as a means to elevate privilege which can potentially reveal the platform security assets. To prevent the leakage of secure information, it is strongly recommended that the ACS test suite is run only on development platforms. If it is run on production systems, the system should be scrubbed after running the test suite.

Limitations

Validating the compliance of certain PCIe rules defined in the SBSA specification requires the PCIe end-point to generate specific stimulus during the runtime of the test. Examples of such stimulus are P2P, PASID, ATC, etc. The tests that requires these stimuli are grouped together in the exerciser module. The exerciser layer is an abstraction layer that enables the integration of hardware capable of generating such stimuli to the test framework. The details of the hardware or Verification IP which enable these exerciser tests are platform specific and are beyond the scope of this document.

Some PCIe and Exerciser test are dependent on PCIe features supported by the test system. Please fill the required API's with test system information.

APIs	Description	Affected tests
pal_pcie_p2p_support	Return 0 if the test system PCIe supports peer to peer transaction, else 1	453, 454, 456, 812, 813
pal_pcie_is_cache_present	Return 1 if the test system supports PCIe address translation cache, else 0	452
pal_pcie_get_legacy_irq_map	Return 0 if system legacy irq map is filled, else 1	412, 450, 806

Below exerciser capabilities are required by exerciser test.

MSI-X interrupt generation.
Incoming Transaction Monitoring (order, type).
Initiating transactions from and to the exerciser.
Ability to check on BDF and register address seen for each configuration address along with access type.
SBSA Test 403 (Check ECAM Memory accessibility) execution time depends on the system PCIe hierarchy. For systems with multiple ECAMs the time taken to complete can be long which is normal. Please wait until the test completes.

License

SBSA ACS is distributed under Apache v2.0 License.

Feedback, contributions, and support

For feedback, use the GitHub Issue Tracker that is associated with this repository.
For support, send an email to "support-enterprise-acs@arm.com" with details.
Arm licensees may contact Arm directly through their partner managers.
Arm welcomes code contributions through GitHub pull requests. See GitHub documentation on how to raise pull requests.

r0bwoo/sbsa-acs-google

Server Base System Architecture - Architecture Compliance Suite