1# meta-arm-systemready Yocto Layer 2 3This layer contains classes and recipes for building and running 4[Arm SystemReady][] validation on the supported machines. 5 6Information regarding contributing, reporting bugs, etc can be found in the 7top-level meta-arm [README.md](../README.md) file. 8 9## Introduction 10 11This layer provides support for the following on supported machines: 12 13* Building the firmware for the [Arm SystemReady][] certification program 14* Running [Arm SystemReady ACS][] (Architecture Compliance Suite) tests 15* Running Linux distributions installation tests 16 17This layer is designed to work alongside with a BSP layer. For example, the 18[`meta-arm-bsp`][] layer in the top-level meta-arm defines the 19[`fvp-base`][] machine, which can be used with the recipes provided by this 20layer to build the firmware, run the [Arm SystemReady IR][] ACS tests, and 21run Linux distributions installation. **Note** that users can use this layer 22with their BSP layer to perform the same build and tests. 23 24### Firmware Build 25 26The `arm-systemready-firmware.bb` recipe is to build the firmware. It requires 27the `ARM_SYSTEMREADY_FIRMWARE` variable set at the MACHINE configuration level 28to list the build dependencies. 29 30### ACS Tests 31 32The recipe to run the ACS tests fetches and deploys the prebuilt ACS test suite 33disk image, and generates the necessary metadata to support executing the test 34suite using the bitbake `testimage` task. A test case `SystemReadyACSTest` is 35introduced in `lib/oeqa/runtime/cases` to monitor the ACS tests output from the 36bitbake `testimage` task. The `ARM_SYSTEMREADY_ACS_CONSOLE` variable must be set 37at the MACHINE configuration level for this test case. 38 39There are two additional recipes for generating the Arm SystemReady ACS tests 40report files through the use of the [EDK2 SCT Results Parser][] and the 41[Arm SystemReady scripts][]. These packages are installed in the 42`edk2-test-parser-native.bb` and `arm-systemready-scripts-native.bb` recipes 43respectively. 44 45The class `arm-systemready-acs.bbclass` implements the common logic to deploy 46the Arm SystemReady ACS prebuilt image and set up the `testimage` environment. 47This class also contains a `testimage` `"postfunc"` called `acs_logs_handle` 48which generates report files and analyzes the test results. 49 50The test result analysis is performed by first using the EDK2 SCT Results 51Parser to create a results.md file, then running the Arm SystemReady result 52check script to check the contents of the result partition as well as the 53console log. The result check will fail if any of the expected files or 54directories are missing, or if any file's contents do not pass its file-specific 55checks. 56 57The ACS test results which are checked by the script can be viewed in 58`${TMPDIR}/work/aarch64-oe-linux/arm-systemready-ir-acs/2.0.0-r0/testimage/`. If 59the check fails, the bitbake `testimage` task will fail. 60 61 62### Linux Distributions Installation 63 64Recipes for testing the installation of Linux distributions are provided under 65`recipes-test/arm-systemready-linux-distros`. These recipes help to download the 66installation CD for the Linux distribution and generate an empty disk as the 67target disk for the installation. 68 69## Supported Band and Machine 70 71Arm SystemReady has four bands: 72* [Arm SystemReady SR][] 73* [Arm SystemReady ES][] 74* [Arm SystemReady IR][] 75* [Arm SystemReady LS][] 76 77Currently, this layer only supports 78[Arm SystemReady IR ACS version v23.03_2.0.0][], which is verified on the 79[`fvp-base`][] machine. 80 81## Build and Run 82 83To build the firmware for Arm SystemReady on the supported machines (take the 84`fvp-base` machine as an example): 85 86 ARM_FVP_EULA_ACCEPT=1 kas build kas/fvp-base.yml:kas/arm-systemready-firmware.yml 87 88 89To run the Arm SystemReady ACS tests on the supported machines (take running 90Arm SystemReady IR on the `fvp-base` machine as an example): 91 92 ARM_FVP_EULA_ACCEPT=1 kas build kas/fvp-base.yml:kas/arm-systemready-ir-acs.yml 93 94To run the Linux distributions installation on the supported machines (take 95installing openSUSE on the `fvp-base` machine as an example): 96 97 ARM_FVP_EULA_ACCEPT=1 kas build kas/fvp-base.yml:kas/arm-systemready-linux-distros-opensuse.yml 98 99 kas shell \ 100 kas/fvp-base.yml:kas/arm-systemready-linux-distros-opensuse.yml \ 101 -c "../scripts/runfvp --verbose --console" 102 103## Guidelines for Reusing and Extending 104 105Currently, this layer only supports the Arm SystemReady IR band running on the 106`fvp-base` machine defined in the `meta-arm-bsp` layer. The supported Arm 107SystemReady IR implementation can be reused on other machines. Furthermore, the 108current implementation can be further extended to support SR, ES and LS bands. 109 110### Reuse 111 112To reuse the supported Arm SystemReady IR on other machines, you will need to: 113 1141. Set the `ARM_SYSTEMREADY_FIRMWARE` variable at the MACHINE configuration 115 level to list the build dependencies. The configuration file of the 116 [`fvp-base`][] machine can be used as a reference. 1172. Set the `ARM_SYSTEMREADY_ACS_CONSOLE` variable at the MACHINE configuration 118 level for running the ACS tests in the bitbake `testimage` task. Also refer 119 to the configuration file of the [`fvp-base`][] machine. 120 121### Extend 122 123To extend support for other bands, you will need to: 124 1251. Add a new recipe to inherit `arm-systemready-acs.bbclass`. You can use 126 [`arm-systemready-ir-acs.bb`][] as a reference. 1272. Add a new `testimage` test case for the newly added band. Refer to 128 [`arm_systemready_ir_acs.py`][]. 1293. Set the necessary variables and prepare the ACS baseline files (as listed in 130 the above **Reuse** section) at the MACHINE configuration level from the BSP 131 layer for the machine to be supported. 132 133**Note**: When reusing and extending, the current classes and libs may need to 134be modified or refactored as necessary. 135 136[Arm SystemReady]: https://www.arm.com/architecture/system-architectures/systemready-certification-program 137[Arm SystemReady ACS]: https://github.com/ARM-software/arm-systemready 138[Arm SystemReady SR]: https://www.arm.com/architecture/system-architectures/systemready-certification-program/sr 139[Arm SystemReady ES]: https://www.arm.com/architecture/system-architectures/systemready-certification-program/es 140[Arm SystemReady IR]: https://www.arm.com/architecture/system-architectures/systemready-certification-program/ir 141[Arm SystemReady LS]: https://www.arm.com/architecture/system-architectures/systemready-certification-program/ls 142[Arm SystemReady IR ACS version v23.03_2.0.0]: https://github.com/ARM-software/arm-systemready/tree/main/IR/prebuilt_images/v23.03_2.0.0 143[Arm SystemReady scripts]: https://gitlab.arm.com/systemready/systemready-scripts 144[EDK2 SCT Results Parser]: https://gitlab.arm.com/systemready/edk2-test-parser 145[`arm-systemready-ir-acs.bb`]: recipes-test/arm-systemready-acs/arm-systemready-ir-acs.bb 146[`arm_systemready_ir_acs.py`]: lib/oeqa/runtime/cases/arm_systemready_ir_acs.py 147[`meta-arm-bsp`]: ../meta-arm-bsp 148[`fvp-base`]: ../meta-arm-bsp/conf/machine/fvp-base.conf 149