Skip to content

Commit

Permalink
SystemReady-band README updates (#241)
Browse files Browse the repository at this point in the history 
* Update README.md : Formatting for structured readme

* Update README.md : Add sections for grub menu, log parser and image directory structure

* Update README.md: Added details of acs config files
  • Loading branch information
@chetan-rathore
chetan-rathore authored Dec 10, 2024
1 parent eb9d9f4 commit 7ddd1f0
Showing 1 changed file with 168 additions and 74 deletions.
242 changes: 168 additions & 74 deletions SystemReady-band/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,39 +1,52 @@
# SystemReadyband ACS
# SystemReady band ACS

## Table of Contents

## Introduction to SystemReady band
- [Introduction](#introduction)
- [Latest Release details](#latest-release-details)
- [Prebuilt Images](#prebuilt-images)
- [Steps to Manually Build Image](#steps-to-manually-build-image)
- [Image Directory Structure](#image-directory-structure)
- [Details and Functionalities of the Image](#details-and-functionalities-of-the-image)
- [Verification on Arm Neoverse N2 reference design](#verification-on-arm-neoverse-n2-reference-design)
- [Security Implication](#security-implication)
- [License](#license)
- [Feedback, contributions, and support](#feedback-contributions-and-support)



## Introduction
SystemReady band is a band of system compliance in the Arm SystemReady program that ensures interoperability of Arm based servers with standard operating systems and hypervisors.

SystemReady band compliant platforms implement a minimum set of hardware and firmware features that an operating system can depend on to deploy the operating system image. Compliant systems must conform to the:
* [Server Base System Architecture (SBSA) specification](https://developer.arm.com/documentation/den0029/h/?lang=en)
* SBBR recipe of the [Base Boot Requirements (BBR) specification](https://developer.arm.com/documentation/den0044/f/?lang=en)
* The SystemReady band compliance and testing requirements are specified in the [Arm SystemReady Requirements Specification (SRS)](https://developer.arm.com/documentation/den0109/latest)
SystemReady band compliant platforms must implement a minimum set of hardware and firmware features that an operating system can depend on to deploy the operating system image.

This section contains the build scripts and the live-images for the SystemReady band.
The SystemReady band compliance and testing requirements are specified in the [Arm SystemReady Requirements Specification (SRS)](https://developer.arm.com/documentation/den0109/latest)

## Release details
- Code quality: v3.0.0-BET0
## Latest Release details
- Release version: v3.0.0-BET0
- **The latest pre-built release of ACS is available for download here: [v24.11_3.0.0-BET0](prebuilt_images/v24.11_3.0.0-BET0)**
- The SBSA tests are written for version 7.1 of the SBSA specification.
- The BSA tests are written for version 1.0 (c) of the BSA specification.
- The BBR tests are written for the SBBR section in version 2.1 of the BBR specification.
- The compliance suite is not a substitute for design verification.
- To review the ACS logs, Arm licensees can contact Arm directly through their partner managers.
- SystemReady-band Image Test Suite details

| Test Suite | Test Suite Tag | Specification Version |
|----------------------------------------------------------------------------------------------|--------------------------------------------------------------|-----------------------|
| [Base System Architecture (BSA)](https://github.com/ARM-software/bsa-acs) | v24.11_REL1.0.9 | BSA v1.0 (c) |
| [Server Base System Architecture (SBSA)](https://github.com/ARM-software/sbsa-acs) | v24.11_REL7.2.1 | SBSA v7.1 |
| [Base Boot Requirements (BBR)](https://github.com/ARM-software/bbr-acs) | v24.11_EBBR_REL2.2.0-BETA0_SBBR_REL2.1.0-BETA0_BBSR_REL1.3.0 | BBR v2.1 |
| [Base Boot Security Requirements (BBSR)](https://github.com/ARM-software/bbr-acs) | v24.11_EBBR_REL2.2.0-BETA0_SBBR_REL2.1.0-BETA0_BBSR_REL1.3.0 | BBSR v1.3 |
| [UEFI Self Certification Tests (UEFI-SCT)](https://github.com/tianocore/edk2-test) | 0e2ced3befa431bb1aebff005c4c4f1a9edfe6b4 | |
| [Firmware Test Suite (FWTS)](http://kernel.ubuntu.com/git/hwe/fwts.git) | v24.09.00 | |

## Steps to build SystemReady band ACS live image

## Code download
- To build a release version of the code, checkout the main branch with the appropriate release tag.
- To build the latest version of the code with bug fixes and new features, use the main branch.

## ACS build steps
## Prebuilt Images
- Prebuilt images for each release are available in the prebuilt_images folder.To access the prebuilt_images, click [prebuilt_images](prebuilt_images/).
- The prebuilt images are archived after compression to the .xz format. On Linux, use the xz utility to uncompress the image <br />
`xz -d systemready_acs_live_image.img.xz` <br />
On Windows, use the 7zip or a similar utility.
- If you choose to use the prebuilt image, skip the build steps and navigate to the [Verification on Arm Neoverse N2 reference design](#verification-on-arm-neoverse-n2-reference-design).

### Prebuilt images
- Prebuilt images for each release are available in the prebuilt_images folder. You can either choose to use these images or build your own image by following the build steps.
- To access the prebuilt_images, click [prebuilt_images](prebuilt_images/)
- The prebuilt images are archived after compression to the .xz format. On Linux, use the xz utility to uncompress the image `xz -d systemready_acs_live_image.img.xz`. On Windows, use the 7zip or a similar utility.
- If you choose to use the prebuilt image, skip the build steps and navigate to the [Verification](#Verification) section below.
## Steps to Manually Build Image

### Prerequisites
Before starting the ACS build, ensure that the following requirements are met:
Expand All @@ -43,7 +56,11 @@ Before starting the ACS build, ensure that the following requirements are met:
- Install `git` using `sudo apt install git`
- `git config --global user.name "Your Name"` and `git config --global user.email "Your Email"` must be configured.

### Steps to build SystemReady band ACS live image
### Code download
- To build a release version of the code, checkout the main branch with the appropriate release [tag](https://github.com/ARM-software/arm-systemready/tags).
- To build the latest version of the code with bug fixes and new features, use the main branch.

### Build Steps
1. Clone the arm-systemready repository <br />
`git clone https://github.com/ARM-software/arm-systemready.git`

Expand All @@ -56,30 +73,141 @@ Before starting the ACS build, ensure that the following requirements are met:
4. To start the build of the ACS live image, execute the below step <br />
`./build-scripts/build-systemready-band-live-image.sh`

5. If all the above steps are successful, then the bootable image will be available at **/path-to-arm-systemready/SystemReady-band/output/systemready_acs_live_image.img.xz**
5. If all the above steps are successful, then the bootable image will be available at <br />
`/path-to-arm-systemready/SystemReady-band/output/systemready_acs_live_image.img.xz`

Note: The image is generated in a compressed (.xz) format. The image must be uncompressed before it is used.<br />

## Build output
### Build output
This image comprise of single FAT file system partition recognized by UEFI: <br />
- 'BOOT_ACS' <br />
Approximate size: 640 MB <br />
contains bootable applications and test suites. <br />
contains a 'acs_results' directory which stores logs of the automated execution of ACS.


## Verification
## Image Directory Structure
```
├── EFI
│   └── BOOT
│   ├── Shell.efi
│   ├── bbsr_startup.nsh
│   ├── bootaa64.efi
│   ├── grub.cfg
│   └── startup.nsh
├── acs_tests
│   ├── app
│   │   └── CapsuleApp.efi
│   ├── bbr
│   │   ├── SCT
│   │   ├── ScrtStartup.nsh
│   │   ├── SctStartup.nsh
│   │   └── bbsr_SctStartup.nsh
│   ├── bbsr-keys
│   │   ├── NullPK.auth
│   │   ├── TestDB1.auth
│   │   ├── TestDB1.der
│   │   ├── TestDBX1.auth
│   │   ├── TestDBX1.der
│   │   ├── TestKEK1.auth
│   │   ├── TestKEK1.der
│   │   ├── TestPK1.auth
│   │   └── TestPK1.der
│   ├── bsa
│   │   ├── Bsa.efi
│   │   ├── bsa.nsh
│   │   └── sbsa
│   ├── config
│   │   ├── acs_config.txt
│   │   ├── acs_run_config.ini
│   │   └── system_config.txt
│   ├── debug
│   │   └── debug_dump.nsh
│   └── parser
│   └── Parser.efi
├── acs_results
├── Image
└── ramdisk-buildroot.img
```
- EFI/BOOT contains the uefi automation startup scripts and grub related files
- acs_tests contains executable files and configs related for test suites
- app directory contains CapsuleApp.efi
- bbr directory contains SCT related bianries and sequence files
- bbsr-keys contains cryptographic keys for secure boot and testing secure firmware updates
- bsa directory contains bsa uefi executable for bsa complaince
- bsa/sbsa directory contains sbsa uefi executable for bsa complaince
- config directory contains system, acs related config files
- debug directory contains script to gather debug information
- parser directory contains uefi parser executable to parse acs_config file
- acs_results will contain result logs of various test suite run
- Image - Linux kernel image file, also contains linux test suites and processing scripts
- /init.sh - linux automation script
- /usr/bin/fwts - fwts executable
- /lib/modules/bsa_acs.ko - BSA Linux test kernel module
- /bin/bsa - BSA Linux app
- /lib/modules/sbsa_acs.ko - SBSA Linux test kernel module
- /bin/sbsa - SBSA Linux app
- /usr/bin/edk2-test-parser - SCT results parser
- /usr/bin/device_driver.sh - device driver script
- /usr/bin/log_parser - directory containing results post processing script
- ramdisk-buildroot.img - ram disk file

## Details and Functionalities of the Image

### Grub Menu
```
│ Linux Boot │
│*SystemReady band ACS (Automation) │
│ SCT for BBSR (optional) │
│ Linux Boot for BBSR (optional) │
│ Linux Boot with SetVirtualAddressMap enabled |
```
- **Linux Boot** : This option will boot the ACS Linux kernel and run the default Linux tool (linux debug dump, fwts, linux bsa, linux sbsa (if selected))
- noacs command line parameter: Edit the Linux Boot grub menu option and add **noacs** at the end of Linux Boot grub menu option, to boot into ACS Linux kernel without running the default Linux test suites.
- initcall_blacklist=psci_checker command line parameter: Edit the Linux Boot grub menu option and add **initcall_blacklist=psci_checker** to skip default linux psci_checker tool.
- **SystemReady band ACS (Automation)** : This is **default** option and will run the automated complaince
- UEFI complaince run - SCT, BSA UEFI, SBSA UEFI (if selected)
- Boots to Linux and run Linux complaince run - FWTS, BSA Linux, SBSA Linux (if selected)
- **SCT for BBSR (optional)** : This option will run the SCT tests required for BBSR complaince. For the verification steps of BBSR ACS, refer to the [BBSR ACS Verification](../common/docs/BBSR_ACS_Verification.md).
- **Linux Boot for BBSR (optional)** : This option will run the SCT tests required for BBSR complaince. For the verification steps of BBSR ACS, refer to the [BBSR ACS Verification](../common/docs/BBSR_ACS_Verification.md).
- **Linux Boot with SetVirtualAddressMap enabled** : This option is for debug purpose, to boot ACS Linux with SetVAMap on.

### ACS configs file
- **acs_config.txt**: The file specifies the ARM specification version that the ACS tool suite complies with, and this information is included in the **System_Information** table of the **ACS_Summary.html** report.

- **acs_run_config.ini**: This file is used to manage the execution of various ACS test suites and supports passing parameters to them. <br />
The current options supported are: <br />
- SbsaRunEnabled - The value supported is 0 and 1.
- 0: Don't run SBSA complaince in automation run
- 1: Run SBSA complaince in automation run

- **system_config.txt**: The file is used to collect below system information which is required for **ACS_Summary.html** report, this needs to be manually filled by user.
- FW source code: Unknown
- Flashing instructions: Unknown
- product website: Unknown
- Tested operated Systems: Unknown
- Testlab assistance: Unknown

### Log Parser scripts
- The scripts will parse the results generated by various test suite tools and consolidate them into JSON files. These JSON files will adhere to a standard format, maintaining a consistent structure for all test suites
- Also for easier intrepretation, results will also be captured in HTML format.
- The JSON and HTML formatted results are present in /acs_results/**acs_summary** folder.


## Verification on Arm Neoverse N2 reference design

Note: UEFI EDK2 setting for "Console Preference": The default is "Graphical". When that is selected, Linux output will goes to the graphical console (HDMI monitor). To force serial console output, you may change the "Console Preference" to "Serial".

### Verification of the SystemReady band image on the Arm Neoverse N2 reference design (RD-N2)
### Arm Neoverse N2 reference design (RD-N2) FVP

Follow the steps mentioned in [RD-N2 platform software user guide](https://neoverse-reference-design.docs.arm.com/en/latest/platforms/rdn2.html) to obtain RD-N2 FVP.

### Arm Neoverse N2 reference design (RD-N2) software stack

#### Prerequisites
sudo permission is required for building RD-N2 software stack.

#### Follow the steps mentioned in [RD-N2 platform software user guide](https://neoverse-reference-design.docs.arm.com/en/latest/platforms/rdn2.html) to obtain RD-N2 FVP.

### For software stack build instructions, follow BusyBox Boot link under Supported Features by RD-N2 platform software stack section in the same guide.
#### For software stack build instructions, follow BusyBox Boot link under Supported Features by RD-N2 platform software stack section in the same guide.

Note: After the download of software stack code, please do the below changes before starting the build steps.<br />
RD-N2 should be built with the GIC changes as mentioned below as applicable.<br />
Expand All @@ -93,17 +221,15 @@ RD-N2 should be built with the GIC changes as mentioned below as applicable.<br
> +mGicNumInterrupts = ARM_GIC_MAX_NUM_INTERRUPT;

#### Verifying the ACS-SR pre-built image
### Verifying the image

1. Set the environment variable 'MODEL' <br />
`export MODEL=<absolute path to the RD-N2 FVP binary/FVP_RD_N2>`

3. Launch the RD-N2 FVP with the pre-built image with the following command <br />
`cd /path to RD-N2_FVP platform software/model-scripts/rdinfra/platforms/rdn2` <br />
`./run_model.sh -v /path-to-systemready-acs-live-image/systemready_acs_live_image.img`

1. Set the environment variable 'MODEL'
```
export MODEL=<absolute path to the RD-N2 FVP binary/FVP_RD_N2>
```
2. Launch the RD-N2 FVP with the pre-built image with the following command
```
cd /path to RD-N2_FVP platform software/model-scripts/rdinfra/platforms/rdn2
./run_model.sh -v /path-to-systemready-acs-live-image/systemready_acs_live_image.img
```
This starts the ACS live image automation and run the test suites in sequence.

Known limitations:<br />
Expand All @@ -118,39 +244,7 @@ The execution continues from the test that is next in sequence of the test prior
2. It may appear that the test execution has stalled with the message “Waiting for few seconds for signal …” displayed on the console.
This is expected behavior and the progress of tests will continue after a 20-minute delay.

Note:
When verifying ACS on hardware, ensure that ACS image is not in two different boot medias (USB, NVMe drives etc) attached to the device.

### Automation
The test suite execution can be automated or manual. Automated execution is the default execution method when no key is pressed during boot. <br />
The live image boots to UEFI Shell. The different test applications can run in the following order:

1. [SCT tests](https://github.com/ARM-software/bbr-acs/blob/main/README.md) for BBR compliance.
2. [BSA](https://github.com/ARM-software/bsa-acs/blob/main/README.md) for BSA compliance.
3. [SBSA](https://github.com/ARM-software/sbsa-acs/blob/master/README.md) for SBSA compliance.
4. [FWTS tests](https://github.com/ARM-software/bbr-acs/blob/main/README.md) for BBR compliance.
5. [OS tests](https://github.com/ARM-software/sbsa-acs/blob/master/README.md) for Linux SBSA compliance.<br />
Note: To skip FWTS and OS tests for debugging, append "noacs" to the Linux command by editing the "Linux Boot" option in the grub menu during image boot.<br />
To start an extended run of UEFI-SCT append "-nostartup startup.nsh sct_extd" to the shell.efi command by editing the "bbr/bsa" option in the grub menu during image boot.<br />

### Running BBSR (BBSR) ACS components.
Now BBSR ACS is integrated with SR ACS image, which can be accessed through GRUB options.

For the verification steps of BBSR ACS, refer to the [BBSR ACS Verification](../common/docs/BBSR_ACS_Verification.md).

## Baselines for Open Source Software in this release:

- [Firmware Test Suite (FWTS)](http://kernel.ubuntu.com/git/hwe/fwts.git) TAG: v24.09.00

- [Server Base System Architecture (SBSA)](https://github.com/ARM-software/sbsa-acs) TAG: v24.11_REL7.2.1

- [Base System Architecture (BSA)](https://github.com/ARM-software/bsa-acs) TAG: v24.11_REL1.0.9

- [Base Boot Requirements (BBR)](https://github.com/ARM-software/bbr-acs) TAG: v24.11_EBBR_REL2.2.0-BETA0_SBBR_REL2.1.0-BETA0_BBSR_REL1.3.0

- [UEFI Self Certification Tests (UEFI-SCT)](https://github.com/tianocore/edk2-test) TAG: 0e2ced3befa431bb1aebff005c4c4f1a9edfe6b4


Note: When verifying ACS on hardware, ensure that ACS image is not in two different boot medias (USB, NVMe drives etc) attached to the device.

## Security Implication
Arm SystemReady band 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.
Expand Down

0 comments on commit 7ddd1f0

Please sign in to comment.