On 2/12/2025 4:51 AM, Jonathan Cameron wrote:
On Tue, 11 Feb 2025 15:48: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>
---
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..9fb1b4ac0a5e
--- /dev/null
+++ b/Documentation/userspace-api/fwctl/pds_fwctl.rst
@@ -0,0 +1,41 @@
+.. 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
+userspace interface is used by an application that is a part of the
+AMD/Pensando software package for the Distributed Service Card (DSC).
Jason, where did we get to on the question of a central open repo etc?
+
+The pds_fwctl driver has little knowledge of the firmware's internals,
+only knows how to send adminq commands 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.
+This list of operations includes a minumum scope level that the pds_fwctl
+driver can use for filtering privilege levels.
Ah. Ok. So the scope is provided in the replies to these queries.
Do we have anything to verify that today?
Also, I wasn't sure when reading driver on whether the operations list
is dynamic or something we can read once and cache?
We request the operations list once on the first query of each endpoint
and cache them for the next time.
+
+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 adminq request is then
Spell out admin q (or is that a typo?)
The "adminq" is the particular object name, so I'll keep that, but I can
certainly add a little more text around it.
Thanks for your review comments, we appreciate it!
Cheers,
sln
+put together with the request data and sent to the firmware, and the
+results are returned to the caller.
+
