From nobody Mon Feb 9 10:28:43 2026 Received: from mail-qv1-f99.google.com (mail-qv1-f99.google.com [209.85.219.99]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id CEA7432C31B for ; Sun, 18 Jan 2026 12:41:17 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.219.99 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768740079; cv=none; b=jYpea9NrT5nHol9o5p7Gs0oI6uX7H8aewDaIajcS9fEVL/KYdtqglscuKLjdrw3vWw1SU1Rep5mg4FkZaz8c9S1va+g3GvOjcprAazYrEZ4VCbU1ADO2oWD8dupbBvYeuIShHAmGm3Pv9YBDq19GeXCyViJPhy7j0ibKsC6khdE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768740079; c=relaxed/simple; bh=p0+9v6bOKj6/t1LScVQUgu9L7VXJ0bMnHc+ppDkUBOc=; h=From:To:Cc:Subject:Date:Message-Id:In-Reply-To:References: MIME-Version; b=pSrkyA+2jRRdSrEQ6pqaj3Gz+fhk/nd7ec0mCHn9mucfUxn2yctGklZxJ5UU1nGfRIA9PkeuT0iy3fWFozA7snAgXqIvHThuXLN6oHI2JrsMgZ8hohLSVBVMUsgqu/cwlcNCRXc9GZSaYhcAHFfckxv+XMat3bJPBBvzWW2J0N4= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=broadcom.com; spf=fail smtp.mailfrom=broadcom.com; dkim=pass (1024-bit key) header.d=broadcom.com header.i=@broadcom.com header.b=STMI2sFK; arc=none smtp.client-ip=209.85.219.99 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=broadcom.com Authentication-Results: smtp.subspace.kernel.org; spf=fail smtp.mailfrom=broadcom.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=broadcom.com header.i=@broadcom.com header.b="STMI2sFK" Received: by mail-qv1-f99.google.com with SMTP id 6a1803df08f44-88a2ad13c24so31973036d6.1 for ; Sun, 18 Jan 2026 04:41:17 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1768740077; x=1769344877; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:dkim-signature:x-gm-gg :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=ylrqotwPOThrY3/hhjb9VMXvSLNMw+ZG4RF4c6zLl9k=; b=Sk37TAi8hRV6xSTBTSlGlAZ5ZkK924WjyIfZnGvViA9ybhYlScbnf9AnBmrZsZL9yN 46q+lUd/RY5PLdroKcfusW4qW8mfBl+TnwpNGqI7H9mtvB3UJmFmSyMHu+zEXwkhTf5y Cb/Ec+nwGKh1WxNYKyENI3EzOFhnd5nDhTADmVgzM+/YWjlv41lOMUVbiudxJohW69py Fxiag6m7dLX8gudyxoOt3D1CZTyD5hY1cRZ1/q1JPNexbkccCBsUSWNkRoViAd+0fpeU lChcb0SkOAv4Z+nzn2E7XakgU1osPcvJ2/RwV50Ee8ExoLcd4D9UF/kk8I2BCI2qOWYW 1IZQ== X-Gm-Message-State: AOJu0YxiaW6D7ZMXR3WuBCuk9VvvxxZNpBLero0jC1DEsVDc+0pioBeH sK4sJdcNuK/2dbiG/Gb9tf4ULQiW2vwcrOWeaTnCcopCY9VheBjZywl0wylMnK3F3Tw+I70sH4V ZWldMGzCnCcqAJtxFHQDsT0cZJljTtZb8kWx5Y3pkxlOpppIGP+8PHt7YnSPt2l8RCcdiRAQRi6 FR2at7VVtJb+BfutH2P+J/zj3EIjU34Rp12rEXNRUBLXyiHJ2we5UdY02aM7jiZHT2s0+rF0nGS 3qckQyxGvBP5bY+2yw= X-Gm-Gg: AY/fxX7tQWJO0ijbEJPHbCqW5ojiQdBbGV+Wh8W6dTrpua0suoTUux3zrDbDNkI+WXj fcpArPSXTaeqIIgy2P1YE89M1le2Uoau7PiZy/JBMKr/VIXcmK8+oQ+T/NItSJCk1xlD65FGO7Y 9b42buAKuARz1Z5HR4m0VTaAri+GtmBHFglhOHAEmOKIAgCwnFl83cZsu9yqIZKW7VNowZbttac pU5Fv4X/Zzx2GVV2y9BQEx+zVhzFnDsSCPf44wNicPsPyFJHozy1JNf0cnGvB1xXimTFs1grfc5 lLPbooN4xW+3clhZLtgDjPNHcRDY+cVCRpf4b7Jcs1PqNx5s3pKEYzcl23P5hv5Ord5XEOXNZMS gLa0czPs4RjRjOHkI5q//L75G6XNI6N1wTlcFPgNdlLiOpIMbqAK2H7ORBI0TNVV0Ut3/fbySOR qpGqqDe3aWxsFqXWK6mhjkQ3o1b+h9O+OC9XxZbPTOqF2sFDw= X-Received: by 2002:a05:6214:76e:b0:88f:ca7d:348c with SMTP id 6a1803df08f44-8942dbed6bcmr115557206d6.14.1768740076708; Sun, 18 Jan 2026 04:41:16 -0800 (PST) Received: from smtp-us-east1-p01-i01-si01.dlp.protect.broadcom.com (address-144-49-247-118.dlp.protect.broadcom.com. [144.49.247.118]) by smtp-relay.gmail.com with ESMTPS id 6a1803df08f44-8942e6cd881sm5292156d6.18.2026.01.18.04.41.16 for (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Sun, 18 Jan 2026 04:41:16 -0800 (PST) X-Relaying-Domain: broadcom.com X-CFilter-Loop: Reflected Received: by mail-pj1-f71.google.com with SMTP id 98e67ed59e1d1-34e70e2e363so2648579a91.1 for ; Sun, 18 Jan 2026 04:41:16 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=broadcom.com; s=google; t=1768740075; x=1769344875; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=ylrqotwPOThrY3/hhjb9VMXvSLNMw+ZG4RF4c6zLl9k=; b=STMI2sFKYtEYl2EcOafCCnigFJYuzTkGVruD9SYYJNtG5u6n0P+57QLu9jDs4Ljomz dvEcIWUH+O7tDH1vQE/vufhCYZDGPPy84lxDg+M/cKmyXKIM+QLzyF3tCn/0LMrMLUjl v/eszlVXL0RclPLQD95xqrIAbjSkcr0fPA944= X-Received: by 2002:a05:6a21:3a85:b0:366:14ac:e200 with SMTP id adf61e73a8af0-38dfe7b7c0bmr7695685637.62.1768740075387; Sun, 18 Jan 2026 04:41:15 -0800 (PST) X-Received: by 2002:a05:6a21:3a85:b0:366:14ac:e200 with SMTP id adf61e73a8af0-38dfe7b7c0bmr7695673637.62.1768740075002; Sun, 18 Jan 2026 04:41:15 -0800 (PST) Received: from PC-MID-R740.dhcp.broadcom.net ([192.19.234.250]) by smtp.gmail.com with ESMTPSA id 41be03b00d2f7-c5edf249c24sm6761246a12.11.2026.01.18.04.41.11 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 18 Jan 2026 04:41:14 -0800 (PST) From: Pavan Chebbi To: jgg@ziepe.ca, michael.chan@broadcom.com Cc: linux-kernel@vger.kernel.org, dave.jiang@intel.com, saeedm@nvidia.com, Jonathan.Cameron@huawei.com, gospo@broadcom.com, selvin.xavier@broadcom.com, leon@kernel.org, kalesh-anakkur.purayil@broadcom.com, Pavan Chebbi Subject: [PATCH fwctl 5/5] fwctl/bnxt_fwctl: Add documentation entries Date: Sun, 18 Jan 2026 04:34:01 -0800 Message-Id: <20260118123401.3188438-6-pavan.chebbi@broadcom.com> X-Mailer: git-send-email 2.39.1 In-Reply-To: <20260118123401.3188438-1-pavan.chebbi@broadcom.com> References: <20260118123401.3188438-1-pavan.chebbi@broadcom.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-DetectorID-Processed: b00c1d49-9d2e-4205-b15f-d015386d3d5e Content-Type: text/plain; charset="utf-8" Add bnxt_fwctl to the driver and fwctl documentation pages. Reviewed-by: Andy Gospodarek Reviewed-by: Dave Jiang Signed-off-by: Pavan Chebbi --- .../userspace-api/fwctl/bnxt_fwctl.rst | 83 +++++++++++++++++++ Documentation/userspace-api/fwctl/fwctl.rst | 1 + Documentation/userspace-api/fwctl/index.rst | 1 + 3 files changed, 85 insertions(+) create mode 100644 Documentation/userspace-api/fwctl/bnxt_fwctl.rst diff --git a/Documentation/userspace-api/fwctl/bnxt_fwctl.rst b/Documentati= on/userspace-api/fwctl/bnxt_fwctl.rst new file mode 100644 index 000000000000..41a74a085324 --- /dev/null +++ b/Documentation/userspace-api/fwctl/bnxt_fwctl.rst @@ -0,0 +1,83 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +fwctl bnxt driver +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +:Author: Pavan Chebbi + +Overview +=3D=3D=3D=3D=3D=3D=3D=3D + +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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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). fwctl_info_msg is set up as follows: + + size =3D sizeof(struct fwctl_info); + flags =3D 0; + device_data_len =3D sizeof(bnxt_info_msg); + out_device_data =3D (__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/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 =3D HWRM_VER_GET; + req.hwrm_intf_maj =3D HWRM_VERSION_MAJOR; + req.hwrm_intf_min =3D HWRM_VERSION_MINOR; + req.hwrm_intf_upd =3D HWRM_VERSION_UPDATE; + req.cmpl_ring =3D -1; + req.target_id =3D -1; + + bnxt_rpc_msg.req_len =3D sizeof(struct hwrm_ver_get_input); + bnxt_rpc_msg.num_dma =3D 0; + bnxt_rpc_msg.req =3D (__aligned_u64)&req; + + fwctl_rpc_msg.size =3D sizeof(struct fwctl_rpc); + fwctl_rpc_msg.scope =3D FWCTL_RPC_DEBUG_READ_ONLY; + fwctl_rpc_msg.in_len =3D sizeof(bnxt_rpc_msg) + sizeof(req); + fwctl_rpc_msg.out_len =3D sizeof(struct hwrm_ver_get_output); + fwctl_rpc_msg.in =3D (__aligned_u64)&bnxt_rpc_msg; + fwctl_rpc_msg.out =3D (__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 diff --git a/Documentation/userspace-api/fwctl/fwctl.rst b/Documentation/us= erspace-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 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 +.. 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/us= erspace-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 firm= ware. :maxdepth: 1 =20 fwctl + bnxt_fwctl fwctl-cxl pds_fwctl --=20 2.39.1