[dpdk-dev,2/2] mbuf: improve API doc for tunnel Tx offloads

  Add few details to remind TSO flag, checksum flags and header lengths.

The doxygen syntax for MPLS-in-UDP is fixed.

Fixes: d95188551fa1 ("mbuf: introduce new Tx offload flag for MPLS-in-UDP")
Cc: harish.patil@cavium.com

Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
---
 lib/librte_mbuf/rte_mbuf.h | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)
  

On Fri, Apr 20, 2018 at 02:13:24AM +0200, Thomas Monjalon wrote:
> Add few details to remind TSO flag, checksum flags and header lengths.
> 
> The doxygen syntax for MPLS-in-UDP is fixed.
> 
> Fixes: d95188551fa1 ("mbuf: introduce new Tx offload flag for MPLS-in-UDP")
> Cc: harish.patil@cavium.com
> 
> Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
> ---
>  lib/librte_mbuf/rte_mbuf.h | 8 +++++---
>  1 file changed, 5 insertions(+), 3 deletions(-)
> 
> diff --git a/lib/librte_mbuf/rte_mbuf.h b/lib/librte_mbuf/rte_mbuf.h
> index 7ae3bab14..adf95e3cd 100644
> --- a/lib/librte_mbuf/rte_mbuf.h
> +++ b/lib/librte_mbuf/rte_mbuf.h
> @@ -201,14 +201,16 @@ extern "C" {
>  
>  /**
>   * Bits 45:48 used for the tunnel type.
> - * When doing Tx offload like TSO or checksum, the HW needs to configure the
> - * tunnel type into the HW descriptors.
> + * The tunnel type must be specified for TSO or checksum on tunnel packets.

on tunnel packets -> on the inner part of tunnel packets

> + * These flags can be used with PKT_TX_TCP_SEG for TSO, or PKT_TX_xxx_CKSUM.
> + * The mbuf fields for inner and outer header lengths may be required:

may be -> are

> + * outer_l2_len, outer_l3_len, l2_len, l3_len, l4_len.

and tso_segsz for TSO.

>   */
>  #define PKT_TX_TUNNEL_VXLAN   (0x1ULL << 45)
>  #define PKT_TX_TUNNEL_GRE     (0x2ULL << 45)
>  #define PKT_TX_TUNNEL_IPIP    (0x3ULL << 45)
>  #define PKT_TX_TUNNEL_GENEVE  (0x4ULL << 45)
> -/**< TX packet with MPLS-in-UDP RFC 7510 header. */
> +/** TX packet with MPLS-in-UDP RFC 7510 header. */
>  #define PKT_TX_TUNNEL_MPLSINUDP (0x5ULL << 45)
>  /* add new TX TUNNEL type here */
>  #define PKT_TX_TUNNEL_MASK    (0xFULL << 45)
> -- 
> 2.16.2
>
  

23/04/2018 10:14, Olivier Matz:
> On Fri, Apr 20, 2018 at 02:13:24AM +0200, Thomas Monjalon wrote:
> > + * These flags can be used with PKT_TX_TCP_SEG for TSO, or PKT_TX_xxx_CKSUM.
> > + * The mbuf fields for inner and outer header lengths may be required:
> 
> may be -> are
> 
> > + * outer_l2_len, outer_l3_len, l2_len, l3_len, l4_len.
> 
> and tso_segsz for TSO.

From a HW point of view, some header lengths may be omitted if they are
guessed by the HW.
But you are right, from an API point of view, we should require them,
no matter what is the underlying hardware.

So the sentence becomes:
 * The mbuf fields for inner and outer header lengths are required:
 * outer_l2_len, outer_l3_len, l2_len, l3_len, l4_len and tso_segsz for TSO.
  

On Mon, Apr 23, 2018 at 10:53:17AM +0200, Thomas Monjalon wrote:
> 23/04/2018 10:14, Olivier Matz:
> > On Fri, Apr 20, 2018 at 02:13:24AM +0200, Thomas Monjalon wrote:
> > > + * These flags can be used with PKT_TX_TCP_SEG for TSO, or PKT_TX_xxx_CKSUM.
> > > + * The mbuf fields for inner and outer header lengths may be required:
> > 
> > may be -> are
> > 
> > > + * outer_l2_len, outer_l3_len, l2_len, l3_len, l4_len.
> > 
> > and tso_segsz for TSO.
> 
> From a HW point of view, some header lengths may be omitted if they are
> guessed by the HW.
> But you are right, from an API point of view, we should require them,
> no matter what is the underlying hardware.
> 
> So the sentence becomes:
>  * The mbuf fields for inner and outer header lengths are required:
>  * outer_l2_len, outer_l3_len, l2_len, l3_len, l4_len and tso_segsz for TSO.

Sounds good, thanks.