From: Ashok Raj <ashok.raj@oss.qualcomm.com>
To: Ahmed Azeem <ahmed.azeem@arm.com>
Cc: linux-arm-kernel@lists.infradead.org,
Sudeep Holla <sudeep.holla@kernel.org>,
Jonathan Corbet <corbet@lwn.net>,
Shuah Khan <skhan@linuxfoundation.org>,
Randy Dunlap <rdunlap@infradead.org>,
Mark Rutland <mark.rutland@arm.com>,
Lorenzo Pieralisi <lpieralisi@kernel.org>,
linux-api@vger.kernel.org, linux-doc@vger.kernel.org,
linux-kernel@vger.kernel.org, Divin Raj <divin.raj@arm.com>,
Bertrand Marquis <Bertrand.Marquis@arm.com>,
jithu.joseph@oss.qualcomm.com, Borislav Petkov <bp@alien8.de>,
Tony Luck <tony.luck@intel.com>,
Ashok Raj <ashok.raj@oss.qualcomm.com>,
Jonathan Cameron <jonathan.cameron@oss.qualcomm.com>
Subject: Re: [PATCH RFC 1/4] uapi: firmware: arm: Add PFDI userspace ABI
Date: Fri, 20 Nov 2026 20:14:52 -0800 [thread overview]
Message-ID: <awEavIhFldTD2k46@hu-ashoraj-lv.qualcomm.com> (raw)
In-Reply-To: <20261119-topics-ahmaze01-upstream-pfdi-rfc-v1-1-4772d18b9115@arm.com>
On Thu, Nov 19, 2026 at 03:36:03PM +0000, Ahmed Azeem wrote:
> From: Divin Raj <divin.raj@arm.com>
>
> 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@arm.com>
> Signed-off-by: Ahmed Azeem <ahmed.azeem@arm.com>
> ---
> 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@lists.infradead.org>
> +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.
Hi Ahmed, Divin,
+ Tony, Boris, Jithu
A few UAPI/design comments below.
The range-based PFDI_PE_TEST_RUN operation has a reasonable case for a
structured interface: it takes an inclusive start/end range and can return a
failing test-part ID. Encoding that in a sysfs write would establish a
permanent text grammar and still require a separate result-retrieval
mechanism.
However, it would be useful to explain why all of the interface is exposed
through per-CPU ioctls. Intel IFS, for example, uses sysfs for simple
control and persistent status: run_test, status, details, image_version, and
current_batch. That does not necessarily mean PFDI should copy IFS, but a
hybrid design may be worth considering:
- sysfs for stable scalar discovery/status such as PFDI version, test
engine ID, test-part count, and power-on test status; and
- a typed interface for the range-based test execution request and its
structured result.
Also, before struct pfdi_test_run becomes stable UAPI, please consider
adding explicit flags and reserved fields. The structure currently leaves
no ABI growth space, despite already having a special -1/-1 all-tests
encoding and likely needing a structured test-result field.
Finally, PFDI_PE_TEST_RESULT reports the result of tests executed at
power-on, before system software booted; it is not the result of the most
recent PFDI_PE_TEST_RUN. Could the naming or ABI documentation make the
power-on semantics more prominent? The current name is easy to read as
the result of the runtime run ioctl.
> +
> + * 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.
> +
Hope this helps.
Cheers,
Ashok
next prev parent reply other threads:[~2026-11-21 4:14 UTC|newest]
Thread overview: 9+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-11-19 15:36 [PATCH RFC 0/4] firmware: arm: Add Platform Fault Detection Interface support Ahmed Azeem
2026-11-19 15:36 ` [PATCH RFC 1/4] uapi: firmware: arm: Add PFDI userspace ABI Ahmed Azeem
2026-11-19 21:35 ` Jonathan Cameron
2026-11-21 4:14 ` Ashok Raj [this message]
2026-11-19 15:36 ` [PATCH RFC 2/4] firmware: arm: Add PFDI misc driver skeleton Ahmed Azeem
2026-11-19 15:36 ` [PATCH RFC 3/4] firmware: arm: Add PFDI run, result, and error injection support Ahmed Azeem
2026-11-21 3:52 ` Ashok Raj
2026-11-19 15:36 ` [PATCH RFC 4/4] firmware: arm: Harden PFDI worker and hotplug handling Ahmed Azeem
2026-11-21 0:44 ` [PATCH RFC 0/4] firmware: arm: Add Platform Fault Detection Interface support Jithu Joseph
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=awEavIhFldTD2k46@hu-ashoraj-lv.qualcomm.com \
--to=ashok.raj@oss.qualcomm.com \
--cc=Bertrand.Marquis@arm.com \
--cc=ahmed.azeem@arm.com \
--cc=bp@alien8.de \
--cc=corbet@lwn.net \
--cc=divin.raj@arm.com \
--cc=jithu.joseph@oss.qualcomm.com \
--cc=jonathan.cameron@oss.qualcomm.com \
--cc=linux-api@vger.kernel.org \
--cc=linux-arm-kernel@lists.infradead.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=lpieralisi@kernel.org \
--cc=mark.rutland@arm.com \
--cc=rdunlap@infradead.org \
--cc=skhan@linuxfoundation.org \
--cc=sudeep.holla@kernel.org \
--cc=tony.luck@intel.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox
all inboxes | Powered by JetHome®