netdev - Re: [PATCH manpages 1/2] udp.7: add UDP

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <CA+FuTSd2=8e73ALPxZR8k03oHOrsJfAQwoaLT+i-YLzwwCf+Bg@mail.gmail.com>
Date:   Wed, 1 Mar 2023 17:22:05 -0500
From:   Willem de Bruijn <willemb@...gle.com>
To:     Alejandro Colomar <alx.manpages@...il.com>
Cc:     Willem de Bruijn <willemdebruijn.kernel@...il.com>,
        linux-man@...r.kernel.org, netdev@...r.kernel.org,
        Paolo Abeni <pabeni@...hat.com>
Subject: Re: [PATCH manpages 1/2] udp.7: add UDP_SEGMENT

On Wed, Mar 1, 2023 at 4:35 PM Alejandro Colomar <alx.manpages@...il.com> wrote:
>
> Hi Willem,
>
> On 3/1/23 22:11, Willem de Bruijn wrote:
> > From: Willem de Bruijn <willemb@...gle.com>
> >
> > UDP_SEGMENT was added in commit bec1f6f69736
> > ("udp: generate gso with UDP_SEGMENT")
> >
> >     $ git describe --contains bec1f6f69736
> >     linux/v4.18-rc1~114^2~377^2~8
> >
> > Kernel source has example code in tools/testing/selftests/net/udpgso*
> >
> > Per https://www.kernel.org/doc/man-pages/patches.html,
> > "Describe how you obtained the information in your patch":
> > I am the author of the above commit and follow-ons.
> >
> > Signed-off-by: Willem de Bruijn <willemb@...gle.com>
> > ---
> >  man7/udp.7 | 25 +++++++++++++++++++++++++
> >  1 file changed, 25 insertions(+)
> >
> > diff --git a/man7/udp.7 b/man7/udp.7
> > index 5822bc551fdf..ec16306df605 100644
> > --- a/man7/udp.7
> > +++ b/man7/udp.7
> > @@ -204,6 +204,31 @@ portable.
> >  .\"     UDP_ENCAP_ESPINUDP draft-ietf-ipsec-udp-encaps-06
> >  .\"     UDP_ENCAP_L2TPINUDP rfc2661
> >  .\" FIXME Document UDP_NO_CHECK6_TX and UDP_NO_CHECK6_RX, added in Linux 3.16
> > +.TP
> > +.BR UDP_SEGMENT " (since Linux 4.18)"
> > +Enables UDP segmentation offload.
> > +Segmentation offload reduces
> > +.BR send(2)
> > +cost by transferring multiple datagrams worth of data as a single
> > +large packet through the kernel transmit path, even when that
>
> Please use semantic newlines.  See man-pages(7):
>
>    Use semantic newlines
>        In the source of a manual page, new sentences should be started
>        on  new  lines,  long  sentences  should be split into lines at
>        clause breaks (commas, semicolons, colons, and so on), and long
>        clauses should be split at phrase boundaries.  This convention,
>        sometimes known as "semantic newlines", makes it easier to  see
>        the  effect of patches, which often operate at the level of in‐
>        dividual sentences, clauses, or phrases.
>
>
> > +exceeds MTU.
> > +As late as possible, the large packet is split by segment size into a
> > +series of datagrams.
> > +This segmentation offload step is deferred to hardware if supported,
> > +else performed in software.
> > +This option takes a value between 0 and USHRT_MAX that sets the
> > +segment size: the size of datagram payload, excluding the UDP header.
> > +The segment size must be chosen such that at most 64 datagrams are
> > +sent in a single call and that the datagrams after segmentation meet
> > +the same MTU rules that apply to datagrams sent without this option.
> > +Segmentation offload depends on checksum offload, as datagram
> > +checksums are computed after segmentation.
> > +The option may also be set for individual
> > +.BR sendmsg(2)
>
> There should be a space between the bold part and the roman part:
>
> .BR foo (2)
>
> Otherwise, it all gets printed in bold.

Thanks Alex. I'll leave this open for other comments for a bit, but
will address both points in both patches in v2.