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`` in 15``struct xdp_umem_reg``. The metadata length is therefore the same for 16every socket that shares the same umem. The metadata layout is a fixed UAPI, 17refer to ``union xsk_tx_metadata`` in ``include/uapi/linux/if_xdp.h``. 18Thus, generally, the ``tx_metadata_len`` field above should contain 19``sizeof(union xsk_tx_metadata)``. 20 21The headroom and the metadata itself should be located right before 22``xdp_desc->addr`` in the umem frame. Within a frame, the metadata 23layout is as follows:: 24 25 tx_metadata_len 26 / \ 27 +-----------------+---------+----------------------------+ 28 | xsk_tx_metadata | padding | payload | 29 +-----------------+---------+----------------------------+ 30 ^ 31 | 32 xdp_desc->addr 33 34An AF_XDP application can request headrooms larger than ``sizeof(struct 35xsk_tx_metadata)``. The kernel will ignore the padding (and will still 36use ``xdp_desc->addr - tx_metadata_len`` to locate 37the ``xsk_tx_metadata``). For the frames that shouldn't carry 38any metadata (i.e., the ones that don't have ``XDP_TX_METADATA`` option), 39the metadata area is ignored by the kernel as well. 40 41The flags field enables the particular offload: 42 43- ``XDP_TXMD_FLAGS_TIMESTAMP``: requests the device to put transmission 44 timestamp into ``tx_timestamp`` field of ``union xsk_tx_metadata``. 45- ``XDP_TXMD_FLAGS_CHECKSUM``: requests the device to calculate L4 46 checksum. ``csum_start`` specifies byte offset of where the checksumming 47 should start and ``csum_offset`` specifies byte offset where the 48 device should store the computed checksum. 49 50Besides the flags above, in order to trigger the offloads, the first 51packet's ``struct xdp_desc`` descriptor should set ``XDP_TX_METADATA`` 52bit in the ``options`` field. Also note that in a multi-buffer packet 53only the first chunk should carry the metadata. 54 55Software TX Checksum 56==================== 57 58For development and testing purposes its possible to pass 59``XDP_UMEM_TX_SW_CSUM`` flag to ``XDP_UMEM_REG`` UMEM registration call. 60In this case, when running in ``XDK_COPY`` mode, the TX checksum 61is calculated on the CPU. Do not enable this option in production because 62it will negatively affect performance. 63 64Querying Device Capabilities 65============================ 66 67Every devices exports its offloads capabilities via netlink netdev family. 68Refer to ``xsk-flags`` features bitmask in 69``Documentation/netlink/specs/netdev.yaml``. 70 71- ``tx-timestamp``: device supports ``XDP_TXMD_FLAGS_TIMESTAMP`` 72- ``tx-checksum``: device supports ``XDP_TXMD_FLAGS_CHECKSUM`` 73 74See ``tools/net/ynl/samples/netdev.c`` on how to query this information. 75 76Example 77======= 78 79See ``tools/testing/selftests/bpf/xdp_hw_metadata.c`` for an example 80program that handles TX metadata. Also see https://github.com/fomichev/xskgen 81for a more bare-bones example. 82