ethdev: add namespace

[dpdk.git] / doc / guides / prog_guide / generic_segmentation_offload_lib.rst

diff --git a/doc/guides/prog_guide/generic_segmentation_offload_lib.rst b/doc/guides/prog_guide/generic_segmentation_offload_lib.rst
index 9959f0d..9b2c31a 100644 (file)
--- a/doc/guides/prog_guide/generic_segmentation_offload_lib.rst
+++ b/doc/guides/prog_guide/generic_segmentation_offload_lib.rst
@@ -25,8 +25,9 @@ Bearing that in mind, the GSO library enables DPDK applications to segment
 packets in software. Note however, that GSO is implemented as a standalone
 library, and not via a 'fallback' mechanism (i.e. for when TSO is unsupported
 in the underlying hardware); that is, applications must explicitly invoke the
-GSO library to segment packets. The size of GSO segments ``(segsz)`` is
-configurable by the application.
+GSO library to segment packets, they also must call ``rte_pktmbuf_free()``
+to free mbuf GSO segments attached after calling ``rte_gso_segment()``.
+The size of GSO segments (``segsz``) is configurable by the application.
 
 Limitations
 -----------
@@ -43,8 +44,9 @@ Limitations
 #. Currently, the GSO library supports the following IPv4 packet types:
 
  - TCP
- - VxLAN
- - GRE
+ - UDP
+ - VXLAN
+ - GRE TCP
 
   See `Supported GSO Packet Types`_ for further details.
 
@@ -146,14 +148,23 @@ TCP/IPv4 GSO
 TCP/IPv4 GSO supports segmentation of suitably large TCP/IPv4 packets, which
 may also contain an optional VLAN tag.
 
-VxLAN GSO
-~~~~~~~~~
-VxLAN packets GSO supports segmentation of suitably large VxLAN packets,
-which contain an outer IPv4 header, inner TCP/IPv4 headers, and optional
-inner and/or outer VLAN tag(s).
-
-GRE GSO
-~~~~~~~
+UDP/IPv4 GSO
+~~~~~~~~~~~~
+UDP/IPv4 GSO supports segmentation of suitably large UDP/IPv4 packets, which
+may also contain an optional VLAN tag. UDP GSO is the same as IP fragmentation.
+Specifically, UDP GSO treats the UDP header as a part of the payload and
+does not modify it during segmentation. Therefore, after UDP GSO, only the
+first output packet has the original UDP header, and others just have l2
+and l3 headers.
+
+VXLAN IPv4 GSO
+~~~~~~~~~~~~~~
+VXLAN packets GSO supports segmentation of suitably large VXLAN packets,
+which contain an outer IPv4 header, inner TCP/IPv4 or UDP/IPv4 headers, and
+optional inner and/or outer VLAN tag(s).
+
+GRE TCP/IPv4 GSO
+~~~~~~~~~~~~~~~~
 GRE GSO supports segmentation of suitably large GRE packets, which contain
 an outer IPv4 header, inner TCP/IPv4 headers, and an optional VLAN tag.
 
@@ -183,11 +194,11 @@ To segment an outgoing packet, an application must:
 
    - the bit mask of required GSO types. The GSO library uses the same macros as
      those that describe a physical device's TX offloading capabilities (i.e.
-     ``DEV_TX_OFFLOAD_*_TSO``) for gso_types. For example, if an application
+     ``RTE_ETH_TX_OFFLOAD_*_TSO``) for gso_types. For example, if an application
      wants to segment TCP/IPv4 packets, it should set gso_types to
-     ``DEV_TX_OFFLOAD_TCP_TSO``. The only other supported values currently
-     supported for gso_types are ``DEV_TX_OFFLOAD_VXLAN_TNL_TSO``, and
-     ``DEV_TX_OFFLOAD_GRE_TNL_TSO``; a combination of these macros is also
+     ``RTE_ETH_TX_OFFLOAD_TCP_TSO``. The only other supported values currently
+     supported for gso_types are ``RTE_ETH_TX_OFFLOAD_VXLAN_TNL_TSO``, and
+     ``RTE_ETH_TX_OFFLOAD_GRE_TNL_TSO``; a combination of these macros is also
      allowed.
 
    - a flag, that indicates whether the IPv4 headers of output segments should
@@ -196,7 +207,7 @@ To segment an outgoing packet, an application must:
 2. Set the appropriate ol_flags in the mbuf.
 
    - The GSO library use the value of an mbuf's ``ol_flags`` attribute to
-     to determine how a packet should be segmented. It is the application's
+     determine how a packet should be segmented. It is the application's
      responsibility to ensure that these flags are set.
 
    - For example, in order to segment TCP/IPv4 packets, the application should
@@ -223,8 +234,9 @@ To segment an outgoing packet, an application must:
 
 #. Invoke the GSO segmentation API, ``rte_gso_segment()``.
 
+#. Call ``rte_pktmbuf_free()`` to free mbuf ``rte_gso_segment()`` segments.
+
 #. If required, update the L3 and L4 checksums of the newly-created segments.
    For tunneled packets, the outer IPv4 headers' checksums should also be
    updated. Alternatively, the application may offload checksum calculation
    to HW.
-