1 .. SPDX-License-Identifier: GPL-2.0 2 3 ================== 4 AF_XDP TX Metadata 5 ================== 6 7 This document describes how to enable offloads when transmitting packets 8 via :doc:`af_xdp`. Refer to :doc:`xdp-rx-metadata` on how to access similar 9 metadata on the receive side. 10 11 General Design 12 ============== 13 14 The 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 16 length is therefore the same for every socket that shares the same umem. 17 The 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`` 19 field above should contain ``sizeof(union xsk_tx_metadata)``. 20 21 Note that in the original implementation the ``XDP_UMEM_TX_METADATA_LEN`` 22 flag was not required. Applications might attempt to create a umem 23 with a flag first and if it fails, do another attempt without a flag. 24 25 The headroom and the metadata itself should be located right before 26 ``xdp_desc->addr`` in the umem frame. Within a frame, the metadata 27 layout is as follows:: 28 29 tx_metadata_len 30 / \ 31 +-----------------+---------+----------------------------+ 32 | xsk_tx_metadata | padding | payload | 33 +-----------------+---------+----------------------------+ 34 ^ 35 | 36 xdp_desc->addr 37 38 An AF_XDP application can request headrooms larger than ``sizeof(struct 39 xsk_tx_metadata)``. The kernel will ignore the padding (and will still 40 use ``xdp_desc->addr - tx_metadata_len`` to locate 41 the ``xsk_tx_metadata``). For the frames that shouldn't carry 42 any metadata (i.e., the ones that don't have ``XDP_TX_METADATA`` option), 43 the metadata area is ignored by the kernel as well. 44 45 The 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 54 Besides the flags above, in order to trigger the offloads, the first 55 packet's ``struct xdp_desc`` descriptor should set ``XDP_TX_METADATA`` 56 bit in the ``options`` field. Also note that in a multi-buffer packet 57 only the first chunk should carry the metadata. 58 59 Software TX Checksum 60 ==================== 61 62 For development and testing purposes its possible to pass 63 ``XDP_UMEM_TX_SW_CSUM`` flag to ``XDP_UMEM_REG`` UMEM registration call. 64 In this case, when running in ``XDK_COPY`` mode, the TX checksum 65 is calculated on the CPU. Do not enable this option in production because 66 it will negatively affect performance. 67 68 Querying Device Capabilities 69 ============================ 70 71 Every devices exports its offloads capabilities via netlink netdev family. 72 Refer 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 78 See ``tools/net/ynl/samples/netdev.c`` on how to query this information. 79 80 Example 81 ======= 82 83 See ``tools/testing/selftests/bpf/xdp_hw_metadata.c`` for an example 84 program that handles TX metadata. Also see https://github.com/fomichev/xskgen 85 for a more bare-bones example.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.