Linux userland API discussions
 help / color / mirror / Atom feed
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

  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