netdev - Re: [PATCH net-next v4 5/5] bnxt_fwctl: Add documentation entries

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <70bd29ff-4805-4ac1-947b-5b4f6edb2dae@intel.com>
Date: Mon, 29 Sep 2025 11:36:10 -0700
From: Dave Jiang <dave.jiang@...el.com>
To: Pavan Chebbi <pavan.chebbi@...adcom.com>, jgg@...pe.ca,
 michael.chan@...adcom.com
Cc: saeedm@...dia.com, Jonathan.Cameron@...wei.com, davem@...emloft.net,
 corbet@....net, edumazet@...gle.com, gospo@...adcom.com, kuba@...nel.org,
 netdev@...r.kernel.org, pabeni@...hat.com, andrew+netdev@...n.ch,
 selvin.xavier@...adcom.com, leon@...nel.org,
 kalesh-anakkur.purayil@...adcom.com
Subject: Re: [PATCH net-next v4 5/5] bnxt_fwctl: Add documentation entries



On 9/27/25 2:39 AM, Pavan Chebbi wrote:
> Add bnxt_fwctl to the driver and fwctl documentation pages.
> 
> Reviewed-by: Andy Gospodarek <gospo@...adcom.com>
> Signed-off-by: Pavan Chebbi <pavan.chebbi@...adcom.com>

Reviewed-by: Dave Jiang <dave.jiang@...el.com>
> ---
>  .../userspace-api/fwctl/bnxt_fwctl.rst        | 78 +++++++++++++++++++
>  Documentation/userspace-api/fwctl/fwctl.rst   |  1 +
>  Documentation/userspace-api/fwctl/index.rst   |  1 +
>  3 files changed, 80 insertions(+)
>  create mode 100644 Documentation/userspace-api/fwctl/bnxt_fwctl.rst
> 
> diff --git a/Documentation/userspace-api/fwctl/bnxt_fwctl.rst b/Documentation/userspace-api/fwctl/bnxt_fwctl.rst
> new file mode 100644
> index 000000000000..7cf2b65ea34b
> --- /dev/null
> +++ b/Documentation/userspace-api/fwctl/bnxt_fwctl.rst
> @@ -0,0 +1,78 @@
> +.. 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
> +===================
> +
> +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 can send a FWCTL_INFO command using ioctl()
> +to discover bnxt_fwctl's RPC capabilities as shown below:
> +
> +        ioctl(fd, FWCTL_INFO, &fwctl_info_msg);
> +
> +where fwctl_info_msg (of type struct fwctl_info) describes bnxt_info_msg
> +(of type struct fwctl_info_bnxt) as shown below:
> +
> +        size = sizeof(fwctl_info_msg);
> +        flags = 0;
> +        device_data_len = sizeof(bnxt_info_msg);
> +        out_device_data = (__aligned_u64)&bnxt_info_msg;
> +
> +The uctx_caps of bnxt_info_msg represents the capabilities as described
> +in fwctl_bnxt_commands of include/uapi/fwctl/bnxt.h
> +
> +The FW RPC itself, FWCTL_RPC can be sent using ioctl() as:
> +
> +        ioctl(fd, FWCTL_RPC, &fwctl_rpc_msg);
> +
> +where fwctl_rpc_msg (of type struct fwctl_rpc) encapsulates fwctl_rpc_bnxt
> +(see bnxt_rpc_msg below). fwctl_rpc_bnxt members are set up as per the
> +requirements of specific HWRM commands described in include/linux/bnxt/hsi.h.
> +An example for HWRM_VER_GET is shown below:
> +
> +        struct fwctl_rpc_bnxt bnxt_rpc_msg;
> +        struct hwrm_ver_get_output resp;
> +        struct fwctl_rpc fwctl_rpc_msg;
> +        struct hwrm_ver_get_input req;
> +
> +        req.req_type = HWRM_VER_GET;
> +        req.hwrm_intf_maj = HWRM_VERSION_MAJOR;
> +        req.hwrm_intf_min = HWRM_VERSION_MINOR;
> +        req.hwrm_intf_upd = HWRM_VERSION_UPDATE;
> +        req.cmpl_ring = -1;
> +        req.target_id = -1;
> +
> +        bnxt_rpc_msg.req_len = sizeof(req);
> +        bnxt_rpc_msg.num_dma = 0;
> +        bnxt_rpc_msg.req = (__aligned_u64)&req;
> +
> +        fwctl_rpc_msg.size = sizeof(fwctl_rpc_msg);
> +        fwctl_rpc_msg.scope = FWCTL_RPC_DEBUG_READ_ONLY;
> +        fwctl_rpc_msg.in_len = sizeof(bnxt_rpc_msg) + sizeof(req);
> +        fwctl_rpc_msg.out_len = sizeof(resp);
> +        fwctl_rpc_msg.in = (__aligned_u64)&bnxt_rpc_msg;
> +        fwctl_rpc_msg.out = (__aligned_u64)&resp;
> 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.h
> diff --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