[PATCH RFC 1/4] uapi: firmware: arm: Add PFDI userspace ABI
From: Ahmed Azeem
Date: Thu Nov 19 2026 - 10:36:54 EST
From: Divin Raj <divin.raj@xxxxxxx>
Define the userspace ABI for the Arm Platform Fault Detection
Interface (PFDI).
Subsequent commits introduce a driver that exposes a per-CPU misc
device. The ioctl definitions, data structures, and return codes
must therefore be shared with userspace. Add these definitions to
a UAPI header and document the ABI for /dev/cpu/<cpu>/pfdi.
Placing the interface under include/uapi ensures availability via
headers_install and clearly identifies it as a userspace contract.
Link: https://developer.arm.com/documentation/110468/1-0alp0
Signed-off-by: Divin Raj <divin.raj@xxxxxxx>
Signed-off-by: Ahmed Azeem <ahmed.azeem@xxxxxxx>
---
Documentation/ABI/testing/dev-cpu-pfdi | 103 +++++++++++++++++++++
Documentation/userspace-api/ioctl/ioctl-number.rst | 1 +
MAINTAINERS | 7 ++
include/uapi/linux/pfdi.h | 89 ++++++++++++++++++
4 files changed, 200 insertions(+)
diff --git a/Documentation/ABI/testing/dev-cpu-pfdi b/Documentation/ABI/testing/dev-cpu-pfdi
new file mode 100644
index 000000000000..e07ed6baa7f8
--- /dev/null
+++ b/Documentation/ABI/testing/dev-cpu-pfdi
@@ -0,0 +1,103 @@
+What: /dev/cpu/<cpu>/pfdi
+Date: May 2026
+KernelVersion: 6.18
+Contact: Linux ARM Kernel Mailing list <linux-arm-kernel@xxxxxxxxxxxxxxxxxxx>
+Reference: Arm Platform Fault Detection Interface, document 110468,
+ version 1.0 ALP0
+Description: Per-CPU Arm Platform Fault Detection Interface (PFDI) misc
+ device nodes. Each node targets the CPU encoded in its
+ path and exposes the PFDI service implemented by firmware.
+ PFDI uses the Arm SMCCC SMC64 calling convention and is
+ PE-local. Userspace is therefore expected to bind itself to
+ the target CPU before opening or issuing ioctls on the
+ matching device node. Each node is single-open: only one
+ userspace owner at a time may hold /dev/cpu/<cpu>/pfdi for a
+ given CPU. Additional open attempts fail with -EBUSY while the
+ device is already open.
+
+ The ABI is defined in <linux/pfdi.h>. The following ioctls
+ are supported:
+
+ * PFDI_IOCTL_VERSION
+ Read the PFDI version for the target CPU. On success the
+ ioctl returns 0 and copies a 32-bit version value to
+ userspace with the following layout:
+ Bits[30:16] PFDI major version
+ Bits[15:0] PFDI minor version
+
+ * PFDI_IOCTL_FEATURES
+ Query whether a PFDI function ID is supported on the
+ target CPU. Userspace passes a 32-bit PFDI function ID.
+ The ioctl returns 0 when the function is supported,
+ and -EOPNOTSUPP when it is not supported on the target
+ CPU, reserved by the specification, or otherwise not
+ recognized by firmware.
+
+ * PFDI_IOCTL_PE_TEST_ID
+ Read the test engine identifier for the target CPU.
+ On success the ioctl returns 0 and copies a 64-bit value to
+ userspace with the following layout:
+ Bits[63:32] reserved and zero
+ Bits[31:24] vendor ID
+ Bits[23:20] reserved and zero
+ Bits[19:16] vendor-defined implementation ID
+ Bits[15:8] major version
+ Bits[7:0] minor version
+
+ * PFDI_IOCTL_PE_TEST_PART_COUNT
+ Read the number of available test parts for the target
+ CPU. On success the ioctl returns 0 and copies a signed
+ 64-bit count to userspace. The smallest schedulable unit is
+ a test part, and valid test part indices are in the range 0
+ to count - 1.
+
+ * PFDI_IOCTL_PE_TEST_RUN
+ Run a requested inclusive test part range on the target
+ CPU. struct pfdi_test_run.range.start and .end are signed
+ 64-bit values.
+ Passing start = -1 and end = -1 requests execution of all
+ available test parts on the target CPU. Any mixed use of
+ -1, reversed ranges, out-of-range indices, or non-zero
+ reserved arguments is rejected with -EINVAL, either by the
+ kernel before the request is issued or by firmware.
+ If firmware reports PFDI_RET_FAULT_FOUND, the ioctl returns
+ -EFAULT and copies a signed 64-bit failing test part
+ identifier to struct pfdi_test_run.ft_id. If the failing
+ part cannot be identified, ft_id is set to
+ PFDI_RET_UNKNOWN.
+
+ * PFDI_IOCTL_PE_TEST_RESULT
+ Fetch the stored out-of-reset test result for the target CPU.
+ If firmware reports PFDI_RET_FAULT_FOUND, the ioctl returns
+ -EFAULT and copies a signed 64-bit failing test part
+ identifier to userspace. If the failing part cannot be
+ identified, the copied value is PFDI_RET_UNKNOWN. If no
+ power-on tests were executed on the target CPU, the ioctl
+ returns -EAGAIN.
+
+ * PFDI_IOCTL_FW_CHECK
+ Ask firmware to execute platform firmware resident software
+ integrity checks. The ioctl returns 0 when no fault is
+ detected. It returns -EFAULT when firmware reports a fault.
+ Platforms that do not implement firmware integrity checks
+ still report success.
+
+ * PFDI_IOCTL_FORCE_ERROR
+ Schedule injection of a specific PFDI return value for the
+ next invocation of a selected PFDI function on the same
+ CPU. The requested function ID must be a supported PFDI
+ function IDs. Only one pending injected error is permitted
+ per CPU and function, and a new request replaces any older
+ undelivered request for the same pair. When the injection
+ is delivered, firmware returns the injected value in x0 and
+ zeros x1 to x4.
+
+ These device nodes reflect the PFDI 1.0 ALP0 specification.
+ PFDI state is not persistent across reset or firmware update;
+ userspace must rediscover capabilities and any test state
+ after such events.
+
+ These nodes are intended for platform bring-up and validation.
+ Access should therefore be restricted to privileged software.
+
+Users: Platform validation and manufacturing test tools
diff --git a/Documentation/userspace-api/ioctl/ioctl-number.rst b/Documentation/userspace-api/ioctl/ioctl-number.rst
index dbe462040999..aa5a6cf20d3c 100644
--- a/Documentation/userspace-api/ioctl/ioctl-number.rst
+++ b/Documentation/userspace-api/ioctl/ioctl-number.rst
@@ -170,6 +170,7 @@ Code Seq# Include File Comments
'I' all linux/isdn.h conflict!
'I' 00-0F drivers/isdn/divert/isdn_divert.h conflict!
'I' 40-4F linux/mISDNif.h conflict!
+'J' 01-08 linux/pfdi.h Arm Platform Fault Detection Interface
'K' all linux/kd.h
'L' 00-1F linux/loop.h conflict!
'L' 10-1F drivers/scsi/mpt3sas/mpt3sas_ctl.h conflict!
diff --git a/MAINTAINERS b/MAINTAINERS
index d738990161bd..de9c296d1de1 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -14012,6 +14012,13 @@ F: drivers/iommu/iova.c
F: include/linux/iommu-dma.h
F: include/linux/iova.h
+Platform Fault Detection Interface - ARM PFDI
+M: Ahmed Azeem <ahmed.azeem@xxxxxxx>
+L: linux-arm-kernel@xxxxxxxxxxxxxxxxxxx (moderated for non-subscribers)
+S: Maintained
+F: Documentation/ABI/testing/dev-cpu-pfdi
+F: include/uapi/linux/pfdi.h
+
IOMMU SUBSYSTEM
M: Joerg Roedel (AMD) <joro@xxxxxxxxxx>
M: Will Deacon <will@xxxxxxxxxx>
diff --git a/include/uapi/linux/pfdi.h b/include/uapi/linux/pfdi.h
new file mode 100644
index 000000000000..e3b7fe19daf4
--- /dev/null
+++ b/include/uapi/linux/pfdi.h
@@ -0,0 +1,89 @@
+/* SPDX-License-Identifier: GPL-2.0-only WITH Linux-syscall-note */
+/*
+ * Arm Platform Fault Detection Interface (PFDI) userspace ABI
+ *
+ * Copyright (C) 2026 Arm Ltd.
+ */
+
+#ifndef _UAPI_LINUX_PFDI_H
+#define _UAPI_LINUX_PFDI_H
+
+#include <linux/ioctl.h>
+#include <linux/types.h>
+
+/*
+ * SMC function IDs for PFDI v1.0.
+ * These follow the SMCCC fast-call, 64-bit, Standard Secure Service encoding.
+ */
+#define PFDI_FN_BASE 0xC40002D0U
+#define PFDI_FN(n) (PFDI_FN_BASE + (n))
+
+#define PFDI_FN_VERSION PFDI_FN(0x00)
+#define PFDI_FN_FEATURES PFDI_FN(0x01)
+#define PFDI_FN_PE_TEST_ID PFDI_FN(0x02)
+#define PFDI_FN_PE_TEST_PART_COUNT PFDI_FN(0x03)
+#define PFDI_FN_PE_TEST_RUN PFDI_FN(0x04)
+#define PFDI_FN_PE_TEST_RESULT PFDI_FN(0x05)
+#define PFDI_FN_FW_CHECK PFDI_FN(0x06)
+#define PFDI_FN_FORCE_ERROR PFDI_FN(0x07)
+
+#define PFDI_VERSION_MAJOR_SHIFT 16
+#define PFDI_VERSION_MAJOR_MASK 0x7FFFU
+#define PFDI_VERSION_MINOR_MASK 0xFFFFU
+
+#define PFDI_VERSION_MAJOR(ver) \
+ (((ver) >> PFDI_VERSION_MAJOR_SHIFT) & PFDI_VERSION_MAJOR_MASK)
+#define PFDI_VERSION_MINOR(ver) ((ver) & PFDI_VERSION_MINOR_MASK)
+#define PFDI_VERSION(maj, min) \
+ ((((maj) & PFDI_VERSION_MAJOR_MASK) << PFDI_VERSION_MAJOR_SHIFT) | \
+ ((min) & PFDI_VERSION_MINOR_MASK))
+
+/* PFDI return values */
+#define PFDI_RET_TEST_COUNT_ZERO (-8)
+#define PFDI_RET_UNKNOWN (-7)
+#define PFDI_RET_NOT_RUN (-6)
+#define PFDI_RET_ERROR (-5)
+#define PFDI_RET_FAULT_FOUND (-4)
+#define PFDI_RET_INVALID_PARAM (-3)
+#ifndef SMCCC_RET_NOT_SUPPORTED
+#define SMCCC_RET_NOT_SUPPORTED (-1)
+#endif
+#ifndef SMCCC_RET_SUCCESS
+#define SMCCC_RET_SUCCESS 0
+#endif
+
+struct pfdi_test_range {
+ __s64 start;
+ __s64 end;
+};
+
+struct pfdi_test_run {
+ struct pfdi_test_range range;
+ __s64 ft_id;
+};
+
+struct pfdi_force_error {
+ __u32 smc_fid;
+ /* Keep the ioctl layout identical for native and compat userspace. */
+ __u32 reserved;
+ __s64 error_id;
+};
+
+#define PFDI_IOCTL_VERSION \
+ _IOR('J', 1, __u32)
+#define PFDI_IOCTL_FEATURES \
+ _IOW('J', 2, __u32)
+#define PFDI_IOCTL_PE_TEST_ID \
+ _IOR('J', 3, __u64)
+#define PFDI_IOCTL_PE_TEST_PART_COUNT \
+ _IOR('J', 4, __s64)
+#define PFDI_IOCTL_PE_TEST_RUN \
+ _IOWR('J', 5, struct pfdi_test_run)
+#define PFDI_IOCTL_PE_TEST_RESULT \
+ _IOR('J', 6, __s64)
+#define PFDI_IOCTL_FW_CHECK \
+ _IO('J', 7)
+#define PFDI_IOCTL_FORCE_ERROR \
+ _IOW('J', 8, struct pfdi_force_error)
+
+#endif /* _UAPI_LINUX_PFDI_H */
--
2.43.0