Documentation: migrate "CONFIG_NET_GUARDSIZE" from wiki

link: https://cwiki.apache.org/confluence/display/NUTTX/CONFIG_NET_GUARDSIZE

Author: raiden00pl

Documentation/components/net/index.rst

@@ -7,6 +7,7 @@ Network Support
 
   sixlowpan.rst
   socketcan.rst
+  netguardsize.rst
 
 ``net`` Directory Structure ::
 

Documentation/components/net/netguardsize.rst

@@ -0,0 +1,74 @@
+====================
+CONFIG_NET_GUARDSIZE
+====================
+
+Global Option for All Drivers
+=============================
+
+``CONFIG_NET_GUARD_SIZE`` is global option.  It is added to the allocated size of
+each driver packet buffer. Currently it is a very small value, defaulting to only
+two bytes. So it is not a memory hog and should be added to the packetsize for
+all drivers for commonality.  But why?
+
+It should (eventually) be larger and common for all drivers. We need to look at
+how it is used today and how it might be used tomorrow. There is a probably a lot
+more involved than you might be initially considering.
+
+Packet Receipt
+==============
+
+For packet receipt, it is necessary for some hardware, but not for others. Often
+the hardware will DMA a 2 byte FCS at the end of the packet or possibly other
+hardware-specific info.  But that is only part of the whole story.
+``CONFIG_NET_GUARDSIZE`` is not just for hardware packet receipt.
+
+Packet Transmission
+===================
+
+There are several issues for packet transmission. These are less well defined
+and need further study, but we need to keep all of the driver packet definitions
+in place until we understand how we are going to handle these things:
+
+* Memory Overrun Bugs
+
+  There was in the past, a bug that caused write past the end of the buffer by
+  a couple of bytes during TX message formatting. I don't know if that bug still
+  exists, but the minimum, two-byte ``CONFIG_NET_GUARDSIZE`` was sufficient to
+  eliminate the bug. That is why it has the name GUARD: Its primary purpose is
+  to protect from overrunning the packet buffer and corrupting the following memory.
+
+  I do no know if we have any such bugs today. Perhaps they still do?
+  Perhaps they do not? Having such a guard is a good thing for reliability in
+  any case.
+
+* Variable size IP/TCP headers
+
+  There is a limitation in the way IP packets are formatted now. Basically they
+  are formatted like this:
+
+    #. When the packet is received a pointer to the location of the payload is
+       set (d_appdata). This is an offset into the packet buffer For TCP, that
+       accounts for the MAC/Ethernet header, the minimum IPv4/IPv6 header size,
+       and the minimum TCP header size.
+
+    #. The TCP payload is written at that location,
+    #. The correctly sized IPv4/IPv6 headers and the correctly sized TCP header
+       are added below the payload, and finally
+    #. The MAC/Ethernet header as added.
+
+  The start offset of the packet in the packet is no longer zero, but some
+  variable offset into the packet buffer.  That new start offset would have
+  to be passed to driver in order to send the packet.
+
+  The key to making this all work is:
+
+    * Keep ``CONFIG_NET_GUARDSIZE`` in all driver buffers, and
+    * Set the ``CONFIG_NET_GUARDSIZE`` to the maximum size of IPv4/IPv6 and TCP options
+      (depending on which IP version is enabled and if TCP is enabled)
+    * Extend the driver interface to accept data offset into the driver's packet buffer.
+
+* Variable MSS
+
+  Closely related to this is the MSS which is the maximum size of the payload.
+  Currently that is a constant because it assumes the minimum header lengths.
+  It should be variable, depending on the actual header sizes.