infra/common: document acs test build/validation procedure

Add a new document that explains the procedure to boot LuvOS and run ACS
tests on the Neoverse Reference Design platforms.

Change-Id: I21815ec145f88432248968562523847debeb3f28
Signed-off-by: Pranav Madhu <pranav.madhu@arm.com>

docs/infra/common/acs-test.rst

+ACS compliance test on Neoverse RD platforms
+============================================
+
+.. contents::
+
+
+What is Arm ACS
+---------------
+
+Architecture Compliance Suite (ACS) is used to ensure architectural compliance
+across different implementations of the architecture. Arm Enterprise ACS
+includes a set of examples of the invariant behaviours that are provided by a
+set of specifications for enterprise systems (e.g. SBSA, SBBR, etc.), so that
+implementers can verify if these behaviours have been interpreted correctly.
+
+
+Overview of ACS test
+--------------------
+
+Reference design (RD) platform is targeted for enterprise, network and other
+infrastructure markets. This requires the platforms to be compliant to the
+various architectural specifications such as SBSA and SBBR. ACS compliance test
+helps to ensure that the RD platform and the software stack is compliant to
+these specifications. The ACS compilance test on RD platforms use a downloadable
+pre-built ACS disk image. On completion of the ACS test on RD platforms, the
+test results are stored on the ACS disk image and can be retrieved from it. The
+results can then be looked into to determine the conformance to the SBSA and
+SBBR standards.
+
+
+Platform Names
+--------------
+Arm's Infra reference platforms are assigned names in order to allow the build
+and execute scripts to recognize the platform that has to be buit and executed.
+The names for the reference platforms are listed below. Please make a note
+of the name of the platform of your choice. This name is required to start the
+build and execute procedure. The names under 'Platform Name' column has to be
+used in place of the placeholder <platform> as mentioned in the commands
+listed below.
+
++--------------------------+-------------------------+
+| Reference Platform       | Platform Name           |
++==========================+=========================+
+| SGI-575                  | sgi575                  |
++--------------------------+-------------------------+
+| RD-N1-Edge (Single Chip) | rdn1edge                |
++--------------------------+-------------------------+
+| RD-N1-Edge (Dual Chip)   | rdn1edgex2              |
++--------------------------+-------------------------+
+| RD-E1-Edge               | rde1edge                |
++--------------------------+-------------------------+
+| RD-Daniel Config-M       | rddaniel                |
++--------------------------+-------------------------+
+| RD-Daniel Config-XLR     | rddanielxlr             |
++--------------------------+-------------------------+
+| RD-N2                    | rdn2                    |
++--------------------------+-------------------------+
+
+
+Download the required platform software
+---------------------------------------
+
+Skip this section if the required sources have been downloaded.
+
+To obtain the required sources for the platform, follow the steps listed on the
+`Download sources`_ page. Ensure that the platform software is downloaded before
+proceeding with the steps listed below. Also, note the host machine requirements
+listed on that page which is essential to build and execute the platform
+software stack.
+
+
+Build the platform software
+---------------------------
+
+This section describes the procedure to build the RD software for ACS test. The
+components of the RD platform software stack that are built is limited to those
+that provide the EFI implementation and the EFI shell (i.e, SCP, TF-A and EDK2).
+
+To build the software stack, the command to be used is
+
+::
+
+  ./build-scripts/build-test-uefi.sh -p <platform> <command>
+
+Supported command line options are listed below
+
+* <platform>
+
+  - Supported platforms are listed in `Platform Names`_.
+
+* <command>
+
+  - Supported commands are
+
+    - ``clean``
+    - ``build``
+    - ``package``
+    - ``all`` (all of the three above)
+
+Examples of the build command are
+
+- Command to clean, build and package the software stack needed for the ACS
+  test on RD-N2 platform:
+
+  ::
+
+    ./build-scripts/build-test-uefi.sh -p rdn2 all
+
+- Command to perform an incremental build of the software components included in
+  the software stack for the RD-N2 platform.
+
+  *Note:* this command should be followed by the ``package`` command to complete
+  the preparation of the FIP and the disk image.
+
+  ::
+
+    ./build-scripts/build-test-uefi.sh -p rdn2 build
+
+- Command to package the previously built software stack and prepares the FIP
+  and the disk image.
+
+  ::
+
+    ./build-scripts/build-test-uefi.sh -p rdn2 package
+
+
+Validate ACS conformance
+------------------------
+
+For running the ACS tests, the ACS test suite disk image is required. The ACS
+test suite disk image can either by build from source by following the
+documentation at `ACS build documentation <https://github.com/ARM-software/arm-enterprise-acs>`_
+or the latest available prebuilt image (luv-live-image) can be downloaded from
+`here <https://github.com/ARM-software/arm-enterprise-acs/tree/release/prebuilt_images>`_.
+It is advised that the latest prebuilt image be used if there are no specfic
+reasons to build this disk image from ACS test suit source code.
+
+To boot and to start ACS test, the commands to be used are
+
+- Set ``MODEL`` path before launching the model:
+
+  ::
+
+    export MODEL=<absolute path to the platform FVP binary>
+
+- If the target platform is SGI-575:
+
+  ::
+
+    cd model-scripts/sgi
+
+- If the target platform is an Reference Design (RD) platform
+
+  ::
+
+    cd model-scripts/rdinfra
+
+- Launch the ACS test
+
+  ::
+
+    ./acs.sh -p <platform> -v <path to luv-live image> -n [true|false] -a <additional_params>
+
+
+Supported command line options are listed below
+
+*  -p <platform>
+
+   - Supported platforms are listed in `Platform Names`_.
+
+*  -v <absolute path to the luv-live prebuilt image>
+
+   -  The absolute path to the luv-live image has to be supplied as the
+      parameter.
+
+*  -n [true|false] (optional)
+
+   -  Controls the use of network ports by the model. If network ports have to
+      be enabled, use 'true' as the option. Default value is set to 'false'.
+
+*  -a <additional_params> (optional)
+
+   -  Specify any additional model parameters to be passed. The model parameters
+      and the data to be passed to those parameters can be found in the FVP
+      documentation.
+
+
+Example commands to perform the ACS tests are as listed below.
+
+- Command to start the execution of the RD-N2 model and perform the ACS tests.
+  The ACS test suite disk image named 'luv-live-image-gpt.img' is picked up from
+  the location /tmp/luv-live-image-gpt.img.
+
+  ::
+
+    ./acs.sh -p rdn2 -v /tmp/luv-live-image-gpt.img
+
+- Command to start the execution of the RD-N2 model with networking enabled and
+  perform the ACS tests. The ACS test suite disk image named 'luv-live-image-gpt.img'
+  is picked up from the location /tmp/luv-live-image-gpt.img. Additional
+  parameters to the model are supplied using the -a command line parameter and
+  networking support is enabled by using the -n parameter.
+
+  ::
+
+    ./acs.sh -p rdn2 -v /tmp/luv-live-image-gpt.img -n true -a "-C board.flash0.diagnostics=1"
+
+
+Note: UEFI SCT tests are currently not supported in RD Platforms because some of
+the SCT tests require reboot. The ACS test suite has the provision to skip SCT
+test and it is recommended to skip the SCT tests. After starting the ACS test
+using the command listed above, choose 'sbbr/sbsa' option from the grub menu.
+This will launch UEFI shell and the shell startup script will launch the ACS
+tests. The UEFI ACS test will prompt `Press any key to stop the EFI SCT running`,
+and the SCT tests can be skipped by pressing any key.
+
+
+Select a SBSA compliance level (optional)
+-----------------------------------------
+
+SBSA specification classifies hardware into different levels, level-3 through
+level-7. The ACS disk image is typically configured for a default level. For ACS
+disk image v3.0, the default SBSA level is 4. For running the ACS tests for any
+higher or lower level, press ESC from UEFI shell and run the SBSA efi binary
+manually to select the appropriate compliance level to be tested. An example
+of the command to use to select the compliance level is listed below.
+
+  ::
+
+    Shell> FS<x>:EFI\BOOT\sbsa\Sbsa.efi -l <y>
+
+    Here, y can be 3, 4, 5 or 6 for the SBSA compliance level.
+
+On completion of the ACS SBSA and SBBR tests, the execution stops at the
+luv-live-image filesystem login prompt. The test can be be stopped by
+terminating the FVP.
+
+
+Retrieve the test results
+-------------------------
+
+On completion of SBSA/SBBR tests, the test results can be retrieved by mounting
+the first partition of ACS test suite disk image that was used for the test.
+
+  ::
+
+    mkdir /tmp/acs-disk
+    sudo mount -o loop,offset=1048576 luv-live-image-gpt /tmp/acs-disk/
+
+The SBSA test results can be found in the folder 'sbsa_results' of this
+partition. There will be seperate folders for the UEFI log and Linux log.
+
+  - UEFI test report  : /tmp/acs-disk/sbsa_results/uefi/SbsaResults.log
+  - Linux test report : /tmp/acs-disk/sbsa_results/linux/SbsaResults.log
+
+The FWTS result will be in folder ‘luv-results*/parsed/fwts’ (Note: Choose the
+most latest ‘luv-results*’ folder because a new ‘luv-results*’ folder is created
+each time on running FWTS test).
+
+  - FWTS result :  /tmp/acs-disk/luv-results-2021-01-25--04-51-20/raw/fwts
+
+Unmount the disk after analysing the logs using the following commands.
+
+  ::
+
+    losetup
+    sudo umount /dev/loop_x     # _x can be 0, 1, 2... based on losetup output
+
+
+--------------
+
+*Copyright (c) 2021, Arm Limited. All rights reserved.*
+
+.. _Download sources: docs/infra/common/download-sources.rst