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    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    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    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