From: Stanislav Fomichev <sdf@google.com>
To: bpf@vger.kernel.org
Cc: ast@kernel.org, daniel@iogearbox.net, andrii@kernel.org,
martin.lau@linux.dev, song@kernel.org, yhs@fb.com,
john.fastabend@gmail.com, kpsingh@kernel.org, sdf@google.com,
haoluo@google.com, jolsa@kernel.org, kuba@kernel.org,
toke@kernel.org, willemb@google.com, dsahern@kernel.org,
magnus.karlsson@intel.com, bjorn@kernel.org,
maciej.fijalkowski@intel.com, hawk@kernel.org,
yoong.siang.song@intel.com, netdev@vger.kernel.org,
xdp-hints@xdp-project.net
Subject: [xdp-hints] [PATCH bpf-next v6 06/13] xsk: Document tx_metadata_len layout
Date: Mon, 27 Nov 2023 11:03:12 -0800 [thread overview]
Message-ID: <20231127190319.1190813-7-sdf@google.com> (raw)
In-Reply-To: <20231127190319.1190813-1-sdf@google.com>
- how to use
- how to query features
- pointers to the examples
Signed-off-by: Stanislav Fomichev <sdf@google.com>
---
Documentation/networking/index.rst | 1 +
Documentation/networking/xdp-rx-metadata.rst | 2 +
Documentation/networking/xsk-tx-metadata.rst | 70 ++++++++++++++++++++
3 files changed, 73 insertions(+)
create mode 100644 Documentation/networking/xsk-tx-metadata.rst
diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst
index 683eb42309cc..a297a894b366 100644
--- a/Documentation/networking/index.rst
+++ b/Documentation/networking/index.rst
@@ -123,6 +123,7 @@ Refer to :ref:`netdev-FAQ` for a guide on netdev development process specifics.
xfrm_sync
xfrm_sysctl
xdp-rx-metadata
+ xsk-tx-metadata
.. only:: subproject and html
diff --git a/Documentation/networking/xdp-rx-metadata.rst b/Documentation/networking/xdp-rx-metadata.rst
index 205696780b78..e3e9420fd817 100644
--- a/Documentation/networking/xdp-rx-metadata.rst
+++ b/Documentation/networking/xdp-rx-metadata.rst
@@ -1,3 +1,5 @@
+.. SPDX-License-Identifier: GPL-2.0
+
===============
XDP RX Metadata
===============
diff --git a/Documentation/networking/xsk-tx-metadata.rst b/Documentation/networking/xsk-tx-metadata.rst
new file mode 100644
index 000000000000..4f376560b23f
--- /dev/null
+++ b/Documentation/networking/xsk-tx-metadata.rst
@@ -0,0 +1,70 @@
+==================
+AF_XDP TX Metadata
+==================
+
+This document describes how to enable offloads when transmitting packets
+via :doc:`af_xdp`. Refer to :doc:`xdp-rx-metadata` on how to access similar
+metadata on the receive side.
+
+General Design
+==============
+
+The headroom for the metadata is reserved via ``tx_metadata_len`` in
+``struct xdp_umem_reg``. The metadata length is therefore the same for
+every socket that shares the same umem. The metadata layout is a fixed UAPI,
+refer to ``union xsk_tx_metadata`` in ``include/uapi/linux/if_xdp.h``.
+Thus, generally, the ``tx_metadata_len`` field above should contain
+``sizeof(union xsk_tx_metadata)``.
+
+The headroom and the metadata itself should be located right before
+``xdp_desc->addr`` in the umem frame. Within a frame, the metadata
+layout is as follows::
+
+ tx_metadata_len
+ / \
+ +-----------------+---------+----------------------------+
+ | xsk_tx_metadata | padding | payload |
+ +-----------------+---------+----------------------------+
+ ^
+ |
+ xdp_desc->addr
+
+An AF_XDP application can request headrooms larger than ``sizeof(struct
+xsk_tx_metadata)``. The kernel will ignore the padding (and will still
+use ``xdp_desc->addr - tx_metadata_len`` to locate
+the ``xsk_tx_metadata``). For the frames that shouldn't carry
+any metadata (i.e., the ones that don't have ``XDP_TX_METADATA`` option),
+the metadata area is ignored by the kernel as well.
+
+The flags field enables the particular offload:
+
+- ``XDP_TXMD_FLAGS_TIMESTAMP``: requests the device to put transmission
+ timestamp into ``tx_timestamp`` field of ``union xsk_tx_metadata``.
+- ``XDP_TXMD_FLAGS_CHECKSUM``: requests the device to calculate L4
+ checksum. ``csum_start`` specifies byte offset of where the checksumming
+ should start and ``csum_offset`` specifies byte offset where the
+ device should store the computed checksum.
+
+Besides the flags above, in order to trigger the offloads, the first
+packet's ``struct xdp_desc`` descriptor should set ``XDP_TX_METADATA``
+bit in the ``options`` field. Also note that in a multi-buffer packet
+only the first chunk should carry the metadata.
+
+Querying Device Capabilities
+============================
+
+Every devices exports its offloads capabilities via netlink netdev family.
+Refer to ``xsk-flags`` features bitmask in
+``Documentation/netlink/specs/netdev.yaml``.
+
+- ``tx-timestamp``: device supports ``XDP_TXMD_FLAGS_TIMESTAMP``
+- ``tx-checksum``: device supports ``XDP_TXMD_FLAGS_CHECKSUM``
+
+See ``tools/net/ynl/samples/netdev.c`` on how to query this information.
+
+Example
+=======
+
+See ``tools/testing/selftests/bpf/xdp_hw_metadata.c`` for an example
+program that handles TX metadata. Also see https://github.com/fomichev/xskgen
+for a more bare-bones example.
--
2.43.0.rc1.413.gea7ed67945-goog
next prev parent reply other threads:[~2023-11-27 19:03 UTC|newest]
Thread overview: 21+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-11-27 19:03 [xdp-hints] [PATCH bpf-next v6 00/13] xsk: TX metadata Stanislav Fomichev
2023-11-27 19:03 ` [xdp-hints] [PATCH bpf-next v6 01/13] xsk: Support tx_metadata_len Stanislav Fomichev
2023-11-28 3:09 ` [xdp-hints] " Jakub Kicinski
2023-11-27 19:03 ` [xdp-hints] [PATCH bpf-next v6 02/13] xsk: Add TX timestamp and TX checksum offload support Stanislav Fomichev
2023-11-29 16:49 ` [xdp-hints] " Jakub Kicinski
2023-11-27 19:03 ` [xdp-hints] [PATCH bpf-next v6 03/13] tools: ynl: Print xsk-features from the sample Stanislav Fomichev
2023-11-29 16:47 ` [xdp-hints] " Jakub Kicinski
2023-11-27 19:03 ` [xdp-hints] [PATCH bpf-next v6 04/13] net/mlx5e: Implement AF_XDP TX timestamp and checksum offload Stanislav Fomichev
2023-11-27 19:03 ` [xdp-hints] [PATCH bpf-next v6 05/13] net: stmmac: Add Tx HWTS support to XDP ZC Stanislav Fomichev
2023-11-27 19:03 ` Stanislav Fomichev [this message]
2023-12-02 17:09 ` [xdp-hints] Re: [PATCH bpf-next v6 06/13] xsk: Document tx_metadata_len layout Simon Horman
2023-12-04 16:48 ` Stanislav Fomichev
2023-12-07 10:47 ` Simon Horman
2023-11-27 19:03 ` [xdp-hints] [PATCH bpf-next v6 07/13] xsk: Validate xsk_tx_metadata flags Stanislav Fomichev
2023-11-27 19:03 ` [xdp-hints] [PATCH bpf-next v6 08/13] xsk: Add option to calculate TX checksum in SW Stanislav Fomichev
2023-11-27 19:03 ` [xdp-hints] [PATCH bpf-next v6 09/13] selftests/xsk: Support tx_metadata_len Stanislav Fomichev
2023-11-27 19:03 ` [xdp-hints] [PATCH bpf-next v6 10/13] selftests/bpf: Add csum helpers Stanislav Fomichev
2023-11-27 19:03 ` [xdp-hints] [PATCH bpf-next v6 11/13] selftests/bpf: Add TX side to xdp_metadata Stanislav Fomichev
2023-11-27 19:03 ` [xdp-hints] [PATCH bpf-next v6 12/13] selftests/bpf: Convert xdp_hw_metadata to XDP_USE_NEED_WAKEUP Stanislav Fomichev
2023-11-27 19:03 ` [xdp-hints] [PATCH bpf-next v6 13/13] selftests/bpf: Add TX side to xdp_hw_metadata Stanislav Fomichev
2023-11-29 23:10 ` [xdp-hints] Re: [PATCH bpf-next v6 00/13] xsk: TX metadata patchwork-bot+netdevbpf
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://lists.xdp-project.net/postorius/lists/xdp-hints.xdp-project.net/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20231127190319.1190813-7-sdf@google.com \
--to=sdf@google.com \
--cc=andrii@kernel.org \
--cc=ast@kernel.org \
--cc=bjorn@kernel.org \
--cc=bpf@vger.kernel.org \
--cc=daniel@iogearbox.net \
--cc=dsahern@kernel.org \
--cc=haoluo@google.com \
--cc=hawk@kernel.org \
--cc=john.fastabend@gmail.com \
--cc=jolsa@kernel.org \
--cc=kpsingh@kernel.org \
--cc=kuba@kernel.org \
--cc=maciej.fijalkowski@intel.com \
--cc=magnus.karlsson@intel.com \
--cc=martin.lau@linux.dev \
--cc=netdev@vger.kernel.org \
--cc=song@kernel.org \
--cc=toke@kernel.org \
--cc=willemb@google.com \
--cc=xdp-hints@xdp-project.net \
--cc=yhs@fb.com \
--cc=yoong.siang.song@intel.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox