From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-oi1-x22e.google.com (mail-oi1-x22e.google.com [IPv6:2607:f8b0:4864:20::22e]) by mail.toke.dk (Postfix) with ESMTPS id 16E46A34AB8 for ; Mon, 23 Oct 2023 11:20:03 +0200 (CEST) Authentication-Results: mail.toke.dk; dkim=pass (2048-bit key; unprotected) header.d=gmail.com header.i=@gmail.com header.a=rsa-sha256 header.s=20230601 header.b=UvnLccVq Received: by mail-oi1-x22e.google.com with SMTP id 5614622812f47-3b41132c33aso208479b6e.1 for ; Mon, 23 Oct 2023 02:20:03 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1698052801; x=1698657601; darn=xdp-project.net; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:from:to:cc:subject:date:message-id:reply-to; bh=vTLLmppAiMZ7nebqhxgQeiaMrLVs8gT7ZeBZYFeZ6xE=; b=UvnLccVq7B/E8jtzdRKspthoCc08zTkmDDJC/v0b1bdM0axegwSH6h+OaB05rOgM/f 5DOc8ReeYudYJs+/BkNvWFDODEPKyB3zVYP2xfMGkNZ8V1Wy6l2A6bkOuQ6yOpNKEj6Y +etdwmaLMsiHLehIu/xBwSWq3O6ew2RMZQozmK6UTHapfouKes9OtCnX21j9c68jAIX/ QF0ABIdjj1iA3aBF311/Gqxa1q07neWCv7faB18845fnF9eWEANGSnKlj8PZ/644wS2r +Ebx/WrnrDrfD+IP4rSj49Qy8QwSl4l+24+3xmVKozTHzv/Tnk7y/l3W4pAIJusllxdL 9P+g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1698052801; x=1698657601; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=vTLLmppAiMZ7nebqhxgQeiaMrLVs8gT7ZeBZYFeZ6xE=; b=BxSnrw0iInHLtGEmxUTzyDg7CaFNAtgMrDYJy0UUI093qA/M7Z+mLPxQTQ9hQRGyn/ 47901MKyvj2fTWOIhVe6TG4DQ6uwSmne2UrGdac7NMwsXab+RlwCiPmSWEThTshkkafB wzl3jWfwoftaDAsweACT1hkdwBUh2zIQhLwjYbbRemELg1dnkUeroBPHuVBpKE9Dr9N3 RBqv1srZX62OGXASiqe8UvgeMGq7Zyfv/Diasx/PYOjqbu+QJfZxBVnonqp05ckLzNfN m5TudtAD7rlsOv1l4pOJ8JH1Eii7mx7Gah7ZTK54S+wdAdlJFSCD9FCMyByh8Lw0gaXk zIAw== X-Gm-Message-State: AOJu0YzW5eDRmxX1a0Os4ra6fsMsMo895v0YsCLrOLsWRyj/0rELPLi2 MZtONVL6L3m6QGOYNEOcoAyKH6I7HbWK5X/umIM= X-Google-Smtp-Source: AGHT+IFriz68SBWCUSMU11F4QB9bXbe0kY3AVlbNs7eJqLAlATQXIQkeCpneiw2ILwtUzPeql2Rdrrw5FcvVA8kr3SI= X-Received: by 2002:a05:6830:a84:b0:6c4:7516:f2cf with SMTP id n4-20020a0568300a8400b006c47516f2cfmr8139106otu.2.1698052801541; Mon, 23 Oct 2023 02:20:01 -0700 (PDT) MIME-Version: 1.0 References: <20231019174944.3376335-1-sdf@google.com> <20231019174944.3376335-12-sdf@google.com> In-Reply-To: <20231019174944.3376335-12-sdf@google.com> From: Magnus Karlsson Date: Mon, 23 Oct 2023 11:19:50 +0200 Message-ID: To: Stanislav Fomichev Content-Type: text/plain; charset="UTF-8" Message-ID-Hash: HSMSKQPRWG36CAEF5FPJSYS6ACSNXTH7 X-Message-ID-Hash: HSMSKQPRWG36CAEF5FPJSYS6ACSNXTH7 X-MailFrom: magnus.karlsson@gmail.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; emergency; loop; banned-address; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header CC: bpf@vger.kernel.org, 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, 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 X-Mailman-Version: 3.3.8 Precedence: list Subject: [xdp-hints] Re: [PATCH bpf-next v4 11/11] xsk: Document tx_metadata_len layout List-Id: XDP hardware hints design discussion Archived-At: List-Archive: List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: On Thu, 19 Oct 2023 at 19:50, Stanislav Fomichev wrote: > > - how to use > - how to query features > - pointers to the examples > > Signed-off-by: Stanislav Fomichev > --- > Documentation/networking/index.rst | 1 + > Documentation/networking/xsk-tx-metadata.rst | 77 ++++++++++++++++++++ > 2 files changed, 78 insertions(+) > create mode 100644 Documentation/networking/xsk-tx-metadata.rst > > diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst > index 2ffc5ad10295..f3c2566d6cad 100644 > --- a/Documentation/networking/index.rst > +++ b/Documentation/networking/index.rst > @@ -122,6 +122,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/xsk-tx-metadata.rst b/Documentation/networking/xsk-tx-metadata.rst > new file mode 100644 > index 000000000000..b7289f06745c > --- /dev/null > +++ b/Documentation/networking/xsk-tx-metadata.rst > @@ -0,0 +1,77 @@ > +================== > +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_TX_METADATA_TIMESTAMP``: requests the device to put transmission > + timestamp into ``tx_timestamp`` field of ``union xsk_tx_metadata``. > +- ``XDP_TX_METADATA_CHECKSUM``: requests the device to calculate L4 > + checksum. ``csum_start`` specifies byte offset of there the checksumming nit: of there -> where > + should start and ``csum_offset`` specifies byte offset where the > + device should store the computed checksum. > +- ``XDP_TX_METADATA_CHECKSUM_SW``: requests checksum calculation to > + be done in software; this mode works only in ``XSK_COPY`` mode and > + is mostly intended for testing. Do not enable this option, it > + will negatively affect performance. > + > +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 not that in a multi-buffer packet nit: not -> note > +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_TX_METADATA_TIMESTAMP`` > +- ``tx-checksum``: device supports ``XDP_TX_METADATA_CHECKSUM`` > + > +Note that every devices supports ``XDP_TX_METADATA_CHECKSUM_SW`` when > +running in ``XSK_COPY`` mode. > + > +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.42.0.655.g421f12c284-goog > >