86 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3==================4AF_XDP TX Metadata5==================6 7This document describes how to enable offloads when transmitting packets8via :doc:`af_xdp`. Refer to :doc:`xdp-rx-metadata` on how to access similar9metadata on the receive side.10 11General Design12==============13 14The headroom for the metadata is reserved via ``tx_metadata_len`` and15``XDP_UMEM_TX_METADATA_LEN`` flag in ``struct xdp_umem_reg``. The metadata16length is therefore the same for every socket that shares the same umem.17The metadata layout is a fixed UAPI, refer to ``union xsk_tx_metadata`` in18``include/uapi/linux/if_xdp.h``. Thus, generally, the ``tx_metadata_len``19field above should contain ``sizeof(union xsk_tx_metadata)``.20 21Note that in the original implementation the ``XDP_UMEM_TX_METADATA_LEN``22flag was not required. Applications might attempt to create a umem23with a flag first and if it fails, do another attempt without a flag.24 25The headroom and the metadata itself should be located right before26``xdp_desc->addr`` in the umem frame. Within a frame, the metadata27layout is as follows::28 29 tx_metadata_len30 / \31 +-----------------+---------+----------------------------+32 | xsk_tx_metadata | padding | payload |33 +-----------------+---------+----------------------------+34 ^35 |36 xdp_desc->addr37 38An AF_XDP application can request headrooms larger than ``sizeof(struct39xsk_tx_metadata)``. The kernel will ignore the padding (and will still40use ``xdp_desc->addr - tx_metadata_len`` to locate41the ``xsk_tx_metadata``). For the frames that shouldn't carry42any metadata (i.e., the ones that don't have ``XDP_TX_METADATA`` option),43the metadata area is ignored by the kernel as well.44 45The flags field enables the particular offload:46 47- ``XDP_TXMD_FLAGS_TIMESTAMP``: requests the device to put transmission48 timestamp into ``tx_timestamp`` field of ``union xsk_tx_metadata``.49- ``XDP_TXMD_FLAGS_CHECKSUM``: requests the device to calculate L450 checksum. ``csum_start`` specifies byte offset of where the checksumming51 should start and ``csum_offset`` specifies byte offset where the52 device should store the computed checksum.53 54Besides the flags above, in order to trigger the offloads, the first55packet's ``struct xdp_desc`` descriptor should set ``XDP_TX_METADATA``56bit in the ``options`` field. Also note that in a multi-buffer packet57only the first chunk should carry the metadata.58 59Software TX Checksum60====================61 62For development and testing purposes its possible to pass63``XDP_UMEM_TX_SW_CSUM`` flag to ``XDP_UMEM_REG`` UMEM registration call.64In this case, when running in ``XDK_COPY`` mode, the TX checksum65is calculated on the CPU. Do not enable this option in production because66it will negatively affect performance.67 68Querying Device Capabilities69============================70 71Every devices exports its offloads capabilities via netlink netdev family.72Refer to ``xsk-flags`` features bitmask in73``Documentation/netlink/specs/netdev.yaml``.74 75- ``tx-timestamp``: device supports ``XDP_TXMD_FLAGS_TIMESTAMP``76- ``tx-checksum``: device supports ``XDP_TXMD_FLAGS_CHECKSUM``77 78See ``tools/net/ynl/samples/netdev.c`` on how to query this information.79 80Example81=======82 83See ``tools/testing/selftests/bpf/xdp_hw_metadata.c`` for an example84program that handles TX metadata. Also see https://github.com/fomichev/xskgen85for a more bare-bones example.86