Skip to content

Commit

Permalink
Exerciser documents and README updates (#402)
Browse files Browse the repository at this point in the history 
- 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]>
  • Loading branch information
@Sujana-M
Sujana-M committed Sep 29, 2023
1 parent b020811 commit a148aeb
Show file tree
Hide file tree
Showing 8 changed files with 1,647 additions and 7 deletions.
25 changes: 22 additions & 3 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,12 +14,18 @@ For more information, download the [SBSA specification](https://developer.arm.co

SBSA **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 [SBSA specification](https://developer.arm.com/documentation/den0029/h/?lang=en), so that implementers can verify if these behaviours have been interpreted correctly.

Most of the tests are executed from UEFI Shell by executing the SBSA UEFI shell application.
A few tests are executed by running the SBSA ACS Linux application which in turn depends on the SBSA 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: REL v7.1.2
- The tests are written for version 7.1 of the SBSA specification.
- For complete coverage of the SBSA rules, availability of an Exerciser is required for Exerciser tests to be run during verficiation at Pre-Silicon level.
- For complete coverage, both SBSA and BSA ACS should be run.
- The SBSA specification compliments the [BSA specification](https://developer.arm.com/documentation/den0094/c/?lang=en).
- The tests can be run at both the Pre-Silicon and Silicon level.
- The compliance suite is not a substitute for design verification.
- To review the SBSA ACS logs, Arm licensees can contact Arm directly through their partner managers.
- To know about the SBSA rules not implemented in this release, see [Test Scenario Document](docs/Arm_SBSA_Architecture_Compliance_Test_Scenario.pdf).
Expand All @@ -31,13 +37,19 @@ A few tests are executed by running the SBSA ACS Linux application which in turn

## Additional reading
- For information about the implementable SBSA rules test algorithm and for unimplemented SBSA rules, see the [Test Scenario Document](docs/Arm_SBSA_Architecture_Compliance_Test_Scenario.pdf).
- For information on test category(UEFI, Linux, BM) and applicable systems(SR,PreSilicon), see [Test Checklist](docs/Arm_SBSA_testcase-checklist.rst)
- For information on test category(UEFI, Linux, Bare-metal) and applicable systems(SR,Pre-Silicon), see [Test Checklist](docs/Arm_SBSA_testcase-checklist.rst)
- For details on the design of the SBSA ACS, see the [Arm SBSA Validation Methodology Document](docs/Arm_SBSA_Architecture_Compliance_Validation_Methodology.pdf).
- For details on the SBSA ACS UEFI Shell Application, Linux Application and PMU Linux Application see the [Arm SBSA ACS User Guide](docs/Arm_SBSA_Architecture_Compliance_User_Guide.pdf).
- For details on the SBSA ACS Baremetal support, see the
- For details on the SBSA ACS Bare-metal support, see the
- [Arm SBSA ACS Bare-metal User Guide](docs/Arm_SBSA_ACS_Bare-metal_User_Guide.pdf).
- [Bare-metal Code](platform/pal_baremetal/). <br />
Note: The Baremetal PCIe enumeration code provided as part of the SBSA 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 SBSA 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 SBSA 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)

## SBSA ACS Linux kernel module
To enable the export of a few kernel APIs that are necessary for PCIe and IOMMU tests, Linux kernel module and a kernel patch file are required. These files are available at [linux-acs](https://gitlab.arm.com/linux-arm/linux-acs).
Expand Down Expand Up @@ -214,6 +226,13 @@ shell> ./sbsa
```
- For information on the SBSA Linux application parameters, see the [SBSA ACS User Guide](docs/Arm_SBSA_Architecture_Compliance_User_Guide.pdf).

## ACS build steps - Bare-metal abstraction

The Bare-metal build environment is platform specific.

To execute the Bare-metal code from UEFI Shell, checkout to [bare-metal](https://github.com/ARM-software/sbsa-acs/tree/baremetal_reference) branch of SBSA and the build steps to integrate and run the same from UEFI shell are provided in the [README.md](https://github.com/ARM-software/sbsa-acs/blob/baremetal_reference/README.md)

For details on generating the binaries to run on Bare-metal environment, refer [README.md](platform/pal_baremetal/README.md)

## Security implication
Arm Enterprise ACS test suite may run at higher privilege level. An attacker may utilize these tests as a means to elevate privilege which can potentially reveal the platform security assets. To prevent the leakage of secure information, it is strongly recommended that the ACS test suite is run only on development platforms. If it is run on production systems, the system should be scrubbed after running the test suite.
Expand Down
127 changes: 127 additions & 0 deletions docs/PCIe_Exerciser/ErrorInjection.md
View file
Original file line number Diff line number Diff line change
@@ -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.*
Loading

0 comments on commit a148aeb

Please sign in to comment.