PERFORCE change 113752 for review

Wed Jan 31 10:49:57 UTC 2007

http://perforce.freebsd.org/chv.cgi?CH=113752

Change 113752 by rwatson at rwatson_cinnamon on 2007/01/31 10:49:47

	Rudimentary documentation of current zero-copy BPF API.  This will
	change.

Affected files ...

.. //depot/projects/zcopybpf/src/share/man/man4/bpf.4#2 edit

Differences ...

==== //depot/projects/zcopybpf/src/share/man/man4/bpf.4#2 (text+ko) ====

@@ -1,3 +1,30 @@
+.\" Copyright (c) 2007 Seccuris Inc.
+.\" All rights reserved.
+.\"
+.\" This sofware was developed by Robert N. M. Watson under contract to
+.\" Seccuris Inc.
+.\"
+.\" 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.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" 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.
+.\" 
 .\" Copyright (c) 1990 The Regents of the University of California.
 .\" All rights reserved.
 .\"
@@ -61,18 +88,53 @@
 all file descriptors listening on that interface apply their filter.
 Each descriptor that accepts the packet receives its own copy.
 .Pp
-Reads from these files return the next group of packets
-that have matched the filter.
-To improve performance, the buffer passed to read must be
-the same size as the buffers used internally by
-.Nm .
+.Nm
+devices operate in one of two buffering modes: buffered
+.Xr read 2 ,
+in which packet data is copied from the kernel explicitly using the
+.Xr read 2
+system call, and zero-copy buffer mode, in which the user process provides
+two memory regions that
+.Nm
+will write to directly as the packets are accepted.
+The buffering mode may be set with the
+.Dv BIOCSETBUFMODE
+ioctl (see below), and will default to buffered
+.Xr read 2
+mode
+.Dv ( BPF_BUFMODE_BUFFER )
+by default.
+Buffers return the next group of packets that have matched the filter.
+Note that an individual packet larger than the buffer size is necessarily
+truncated.
+.Pp
+In the case of buffered
+.Xr read 2 ,
+the user process will declare a fixed buffer size that will be used both for
+sizing internal buffers and for all
+.Xr read 2
+operations on the file.
 This size is returned by the
 .Dv BIOCGBLEN
 ioctl (see below), and
 can be set with
 .Dv BIOCSBLEN .
-Note that an individual packet larger than this size is necessarily
-truncated.
+.Pp
+In zero-copy buffering, the user process registers two memory buffers with
+.Nm
+via the
+.Dv BIOCSETZBUF
+ioctl (see below).
+The user process may monitor for completion (filling) of a buffer, at which
+point the memory contents of the buffer will be stable until the buffer is
+returned for further kernel use using the
+.Dv BIOCACKZBUF
+ioctl.
+Buffers will be of a fixed (and equal) size, be
+page-aligned, and the size must be an integer multiple of the page size.
+The maximum zero-copy buffer size is returned by the
+.Dv BIOCGETZMAX
+ioctl (see below).
 .Pp
 The packet filter will support any link level protocol that has fixed length
 headers.
@@ -127,7 +189,7 @@
 The (third) argument to
 .Xr ioctl 2
 should be a pointer to the type indicated.
-.Bl -tag -width BIOCGRTIMEOUT
+.Bl -tag -width BIOCGETBUFMODE
 .It Dv BIOCGBLEN
 .Pq Li u_int
 Returns the required buffer length for reads on
@@ -318,6 +380,70 @@
 This prevents the execution of
 ioctl commands which could change the underlying operating parameters of
 the device.
+.It Dv BIOCGETBUFMODE
+.It Dv BIOCSETBUFMODE
+.Pq Li u_int
+Get or set the current
+.Nm
+buffering mode; possible values are
+.Dv BPF_BUFMODE_BUFFER ,
+buffered
+.Xr read 2
+mode, and
+.Dv BPF_BUFMODE_ZBUF ,
+zero-copy buffer mode.
+.It Dv BIOCACKZBUF
+.Pq Li struct bpf_zbuf
+Return a completed zero-copy buffer to the kernel for reuse.
+The following structure is used as an argument to these and other zero-copy
+buffer ioctls:
+.Bd -literal
+struct bpf_zbuf {
+	void *bz_bufa;
+	void *bz_bufb;
+	size_t bz_buflen;
+};
+.Ed
+.Pp
+Only the
+.Vt bz_bufa
+field will be used with this ioctl.
+.It Dv BIOCGETZBUF
+.It Dv BIOCSETZBUF
+.Pq Li struct bpf_zbuf
+Get or set the current zero-copy buffer locations; buffer locations may be
+set only once zero-copy buffer mode has been selected, and prior to attaching
+the
+.Nm
+device to an interface.
+Buffers must be of identical size, page-aligned, and an integer multiple of
+pages in size.
+The three fields
+.Vt bz_bufa ,
+.Vt bz_bufb ,
+and
+.Vt bz_buflen
+must be filled out.
+.It Dv BIOCGETZMAX
+.Pq Li u_int
+Get the largest individual zero-copy buffer size allowed.
+As two buffers are used in zero-copy buffer mode, the limit (in practice) is
+twice this size.
+As zero-copy buffers consume kernel address space, conservative selection of
+buffer size, especially when there are multiple
+.Nm
+descriptors in use on 32-bit systems.
+.It Dv BIOCGETZNEXT
+.Pq Li struct bpf_zbuf
+Get the buffer pointer of the next completed zero-copy buffer and length of
+pending data, or
+.Dv NULL
+if there is no pending completed buffer.
+Only the
+.Vt bz_bufa
+and
+.Vt bz_buflen
+fields will be used with this ioctl.
 .El
 .Sh BPF HEADER
 The following structure is prepended to each packet returned by
