Exerciser documents and README updates (#218)

- Added the README which provides information on where to download the RDN2 SW stack - Any changes required for running SBSA exerciser on RDN2 reference - All the documentation and README updates related to PCIe exerciser functionality Signed-off-by: Sujana M <[email protected]>
ARM-software · Sep 29, 2023 · 53d2118 · 53d2118
1 parent 4082a94
commit 53d2118
Show file tree

Hide file tree

Showing 8 changed files with 1,829 additions and 4 deletions.
diff --git a/README.md b/README.md
@@ -14,11 +14,13 @@ BSA **Architecture Compliance Suite** (ACS) is a collection of self-checking, po
 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
  - 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).
@@ -29,13 +31,19 @@ A few tests are executed by running the BSA ACS Linux application which in turn
 
 ## 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, BM) and applicable systems(IR,ES,SR,PreSilicon), see the [Test Checklist](docs/Arm_BSA_testcase-checklist.rst).
+  - 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 details on the BSA ACS Baremetal support, see the
+  - 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).
     - [Bare-metal Code](platform/pal_baremetal/). <br />
-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.
+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.
+
+### Running Exerciser tests for complete coverage
+
+Exerciser is a client device wrapped up by PCIe Endpoint. This device is created to meet BSA requirements for various PCIe capability validation tests. Running the Exerciser tests provides additional test coverage on the platform.
+
+Note: To run the exerciser tests on a UEFI Based platform with Exerciser, the Exerciser PAL API's need to be implemented. For details on the reference Exerciser implementation and support, see the [Exerciser.md](docs/PCIe_Exerciser/Exerciser.md) and [Exerciser_API_porting_guide.md](docs/PCIe_Exerciser/Exerciser_API_porting_guide.md)
 
 ## ACS build steps - UEFI Shell application
 
@@ -220,6 +228,14 @@ shell> ./bsa
 ```
   - For information on the BSA Linux application parameters, see the [User Guide](docs/Arm_Base_System_Architecture_Compliance_User_Guide.pdf).
 
+## ACS build steps - Bare-metal abstraction
+
+The Bare-metal build environment is platform specific.
+
+To provide a baseline, the build steps to integrate and run the Bare-metal tests from UEFI shell are provided in [README.md](platform/pal_baremetal/FVP/README.md).
+
+For details on generating the binaries to run on Bare-metal environment, refer [README.md](platform/pal_baremetal/README.md)
+
 ## Security implication
 The Arm SystemReady 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.
 

diff --git a/docs/PCIe_Exerciser/ErrorInjection.md b/docs/PCIe_Exerciser/ErrorInjection.md
@@ -0,0 +1,127 @@
+# PCIe Error Injection user documentation
+This document gives details of the error injection mechanism for PCIe endpoints and how it can be used to inject errors and check for error reporting inside PCIe subsystem.
+
+## Introduction to PCIe error injection mechanism
+
+A new Error injection extended capability, implemented as a DVSEC, has been added to enable user to inject errors in an PCIe endpoint. This capability can be enabled using a new parameter : `error_injection_supported`. The layout of this capability is as follows:
+
+```
+ Register Name                Description                                   Address offset
+ -------------                -----------                                   --------------
+
+ Extended Capability Header   Standard DVSEC header.                             0x0
+
+ DVSEC Header 1               Error injection DVSEC details.                     0x4
+
+ Control Register             Configure and inject errors (ERROR_CTL_REG)        0x8
+
+```
+
+## Register description
+
+```
+ Extended Capability Header  Bits   Description                                   r/w  Value at reset
+ --------------------------  -----  -----------                                   ---  --------------
+
+ extended_capability_id      15:0   Identifies which extended capability          RO      0x0023
+                                    structure this is.
+
+ capability_version          19:16  Identifies the version of this                RO      0x1
+                                    structure.
+
+ next_capability_offset      31:20  Provides the byte offset from the top of      RO     Depends on
+                                    config space to the next extended capability         position of
+                                    structure. A value of 000h ends the linked         next capability
+                                    list of extended capability structures.
+
+
+ DVSEC Header 1              Bits   Description                                   r/w  Value at reset
+ --------------------------  -----  -----------                                   ---  --------------
+
+ dvsec_vendor_id             15:0   Holds a designated VendorID assigned by the   RO       0x13B5
+                                    PCI-SIG. This VendorID would be assigned to
+                                    a group of companies collaborating on a
+                                    common set of register definitions which
+                                    would like in this structure in PCI config
+                                    space.
+
+ dvsec_rev                   19:16  Holds a vendor-defined version number         RO       0x0
+
+ dvsec_length                31:20  Indicates the size (in bytes) of this         RO       0xC
+                                    extended capability structure, including
+                                    the Extended Capability Header, DVSEC
+                                    Header1 and DVSEC Header 2.
+
+
+ Control Register            Bits   Description                                   r/w  Value at reset
+ --------------------------  -----  -----------                                   ---  --------------
+
+ dvsec_id                    15:0   Holds a vendor-defined identification         RO       0x1
+                                    number to help determine the nature and
+                                    format of this structure.
+
+ inject_error_on_dma         16     Put endpoint in Corrupt DMA mode. See         RW       0x0
+                                    Corrupt DMA section for more details.
+
+ inject_error_immediately    17     Inject error in this endpoint configured      RW       0x0
+                                    using the error_code field.
+
+ reserved                    19:18  Reserved                                      RO       0x0
+
+ error_code                  30:20  Error code configuration for corrupt DMA      RW       0x0
+                                    mode and inject_error_immediately
+
+ treat_uncorrectable_as_     31     If error code is an uncorrectable error,      RW       0x0
+ fatal                              then this bit configures severity of the
+                                    error. This bit has no effect if endpoint
+                                    supports Advanced Error Reporting (AER).
+                                    If AER is supported, this bit is
+                                    overridden by AER uncorrectable severity
+                                    register.
+```
+
+## How to inject errors
+
+There are 2 ways to inject errors:
+  * Inject immediately : Using the `inject_error_immediately` bit set, the user can inject an error at that endpoint with the error configured using the `error_code` field in control register. The error_codes are defined in Error Codes section. This bit is cleared once the error has been injected.
+
+  * Corrupt DMA : With the `inject_error_on_dma` bit set, the endpoint is put in Corrupt DMA mode. Any peer-to-peer DMAs generated in corrupt DMA mode, will lead to an error injection in destination endpoint. All DMAs will fail by default in this mode, so this bit will need to be cleared for normal functioning of DMAs for this endpoint. The injected error in destination endpoint will be as configured by `error_code` field in control register. The error_codes are defined in Error Codes section.
+
+## Error Codes
+```
+    Error Name                             Error Code
+    ----------                             ----------
+    Correctable Receiver Error                0x00
+    Correctable Bad TLP                       0x01
+    Correctable Bad DLLP                      0x02
+    Correctable Replay Num Rollover           0x03
+    Correctable Replay Timer Timeout          0x04
+    Correctable Advisory Non-Fatal Error      0x05
+    Correctable Internal Error                0x06
+    Correctable Header Log OverFlow           0x07
+    Uncorrectable Data Link Error             0x08
+    Uncorrectable Surprise Down Error         0x09
+    Uncorrectable Poisoned TLP Received       0x0A
+    Uncorrectable Flow Control Error          0x0B
+    Uncorrectable Completion Timeout          0x0C
+    Uncorrectable Completer Abort             0x0D
+    Uncorrectable Unexpected Completion       0x0E
+    Uncorrectable Receiver Overflow           0x0F
+    Uncorrectable Malformed TLP               0x10
+    Uncorrectable ECRC Error                  0x11
+    Uncorrectable Unsupported Request         0x12
+    Uncorrectable ACS Violation               0x13
+    Uncorrectable Internal Error              0x14
+    Uncorrectable MultiCast Blocked TLP       0x15
+    Uncorrectable Atomic Op Egress Blocked    0x16
+    Uncorrectable TLP Prefix Blocked Egress   0x17
+    Uncorrectable Poisoned TLP Egress Blocked 0x18
+    Invalid configuration                     0x19 onwards
+```
+
+## Error reporting in intermediate components:
+When an corrupt DMA passes through an intermediate component such as a switch, it can detect and report an uncorrectable error as an advisory non-fatal error. The detecting bridges (inside the switch) will, in this case, log a correctable advisory non-fatal error and optionally report an correctable error message to its parent root port. This detection and reporting of intermediate errors can be enabled using a new parameter `report_advisory_non_fatal_errors` for a switch.
+
+--------------
+
+*Copyright (c) 2023, Arm Limited and Contributors. All rights reserved.*