Documentation/networking/xsk-tx-metadata.rst

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