Re: [PATCH net-next v3 5/5] bnxt_fwctl: Add documentation entries
From: Dave Jiang <dave.jiang@intel.com>
Date: 2025-09-26 17:53:19
On 9/26/25 1:59 AM, Pavan Chebbi wrote:
quoted hunk ↗ jump to hunk
Add bnxt_fwctl to the driver and fwctl documentation pages. Reviewed-by: Andy Gospodarek <redacted> Signed-off-by: Pavan Chebbi <pavan.chebbi@broadcom.com> --- .../userspace-api/fwctl/bnxt_fwctl.rst | 38 +++++++++++++++++++ Documentation/userspace-api/fwctl/fwctl.rst | 1 + Documentation/userspace-api/fwctl/index.rst | 1 + 3 files changed, 40 insertions(+) create mode 100644 Documentation/userspace-api/fwctl/bnxt_fwctl.rstdiff --git a/Documentation/userspace-api/fwctl/bnxt_fwctl.rst b/Documentation/userspace-api/fwctl/bnxt_fwctl.rst new file mode 100644 index 000000000000..2d7dbe56c622 --- /dev/null +++ b/Documentation/userspace-api/fwctl/bnxt_fwctl.rst@@ -0,0 +1,38 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================ +fwctl bnxt driver +================ + +:Author: Pavan Chebbi + +Overview +======== + +BNXT driver makes a fwctl service available through an auxiliary_device. +The bnxt_fwctl driver binds to this device and registers itself with the +fwctl subsystem. + +The bnxt_fwctl driver is agnostic to the device firmware internals. It +uses the Upper Layer Protocol (ULP) conduit provided by bnxt to send +HardWare Resource Manager (HWRM) commands to firmware. + +These commands can query or change firmware driven device configurations +and read/write registers that are useful for debugging. + +bnxt_fwctl User API +================== +
May be a good idea to add the info() call and detail what gets returned. What are the expectations of the bits in caps value.
+Each RPC request contains a message request structure (HWRM input), its +length, optional request timeout, and dma buffers' information if the +command needs any DMA. The request is then put together with the request +data and sent through bnxt's message queue to the firmware, and the results +are returned to the caller. + +A typical user application would send a FWCTL_RPC using ioctl() for a FW +command as below: + + ioctl(fd, FWCTL_RPC, &rpc_msg); + +where rpc_msg (struct fwctl_rpc) is an encapsulation of fwctl_rpc_bnxt +(which contains the HWRM command description) and its response.
This part looks good. May want to add the expectation of the input and output buffer contents? Main thing is you want to make it easier for the user application developer when they look at this guide and know what they need to do.
quoted hunk ↗ jump to hunk
diff --git a/Documentation/userspace-api/fwctl/fwctl.rst b/Documentation/userspace-api/fwctl/fwctl.rst index a74eab8d14c6..826817bfd54d 100644 --- a/Documentation/userspace-api/fwctl/fwctl.rst +++ b/Documentation/userspace-api/fwctl/fwctl.rst@@ -148,6 +148,7 @@ area resulting in clashes will be resolved in favour of a kernel implementation. fwctl User API ============== +.. kernel-doc:: include/uapi/fwctl/bnxt.h .. kernel-doc:: include/uapi/fwctl/fwctl.h .. kernel-doc:: include/uapi/fwctl/mlx5.h .. kernel-doc:: include/uapi/fwctl/pds.hdiff --git a/Documentation/userspace-api/fwctl/index.rst b/Documentation/userspace-api/fwctl/index.rst index 316ac456ad3b..8062f7629654 100644 --- a/Documentation/userspace-api/fwctl/index.rst +++ b/Documentation/userspace-api/fwctl/index.rst@@ -10,5 +10,6 @@ to securely construct and execute RPCs inside device firmware. :maxdepth: 1 fwctl + bnxt_fwctl fwctl-cxl pds_fwctl