share/man/man9/zero_copy.9

   1 .\"
   2 .\" Copyright (c) 2002 Kenneth D. Merry.
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions, and the following disclaimer,
  10 .\"    without modification, immediately at the beginning of the file.
  11 .\" 2. The name of the author may not be used to endorse or promote products
  12 .\"    derived from this software without specific prior written permission.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR
  18 .\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd October 23, 2012
  29 .Dt ZERO_COPY 9
  30 .Os
  31 .Sh NAME
  32 .Nm zero_copy ,
  33 .Nm zero_copy_sockets
  34 .Nd "zero copy sockets code"
  35 .Sh SYNOPSIS
  36 .Cd "options SOCKET_SEND_COW"
  37 .Cd "options SOCKET_RECV_PFLIP"
  38 .Sh DESCRIPTION
  39 The
  40 .Fx
  41 kernel includes a facility for eliminating data copies on
  42 socket reads and writes.
  43 .Pp
  44 This code is collectively known as the zero copy sockets code, because during
  45 normal network I/O, data will not be copied by the CPU at all.
  46 Rather it
  47 will be DMAed from the user's buffer to the NIC (for sends), or DMAed from
  48 the NIC to a buffer that will then be given to the user (receives).
  49 .Pp
  50 The zero copy sockets code uses the standard socket read and write
  51 semantics, and therefore has some limitations and restrictions that
  52 programmers should be aware of when trying to take advantage of this
  53 functionality.
  54 .Pp
  55 For sending data, there are no special requirements or capabilities that
  56 the sending NIC must have.
  57 The data written to the socket, though, must be
  58 at least a page in size and page aligned in order to be mapped into the
  59 kernel.
  60 If it does not meet the page size and alignment constraints, it
  61 will be copied into the kernel, as is normally the case with socket I/O.
  62 .Pp
  63 The user should be careful not to overwrite buffers that have been written
  64 to the socket before the data has been freed by the kernel, and the
  65 copy-on-write mapping cleared.
  66 If a buffer is overwritten before it has
  67 been given up by the kernel, the data will be copied, and no savings in CPU
  68 utilization and memory bandwidth utilization will be realized.
  69 .Pp
  70 The
  71 .Xr socket 2
  72 API does not really give the user any indication of when his data has
  73 actually been sent over the wire, or when the data has been freed from
  74 kernel buffers.
  75 For protocols like TCP, the data will be kept around in
  76 the kernel until it has been acknowledged by the other side; it must be
  77 kept until the acknowledgement is received in case retransmission is required.
  78 .Pp
  79 From an application standpoint, the best way to guarantee that the data has
  80 been sent out over the wire and freed by the kernel (for TCP-based sockets)
  81 is to set a socket buffer size (see the
  82 .Dv SO_SNDBUF
  83 socket option in the
  84 .Xr setsockopt 2
  85 manual page) appropriate for the application and network environment and then
  86 make sure you have sent out twice as much data as the socket buffer size
  87 before reusing a buffer.
  88 For TCP, the send and receive socket buffer sizes
  89 generally directly correspond to the TCP window size.
  90 .Pp
  91 For receiving data, in order to take advantage of the zero copy receive
  92 code, the user must have a NIC that is configured for an MTU greater than
  93 the architecture page size.
  94 (E.g., for i386 it would be 4KB.)
  95 Additionally, in order for zero copy receive to work,
  96 packet payloads must be at least a page in size and page aligned.
  97 .Pp
  98 Achieving page aligned payloads requires a NIC that can split an incoming
  99 packet into multiple buffers.
 100 It also generally requires some sort of
 101 intelligence on the NIC to make sure that the payload starts in its own
 102 buffer.
 103 This is called
 104 .Dq "header splitting" .
 105 Currently the only NICs with
 106 support for header splitting are Alteon Tigon 2 based boards running
 107 slightly modified firmware.
 108 The
 109 .Fx
 110 .Xr ti 4
 111 driver includes modified firmware for Tigon 2 boards only.
 112 Header
 113 splitting code can be written, however, for any NIC that allows putting
 114 received packets into multiple buffers and that has enough programmability
 115 to determine that the header should go into one buffer and the payload into
 116 another.
 117 .Pp
 118 You can also do a form of header splitting that does not require any NIC
 119 modifications if your NIC is at least capable of splitting packets into
 120 multiple buffers.
 121 This requires that you optimize the NIC driver for your
 122 most common packet header size.
 123 If that size (ethernet + IP + TCP headers)
 124 is generally 66 bytes, for instance, you would set the first buffer in a
 125 set for a particular packet to be 66 bytes long, and then subsequent
 126 buffers would be a page in size.
 127 For packets that have headers that are
 128 exactly 66 bytes long, your payload will be page aligned.
 129 .Pp
 130 The other requirement for zero copy receive to work is that the buffer that
 131 is the destination for the data read from a socket must be at least a page
 132 in size and page aligned.
 133 .Pp
 134 Obviously the requirements for receive side zero copy are impossible to
 135 meet without NIC hardware that is programmable enough to do header
 136 splitting of some sort.
 137 Since most NICs are not that programmable, or their
 138 manufacturers will not share the source code to their firmware, this approach
 139 to zero copy receive is not widely useful.
 140 .Pp
 141 There are other approaches, such as RDMA and TCP Offload, that may
 142 potentially help alleviate the CPU overhead associated with copying data
 143 out of the kernel.
 144 Most known techniques require some sort of support at
 145 the NIC level to work, and describing such techniques is beyond the scope
 146 of this manual page.
 147 .Pp
 148 The zero copy send and zero copy receive code can be individually turned
 149 off via the
 150 .Va kern.ipc.zero_copy.send
 151 and
 152 .Va kern.ipc.zero_copy.receive
 153 .Nm sysctl
 154 variables respectively.
 155 .Sh SEE ALSO
 156 .Xr sendfile 2 ,
 157 .Xr socket 2 ,
 158 .Xr ti 4
 159 .Sh HISTORY
 160 The zero copy sockets code first appeared in
 161 .Fx 5.0 ,
 162 although it has
 163 been in existence in patch form since at least mid-1999.
 164 .Sh AUTHORS
 165 .An -nosplit
 166 The zero copy sockets code was originally written by
 167 .An Andrew Gallatin Aq gallatin@FreeBSD.org
 168 and substantially modified and updated by
 169 .An Kenneth Merry Aq ken@FreeBSD.org .
 170 .Sh BUGS
 171 The COW based send mechanism is not safe and may result in kernel crashes.