-.. BSD LICENSE
- Copyright(c) 2017 Intel Corporation. All rights reserved.
- All rights reserved.
-
- Redistribution and use in source and binary forms, with or without
- modification, are permitted provided that the following conditions
- are met:
-
- * Redistributions of source code must retain the above copyright
- notice, this list of conditions and the following disclaimer.
- * Redistributions in binary form must reproduce the above copyright
- notice, this list of conditions and the following disclaimer in
- the documentation and/or other materials provided with the
- distribution.
- * Neither the name of Intel Corporation nor the names of its
- contributors may be used to endorse or promote products derived
- from this software without specific prior written permission.
-
- THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
- OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
- OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright(c) 2017 Intel Corporation.
Generic Segmentation Offload Library
====================================
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
-----------
#. 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.
.. _figure_gso-output-segment-format:
-.. figure:: img/gso-output-segment-format.svg
+.. figure:: img/gso-output-segment-format.*
:align: center
Two-part GSO output segment
.. _figure_gso-three-seg-mbuf:
-.. figure:: img/gso-three-seg-mbuf.svg
+.. figure:: img/gso-three-seg-mbuf.*
:align: center
Three-part GSO output segment
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.
- a pointer to the mbuf pool for allocating indirect buffers, which are
used to locate GSO segments' packet payloads.
-.. note::
+ .. note::
+
+ An application may use the same pool for both direct and indirect
+ buffers. However, since indirect mbufs simply store a pointer, the
+ application may reduce its memory consumption by creating a separate memory
+ pool, containing smaller elements, for the indirect pool.
- An application may use the same pool for both direct and indirect
- buffers. However, since each indirect mbuf simply stores a pointer, the
- application may reduce its memory consumption by creating a separate memory
- pool, containing smaller elements, for the indirect pool.
- the size of each output segment, including packet headers and payload,
measured in bytes.
- 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
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
#. 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.
-
git.droids-corp.org / dpdk.git / blobdiff