NAME

       zero_copy, zero_copy_sockets — zero copy sockets code

SYNOPSIS

       options ZERO_COPY_SOCKETS

DESCRIPTION

       The FreeBSD kernel includes a facility for eliminating data copies on socket reads and writes.

       This  code  is  collectively known as the zero copy sockets code, because during normal network I/O, data
       will not be copied by the CPU at all.  Rather it will be DMAed from the user's buffer  to  the  NIC  (for
       sends), or DMAed from the NIC to a buffer that will then be given to the user (receives).

       The  zero  copy  sockets  code  uses the standard socket read and write semantics, and therefore has some
       limitations and restrictions that programmers should be aware of when trying to take  advantage  of  this
       functionality.

       For  sending data, there are no special requirements or capabilities that the sending NIC must have.  The
       data written to the socket, though, must be at least a page in size and  page  aligned  in  order  to  be
       mapped  into  the kernel.  If it does not meet the page size and alignment constraints, it will be copied
       into the kernel, as is normally the case with socket I/O.

       The user should be careful not to overwrite buffers that have been written to the socket before the  data
       has  been  freed by the kernel, and the copy-on-write mapping cleared.  If a buffer is overwritten before
       it has been given up by the kernel, the data will be copied, and no savings in CPU utilization and memory
       bandwidth utilization will be realized.

       The socket(2) API does not really give the user any indication of when his data has  actually  been  sent
       over  the  wire,  or  when the data has been freed from kernel buffers.  For protocols like TCP, the data
       will be kept around in the kernel until it has been acknowledged by the other side; it must be kept until
       the acknowledgement is received in case retransmission is required.

       From an application standpoint, the best way to guarantee that the data has been sent out over  the  wire
       and  freed by the kernel (for TCP-based sockets) is to set a socket buffer size (see the SO_SNDBUF socket
       option in the setsockopt(2) manual page) appropriate for the application and network environment and then
       make sure you have sent out twice as much data as the socket buffer size before reusing  a  buffer.   For
       TCP, the send and receive socket buffer sizes generally directly correspond to the TCP window size.

       For  receiving  data,  in order to take advantage of the zero copy receive code, the user must have a NIC
       that is configured for an MTU greater than the architecture page size.  (E.g., for i386 it would be 4KB.)
       Additionally, in order for zero copy receive to work, packet payloads must be at least a page in size and
       page aligned.

       Achieving page aligned payloads requires a NIC that can split an incoming packet into  multiple  buffers.
       It  also  generally requires some sort of intelligence on the NIC to make sure that the payload starts in
       its own buffer.  This is called “header splitting”.  Currently the only  NICs  with  support  for  header
       splitting  are  Alteon Tigon 2 based boards running slightly modified firmware.  The FreeBSD ti(4) driver
       includes modified firmware for Tigon 2 boards only.  Header splitting code can be written,  however,  for
       any NIC that allows putting received packets into multiple buffers and that has enough programmability to
       determine that the header should go into one buffer and the payload into another.

       You  can also do a form of header splitting that does not require any NIC modifications if your NIC is at
       least capable of splitting packets into multiple buffers.  This requires that you optimize the NIC driver
       for your most common packet header size.  If that size (ethernet + IP +  TCP  headers)  is  generally  66
       bytes, for instance, you would set the first buffer in a set for a particular packet to be 66 bytes long,
       and  then  subsequent buffers would be a page in size.  For packets that have headers that are exactly 66
       bytes long, your payload will be page aligned.

       The other requirement for zero copy receive to work is that the buffer that is the  destination  for  the
       data read from a socket must be at least a page in size and page aligned.

       Obviously the requirements for receive side zero copy are impossible to meet without NIC hardware that is
       programmable  enough  to do header splitting of some sort.  Since most NICs are not that programmable, or
       their manufacturers will not share the source code to their firmware, this approach to zero copy  receive
       is not widely useful.

       There  are  other  approaches,  such as RDMA and TCP Offload, that may potentially help alleviate the CPU
       overhead associated with copying data out of the kernel.  Most known  techniques  require  some  sort  of
       support at the NIC level to work, and describing such techniques is beyond the scope of this manual page.

       The   zero   copy   send   and   zero   copy  receive  code  can  be  individually  turned  off  via  the
       kern.ipc.zero_copy.send and kern.ipc.zero_copy.receive sysctl variables respectively.

SEE ALSO

       sendfile(2), socket(2), ti(4)

HISTORY

       The zero copy sockets code first appeared in FreeBSD 5.0, although it has been in existence in patch form
       since at least mid-1999.

AUTHORS

       The zero copy  sockets  code  was  originally  written  by  Andrew  Gallatin  <gallatin@FreeBSD.org>  and
       substantially modified and updated by Kenneth Merry <ken@FreeBSD.org>.

Debian                                          December 5, 2004                                    ZERO_COPY(9)