[PATCH net-next] docs: fbnic: explain the ring config

[PATCH net-next] docs: fbnic: explain the ring config

[Jakub Kicinski]

fbnic takes 4 parameters to configure the Rx queues. The semantics
are similar to other existing NICs but confusing to newcomers.
Document it.

Signed-off-by: Jakub Kicinski <kuba@kernel.org>
---
 .../device_drivers/ethernet/meta/fbnic.rst    | 30 +++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/Documentation/networking/device_drivers/ethernet/meta/fbnic.rst b/Documentation/networking/device_drivers/ethernet/meta/fbnic.rst
index f8592dec8851..afb8353daefd 100644
--- a/Documentation/networking/device_drivers/ethernet/meta/fbnic.rst
+++ b/Documentation/networking/device_drivers/ethernet/meta/fbnic.rst
@@ -28,6 +28,36 @@ devlink dev info provides version information for all three components. In
 addition to the version the hg commit hash of the build is included as a
 separate entry.
 
+Configuration
+-------------
+
+Ringparams (ethtool -g / -G)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+fbnic has two submission (host -> device) rings for every completion
+(device -> host) ring. The three ring objects together form a single
+"queue" as used by higher layer software (a Rx, or a Tx queue).
+
+For Rx the two submission rings are used to pass empty pages to the NIC.
+Ring 0 is the Header Page Queue (HPQ), NIC will use its pages to place
+L2-L4 headers (or full frames if frame is not header-data split).
+Ring 1 is the Payload Page Queue (PPQ) and used for packet payloads.
+The completion ring is used to receive packet notifications / metadata.
+ethtool ``rx`` ringparam maps to the size of the completion ring,
+``rx-mini`` to the HPQ, and ``rx-jumbo`` to the PPQ.
+
+For Tx both submission rings can be used to submit packets, the completion
+ring carries notifications for both. fbnic uses one of the submission
+rings for normal traffic from the stack and the second one for XDP frames.
+ethtool ``tx`` ringparam controls both the size of the submission rings
+and the completion ring.
+
+Every single entry on the HPQ and PPQ (``rx-mini``, ``rx-jumbo``)
+corresponds to 4kB of allocated memory, while entries on the remaining
+rings are in units of descriptors (8B). The ideal ratio of submission
+and completion ring sizes will depend on the workload, as for small packets
+multiple packets will fit into a single page.
+
 Upgrading Firmware
 ------------------
 
-- 
2.50.0

Re: [PATCH net-next] docs: fbnic: explain the ring config

[Simon Horman]

On Thu, Jun 26, 2025 at 12:15:53PM -0700, Jakub Kicinski wrote:
> fbnic takes 4 parameters to configure the Rx queues. The semantics
> are similar to other existing NICs but confusing to newcomers.
> Document it.
> 
> Signed-off-by: Jakub Kicinski <kuba@kernel.org>

Reviewed-by: Simon Horman <horms@kernel.org>

Re: [PATCH net-next] docs: fbnic: explain the ring config

[patchwork-bot+netdevbpf]

Hello:

This patch was applied to netdev/net-next.git (main)
by Paolo Abeni <pabeni@redhat.com>:

On Thu, 26 Jun 2025 12:15:53 -0700 you wrote:
> fbnic takes 4 parameters to configure the Rx queues. The semantics
> are similar to other existing NICs but confusing to newcomers.
> Document it.
> 
> Signed-off-by: Jakub Kicinski <kuba@kernel.org>
> ---
>  .../device_drivers/ethernet/meta/fbnic.rst    | 30 +++++++++++++++++++
>  1 file changed, 30 insertions(+)

Here is the summary with links:
  - [net-next] docs: fbnic: explain the ring config
    https://git.kernel.org/netdev/net-next/c/8b79380dfe3c

You are awesome, thank you!
-- 
Deet-doot-dot, I am a bot.
https://korg.docs.kernel.org/patchwork/pwbot.html