Merge pull request #4 from chetan-rathore/main

BSA 0.9 Beta changes

Author: prasanth-pulla

README.md

@@ -4,7 +4,7 @@
 ## Base System Architecture
 **Base System Architecture** (BSA) specification describes a hardware system architecture based on the Arm 64-bit architecture. System software such as operating systems, hypervisors, and firmware rely on this. It addresses PE features and key aspects of system architecture.
 
-For more information, download the [BSA specification](https://developer.arm.com/documentation/den0094/latest)
+For more information, see [BSA specification](https://developer.arm.com/documentation/den0094/latest)
 
 
 ## BSA - Architecture Compliance Suite
@@ -16,35 +16,49 @@ A few tests are executed by running the BSA ACS Linux application which in turn
 
 
 ## Release details
- - Code quality: v0.5 Alpha
+ - Code quality: v0.9 Beta
  - The tests are written for version 1.0 of the BSA specification.
  - The compliance suite is not a substitute for design verification.
  - To review the BSA ACS logs, Arm licensees can contact Arm directly through their partner managers.
 
 
 ## GitHub branch
-  - To pick up the release version of the code, checkout the coresponding tag from main branch.
+  - To pick up the release version of the code, checkout the corresponding tag from the main branch.
   - To get the latest version of the code with bug fixes and new features, use the main branch.
 
 ## Additional reading
-  - For information on the test scenarios currently implemented for IR, see [Scenario Document](docs/Arm_Base_System_Architecture_Scenario_IR.pdf).
+  - For information on the test scenarios currently implemented for platform using Device tree, see [Scenario Document](docs/Arm_Base_System_Architecture_Scenario_IR.pdf).
+  - For information on the test scenarios currently implemented for platform using ACPI table, see [Scenario Document](docs/Arm_Base_System_Architecture_Scenario_ES.pdf).
 
 ## 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, see the Test suite execution section below for details on how to run the application.
 
-### Prerequisites
+### 1. Building from source
     Before you start 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-stable202102 tag of [EDK2 tree](https://github.com/tianocore/edk2).
 - git clone the [EDK2 port of libc](https://github.com/tianocore/edk2-libc) to local <edk2_path>.
-- Install GCC 7.5 or a later toolchain for Linux from [here](https://releases.linaro.org/components/toolchain/binaries/).
+- GCC 7.5 or a later toolchain for Linux from [here](https://releases.linaro.org/components/toolchain/binaries/).
 - 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 for IR, perform the following steps:
+#### 1.1 Target Platform
+##### To start the ACS build for platform using ACPI table, perform the following steps:
+
+1.  cd local_edk2_path
+2.  git submodule update --init --recursive
+3.  git clone https://github.com/ARM-software/bsa-acs.git ShellPkg/Application/bsa-acs
+4.  Add the following to the [LibraryClasses.common] section in ShellPkg/ShellPkg.dsc
+>          BsaValLib|ShellPkg/Application/bsa-acs/val/BsaValLib.inf
+>          BsaPalLib|ShellPkg/Application/bsa-acs/platform/pal_uefi_acpi/BsaPalLib.inf
+
+5.  Add the following in the [components] section of ShellPkg/ShellPkg.dsc
+>          ShellPkg/Application/bsa-acs/uefi_app/BsaAcs.inf
+
+##### To start the ACS build for platform using Device tree, perform the following steps:
 
 1.  cd local_edk2_path
 2.  git submodule update --init --recursive
@@ -64,25 +78,25 @@ To start the ACS build for IR, perform the following steps:
 >          +//Status = gBS->LocateProtocol (&gEfiHiiConfigRoutingProtocolGuid, NULL, (VOID **) &gHiiConfigRouting);
 >          +//ASSERT_EFI_ERROR (Status);
 
-### Linux build environment
-If the build environment is Linux, perform the following steps:
+####    1.2 Build environment
+##### If the build environment is Linux, perform the following steps:
 1.  export GCC49_AARCH64_PREFIX= GCC7.5 toolchain path pointing to /bin/aarch64-linux-gnu- in case of x86 machine. For an AArch64 build it should point to /usr/bin/
 2.  export PACKAGES_PATH= path pointing to edk2-libc
 3.  source edksetup.sh
 4.  make -C BaseTools/Source/C
 5.  source ShellPkg/Application/bsa-acs/tools/scripts/acsbuild.sh
 
-### Build output
+#### 1.3 Build output
 
 The EFI executable file is generated at <edk2_path>/Build/Shell/DEBUG_GCC49/AARCH64/Bsa.efi
 
 
-## Test suite execution
+### 2. Test suite execution
 
 The execution of the compliance suite varies depending on the test environment. The below steps assume that the test suite is invoked through the ACS UEFI shell application.
 
 
-### Prerequisites
+#### Prerequisites
 - If the system supports LPIs (Interrupt ID > 8192) then Firmware should support installation of handler for LPI interrupts.
     - If you are using edk2, change the ArmGic driver in the ArmPkg to support installation of handler for LPIs.
     - Add the following in edk2/ArmPkg/Drivers/ArmGic/GicV3/ArmGicV3Dxe.c
@@ -92,7 +106,8 @@ The execution of the compliance suite varies depending on the test environment.
 >          -mGicNumInterrupts      = ArmGicGetMaxNumInterrupts (mGicDistributorBase);
 >          +mGicNumInterrupts      = ARM_GIC_MAX_NUM_INTERRUPT;
 
-### Silicon
+#### 2.1 Silicon
+
 On a system where a USB port is available and functional, perform the following steps:
 
 #### For IR Systems:
@@ -111,12 +126,13 @@ On a system where a USB port is available and functional, perform the following
 9. Copy the UART console output to a log file.
 Note: 'Shell.efi' is available in the [pebuilt_images/IR](prebuilt_images)
 
-### Emulation environment with secondary storage
+#### 2.2 Emulation environment with secondary storage
 On an emulation environment with secondary storage, perform the following steps:
 
 1. Create an image file which contains the 'Bsa.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/bsa
+  - sudo mount -o rw,loop=/dev/loop0,uid=\`whoami\`,gid=\`whoami\` hda.img /mnt/bsa
+    In case loop0 is busy, please specify the one that is free.
   - sudo cp  "<path to application>/Bsa.efi" /mnt/bsa/
   - sudo umount /mnt/bsa
 2. Load the image file to the secondary storage using a backdoor. The steps to load the image file are emulation environment-specific and beyond the scope of this document.
@@ -126,8 +142,10 @@ On an emulation environment with secondary storage, perform the following steps:
 6. To start the compliance tests, run the executable Bsa.efi with the appropriate parameters.
 7. Copy the UART console output to a log file for analysis and certification.
 
+  - For information on the BSA uefi shell application parameters, see [User Guide](docs/Arm_Base_System_Architecture_Compliance_User_Guide.pdf).
+
 
-### Emulation environment without secondary storage
+#### 2.3 Emulation environment without secondary storage
 
 On an emulation platform where secondary storage is not available, perform the following steps:
 
@@ -139,81 +157,63 @@ On an emulation platform where secondary storage is not available, perform the f
 
 
 ## Linux OS-based tests
-Certain Peripheral, PCIe and Memory map tests require Linux operating system with kernel version 5.10 or above.
+Certain Peripheral, PCIe and Memory map tests require Linux operating system with kernel version 5.11 or above.
 This chapter provides information on executing tests from the Linux application.
 
-### Build steps and environment setup
+### 1. Build steps and environment setup
 This section lists the porting and build steps for the kernel module.
-The patch for the kernel tree and the Linux PAL are hosted separately on [linux-acs](https://gitlab.arm.com/linux-arm/linux-acs) repo
+The patch for the kernel tree and the Linux PAL are hosted separately on [linux-acs](https://git.gitlab.arm.com/linux-arm/linux-acs.git) repo
 
-### Building the kernel module
+### 1.1 Building the kernel module
 #### Prerequisites
-- Linux kernel source version 5.10.
+- Linux kernel source version 5.11.
 - Linaro GCC tool chain 7.5 or above.
 - Build environment for AArch64 Linux kernel.
 
 #### Porting steps for Linux kernel
 1. git clone https://git.gitlab.arm.com/linux-arm/linux-acs.git bsa-acs-drv
 2. git clone https://github.com/ARM-software/bsa-acs.git bsa-acs
-3. git clone https://github.com/torvalds/linux.git -b v5.10
+3. git clone https://github.com/torvalds/linux.git -b v5.11
 4. export CROSS_COMPILE=<GCC7.5 toolchain path> pointing to /bin/aarch64-linux-gnu-
-5. git apply <local_dir>/bsa-acs-drv/kernel/src/0001-BSA-SBSA-ACS-Linux-5.10.patch to your kernel source tree.
+5. git apply <local_dir>/bsa-acs-drv/kernel/src/0001-BSA-ACS-Linux-5.11.patch to your kernel source tree.
 6. make ARCH=arm64 defconfig && make -j $(nproc) ARCH=arm64
 
-#### Build steps for BSA kernel module
+#### 1.2 Build steps for BSA kernel module
 1. cd <local_dir>/bsa-acs-drv/files
 2. export CROSS_COMPILE=<ARM64 toolchain path>/bin/aarch64-linux-gnu-
 3. export KERNEL_SRC=<linux kernel path>
 4. ./setup.sh <local_dir/bsa-acs>
 5. ./linux_bsa_acs.sh
-bsa_acs.ko file is generated.
 
-#### BSA Linux application build
+Successfull completion of above steps will generate bsa_acs.ko
+
+#### 1.3 BSA Linux application build
 1. cd <bsa-acs path>/linux_app/bsa-acs-app
 2. export CROSS_COMPILE=<ARM64 toolchain path>/bin/aarch64-linux-gnu-
 3. make
-The executable file bsa is generated.
-
-## Linux application arguments
-Run the Linux application with the following set of arguments
-```sh
-shell> bsa [--v <n>] [--skip <x,y,z>]
-```
 
-| Argument | Description |
-| ------ | ------ |
-| v | Print level |
-|| 1.  INFO and above|
-|| 2.  DEBUG and above|
-|| 3.  TEST and above|
-|| 4.  WARN and ERROR|
-|| 5.  ERROR|
-|||
-| skip | Overrides the suite to skip the execution of a particular test.
-|| For example, 53 skips test case with ID 53.|
-
-### Example
-```sh
-shell> bsa --v 3 --skip 53
-```
-This set of parameters tests for compliance against BSA with print verbosity set to 3, and skips test number 53.
+Successfull completion of above steps will generate executable file bsa
 
-### Loading the kernel module
+### 2. Loading the kernel module
 Before the BSA ACS Linux application can be run, load the BSA ACS kernel module using the insmod command.
 ```sh
 shell> insmod bsa_acs.ko
 ```
 
-### Running BSA ACS
+### 3. Running BSA ACS
 ```sh
 shell> ./bsa
 ```
+  - For information on the BSA Linux application parameters, see [User Guide](docs/Arm_Base_System_Architecture_Compliance_User_Guide.pdf).
 
 ## Security implication
 The Arm System Ready ACS test suite may run at a higher privilege level. An attacker may utilize these tests to elevate the privilege which can potentially reveal the platform security assets. To prevent the leakage of secure information, Arm strongly recommends that you run the ACS test suite only on development platforms. If it is run on production systems, the system should be scrubbed after running the test suite.
 
 ## Limitations
- No known limitations.
+
+ - PCIE iEP rules are out of scope for current release.
+ - ITS rules are available only for systems that present firmware compliant to SBBR.
+ - Peripheral rules RB_PER_01,02,03 are not implemented in current release for systems that present firmware compliant to EBBR.
 
 ## License
 BSA ACS is distributed under Apache v2.0 License.

changelog.txt

@@ -6,3 +6,9 @@ v21.05_05_ALPHA
 * BSA: Provided documentations required to build and run BSA ACS on supported platforms.
 * BSA: Provided documentation on test scenarios. 
 
+v21.07_0.9_BETA
+
+* BSA: Increaed PCIe rules coverage
+* BSA: Initial ITS tests for systems presenting firmware which is SBBR complaint
+* BSA: Renamed pal_uefi to pal_uefi_acpi
+* BSA: Bug Fixes on Alpha release

docs/Arm_Base_System_Architecture_Compliance_User_Guide.pdf

@@ -143,12 +143,12 @@ main (int argc, char **argv)
         return 0;
     }
 
-    printf("\n      *** Starting Peripherals tests ***  \n");
-    execute_tests_peripheral(1, g_print_level);
-
     printf("\n      *** Starting Memory Map tests ***  \n");
     execute_tests_memory(1, g_print_level);
 
+    printf("\n      *** Starting Peripherals tests ***  \n");
+    execute_tests_peripheral(1, g_print_level);
+
     if (run_exerciser) {
         printf("\n      *** PCIe Exerciser tests only runs on UEFI ***  \n");
         //execute_tests_exerciser(1, g_print_level);

docs/Arm_Base_System_Architecture_Compliance_Validation_Methodology.pdf

@@ -21,7 +21,7 @@
 
 
 #define BSA_APP_VERSION_MAJOR  0
-#define BSA_APP_VERSION_MINOR  5
+#define BSA_APP_VERSION_MINOR  9
 
 #define G_SW_OS            0
 #define G_SW_HYP           1