At long last, commit the zero copy sockets code.

MAKEDEV:	Add MAKEDEV glue for the ti(4) device nodes.

ti.4:		Update the ti(4) man page to include information on the
		TI_JUMBO_HDRSPLIT and TI_PRIVATE_JUMBOS kernel options,
		and also include information about the new character
		device interface and the associated ioctls.

man9/Makefile:	Add jumbo.9 and zero_copy.9 man pages and associated
		links.

jumbo.9:	New man page describing the jumbo buffer allocator
		interface and operation.

zero_copy.9:	New man page describing the general characteristics of
		the zero copy send and receive code, and what an
		application author should do to take advantage of the
		zero copy functionality.

NOTES:		Add entries for ZERO_COPY_SOCKETS, TI_PRIVATE_JUMBOS,
		TI_JUMBO_HDRSPLIT, MSIZE, and MCLSHIFT.

conf/files:	Add uipc_jumbo.c and uipc_cow.c.

conf/options:	Add the 5 options mentioned above.

kern_subr.c:	Receive side zero copy implementation.  This takes
		"disposable" pages attached to an mbuf, gives them to
		a user process, and then recycles the user's page.
		This is only active when ZERO_COPY_SOCKETS is turned on
		and the kern.ipc.zero_copy.receive sysctl variable is
		set to 1.

uipc_cow.c:	Send side zero copy functions.  Takes a page written
		by the user and maps it copy on write and assigns it
		kernel virtual address space.  Removes copy on write
		mapping once the buffer has been freed by the network
		stack.

uipc_jumbo.c:	Jumbo disposable page allocator code.  This allocates
		(optionally) disposable pages for network drivers that
		want to give the user the option of doing zero copy
		receive.

uipc_socket.c:	Add kern.ipc.zero_copy.{send,receive} sysctls that are
		enabled if ZERO_COPY_SOCKETS is turned on.

		Add zero copy send support to sosend() -- pages get
		mapped into the kernel instead of getting copied if
		they meet size and alignment restrictions.

uipc_syscalls.c:Un-staticize some of the sf* functions so that they
		can be used elsewhere.  (uipc_cow.c)

if_media.c:	In the SIOCGIFMEDIA ioctl in ifmedia_ioctl(), avoid
		calling malloc() with M_WAITOK.  Return an error if
		the M_NOWAIT malloc fails.

		The ti(4) driver and the wi(4) driver, at least, call
		this with a mutex held.  This causes witness warnings
		for 'ifconfig -a' with a wi(4) or ti(4) board in the
		system.  (I've only verified for ti(4)).

ip_output.c:	Fragment large datagrams so that each segment contains
		a multiple of PAGE_SIZE amount of data plus headers.
		This allows the receiver to potentially do page
		flipping on receives.

if_ti.c:	Add zero copy receive support to the ti(4) driver.  If
		TI_PRIVATE_JUMBOS is not defined, it now uses the
		jumbo(9) buffer allocator for jumbo receive buffers.

		Add a new character device interface for the ti(4)
		driver for the new debugging interface.  This allows
		(a patched version of) gdb to talk to the Tigon board
		and debug the firmware.  There are also a few additional
		debugging ioctls available through this interface.

		Add header splitting support to the ti(4) driver.

		Tweak some of the default interrupt coalescing
		parameters to more useful defaults.

		Add hooks for supporting transmit flow control, but
		leave it turned off with a comment describing why it
		is turned off.

if_tireg.h:	Change the firmware rev to 12.4.11, since we're really
		at 12.4.11 plus fixes from 12.4.13.

		Add defines needed for debugging.

		Remove the ti_stats structure, it is now defined in
		sys/tiio.h.

ti_fw.h:	12.4.11 firmware.

ti_fw2.h:	12.4.11 firmware, plus selected fixes from 12.4.13,
		and my header splitting patches.  Revision 12.4.13
		doesn't handle 10/100 negotiation properly.  (This
		firmware is the same as what was in the tree previously,
		with the addition of header splitting support.)

sys/jumbo.h:	Jumbo buffer allocator interface.

sys/mbuf.h:	Add a new external mbuf type, EXT_DISPOSABLE, to
		indicate that the payload buffer can be thrown away /
		flipped to a userland process.

socketvar.h:	Add prototype for socow_setup.

tiio.h:		ioctl interface to the character portion of the ti(4)
		driver, plus associated structure/type definitions.

uio.h:		Change prototype for uiomoveco() so that we'll know
		whether the source page is disposable.

ufs_readwrite.c:Update for new prototype of uiomoveco().

vm_fault.c:	In vm_fault(), check to see whether we need to do a page
		based copy on write fault.

vm_object.c:	Add a new function, vm_object_allocate_wait().  This
		does the same thing that vm_object allocate does, except
		that it gives the caller the opportunity to specify whether
		it should wait on the uma_zalloc() of the object structre.

		This allows vm objects to be allocated while holding a
		mutex.  (Without generating WITNESS warnings.)

		vm_object_allocate() is implemented as a call to
		vm_object_allocate_wait() with the malloc flag set to
		M_WAITOK.

vm_object.h:	Add prototype for vm_object_allocate_wait().

vm_page.c:	Add page-based copy on write setup, clear and fault
		routines.

vm_page.h:	Add page based COW function prototypes and variable in
		the vm_page structure.

Many thanks to Drew Gallatin, who wrote the zero copy send and receive
code, and to all the other folks who have tested and reviewed this code
over the years.

3 files changed, 301 insertions, 1 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 2a6247cfb19e..d121f2fbef26 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -45,6 +45,7 @@ MAN=	BUF_LOCK.9 BUF_LOCKFREE.9 BUF_LOCKINIT.9 BUF_REFCNT.9 \
 	getnewvnode.9 \
 	groupmember.9 \
 	ifnet.9 inittodr.9 intro.9 ithread.9 \
+	jumbo.9 \
 	kernacc.9 kobj.9 kthread.9 ktr.9 \
 	lock.9 \
 	make_dev.9 malloc.9 mbchain.9 mbuf.9 mdchain.9 \
@@ -77,7 +78,7 @@ MAN=	BUF_LOCK.9 BUF_LOCKFREE.9 BUF_LOCKINIT.9 BUF_REFCNT.9 \
 	vm_page_wire.9 vm_page_zero_fill.9 vm_set_page_size.9 \
 	vn_isdisk.9 vnode.9 vput.9 vref.9 vrele.9 \
 	vslock.9 \
-	zone.9
+	zero_copy.9 zone.9
 
 MLINKS+=DRIVER_MODULE.9 MULTI_DRIVER_MODULE.9
 MLINKS+=MD5.9 MD5Init.9 MD5.9 MD5Transform.9
@@ -148,6 +149,9 @@ MLINKS+=ifnet.9 if_data.9 ifnet.9 ifaddr.9 ifnet.9 ifqueue.9
 MLINKS+=ithread.9 ithread_add_handler.9 ithread.9 ithread_create.9
 MLINKS+=ithread.9 ithread_destroy.9 ithread.9 ithread_priority.9
 MLINKS+=ithread.9 ithread_remove_handler.9 ithread.9 ithread_schedule.9
+MLINKS+=jumbo.9 jumbo_vm_init.9 jumbo.9 jumbo_pg_alloc.9
+MLINKS+=jumbo.9 jumbo_pg_free.9 jumbo.9 jumbo_freem.9
+MLINKS+=jumbo.9 jumbo_pg_steal.9 jumbo.9 jumbo_phys_to_kva.9
 MLINKS+=kernacc.9 useracc.9
 MLINKS+=kthread.9 kproc_start.9 kthread.9 kproc_shutdown.9
 MLINKS+=kthread.9 kthread_create.9 kthread.9 kthread_exit.9
@@ -250,6 +254,7 @@ MLINKS+=vm_page_wakeup.9 vm_page_flash.9
 MLINKS+=vm_page_wire.9 vm_page_unwire.9
 MLINKS+=vref.9 VREF.9
 MLINKS+=vslock.9 vsunlock.9
+MLINKS+=zero_copy.9 zero_copy_sockets.9
 
 MLINKS+=device_add_child.9 device_add_child_ordered.9
 MLINKS+=device_enable.9 device_disable.9
diff --git a/share/man/man9/jumbo.9 b/share/man/man9/jumbo.9
new file mode 100644
index 000000000000..ff7bf9f959e6
--- /dev/null
+++ b/share/man/man9/jumbo.9
@@ -0,0 +1,153 @@
+.\"
+.\" Copyright (c) 2002 Kenneth D. Merry.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions, and the following disclaimer,
+.\"    without modification, immediately at the beginning of the file.
+.\" 2. The name of the author may not be used to endorse or promote products
+.\"    derived from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR
+.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd June 23, 2002
+.Dt JUMBO 9
+.Os
+.Sh NAME
+.Nm jumbo ,
+.Nm jumbo_vm_init ,
+.Nm jumbo_pg_alloc ,
+.Nm jumbo_pg_free ,
+.Nm jumbo_freem ,
+.Nm jumbo_pg_steal ,
+.Nm jumbo_phys_to_kva
+.Nd kernel interface for allocating and freeing page-sized disposable buffers
+.Sh SYNOPSIS
+.In sys/jumbo.h
+.Ft int
+.Fo jumbo_vm_init
+.Fa "void"
+.Fc
+.Ft vm_page_t
+.Fo jumbo_pg_alloc
+.Fa "void"
+.Fc
+.Ft void
+.Fo jumbo_pg_free
+.Fa "vm_offset_t addr"
+.Fc
+.Ft void
+.Fo jumbo_freem
+.Fa "caddr_t addr"
+.Fa "void *args"
+.Fc
+.Ft void
+.Fo jumbo_pg_steal
+.Fa "vm_page_t pg"
+.Fc
+.Ft caddr_t
+.Fo jumbo_phys_to_kva
+.Fa "vm_offset_t pa"
+.Fc
+.Sh DESCRIPTION
+The
+.Nm
+buffer facility is designed for allocating disposable page-sized
+buffers.  Buffers allocated via this facility can either be returned or
+not.  This facility is primarily intended for use with network adapters
+that have MTUs of a page or greater size.  The buffers will normally be
+disposed of by the
+.Xr zero_copy 9
+receive code.
+.Pp
+.Fn jumbo_vm_init
+initializes the pool of KVA the
+.Nm
+code needs to operate and does some
+other initialization to prepare the subsystem for operation.  This routine
+only needs to be called once.  Calling it multiple times will have no
+effect.  It is recommended that this initialization routine be called in a
+device driver attach routine, so that resources are not allocated if the
+.Nm
+subsystem won't end up being used.
+.Fn jumbo_vm_init
+returns 1 upon successful completion, and 0 upon failure.
+.Pp
+.Fn jumbo_pg_alloc
+allocates a physical page and assigns a piece of KVA from the
+.Nm
+KVA pool.  It returns the allocated page if successful, and NULL in the case of
+failure.
+.Pp
+.Fn jumbo_pg_free
+frees a page allocated by
+.Fn jumbo_pg_alloc .
+It takes the address of the memory in question as an argument.  This
+routine will normally be used in cases where the allocated
+.Nm jumbo
+page cannot be used for some reason.  The normal free path is via
+.Fn jumbo_freem .
+.Pp
+.Fn jumbo_freem
+is the routine that should be given as the external free routine when an
+external mbuf is allocated using pages from the 
+.Nm
+allocator.  It takes the virtual address of the page in question, and
+ignores the second argument.
+.Pp
+.Fn jumbo_pg_steal
+"steals" a page and recycles its KVA space.
+.Pp
+.Fn jumbo_phys_to_kva
+translates the physical address of a
+.Nm
+allocated page to the proper kernel virtual address.
+.Sh SEE ALSO
+.Xr ti 4 ,
+.Xr zero_copy 9
+.Sh HISTORY
+The
+.Nm
+allocator is primarily based on a page allocator system originally written
+by
+.An Andrew Gallatin Aq gallatin@FreeBSD.org
+as part of a set of zero copy patches for the
+.Xr ti 4
+driver.  The allocator was taken out of the
+.Xr ti 4
+driver, cleaned up and ported to the new mutex interface by
+.An Kenneth Merry Aq ken@FreeBSD.org .
+.Pp
+The
+.Nm
+allocator first appeared in
+.Fx 5.0 ,
+and has existed in patch form since at least 1999.
+.Sh AUTHORS
+.An Andrew Gallatin Aq gallatin@FreeBSD.org
+and
+.An Kenneth Merry Aq ken@FreeBSD.org .
+.Sh BUGS
+There is currently a static number of KVA pages allocated by the
+.Nm
+allocator, with no real provision for increasing the number of pages
+allocated should demand exceed supply.
+.Pp
+The
+.Fn jumbo_pg_steal
+function isn't currently used anywhere.
diff --git a/share/man/man9/zero_copy.9 b/share/man/man9/zero_copy.9
new file mode 100644
index 000000000000..8c2f6e85184b
--- /dev/null
+++ b/share/man/man9/zero_copy.9
@@ -0,0 +1,142 @@
+.\"
+.\" Copyright (c) 2002 Kenneth D. Merry.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions, and the following disclaimer,
+.\"    without modification, immediately at the beginning of the file.
+.\" 2. The name of the author may not be used to endorse or promote products
+.\"    derived from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR
+.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd June 23, 2002
+.Dt ZERO_COPY 9
+.Os
+.Sh NAME
+.Nm zero_copy ,
+.Nm zero_copy_sockets
+.Sh SYNOPSIS
+.Cd options ZERO_COPY_SOCKETS
+.Sh DESCRIPTION
+The FreeBSD kernel includes a facility for eliminating data copies on
+socket reads and writes.
+.Pp
+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).
+.Pp
+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.
+.Pp
+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 doesn't meet the page size and alignment constraints, it
+will be copied into the kernel, as is normally the case with socket I/O.
+.Pp
+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.
+.Pp
+The
+.Xr socket 2
+API doesn't 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.
+.Pp
+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
+.Xr setsockopt 2
+man 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.  
+.Pp
+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 alpha this would be 8KB, 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.
+.Pp
+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
+.Xr 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 programability
+to determine that the header should go into one buffer and the payload into
+another.
+.Pp
+You can also do a form of header splitting that doesn't 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.
+.Pp
+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.
+.Pp
+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 aren't that programmable, or their
+manufacturers won't share the source code to their firmware, this approach
+to zero copy receive isn't widely useful.
+.Pp
+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.
+.Pp
+The zero copy send and zero copy receive code can be individually turned
+off via the
+.Va kern.ipc.zero_copy.send
+and
+.Va kern.ipc.zero_copy.receive
+.Nm sysctl
+variables respectively.
+.Sh SEE ALSO
+.Xr socket 2 ,
+.Xr sendfile 2 ,
+.Xr ti 4,
+.Xr jumbo 9
+.Sh 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.
+.Sh AUTHORS
+The zero copy sockets code was originally written by
+.An Andrew Gallatin Aq gallatin@FreeBSD.org
+and substantially modified and updated by 
+.An Kenneth Merry Aq ken@FreeBSD.org .