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 39The 40.Fx 41kernel includes a facility for eliminating data copies on 42socket reads and writes. 43.Pp 44This code is collectively known as the zero copy sockets code, because during 45normal network I/O, data will not be copied by the CPU at all. 46Rather it 47will be DMAed from the user's buffer to the NIC (for sends), or DMAed from 48the NIC to a buffer that will then be given to the user (receives). 49.Pp 50The zero copy sockets code uses the standard socket read and write 51semantics, and therefore has some limitations and restrictions that 52programmers should be aware of when trying to take advantage of this 53functionality. 54.Pp 55For sending data, there are no special requirements or capabilities that 56the sending NIC must have. 57The data written to the socket, though, must be 58at least a page in size and page aligned in order to be mapped into the 59kernel. 60If it does not meet the page size and alignment constraints, it 61will be copied into the kernel, as is normally the case with socket I/O. 62.Pp 63The user should be careful not to overwrite buffers that have been written 64to the socket before the data has been freed by the kernel, and the 65copy-on-write mapping cleared. 66If a buffer is overwritten before it has 67been given up by the kernel, the data will be copied, and no savings in CPU 68utilization and memory bandwidth utilization will be realized. 69.Pp 70The 71.Xr socket 2 72API does not really give the user any indication of when his data has 73actually been sent over the wire, or when the data has been freed from 74kernel buffers. 75For protocols like TCP, the data will be kept around in 76the kernel until it has been acknowledged by the other side; it must be 77kept until the acknowledgement is received in case retransmission is required. 78.Pp 79From an application standpoint, the best way to guarantee that the data has 80been sent out over the wire and freed by the kernel (for TCP-based sockets) 81is to set a socket buffer size (see the 82.Dv SO_SNDBUF 83socket option in the 84.Xr setsockopt 2 85manual page) appropriate for the application and network environment and then 86make sure you have sent out twice as much data as the socket buffer size 87before reusing a buffer. 88For TCP, the send and receive socket buffer sizes 89generally directly correspond to the TCP window size. 90.Pp 91For receiving data, in order to take advantage of the zero copy receive 92code, the user must have a NIC that is configured for an MTU greater than 93the architecture page size. 94(E.g., for i386 it would be 4KB.) 95Additionally, in order for zero copy receive to work, 96packet payloads must be at least a page in size and page aligned. 97.Pp 98Achieving page aligned payloads requires a NIC that can split an incoming 99packet into multiple buffers. 100It also generally requires some sort of 101intelligence on the NIC to make sure that the payload starts in its own 102buffer. 103This is called 104.Dq "header splitting" . 105Currently the only NICs with 106support for header splitting are Alteon Tigon 2 based boards running 107slightly modified firmware. 108The 109.Fx 110.Xr ti 4 111driver includes modified firmware for Tigon 2 boards only. 112Header 113splitting code can be written, however, for any NIC that allows putting 114received packets into multiple buffers and that has enough programmability 115to determine that the header should go into one buffer and the payload into 116another. 117.Pp 118You can also do a form of header splitting that does not require any NIC 119modifications if your NIC is at least capable of splitting packets into 120multiple buffers. 121This requires that you optimize the NIC driver for your 122most common packet header size. 123If that size (ethernet + IP + TCP headers) 124is generally 66 bytes, for instance, you would set the first buffer in a 125set for a particular packet to be 66 bytes long, and then subsequent 126buffers would be a page in size. 127For packets that have headers that are 128exactly 66 bytes long, your payload will be page aligned. 129.Pp 130The other requirement for zero copy receive to work is that the buffer that 131is the destination for the data read from a socket must be at least a page 132in size and page aligned. 133.Pp 134Obviously the requirements for receive side zero copy are impossible to 135meet without NIC hardware that is programmable enough to do header 136splitting of some sort. 137Since most NICs are not that programmable, or their 138manufacturers will not share the source code to their firmware, this approach 139to zero copy receive is not widely useful. 140.Pp 141There are other approaches, such as RDMA and TCP Offload, that may 142potentially help alleviate the CPU overhead associated with copying data 143out of the kernel. 144Most known techniques require some sort of support at 145the NIC level to work, and describing such techniques is beyond the scope 146of this manual page. 147.Pp 148The zero copy send and zero copy receive code can be individually turned 149off via the 150.Va kern.ipc.zero_copy.send 151and 152.Va kern.ipc.zero_copy.receive 153.Nm sysctl 154variables respectively. 155.Sh SEE ALSO 156.Xr sendfile 2 , 157.Xr socket 2 , 158.Xr ti 4 159.Sh HISTORY 160The zero copy sockets code first appeared in 161.Fx 5.0 , 162although it has 163been in existence in patch form since at least mid-1999. 164.Sh AUTHORS 165.An -nosplit 166The zero copy sockets code was originally written by 167.An Andrew Gallatin Aq gallatin@FreeBSD.org 168and substantially modified and updated by 169.An Kenneth Merry Aq ken@FreeBSD.org . 170.Sh BUGS 171The COW based send mechanism is not safe and may result in kernel crashes. 172