doc: add GRO API requirement in prog_guide

  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(+)
  

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.
  

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