1.. SPDX-License-Identifier: GPL-2.0 2 3================== 4AF_XDP TX Metadata 5================== 6 7This document describes how to enable offloads when transmitting packets 8via :doc:`af_xdp`. Refer to :doc:`xdp-rx-metadata` on how to access similar 9metadata on the receive side. 10 11General Design 12============== 13 14The headroom for the metadata is reserved via ``tx_metadata_len`` and 15``XDP_UMEM_TX_METADATA_LEN`` flag in ``struct xdp_umem_reg``. The metadata 16length 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`` in 18``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 umem 23with a flag first and if it fails, do another attempt without a flag. 24 25The headroom and the metadata itself should be located right before 26``xdp_desc->addr`` in the umem frame. Within a frame, the metadata 27layout is as follows:: 28 29 tx_metadata_len 30 / \ 31 +-----------------+---------+----------------------------+ 32 | xsk_tx_metadata | padding | payload | 33 +-----------------+---------+----------------------------+ 34 ^ 35 | 36 xdp_desc->addr 37 38An AF_XDP application can request headrooms larger than ``sizeof(struct 39xsk_tx_metadata)``. The kernel will ignore the padding (and will still 40use ``xdp_desc->addr - tx_metadata_len`` to locate 41the ``xsk_tx_metadata``). For the frames that shouldn't carry 42any 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 transmission 48 timestamp into ``tx_timestamp`` field of ``union xsk_tx_metadata``. 49- ``XDP_TXMD_FLAGS_CHECKSUM``: requests the device to calculate L4 50 checksum. ``csum_start`` specifies byte offset of where the checksumming 51 should start and ``csum_offset`` specifies byte offset where the 52 device should store the computed checksum. 53 54Besides the flags above, in order to trigger the offloads, the first 55packet's ``struct xdp_desc`` descriptor should set ``XDP_TX_METADATA`` 56bit in the ``options`` field. Also note that in a multi-buffer packet 57only the first chunk should carry the metadata. 58 59Software TX Checksum 60==================== 61 62For development and testing purposes its possible to pass 63``XDP_UMEM_TX_SW_CSUM`` flag to ``XDP_UMEM_REG`` UMEM registration call. 64In this case, when running in ``XDK_COPY`` mode, the TX checksum 65is calculated on the CPU. Do not enable this option in production because 66it will negatively affect performance. 67 68Querying Device Capabilities 69============================ 70 71Every devices exports its offloads capabilities via netlink netdev family. 72Refer to ``xsk-flags`` features bitmask in 73``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 80Example 81======= 82 83See ``tools/testing/selftests/bpf/xdp_hw_metadata.c`` for an example 84program that handles TX metadata. Also see https://github.com/fomichev/xskgen 85for a more bare-bones example. 86