Re: [PATCH v1 net-next 1/5] Documentations: Analyze heavily used Networking related structs

[Jakub Kicinski <kuba@kernel.org>]

On Sat, 16 Sep 2023 01:06:21 +0000 Coco Li wrote:
> Analyzed a few structs in the networking stack by looking at variables
> within them that are used in the TCP/IP fast path.
> 
> Fast path is defined as TCP path where data is transferred from sender to
> receiver unidirectionaly. It doesn't include phases other than
> TCP_ESTABLISHED, nor does it look at error paths.
> 
> We hope to re-organizing variables that span many cachelines whose fast
> path variables are also spread out, and this document can help future
> developers keep networking fast path cachelines small.
> 
> Optimized_cacheline field is computed as
> (Fastpath_Bytes/L3_cacheline_size_x86), and not the actual organized
> results (see patches to come for these).

Great work! I wonder if it's not better to drop the Documentation/
files and just add the info from the "comments" inline in the struct?
Is there precedent for such out-of-line documentation?
The grouping in structures makes it clear what the category of the
field is (and we can add comments where it isn't).

Right now the "documentation" does not seem to be mentioned anywhere 
in the source code. Chances that anyone will know to look for it are
close to zero :(

The guidance on how the optimizations were performed OTOH would be
quite useful to document.