Documentation/networking/device_drivers/ethernet/meta/fbnic.rst

Source file repositories/reference/linux-study-clean/Documentation/networking/device_drivers/ethernet/meta/fbnic.rst

File Facts

System
Linux kernel
Corpus path
Documentation/networking/device_drivers/ethernet/meta/fbnic.rst
Extension
.rst
Size
8276 bytes
Lines
193
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: GPL-2.0+

=====================================
Meta Platforms Host Network Interface
=====================================

Firmware Versions
-----------------

fbnic has three components stored on the flash which are provided in one PLDM
image:

1. fw - The control firmware used to view and modify firmware settings, request
   firmware actions, and retrieve firmware counters outside of the data path.
   This is the firmware which fbnic_fw.c interacts with.
2. bootloader - The firmware which validate firmware security and control basic
   operations including loading and updating the firmware. This is also known
   as the cmrt firmware.
3. undi - This is the UEFI driver which is based on the Linux driver.

fbnic stores two copies of these three components on flash. This allows fbnic
to fall back to an older version of firmware automatically in case firmware
fails to boot. Version information for both is provided as running and stored.
The undi is only provided in stored as it is not actively running once the Linux
driver takes over.

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
------------------

fbnic supports updating firmware using signed PLDM images with devlink dev
flash. PLDM images are written into the flash. Flashing does not interrupt
the operation of the device.

On host boot the latest UEFI driver is always used, no explicit activation
is required. Firmware activation is required to run new control firmware. cmrt
firmware can only be activated by power cycling the NIC.

Annotation

Implementation Notes