On 3/4/2025 1:12 AM, Jonathan Cameron wrote:
On Fri, 28 Feb 2025 17:35:54 -0800
Shannon Nelson <shannon.nelson@xxxxxxx> wrote:
Add pds_fwctl to the driver and fwctl documentation pages.
Signed-off-by: Shannon Nelson <shannon.nelson@xxxxxxx>
Really minor stuff inline.
Thanks,
Jonathan
---
Documentation/userspace-api/fwctl/fwctl.rst | 1 +
Documentation/userspace-api/fwctl/index.rst | 1 +
.../userspace-api/fwctl/pds_fwctl.rst | 41 +++++++++++++++++++
3 files changed, 43 insertions(+)
create mode 100644 Documentation/userspace-api/fwctl/pds_fwctl.rst
diff --git a/Documentation/userspace-api/fwctl/fwctl.rst b/Documentation/userspace-api/fwctl/fwctl.rst
index 428f6f5bb9b4..72853b0d3dc8 100644
--- a/Documentation/userspace-api/fwctl/fwctl.rst
+++ b/Documentation/userspace-api/fwctl/fwctl.rst
@@ -150,6 +150,7 @@ fwctl User API
.. kernel-doc:: include/uapi/fwctl/fwctl.h
.. kernel-doc:: include/uapi/fwctl/mlx5.h
+.. kernel-doc:: include/uapi/fwctl/pds.h
sysfs Class
-----------
diff --git a/Documentation/userspace-api/fwctl/index.rst b/Documentation/userspace-api/fwctl/index.rst
index 06959fbf1547..12a559fcf1b2 100644
--- a/Documentation/userspace-api/fwctl/index.rst
+++ b/Documentation/userspace-api/fwctl/index.rst
@@ -10,3 +10,4 @@ to securely construct and execute RPCs inside device firmware.
:maxdepth: 1
fwctl
+ pds_fwctl
diff --git a/Documentation/userspace-api/fwctl/pds_fwctl.rst b/Documentation/userspace-api/fwctl/pds_fwctl.rst
new file mode 100644
index 000000000000..f34645dbf5ea
--- /dev/null
+++ b/Documentation/userspace-api/fwctl/pds_fwctl.rst
@@ -0,0 +1,40 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+================
+fwctl pds driver
+================
+
+:Author: Shannon Nelson
+
+Overview
+========
+
+The PDS Core device makes an fwctl service available through an
+auxiliary_device named pds_core.fwctl.N. The pds_fwctl driver binds
+to this device and registers itself with the fwctl bus. The resulting
fwctl is a class not a bus though here I'd be tempted to say subsystem.
Subsystem works for me, unless Jason has any preference.
+userspace interface is used by an application that is a part of the
+AMD/Pensando software package for the Distributed Service Card (DSC).
+
+The pds_fwctl driver has little knowledge of the firmware's internals,
+only knows how to send commands through pds_core's message queue to the
+firmware for fwctl requests. The set of operations available through this
+interface depends on the firmware in the DSC, and the userspace application
+version must match the firmware so that they can talk to each other.
+
+This set of available operations is not known to the pds_fwctl driver.
+When a connection is created the pds_fwctl driver requests from the
+firmware list of endpoints and a list of operations for each endpoint.
requests from the firmware both a list of endpoints and a list of operations for
each endpoint.
As currently written the sentence suggest that we are asking for something
unspecified from the "firmware list of endpoints..."
I'll clean this up.
Thanks,
sln
+This list of operations includes a minimum scope level that the pds_fwctl
+driver can use for filtering privilege levels.
+
+pds_fwctl User API
+==================
+
+.. kernel-doc:: include/uapi/fwctl/pds.h
+
+Each RPC request includes the target endpoint and the operation id, and in
+and out buffer lengths and pointers. The driver verifies the existence
+of the requested endpoint and operations, then checks the current scope
+against the required scope of the operation. The request is then put
+together with the request data and sent through pds_core's message queue
+to the firmware, and the results are returned to the caller.
