BSA README and Document updates (#219)

* Updates to BSA Documents - Updated Documents Name - Documents & README Updates Signed-off-by: Sujana M <[email protected]> * BSA Release README & Version Changes - README Updates - Version Changes Signed-off-by: Sujana M <[email protected]> --------- Signed-off-by: Sujana M <[email protected]>
ARM-software · Sep 29, 2023 · 8bfc90d · 8bfc90d
1 parent 53d2118
commit 8bfc90d
Show file tree

Hide file tree

Showing 14 changed files with 34 additions and 33 deletions.
diff --git a/README.md b/README.md
@@ -12,30 +12,31 @@ For more information, download the [BSA specification](https://developer.arm.com
 
 BSA **Architecture Compliance Suite** (ACS) is a collection of self-checking, portable C-based tests.
 This suite includes a set of examples of the invariant behaviors that are provided by the [BSA](https://developer.arm.com/documentation/den0094/c/?lang=en) specification, so that you can verify if these behaviour have been interpreted correctly.
+
 Most of the tests are executed from UEFI (Unified Extensible Firmware Interface) Shell by executing the BSA UEFI shell application.
 A few tests are executed by running the BSA ACS Linux application which in turn depends on the BSA ACS Linux kernel module.
 The tests can also be executed in a Bare-metal environment. The initialization of the Bare-metal environment is specific to the environment and is out of scope of this document.
 
 ## Release details
- - Code quality: v1.0.5
+ - Code quality: v1.0.6
  - The tests are written for version 1.0 (c) of the BSA specification.
  - The tests can be run at both the Pre-Silicon and Silicon level.
  - For complete coverage of the BSA rules, availability of an Exerciser is required for Exerciser tests to be run during verficiation at Pre-Silicon level.
  - 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.
- - To know about the BSA rules not implemented in this release, see the [Test Scenario Document](docs/Arm_BSA_Architecture_Compliance_Test_Scenario.pdf).
+ - To know about the BSA rules not implemented in this release, see the [Test Scenario Document](docs/arm_bsa_architecture_compliance_test_scenario.pdf).
 
 ## GitHub 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 about the implementable BSA rules test algorithm and for unimplemented BSA rules, see the [Scenario Document](docs/Arm_BSA_Architecture_Compliance_Test_Scenario.pdf).
-  - For information on test category(UEFI, Linux, Bare-metal) and applicable systems(IR,ES,SR,Pre-Silicon), see the [Test Checklist](docs/Arm_BSA_testcase-checklist.rst).
-  - For details on the design of the BSA ACS, see the [Arm BSA Validation Methodology Document](docs/Arm_Base_System_Architecture_Compliance_Validation_Methodology.pdf).
-  - For details on the BSA ACS UEFI Shell Application and Linux Application see the [Arm BSA ACS User Guide](docs/Arm_Base_System_Architecture_Compliance_User_Guide.pdf).
+  - For information about the implementable BSA rules test algorithm and for unimplemented BSA rules, see the [arm BSA Test Scenario Document](docs/arm_bsa_architecture_compliance_test_scenario.pdf).
+  - For information on test category(UEFI, Linux, Bare-metal) and applicable systems(IR,ES,SR,Pre-Silicon), see the [arm BSA Test Checklist](docs/arm_bsa_testcase_checklist.rst).
+  - For details on the design of the BSA ACS, see the [arm BSA Validation Methodology Document](docs/arm_bsa_architecture_compliance_validation_methodology.pdf).
+  - For details on the BSA ACS UEFI Shell Application and Linux Application see the [arm BSA ACS User Guide](docs/arm_bsa_architecture_compliance_user_guide.pdf).
   - For details on the BSA ACS Bare-metal support, see the
-    - [Arm BSA ACS Bare-metal User Guide](docs/Arm_BSA_ACS_Bare-metal_User_Guide.pdf).
+    - [arm BSA ACS Bare-metal User Guide](docs/arm_bsa_architecture_compliance_bare-metal_user_guide.pdf).
     - [Bare-metal Code](platform/pal_baremetal/). <br />
 Note: The Bare-metal PCIe enumeration code provided as part of the BSA ACS should be used and should not be replaced. This code is vital in analyzing of the test result.
 
@@ -54,13 +55,12 @@ Prebuilt images for each release are available in the prebuilt_images folder of
     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 tree](https://github.com/tianocore/edk2). Recommended edk2 tag is edk2-stable202208
+- git clone the [EDK2 tree](https://github.com/tianocore/edk2). Recommended edk2 tag is edk2-stable202302
 - git clone the [EDK2 port of libc](https://github.com/tianocore/edk2-libc) to local <edk2_path>.
-- GCC 7.5 or a later toolchain for Linux from [here](https://releases.linaro.org/components/toolchain/binaries/).
+- Install GCC-ARM 10.3 [toolchain](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-a/downloads).
 - Install the build prerequisite packages to build EDK2.<br />
 Note:<br />
 - The details of the packages are beyond the scope of this document.
-- GCC 7.5 is recommended toolchain, build issues are observed with toolchain version 10.xx and above.
 
 #### 1.1 Target Platform
 ##### To start the ACS build for platform using ACPI table, perform the following steps:
@@ -97,7 +97,7 @@ Note:<br />
 
 ####    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.<br /> For an AArch64 build it should point to /usr/bin/
+1.  export GCC49_AARCH64_PREFIX= GCC10.3 toolchain path pointing to /bin/aarch64-linux-gnu- in case of x86 machine.<br /> 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
@@ -159,7 +159,7 @@ 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 the [User Guide](docs/Arm_Base_System_Architecture_Compliance_User_Guide.pdf).
+  - For information on the BSA uefi shell application parameters, see the [User Guide](docs/arm_bsa_architecture_compliance_user_guide.pdf).
 
 
 #### 2.3 Emulation environment without secondary storage
@@ -169,7 +169,7 @@ On an emulation platform where secondary storage is not available, perform the f
 1. Add the path to 'Bsa.efi' file in the UEFI FD file.
 2. Build UEFI image including the UEFI Shell.
 3. Boot the system to UEFI shell.
-4. Run the executable 'Bsa.efi' to start the compliance tests. For details about the parameters,see the [User Guide](docs/Arm_Base_System_Architecture_Compliance_User_Guide.pdf).
+4. Run the executable 'Bsa.efi' to start the compliance tests. For details about the parameters,see the [User Guide](docs/arm_bsa_architecture_compliance_user_guide.pdf).
 5. Copy the UART console output to a log file for analysis and certification.
 
 
@@ -183,22 +183,21 @@ The patch for the kernel tree and the Linux PAL are hosted separately on [linux-
 
 ### 1.1 Building the kernel module
 #### Prerequisites
-- Linux kernel source version 5.11, 5.13, 5.15, 6.0.
-- Linaro GCC tool chain 7.5 or above.
+- Linux kernel source version 5.11, 5.13, 5.15, 6.0, 6.4.
+- Install GCC-ARM 10.3 [toolchain](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-a/downloads).
 - Build environment for AArch64 Linux kernel.<br />
 NOTE: <br />
-- Linux version 6.0 is recommened version.
-- GCC 7.5 is recommended toolchain, build issues are observed with toolchain version 10.xx and above.
+- Linux version 6.4 is recommened version.
 
 #### 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 v6.0
-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-ACS-Linux-6.0.patch to your kernel source tree.
+3. git clone https://github.com/torvalds/linux.git -b v6.4
+4. export CROSS_COMPILE=<GCC10.3 toolchain path> pointing to /bin/aarch64-linux-gnu-
+5. git apply <local_dir>/bsa-acs-drv/kernel/src/0001-BSA-ACS-Linux-6.4.patch to your kernel source tree.
 6. make ARCH=arm64 defconfig && make -j $(nproc) ARCH=arm64
 
-NOTE: The steps mentions Linux version 6.0, as it is latest version which is verified at ACS end.
+NOTE: The steps mentions Linux version 6.4, as it is latest version which is verified at ACS end.
 
 #### 1.2 Build steps for BSA kernel module
 1. cd <local_dir>/bsa-acs-drv/files
@@ -226,7 +225,7 @@ shell> insmod bsa_acs.ko
 ```sh
 shell> ./bsa
 ```
-  - For information on the BSA Linux application parameters, see the [User Guide](docs/Arm_Base_System_Architecture_Compliance_User_Guide.pdf).
+  - For information on the BSA Linux application parameters, see the [User Guide](docs/arm_bsa_architecture_compliance_user_guide.pdf).
 
 ## ACS build steps - Bare-metal abstraction
 
@@ -246,7 +245,8 @@ The Arm SystemReady ACS test suite may run at a higher privilege level. An attac
    Please fill the required API's with test system information.
    - pal_pcie_p2p_support : If the test system PCIe supports peer to peer transaction.
    - pal_pcie_is_cache_present : If the test system supports PCIe address translation cache.
-   - pal_pcie_get_legacy_ir_map : Fill system legacy ir map
+   - pal_pcie_get_legacy_irq_map : Fill system legacy irq map
+
    Below exerciser capabilities are required by exerciser test.
    - MSI-X interrupt generation.
    - Incoming Transaction Monitoring(order, type).
@@ -257,6 +257,7 @@ The Arm SystemReady ACS test suite may run at a higher privilege level. An attac
 --------------------------------------------------------------------------------------------
 |    BSA Spec Version   |   BSA ACS Version   |      BSA Tag ID     |    Pre-Si Support    |
 |-----------------------|:-------------------:|:-------------------:|:--------------------:|
+|       BSA v1.0(c)     |        v1.0.6       |   v23.09_REL1.0.6   |       Yes            |
 |       BSA v1.0(c)     |        v1.0.5       |   v23.07_REL1.0.5   |       Yes            |
 |       BSA v1.0(c)     |        v1.0.4       |   v23.03_REL1.0.4   |       Yes            |
 |       BSA v1.0        |        v1.0.3       |   v23.01_REL1.0.3   |       No             |

diff --git a/baremetal_app/BsaAcs.h b/baremetal_app/BsaAcs.h
@@ -23,7 +23,7 @@
 
   #define BSA_ACS_MAJOR_VER      1
   #define BSA_ACS_MINOR_VER      0
-  #define BSA_ACS_SUBMINOR_VER   5
+  #define BSA_ACS_SUBMINOR_VER   6
 
   #ifdef _AARCH64_BUILD_
   unsigned long __stack_chk_guard = 0xBAAAAAAD;

diff --git a/docs/Arm_BSA_ACS_Bare-metal_User_Guide.pdf b/docs/Arm_BSA_ACS_Bare-metal_User_Guide.pdf
diff --git a/docs/Arm_Base_System_Architecture_Compliance_User_Guide.pdf b/docs/Arm_Base_System_Architecture_Compliance_User_Guide.pdf
diff --git a/docs/Arm_Base_System_Architecture_Compliance_Validation_Methodology.pdf b/docs/Arm_Base_System_Architecture_Compliance_Validation_Methodology.pdf
diff --git a/docs/arm_bsa_architecture_compliance_bare-metal_user_guide.pdf b/docs/arm_bsa_architecture_compliance_bare-metal_user_guide.pdf
diff --git a/...Architecture_Compliance_Test_Scenario.pdf → ...architecture_compliance_test_scenario.pdf b/...Architecture_Compliance_Test_Scenario.pdf → ...architecture_compliance_test_scenario.pdf
diff --git a/docs/arm_bsa_architecture_compliance_user_guide.pdf b/docs/arm_bsa_architecture_compliance_user_guide.pdf
diff --git a/docs/arm_bsa_architecture_compliance_validation_methodology.pdf b/docs/arm_bsa_architecture_compliance_validation_methodology.pdf
diff --git a/docs/Arm_BSA_testcase-checklist.rst → docs/arm_bsa_testcase_checklist.rst b/docs/Arm_BSA_testcase-checklist.rst → docs/arm_bsa_testcase_checklist.rst
@@ -249,4 +249,4 @@ The below table provides the following details
 |917    |Check BME functionality of RP               |IE_REG_3, PCI_IN_05                                         |No   |No   |No   |Yes  |Yes       |No   |Yes                |
 +-------+--------------------------------------------+------------------------------------------------------------+-----+-----+-----+-----+----------+-----+-------------------+
 
-*For running tests on a bare-metal environment, integration of ACS with platform boot code is required. See `Bare-metal User Guide <Arm_BSA_ACS_Bare-metal_User_Guide.pdf>`_
+*For running tests on a bare-metal environment, integration of ACS with platform boot code is required. See ` arm BSA Bare-metal User Guide <docs/arm_bsa_architecture_compliance_bare-metal_user_guide.pdf>`_
diff --git a/linux_app/bsa-acs-app/include/bsa_app.h b/linux_app/bsa-acs-app/include/bsa_app.h
@@ -22,7 +22,7 @@
 
 #define BSA_APP_VERSION_MAJOR     1
 #define BSA_APP_VERSION_MINOR     0
-#define BSA_APP_VERSION_SUBMINOR  5
+#define BSA_APP_VERSION_SUBMINOR  6
 
 #define G_SW_OS            0
 #define G_SW_HYP           1

diff --git a/platform/pal_baremetal/FVP/README.md b/platform/pal_baremetal/FVP/README.md
@@ -14,7 +14,7 @@ This suite includes a set of examples of the invariant behaviors that are provid
 The tests are executed in a baremetal environment. The initialization of the baremetal environment is specific to the environment and is out of scope of this document.
 
 ## Release details
- - Code Quality: REL v1.0.5
+ - Code Quality: REL v1.0.6
  - The tests are written for version 1.0 (c) 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.
@@ -27,8 +27,8 @@ Contact your EDA vendor and ask if they include these tests as part of their ver
   - To get the latest version of the code with bug fixes and new features, use the main branch.
 
 ## Additional reading
-  - For details on the BSA ACS test execution, see the [Arm BSA ACS User Guide](../../../docs/Arm_BSA_ACS_Bare-metal_User_Guide.pdf).
-  - For details on the Design of the BSA ACS, see the [Arm BSA Validation Methodology Document](../../../docs/Arm_Base_System_Architecture_Compliance_Validation_Methodology.pdf).
+  - For details on the BSA ACS test execution, see the [Arm BSA ACS User Guide](../../../docs/arm_bsa_architecture_compliance_bare-metal_user_guide.pdf).
+  - For details on the Design of the BSA ACS, see the [Arm BSA Validation Methodology Document](../../../docs/arm_bsa_architecture_compliance_validation_methodology.pdf).
 Note: The Baremetal PCIe enumeration code provided as part of the BSA ACS should be used and should not be replaced. This code is vital in analyzing of the test result.
 
 ## Target platforms
@@ -111,7 +111,7 @@ The EFI executable file is generated at <edk2_path>/Build/Shell/DEBUG_GCC49/AARC
 
 The execution of the compliance suite varies depending on the test environment. These steps assume that the test suite is invoked through the ACS UEFI shell application.
 
-For details about the BSA ACS UEFI Shell application, see the [BSA ACS USER Guide](../../../docs/Arm_Base_System_Architecture_Compliance_User_Guide.pdf)
+For details about the BSA ACS UEFI Shell application, see the [BSA ACS USER Guide](../../../docs/arm_bsa_architecture_compliance_user_guide.pdf)
 
 ### On-Silicon
 
@@ -125,7 +125,7 @@ On a system where a USB port is available and functional, perform the following
 4. To determine the file system number of the plugged in USB drive, execute 'map -r' command.
 5. Type 'fsx' where 'x' is replaced by the number determined in step 4.
 6. To start the compliance tests, run the executable Bsa.efi with the appropriate parameters.
-   For details on the parameters, refer to [BSA ACS User Guide](../../../docs/Arm_Base_System_Architecture_Compliance_User_Guide.pdf)
+   For details on the parameters, refer to [BSA ACS User Guide](../../../docs/arm_bsa_architecture_compliance_user_guide.pdf)
 
 ## Limitations
 Validating the compliance of certain PCIe rules defined in the BSA specification requires the PCIe end-point to generate specific stimulus during the runtime of the test. Examples of such stimulus are  P2P, PASID, ATC, etc. The tests that requires these stimuli are grouped together in the exerciser module. The exerciser layer is an abstraction layer that enables the integration of hardware capable of generating such stimuli to the test framework.

diff --git a/platform/pal_baremetal/README.md b/platform/pal_baremetal/README.md
@@ -22,7 +22,7 @@ The output library files will be generated at <bsa_path>/build/lib/
 
 Note: Any platform specific changes can be done by using TARGET_EMULATION macro defintion. The pal_baremetal reference code is located in [pal_baremetal](.). To customize the bare-metal code for different platforms, create a directory <platform_name> in [pal_baremetal](.) folder and copy the reference code from [source](src) folder and [RDN2](FVP/RDN2) folder to <platform_name>.
 
-For more details on how to port the reference code to a specific platform and for further customisation please refer to the [User Guide](../../docs/Arm_BSA_ACS_Bare-metal_User_Guide.pdf)
+For more details on how to port the reference code to a specific platform and for further customisation please refer to the [User Guide](../../docs/arm_bsa_architecture_compliance_bare-metal_user_guide.pdf)
 
 -----------------
 

diff --git a/uefi_app/BsaAcs.h b/uefi_app/BsaAcs.h
@@ -22,7 +22,7 @@
 
   #define BSA_ACS_MAJOR_VER      1
   #define BSA_ACS_MINOR_VER      0
-  #define BSA_ACS_SUBMINOR_VER   5
+  #define BSA_ACS_SUBMINOR_VER   6
 
   #define G_PRINT_LEVEL ACS_PRINT_TEST
-Original file line number
+Diff line change
@@ Expand Up @@
     Note: Any platform specific changes can be done by using TARGET_EMULATION macro defintion. The pal_baremetal reference code is located in [pal_baremetal](.). To customize the bare-metal code for different platforms, create a directory <platform_name> in [pal_baremetal](.) folder and copy the reference code from [source](src) folder and [RDN2](FVP/RDN2) folder to <platform_name>.
-    For more details on how to port the reference code to a specific platform and for further customisation please refer to the [User Guide](../../docs/Arm_BSA_ACS_Bare-metal_User_Guide.pdf)
+    For more details on how to port the reference code to a specific platform and for further customisation please refer to the [User Guide](../../docs/arm_bsa_architecture_compliance_bare-metal_user_guide.pdf)
     -----------------
@@ Expand Down @@