gso: add gso documentation

Type: docs

Signed-off-by: Mohsin Kazmi <sykazmi@cisco.com>
Change-Id: I8a96e6cc73b5f7ab3049fef37aafba43f3ef4d84

docs/developer/corefeatures/gso.rst

@@ -0,0 +1 @@
+../../../src/vnet/gso/gso.rst

docs/developer/corefeatures/index.rst

@@ -16,6 +16,7 @@ Core Features
     ipfix_doc
     span_doc
     mtu
+    gso
     sylog_doc
     eventviewer
     stats

docs/spelling_wordlist.txt

@@ -1346,3 +1346,4 @@ zoomin
 zoomout
 zx
 µs
+oflags

src/vnet/gso/gso.rst

@@ -0,0 +1,154 @@
+.. _gso_doc:
+
+Generic Segmentation Offload
+============================
+
+Overview
+________
+
+Modern physical NICs provide offload capabilities to software based network
+stacks to transfer some type of the packet processing from CPU to physical
+NICs. TCP Segmentation Offload (TSO) is one among many which is provided by
+modern physical NICs. Software based network stack can offload big (up to 64KB)
+TCP packets to NIC and NIC will segment them into Maximum Segment Size packets.
+Hence network stack save CPU cycles by processing few big packets instead of
+processing many small packets.
+
+GSO is software based analogous to TSO which is used by virtual interfaces
+i.e. tap, virtio, af_packet, vhost-user etc. Typically, virtual interfaces
+provide capability to offload big packets (64KB size). But in reality, they
+just pass the packet as it is to the other end without segmenting it. Hence, it
+is necessary to validate the support of GSO offloading in whole setup otherwise
+packet will be dropped when it will be processed by virtual entity which does
+not support GSO.
+
+The GSO Infrastructure
+_______________________
+
+Software based network stacks implements GSO packet segmentation in software
+where egress interface (virtual or physical) does not support GSO or TSO
+offload. VPP implements GSO stack to provide support for software based packet
+chunking of GSO packets when egress interface does not support GSO or TSO
+offload.
+
+It is implemented as a feature node on interface-output feature arc. It
+implements support for basic GSO, GSO with VXLAN tunnel and GSO with IPIP
+tunnel. GSO with Geneve and GSO with NVGRE are not supported today. But one can
+enable GSO feature node on tunnel interfaces i.e. IPSEC etc to segment GSO
+packets before they will be tunneled.
+
+Virtual interfaces does not support GSO with tunnels. So, special care is
+needed when user configures tunnel(s) along with GSO in the setup. In such case,
+either enable GSO feature node on tunnel interface (mean chunk the GSO packets
+before they will be encapsulated in tunnel) or disable the GSO offload on the
+egress interface (only work for VXLAN tunnel and IPIP tunnel), if it is enabled,
+should work fine.
+
+Similarly, many physical interfaces does not support GSO with tunnels too. User
+can do the same configuration as it is mentioned previously for virtual
+interfaces.
+
+Data structures
+^^^^^^^^^^^^^^^
+
+VPP ``vlib_buffer_t`` uses ``VNET_BUFFER_F_GSO`` flags to mark the buffer carrying GSO
+packet and also contain metadata fields with respect to GSO:
+
+.. code:: c
+
+  i16 l2_hdr_offset;
+  i16 l3_hdr_offset;
+  i16 l4_hdr_offset;
+
+  u16 gso_size;
+  u16 gso_l4_hdr_sz;
+  i16 outer_l3_hdr_offset;
+  i16 outer_l4_hdr_offset;
+
+Packet header offsets are computed from the reference of ``vlib_buffer_t`` data
+pointer.
+
+``l2_hdr_offset``, ``l3_hdr_offset`` and ``l4_hdr_offset`` are set on input of checksum
+offload or GSO enabled interfaces or features i.e. host stack. Appropriate
+offload flags are also set to ``vnet_buffer_oflags_t`` to reflect the actual packet
+offloads which will be used later at egress interface tx node or
+interface-output node or GSO node to process the packet appropriately. These
+fields are present in 1st cache line and does not incur extra cycles as most of
+the VPP features fetch the ``vlib_buffer_t`` 1st cache line to access ``current_data``
+or ``current_length`` fields of the packet.
+
+Please note that ``gso_size``, ``gso_l4_hdr_sz``, ``outer_l3_hdr_offset`` and
+``outer_l4_hdr_offset`` are in second cache line of ``vlib_buffer_t``. Accessing them in
+data plane will incur some extra cycles but cost of these cycles will be
+amortized over (up to 64KB) packet.
+
+The ``gso_size`` and ``gso_l4_hdr_sz`` are set on input of GSO enabled interfaces (tap,
+virtio, af_packet etc) or features (vpp host stack), when we receive a GSO
+packet (a chain of buffers with the first one having ``VNET_BUFFER_F_GSO`` bit set),
+and needs to persist all the way to the interface-output, in case the egress
+interface is not GSO-enabled - then we need to perform the segmentation, and use
+these values to chunk the payload appropriately.
+
+``outer_l3_hdr_offset`` and ``outer_l4_hdr_offset`` are used in case of tunneled packet
+(i.e. VXLAN or IPIP). ``outer_l3_hdr_offset`` will point to outer l3 header of the
+tunnel headers and ``outer_l4_hdr_offset`` will point to outer l4 header of the
+tunnel headers, if any.
+
+Following are the helper functions used to set and clear the offload flags from
+``vlib_buffer_t`` metadata:
+
+.. code:: c
+
+  static_always_inline void
+  vnet_buffer_offload_flags_set (vlib_buffer_t *b, vnet_buffer_oflags_t oflags)
+  {
+    if (b->flags & VNET_BUFFER_F_OFFLOAD)
+      {
+        /* add a flag to existing offload */
+        vnet_buffer (b)->oflags |= oflags;
+      }
+    else
+      {
+        /* no offload yet: reset offload flags to new value */
+        vnet_buffer (b)->oflags = oflags;
+        b->flags |= VNET_BUFFER_F_OFFLOAD;
+      }
+  }
+
+  static_always_inline void
+  vnet_buffer_offload_flags_clear (vlib_buffer_t *b, vnet_buffer_oflags_t oflags)
+  {
+    vnet_buffer (b)->oflags &= ~oflags;
+    if (0 == vnet_buffer (b)->oflags)
+      b->flags &= ~VNET_BUFFER_F_OFFLOAD;
+  }
+
+
+ENABLE GSO FEATURE NODE
+-----------------------
+
+GSO feature node is not enabled by default when egress interface does not
+support GSO. User has to enable it explicitly using api or cli.
+
+GSO API
+^^^^^^^
+
+This API message is used to enable GSO feature node on an interface.
+
+.. code:: c
+
+  autoreply define feature_gso_enable_disable
+  {
+    u32 client_index;
+    u32 context;
+    vl_api_interface_index_t sw_if_index;
+    bool  enable_disable;
+    option vat_help = "<intfc> | sw_if_index <nn> [enable | disable]";
+  };
+
+GSO CLI
+^^^^^^^
+
+::
+
+  set interface feature gso <intfc> [enable | disable]