Commit 44230bb3 authored by Pavan Chebbi's avatar Pavan Chebbi Committed by Jason Gunthorpe
Browse files

fwctl/bnxt_fwctl: Add documentation entries 

Add bnxt_fwctl to the driver and fwctl documentation pages.

Link: https://patch.msgid.link/r/20260314151605.932749-6-pavan.chebbi@broadcom.com


Reviewed-by: default avatarAndy Gospodarek <gospo@broadcom.com>
Reviewed-by: default avatarDave Jiang <dave.jiang@intel.com>
Signed-off-by: default avatarPavan Chebbi <pavan.chebbi@broadcom.com>
Signed-off-by: default avatarJason Gunthorpe <jgg@nvidia.com>
parent e782efb8

Documentation/userspace-api/fwctl/bnxt_fwctl.rst

0 → 100644
+74 −0
Original line number Diff line number Diff line 
.. 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 the HWRM input structure in the fwctl_rpc

'in' buffer while 'out' will contain the response.



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). fwctl_info_msg is set up as follows:



        size = sizeof(struct fwctl_info);

        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) carries the HWRM command

in its 'in' buffer. The HWRM input structures are described in

include/linux/bnxt/hsi.h. An example for HWRM_VER_GET is shown below:



        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;



        fwctl_rpc_msg.size = sizeof(struct fwctl_rpc);

        fwctl_rpc_msg.scope = FWCTL_RPC_DEBUG_READ_ONLY;

        fwctl_rpc_msg.in_len = sizeof(req);

        fwctl_rpc_msg.out_len = sizeof(resp);

        fwctl_rpc_msg.in = (__aligned_u64)&req;

        fwctl_rpc_msg.out = (__aligned_u64)&resp;



An example python3 program that can exercise this interface can be found in

the following git repository:



https://github.com/Broadcom/fwctl-tools

Documentation/userspace-api/fwctl/fwctl.rst

+1 −0
Original line number Diff line number Diff line
@@ -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

Documentation/userspace-api/fwctl/index.rst

+1 −0
Original line number Diff line number Diff line
@@ -10,5 +10,6 @@ to securely construct and execute RPCs inside device firmware. 
   :maxdepth: 1



   fwctl

   bnxt_fwctl

   fwctl-cxl

   pds_fwctl