README.md

<!--
#
# Platform Fault Detection Interface (PFDI)
#
# SPDX-FileCopyrightText: <text>Copyright 2025
#   Arm Limited and/or its affiliates <open-source-office@arm.com></text>
# SPDX-License-Identifier: MIT
#
-->

# Platform Fault Detection Interface Reference Implementation

The Platform Fault Detection Interface (PFDI) Reference Implementation provides a reference implementation of the
[Platform Fault Detection Interface][1] specification. PFDI defines a standardized firmware interface that enables
System Software (such as operating systems and hypervisors) to interact with Platform Firmware, executing at
Exception Level 3 (EL3) or within the Secure World, for the purpose of:
- Performing hardware self-tests.
- Retrieving boot-time diagnostics.
- Enabling controlled fault injection for software validation.

Specifically, the interface supports:
- Power-on self-tests of Processing Elements (PEs).
- Retrieval of firmware-internal boot-time check results.
- Runtime test execution of PE-local or platform-level diagnostics.
- Controlled fault injection to validate error-handling mechanisms in System Software.

The PFDI reference implementation includes the following components:
- libpfdi – A userspace C library that enables interaction between System Software and Platform Firmware through a device interface.
- pfdi-sample-app – A multi-threaded test runner that initiates platform-level tests using the libpfdi API.
- pfdi-cli – A command-line interface for querying firmware status and injecting faults.
- pfdi-tool – A Python-based utility suite for generating, validating, and packaging YAML-based test configurations.

---

## Components

### `libpfdi`
A userspace C library that communicates with platform firmware through a miscellaneous device interface.
It provides:
- Initialization and cleanup of device handles
- Firmware version and  libpfdi version
- Boot-time test results and runtime test execution
- Error injection support for testing recovery logic

### `pfdi-sample-app`
A sample multi-threaded test runner that reads a binary configuration file and executes platform tests
across all configured CPUs using the `libpfdi` API.

### `pfdi-cli`
A command-line interface that exposes direct PFDI test and query functionality such as fault injection,
test results, Firmware version and libpfdi version.

### `pfdi-tool`
A Python-based toolkit to help developers:
- Generate YAML test configurations
- Validate and fix CPU task ranges
- Pack YAML files into a binary format readable by `pfdi-sample-app`

---

## Directory Layout

| Path                        | Purpose                                               |
|-----------------------------|-------------------------------------------------------|
| `libpfdi/`                  | Userspace C library (headers and .c)                  |
| `pfdi-demo/`                | Userspace application and tools                       |
| `pfdi-demo/pfdi-sample-app` | Multi-CPU sample test runner                          |
| `pfdi-demo/pfdi-cli`        | Command-line tool for interacting with PFDI features  |
| `pfdi-demo/pfdi-common`     | Shared utilities and common code for PFDI demo apps   |
| `pfdi-demo/pfdi-tool/`      | Python tools for YAML config workflow                 |

---

## Dependencies

- CMake ≥ 3.16
- GCC ≥ 9.4
- Python ≥ 3.8.10
- Pip ≥ 20.0
- python-venv
- Doxygen (optional, for generating documentation)

---

## Installation & Build

### Build the C Components
```bash
mkdir build
cd build
cmake ../
make
```

### Set up Python Virtual Environment
```bash
python -m venv ./venv
source ./venv/bin/activate
pip install pfdi-demo/pfdi-tool
```

---

## Test Workflow Overview

1. Use `pfdi-tool` to create or manage YAML configurations.
2. Pack configurations into a `.pack` binary file.
3. Run `pfdi-sample-app` with the binary file to perform CPU-based tests.
4. Use `pfdi-cli` for interactive test or debug steps.

---

## `pfdi-tool` Commands

### Generate
```bash
pfdi-tool generate 0 40 60 5 16 ./configs
```

- Range: 0 to 40
- Interval: 60 ms
- 5 config files, max 16 CPUs each

### Validate
```bash
pfdi-tool validate ./configs
```

### Fix
```bash
pfdi-tool fix ./configs
```

### Pack
```bash
pfdi-tool pack ./configs ./binary_configs
```

---

## Sample YAML Format

```yaml
%YAML 1.2
---

pfdi_conf_version: "1.0"

interval: 60

max_cpu_num: 16

tasks:
  - cpu: 0
    range:
      start: 0
      end: 1

```

---

## Run PFDI App

```bash
pfdi-sample-app --config ./binary_configs/pfdi_test_config.pack --mode [single|periodic]
```

- `single` – run tests once
- `periodic` – loop with intervals from the config (default is periodic)

Optional logging flags:
- `-i, --info` info only
- `-v, --verbose` verbose (debug)
- `-l, --log` file to store pfdi logs
- `-m, --mode` test frequency single or periodic

Example:
```bash
pfdi-sample-app -ic ./binary_configs/pfdi_test_config.pack -m single
```

---

## Example Output

```
[info] libPFDI version: 1.0
[warn] Stub firmware detected – No real diagnostics will be executed
[info] Firmware reports 41 available diagnostic tests
[info] Loaded config v1.0: running 4 tasks every 60 ms
```

---

##  `pfdi-cli` Commands

### Force Error
```bash
pfdi-cli -e <cpu_id> <fid> <error_id>
```

### Read Firmware Info
```bash
pfdi-cli -p <cpu_id>
```

### Userspace Library Info
```bash
pfdi-cli -i
```

### Test Count
```bash
pfdi-cli -c <cpu_id>
```

### Out-of-Reset Test Result
```bash
pfdi-cli -r <cpu_id>
```

# Disclaimer

Arm is a registered trademark of Arm Limited (or its subsidiaries or affiliates).

[1]: https://developer.arm.com/documentation/110468/1-0alp0