From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-qt1-f174.google.com (mail-qt1-f174.google.com [209.85.160.174]) by mail.toke.dk (Postfix) with ESMTPS id 5214B9D9067 for ; Wed, 4 Jan 2023 17:02:50 +0100 (CET) Received: by mail-qt1-f174.google.com with SMTP id j16so27535063qtv.4 for ; Wed, 04 Jan 2023 08:02:50 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=user-agent:in-reply-to:content-disposition:mime-version:references :message-id:subject:cc:to:from:date:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=qwSsj6dKaBLyzBS+oljx3z67n7iA+If7j6wt5yj7OGk=; b=2cHyiyifUQL6ZwGsrpI6uW+Y177+AeAw2Xw2WTUB2RJtXv6ZhhFqqKpnu+7jYkR/J0 goBZNWPBi8kjo71nSBZMsVnQhDH0k/51jqaaqWbu1a6dM/5LqoHzP4lN80u7QeVar++6 sWC2jxlLfxXF9dtKMxuhpJ0L4WIKW7euIYEB8kSddYEH5Ggs6SkbB7xKfJMWFyHyyzcc M+K8A93tyAA6GNI+MCjFcKvs7fEQOLbk1gOqwYwmGdMiogoDr5Mt0uvnPItgSDs+PtY/ IeZxdZkt80nIZWy7TBBjcUDdyM9rqwIrYzTkyw8slgBLKkZawNaORX80oiSnA9pteSDe W3Fg== X-Gm-Message-State: AFqh2kqtSojEKjIXhPhz4AUxMxsL8GireV6v1EsRTo5NlJ3WvJcNtqg8 Ml7vJmyzQojtV8/3S9Iiq8E= X-Google-Smtp-Source: AMrXdXuMglJVXwPAb6rs5TQsBK2qJgPizgdczySE1YEsATFGWEriPNwr0oOzc96UlJ9LEqSbLw7X3w== X-Received: by 2002:ac8:4a07:0:b0:3a5:8084:9f60 with SMTP id x7-20020ac84a07000000b003a580849f60mr67619083qtq.64.1672848169338; Wed, 04 Jan 2023 08:02:49 -0800 (PST) Received: from maniforge.lan ([2620:10d:c091:480::1:7c6c]) by smtp.gmail.com with ESMTPSA id t1-20020ac865c1000000b003a7e4129f83sm19996524qto.85.2023.01.04.08.02.47 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 04 Jan 2023 08:02:48 -0800 (PST) Date: Wed, 4 Jan 2023 10:02:48 -0600 From: David Vernet To: Stanislav Fomichev Message-ID: References: <20221220222043.3348718-1-sdf@google.com> <20221220222043.3348718-2-sdf@google.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: User-Agent: Mutt/2.2.9 (2022-11-12) Message-ID-Hash: HW4AMSEGIXHZ67REWSUH6BTZQEPURZVI X-Message-ID-Hash: HW4AMSEGIXHZ67REWSUH6BTZQEPURZVI X-MailFrom: dcvernet@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, David Ahern , Jakub Kicinski , Willem de Bruijn , Jesper Dangaard Brouer , Anatoly Burakov , Alexander Lobakin , Magnus Karlsson , Maryam Tahhan , xdp-hints@xdp-project.net, netdev@vger.kernel.org X-Mailman-Version: 3.3.7 Precedence: list Subject: [xdp-hints] Re: [PATCH bpf-next v5 01/17] bpf: Document XDP RX metadata List-Id: XDP hardware hints design discussion Archived-At: List-Archive: List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: On Tue, Jan 03, 2023 at 02:23:03PM -0800, Stanislav Fomichev wrote: > On Wed, Dec 28, 2022 at 9:25 AM David Vernet wrote: > > > > On Tue, Dec 20, 2022 at 02:20:27PM -0800, Stanislav Fomichev wrote: > > > Document all current use-cases and assumptions. > > > > > > Cc: John Fastabend > > > Cc: David Ahern > > > Cc: Martin KaFai Lau > > > Cc: Jakub Kicinski > > > Cc: Willem de Bruijn > > > Cc: Jesper Dangaard Brouer > > > Cc: Anatoly Burakov > > > Cc: Alexander Lobakin > > > Cc: Magnus Karlsson > > > Cc: Maryam Tahhan > > > Cc: xdp-hints@xdp-project.net > > > Cc: netdev@vger.kernel.org > > > Signed-off-by: Stanislav Fomichev > > > --- > > > Documentation/networking/index.rst | 1 + > > > Documentation/networking/xdp-rx-metadata.rst | 107 +++++++++++++++++++ > > > 2 files changed, 108 insertions(+) > > > create mode 100644 Documentation/networking/xdp-rx-metadata.rst > > > > > > diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst > > > index 4f2d1f682a18..4ddcae33c336 100644 > > > --- a/Documentation/networking/index.rst > > > +++ b/Documentation/networking/index.rst > > > @@ -120,6 +120,7 @@ Refer to :ref:`netdev-FAQ` for a guide on netdev development process specifics. > > > xfrm_proc > > > xfrm_sync > > > xfrm_sysctl > > > + xdp-rx-metadata > > > > > > .. only:: subproject and html > > > > > > diff --git a/Documentation/networking/xdp-rx-metadata.rst b/Documentation/networking/xdp-rx-metadata.rst > > > new file mode 100644 > > > index 000000000000..37e8192d9b60 > > > --- /dev/null > > > +++ b/Documentation/networking/xdp-rx-metadata.rst > > > > Hey Stanislav, > > > > This is looking excellent. Left a few more minor comments and > > suggestions. > > > > > @@ -0,0 +1,107 @@ > > > +=============== > > > +XDP RX Metadata > > > +=============== > > > + > > > +This document describes how an XDP program can access hardware metadata > > > > In similar fashion to LWN articles, can we spell out what XDP means the > > first time it's used, e.g.: > > > > ...describes how an eXpress Data Path (XDP) program... > > > > In general this applies to other acronyms unless they're super obvious, > > like "CPU" (thanks for already having done it for XSK). > > Sure. Hopefully no need to explain RX below? Don't see anything else.. > LMK if I missed something Yeah, I think we can forego RX. > > > > +related to a packet using a set of helper functions, and how it can pass > > > +that metadata on to other consumers. > > > + > > > +General Design > > > +============== > > > + > > > +XDP has access to a set of kfuncs to manipulate the metadata in an XDP frame. > > > +Every device driver that wishes to expose additional packet metadata can > > > +implement these kfuncs. The set of kfuncs is declared in ``include/net/xdp.h`` > > > +via ``XDP_METADATA_KFUNC_xxx``. > > > + > > > +Currently, the following kfuncs are supported. In the future, as more > > > +metadata is supported, this set will grow: > > > + > > > +- ``bpf_xdp_metadata_rx_timestamp`` returns a packet's RX timestamp > > > +- ``bpf_xdp_metadata_rx_hash`` returns a packet's RX hash > > > > So, I leave this up to you as to whether or not you want to do this, but > > there is a built-in mechanism in sphinx that converts doxygen comments > > to rendered documentation for a function, struct, etc, and also > > automatically links other places in documentation where the function is > > referenced. See [0] for an example of this in code, and [1] for an > > example of how it's rendered. > > > > [0]: https://git.kernel.org/pub/scm/linux/kernel/git/bpf/bpf-next.git/tree/Documentation/bpf/kfuncs.rst#n239 > > [1]: https://docs.kernel.org/bpf/kfuncs.html#c.bpf_task_acquire > > > > So you would do something like add function headers to the kfuncs, and > > then do: > > > > .. kernel-doc:: net/core/xdp.c > > :identifiers: bpf_xdp_metadata_rx_timestamp bpf_xdp_metadata_rx_hash > > > > At some point we will need a consistent story for how we document > > kfuncs. That's not set in stone yet, which is why I'm saying it's up to > > you whether or not you want to do this or just leave it as teletype with > > a written description next to it. Later on when we settle on a > > documentation story for kfuncs, we can update all of them to be > > documented in the same way. > > Let me try and see how it looks in the html doc. I like the idea of > referencing the code directly, hopefully less chance it goes stale. Sounds good! [...] Thanks for making all these changes. - David