Clarify that drivers must remove device-reserved metadata from the data_meta area before passing frames to XDP programs. Additionally, expand the explanation of how userspace and BPF programs should coordinate the use of METADATA_SIZE, and add a detailed diagram to illustrate pointer adjustments and metadata layout. Also describe the requirements and constraints enforced by bpf_xdp_adjust_meta(). Signed-off-by: Song Yoong Siang <yoong.siang.song@xxxxxxxxx> --- V5: - create a new section called 'Driver implementation' (Stanislav) - reword 'utilize the data_meta area' to 'prepend metadata to received packets' (Jakub) V4: https://lore.kernel.org/netdev/20250715071502.3503440-1-yoong.siang.song@xxxxxxxxx/ - update the documentation to indicate that drivers are expected to copy any device-reserved metadata from the metadata area (Jakub) - remove selftest tool changes. V3: https://lore.kernel.org/netdev/20250702165757.3278625-1-yoong.siang.song@xxxxxxxxx/ - update doc and commit msg accordingly. V2: https://lore.kernel.org/netdev/20250702030349.3275368-1-yoong.siang.song@xxxxxxxxx/ - unconditionally do bpf_xdp_adjust_meta with -XDP_METADATA_SIZE (Stanislav) V1: https://lore.kernel.org/netdev/20250701042940.3272325-1-yoong.siang.song@xxxxxxxxx/ --- Documentation/networking/xdp-rx-metadata.rst | 33 ++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/Documentation/networking/xdp-rx-metadata.rst b/Documentation/networking/xdp-rx-metadata.rst index a6e0ece18be5..ce96f4c99505 100644 --- a/Documentation/networking/xdp-rx-metadata.rst +++ b/Documentation/networking/xdp-rx-metadata.rst @@ -120,6 +120,39 @@ It is possible to query which kfunc the particular netdev implements via netlink. See ``xdp-rx-metadata-features`` attribute set in ``Documentation/netlink/specs/netdev.yaml``. +Driver Implementation +===================== + +Certain devices may prepend metadata to received packets. However, as of now, +``AF_XDP`` lacks the ability to communicate the size of the ``data_meta`` area +to the consumer. Therefore, it is the responsibility of the driver to copy any +device-reserved metadata out from the metadata area and ensure that +``xdp_buff->data_meta`` is pointing to ``xdp_buff->data`` before presenting the +frame to the XDP program. This is necessary so that, after the XDP program +adjusts the metadata area, the consumer can reliably retrieve the metadata +address using ``METADATA_SIZE`` offset. + +The following diagram shows how custom metadata is positioned relative to the +packet data and how pointers are adjusted for metadata access:: + + |<-- bpf_xdp_adjust_meta(xdp_buff, -METADATA_SIZE) --| + new xdp_buff->data_meta old xdp_buff->data_meta + | | + | xdp_buff->data + | | + +----------+----------------------------------------------------+------+ + | headroom | custom metadata | data | + +----------+----------------------------------------------------+------+ + | | + | xdp_desc->addr + |<------ xsk_umem__get_data() - METADATA_SIZE -------| + +``bpf_xdp_adjust_meta`` ensures that ``METADATA_SIZE`` is aligned to 4 bytes, +does not exceed 252 bytes, and leaves sufficient space for building the +xdp_frame. If these conditions are not met, it returns a negative error. In this +case, the BPF program should not proceed to populate data into the ``data_meta`` +area. + Example ======= -- 2.34.1
