diff mbox series

doc: add GRO API requirement in prog_guide

Message ID 1545107119-85376-1-git-send-email-jiayu.hu@intel.com (mailing list archive)
State Superseded, archived
Delegated to: Thomas Monjalon
Headers show
Series doc: add GRO API requirement in prog_guide | expand

Checks

Context Check Description
ci/checkpatch success coding style OK
ci/Intel-compilation success Compilation OK
ci/mellanox-Performance-Testing success Performance Testing PASS
ci/intel-Performance-Testing success Performance Testing PASS

Commit Message

Hu, Jiayu Dec. 18, 2018, 4:25 a.m. UTC
The GRO library requires that applications set correct values for
MBUF->l2_len/l3_len/l4_len/outer_l2_len/outer_l3_len/pkt_len/data_len.

This patch adds the requirement in prog_guide.

Signed-off-by: Jiayu Hu <jiayu.hu@intel.com>
---
 doc/guides/prog_guide/generic_receive_offload_lib.rst | 6 ++++++
 1 file changed, 6 insertions(+)

Comments

Stephen Hemminger Jan. 4, 2019, 7:35 p.m. UTC | #1
On Tue, 18 Dec 2018 12:25:19 +0800
Jiayu Hu <jiayu.hu@intel.com> wrote:

> +.. note::
> +        To use the GRO library, applications must guarantee that
> +        MBUF->l2_len/l3_len/l4_len/outer_l2_len/outer_l3_len and
> +        MBUF->pkt_len/data_len of input packets are set to correct
> +        values.
> +

This statement seems confusing to me since
this is Generic Receive Offload, and receive buffers come from
the poll mode driver.

Aren't you saying that the PMD must set the correct values.
If this is correct, then any PMD not doing so is buggy.
And should be reported and fixed. If it is really buggy PMD's
then the statement in the programmers guide is not the place to handle
this kind of issue.  Better to just shame the buggy drivers in the
release notes for that NIC.
Hu, Jiayu Jan. 8, 2019, 2:35 a.m. UTC | #2
Hi Stephen,

> -----Original Message-----
> From: Stephen Hemminger [mailto:stephen@networkplumber.org]
> Sent: Saturday, January 5, 2019 3:36 AM
> To: Hu, Jiayu <jiayu.hu@intel.com>
> Cc: dev@dpdk.org
> Subject: Re: [dpdk-dev] [PATCH] doc: add GRO API requirement in
> prog_guide
> 
> On Tue, 18 Dec 2018 12:25:19 +0800
> Jiayu Hu <jiayu.hu@intel.com> wrote:
> 
> > +.. note::
> > +        To use the GRO library, applications must guarantee that
> > +        MBUF->l2_len/l3_len/l4_len/outer_l2_len/outer_l3_len and
> > +        MBUF->pkt_len/data_len of input packets are set to correct
> > +        values.
> > +
> 
> This statement seems confusing to me since
> this is Generic Receive Offload, and receive buffers come from
> the poll mode driver.
> 
> Aren't you saying that the PMD must set the correct values.
> If this is correct, then any PMD not doing so is buggy.
> And should be reported and fixed. If it is really buggy PMD's
> then the statement in the programmers guide is not the place to handle
> this kind of issue.  Better to just shame the buggy drivers in the
> release notes for that NIC.

IMO, since GRO is a library, all input packets are from user applications.
So I want to tell them that GRO relies on MBUF->l2_len/... to
parse packets. If they want correct reassembly results, all those fields of MBUF
should be set correctly. If the packets are received by buggy PMDs and user
applications directly pass them to GRO, GRO results are unknown. If the
packets are received from correct PMDs, but user applications modify MBUF
and make MBUF->l2_len/... incorrect, GRO results are still unknown.

This statement is more like a programmer note. If you think it is confusing,
how do you think this one:
GRO library uses MBUF->l2_len/... to parse packet headers. If the input packets
have incorrect values of MBUF->l2_len/.., GRO reassembly results are unknown.

Thanks,
Jiayu
diff mbox series

Patch

diff --git a/doc/guides/prog_guide/generic_receive_offload_lib.rst b/doc/guides/prog_guide/generic_receive_offload_lib.rst
index 9c6a4d0..7e6944d 100644
--- a/doc/guides/prog_guide/generic_receive_offload_lib.rst
+++ b/doc/guides/prog_guide/generic_receive_offload_lib.rst
@@ -34,6 +34,12 @@  Currently, the GRO library provides GRO supports for TCP/IPv4 packets and
 VxLAN packets which contain an outer IPv4 header and an inner TCP/IPv4
 packet.
 
+.. note::
+        To use the GRO library, applications must guarantee that
+        MBUF->l2_len/l3_len/l4_len/outer_l2_len/outer_l3_len and
+        MBUF->pkt_len/data_len of input packets are set to correct
+        values.
+
 Two Sets of API
 ---------------