Date: Wed, 31 Jan 2007 10:49:56 GMT From: Robert Watson <rwatson@FreeBSD.org> To: Perforce Change Reviews <perforce@freebsd.org> Subject: PERFORCE change 113752 for review Message-ID: <200701311049.l0VAnuhV015654@repoman.freebsd.org>
next in thread | raw e-mail | index | archive | help
http://perforce.freebsd.org/chv.cgi?CH=113752 Change 113752 by rwatson@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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200701311049.l0VAnuhV015654>