[PATCH manpages v2 1/2] udp.7: add UDP_SEGMENT

[PATCH manpages v2 1/2] udp.7: add UDP_SEGMENT

[Willem de Bruijn]

From: Willem de Bruijn <willemb@google.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@google.com>

---

Changes v1->v2
  - semantic newlines: also break on comma and colon
  - remove bold: section number following function name
  - add bold: special macro USHRT_MAX
---
 man7/udp.7 | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/man7/udp.7 b/man7/udp.7
index 5822bc551fdf..6646c1e96bb0 100644
--- a/man7/udp.7
+++ b/man7/udp.7
@@ -204,6 +204,34 @@ 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 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
+.BR 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)
+calls by passing it as a
+.BR cmsg (7).
+A value of zero disables the feature.
+This option should not be used in code intended to be portable.
 .SS Ioctls
 These ioctls can be accessed using
 .BR ioctl (2).
-- 
2.39.2.722.g9855ee24e9-goog

[PATCH manpages v2 2/2] udp.7: add UDP_GRO

[Willem de Bruijn]

From: Willem de Bruijn <willemb@google.com>

UDP_GRO was added in commit e20cf8d3f1f7
("udp: implement GRO for plain UDP sockets.")

    $ git describe --contains e20cf8d3f1f7
    linux/v5.0-rc1~129^2~379^2~8

Kernel source has example code in tools/testing/selftests/net/udpgro*

Per https://www.kernel.org/doc/man-pages/patches.html,
"Describe how you obtained the information in your patch":
I reviewed the relevant UDP_GRO patches.

Signed-off-by: Willem de Bruijn <willemb@google.com>

---

Changes v1->v2
  - semantic newlines: also break on comma
  - remove bold: section number following function name
---
 man7/udp.7 | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/man7/udp.7 b/man7/udp.7
index 6646c1e96bb0..a350a40da340 100644
--- a/man7/udp.7
+++ b/man7/udp.7
@@ -232,6 +232,20 @@ calls by passing it as a
 .BR cmsg (7).
 A value of zero disables the feature.
 This option should not be used in code intended to be portable.
+.TP
+.BR UDP_GRO " (since Linux 5.0)"
+Enables UDP receive offload.
+If enabled,
+the socket may receive multiple datagrams worth of data as a single large
+buffer,
+together with a
+.BR cmsg (7)
+that holds the segment size.
+This option is the inverse of segmentation offload.
+It reduces receive cost by handling multiple datagrams worth of data
+as a single large packet in the kernel receive path,
+even when that exceeds MTU.
+This option should not be used in code intended to be portable.
 .SS Ioctls
 These ioctls can be accessed using
 .BR ioctl (2).
-- 
2.39.2.722.g9855ee24e9-goog

Re: [PATCH manpages v2 1/2] udp.7: add UDP_SEGMENT

[Simon Horman]

On Thu, Mar 02, 2023 at 10:48:07AM -0500, Willem de Bruijn wrote:
> From: Willem de Bruijn <willemb@google.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@google.com>

Reviewed-by: Simon Horman <simon.horman@corigine.com>

Re: [PATCH manpages v2 2/2] udp.7: add UDP_GRO

[Simon Horman]

On Thu, Mar 02, 2023 at 10:48:08AM -0500, Willem de Bruijn wrote:
> From: Willem de Bruijn <willemb@google.com>
> 
> UDP_GRO was added in commit e20cf8d3f1f7
> ("udp: implement GRO for plain UDP sockets.")
> 
>     $ git describe --contains e20cf8d3f1f7
>     linux/v5.0-rc1~129^2~379^2~8
> 
> Kernel source has example code in tools/testing/selftests/net/udpgro*
> 
> Per https://www.kernel.org/doc/man-pages/patches.html,
> "Describe how you obtained the information in your patch":
> I reviewed the relevant UDP_GRO patches.
> 
> Signed-off-by: Willem de Bruijn <willemb@google.com>

Reviewed-by: Simon Horman <simon.horman@corigine.com>

Re: [PATCH manpages v2 1/2] udp.7: add UDP_SEGMENT

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 2698 bytes --]

Hi Willem,

On 3/2/23 16:48, Willem de Bruijn wrote:
> From: Willem de Bruijn <willemb@google.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@google.com>

Patch applied, with some minor tweaks and Simon's review tag.

Cheers,

Alex

> 
> ---
> 
> Changes v1->v2
>   - semantic newlines: also break on comma and colon
>   - remove bold: section number following function name
>   - add bold: special macro USHRT_MAX
> ---
>  man7/udp.7 | 28 ++++++++++++++++++++++++++++
>  1 file changed, 28 insertions(+)
> 
> diff --git a/man7/udp.7 b/man7/udp.7
> index 5822bc551fdf..6646c1e96bb0 100644
> --- a/man7/udp.7
> +++ b/man7/udp.7
> @@ -204,6 +204,34 @@ 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 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
> +.BR 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)
> +calls by passing it as a
> +.BR cmsg (7).
> +A value of zero disables the feature.
> +This option should not be used in code intended to be portable.
>  .SS Ioctls
>  These ioctls can be accessed using
>  .BR ioctl (2).

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH manpages v2 1/2] udp.7: add UDP_SEGMENT

[Alejandro Colomar]

Hi Willem,

On 3/2/23 16:48, Willem de Bruijn wrote:
> From: Willem de Bruijn <willemb@google.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@google.com>
> 

It doesn't apply.  Can you please rebase on top of master?

Thanks,

Alex

> ---
> 
> Changes v1->v2
>   - semantic newlines: also break on comma and colon
>   - remove bold: section number following function name
>   - add bold: special macro USHRT_MAX
> ---
>  man7/udp.7 | 28 ++++++++++++++++++++++++++++
>  1 file changed, 28 insertions(+)
> 
> diff --git a/man7/udp.7 b/man7/udp.7
> index 5822bc551fdf..6646c1e96bb0 100644
> --- a/man7/udp.7
> +++ b/man7/udp.7
> @@ -204,6 +204,34 @@ 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 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
> +.BR 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)
> +calls by passing it as a
> +.BR cmsg (7).
> +A value of zero disables the feature.
> +This option should not be used in code intended to be portable.
>  .SS Ioctls
>  These ioctls can be accessed using
>  .BR ioctl (2).

Re: [PATCH manpages v2 1/2] udp.7: add UDP_SEGMENT

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 2923 bytes --]



On 3/6/23 14:30, Alejandro Colomar wrote:
> Hi Willem,
> 
> On 3/2/23 16:48, Willem de Bruijn wrote:
>> From: Willem de Bruijn <willemb@google.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@google.com>
>>
> 
> It doesn't apply.  Can you please rebase on top of master?

Oops, sorry, I tried to apply 1/2 twice, instead of 1/2 and 2/2 :-)
Ignore that.

Cheers,

Alex
> 
> Thanks,
> 
> Alex
> 
>> ---
>>
>> Changes v1->v2
>>   - semantic newlines: also break on comma and colon
>>   - remove bold: section number following function name
>>   - add bold: special macro USHRT_MAX
>> ---
>>  man7/udp.7 | 28 ++++++++++++++++++++++++++++
>>  1 file changed, 28 insertions(+)
>>
>> diff --git a/man7/udp.7 b/man7/udp.7
>> index 5822bc551fdf..6646c1e96bb0 100644
>> --- a/man7/udp.7
>> +++ b/man7/udp.7
>> @@ -204,6 +204,34 @@ 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 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
>> +.BR 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)
>> +calls by passing it as a
>> +.BR cmsg (7).
>> +A value of zero disables the feature.
>> +This option should not be used in code intended to be portable.
>>  .SS Ioctls
>>  These ioctls can be accessed using
>>  .BR ioctl (2).

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH manpages v2 2/2] udp.7: add UDP_GRO

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 1904 bytes --]

Hi Willem, 

On 3/2/23 16:48, Willem de Bruijn wrote:
> From: Willem de Bruijn <willemb@google.com>
> 
> UDP_GRO was added in commit e20cf8d3f1f7
> ("udp: implement GRO for plain UDP sockets.")
> 
>     $ git describe --contains e20cf8d3f1f7
>     linux/v5.0-rc1~129^2~379^2~8
> 
> Kernel source has example code in tools/testing/selftests/net/udpgro*
> 
> Per https://www.kernel.org/doc/man-pages/patches.html,
> "Describe how you obtained the information in your patch":
> I reviewed the relevant UDP_GRO patches.
> 
> Signed-off-by: Willem de Bruijn <willemb@google.com>

Patch applied.  BTW, it was cmsg(3), not (7) :)

Cheers,

Alex

> 
> ---
> 
> Changes v1->v2
>   - semantic newlines: also break on comma
>   - remove bold: section number following function name
> ---
>  man7/udp.7 | 14 ++++++++++++++
>  1 file changed, 14 insertions(+)
> 
> diff --git a/man7/udp.7 b/man7/udp.7
> index 6646c1e96bb0..a350a40da340 100644
> --- a/man7/udp.7
> +++ b/man7/udp.7
> @@ -232,6 +232,20 @@ calls by passing it as a
>  .BR cmsg (7).
>  A value of zero disables the feature.
>  This option should not be used in code intended to be portable.
> +.TP
> +.BR UDP_GRO " (since Linux 5.0)"
> +Enables UDP receive offload.
> +If enabled,
> +the socket may receive multiple datagrams worth of data as a single large
> +buffer,
> +together with a
> +.BR cmsg (7)
> +that holds the segment size.
> +This option is the inverse of segmentation offload.
> +It reduces receive cost by handling multiple datagrams worth of data
> +as a single large packet in the kernel receive path,
> +even when that exceeds MTU.
> +This option should not be used in code intended to be portable.
>  .SS Ioctls
>  These ioctls can be accessed using
>  .BR ioctl (2).

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH manpages v2 1/2] udp.7: add UDP_SEGMENT

[Willem de Bruijn]

Alejandro Colomar wrote:
> 
> 
> On 3/6/23 14:30, Alejandro Colomar wrote:
> > Hi Willem,
> > 
> > On 3/2/23 16:48, Willem de Bruijn wrote:
> >> From: Willem de Bruijn <willemb@google.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@google.com>
> >>
> > 
> > It doesn't apply.  Can you please rebase on top of master?
> 
> Oops, sorry, I tried to apply 1/2 twice, instead of 1/2 and 2/2 :-)
> Ignore that.

Great. Thanks for applying, and for fixing up the cmsg references, Alex.