Date: Mon, 24 Dec 2007 23:52:36 GMT From: Robert Watson <rwatson@FreeBSD.org> To: Perforce Change Reviews <perforce@freebsd.org> Subject: PERFORCE change 131561 for review Message-ID: <200712242352.lBONqae7052539@repoman.freebsd.org>
next in thread | raw e-mail | index | archive | help
http://perforce.freebsd.org/chv.cgi?CH=131561 Change 131561 by rwatson@rwatson_cinnamon on 2007/12/24 23:52:20 Further refine bpf.4 man page. Affected files ... .. //depot/projects/zcopybpf/src/share/man/man4/bpf.4#6 edit Differences ... ==== //depot/projects/zcopybpf/src/share/man/man4/bpf.4#6 (text+ko) ==== @@ -88,19 +88,6 @@ all file descriptors listening on that interface apply their filter. Each descriptor that accepts the packet receives its own copy. .Pp -.Nm -devices operate in one of two buffering modes: -.Xr read 2 , -and zero-copy. -In buffered read mode, packet data is copied explicitly from the kernel to -user memory buffers using the -.Xr read 2 -system call. -In zero-copy buffering mode, the kernel writes packet data directly into -shared memory buffers provided by the user application. -Note that an individual packet larger than the buffer size is necessarily -truncated. -.Pp The packet filter will support any link level protocol that has fixed length headers. Currently, only Ethernet, @@ -148,18 +135,21 @@ ioctl, and is set using the .Dv BIOCSBLEN ioctl. +Note that an individual packet larger than the buffer size is necessarily +truncated. .Ss Zero-copy buffer mode .Nm devices may also operate in the .Dv BPF_BUFMODE_ZEROCOPY -mode, in which packet data is written directly by the kernel to memory -buffers provided by the process, avoiding both both system call and memory -copying overhead. +mode, in which packet data is written directly into a pair of user memory +buffers by the kernel, avoiding both system call and copying overhead. Buffers are of fixed (and equal) size, page-aligned, and an even multiple of the page size. The maximum zero-copy buffer size is returned by the .Dv BIOCGETZMAX ioctl. +Note that an individual packet larger than the buffer size is necessarily +truncated. .Pp The user process registers two memory buffers using the .Dv BIOCSETZBUF @@ -180,42 +170,45 @@ .Vt bz_bufb is a pointer to the second buffer. .Nm -will then cycle between the two buffers. +will then cycle between the two buffers starting with +.Vt bz_bufa. .Pp -Buffer memory begins with a short, fixed-length header holding -synchronization and data length information for the buffer: +Each buffer begins with a fixed-length header to hold synchronization and +data length information for the buffer: .Bd -literal struct bpf_zbuf_header { volatile u_int bzh_kernel_gen; /* Kernel generation number. */ - volatile u_int bzh_kernel_len; /* Length of buffer. */ + volatile u_int bzh_kernel_len; /* Length of data in the buffer. */ volatile u_int bzh_user_gen; /* User generation number. */ /* ...padding for future use... */ }; .Ed .Pp -This is followed immediately by packet data, laid out as described below. +This is followed by packet data, laid out as in buffered read mode. .Pp The kernel and the user process follow a simple acknowledgement protocol using shared memory and ioctls to synchronize access to the two buffers. Ownership of the buffer is signaled using the kernel and user generation -numbers in shared memory: the kernel modifies +numbers in the shared buffer header: the kernel sets .Vt bzh_kernel_gen -to assign ownership to userspace, and the user process sets +to a different value than +.Vt bzh_user_gen +in order to assign ownership to userspace, and the user process sets .Vt bzh_user_gen to the value in .Vt bzh_kernel_gen -to acknowledge the buffer and return it to kernel ownership. -While the kernel owns the buffer, the contents are unstable and will change +to acknowledge the buffer and return it for reuse by the kernel. +While the kernel owns the buffer, the contents are unstable and may change asynchronously; while the user process owns the buffer, its contents are -considered stable and will not be changed until the buffer is acknowledged. +stable and will not be changed until after the buffer is acknowledged. The user process will initialize the .Vt struct bpf_zbuf_header to all 0's before registering the buffer, assigning initial ownership to the kernel. .Pp In order to avoid caching and memory re-ordering effects, the user process -must use appropriate atomic operations and memory barriers when checking for -and acknowledging buffers: +must use atomic operations and memory barriers when checking for and +acknowledging buffers: .Bd -literal #include <machine/atomic.h> @@ -227,7 +220,7 @@ { atomic_store_rel_int(&bzh->bzh_user_gen, bzh->bzh_kernel_gen); -}; +} /* * Check whether a buffer has been assigned to userspace by the kernel. @@ -247,18 +240,18 @@ .Dv BIOCROTZBUF ioctl. This allows the user process to retrieve data in a partially filled buffer -before the buffer is completed, such as following a timeout; the process must -still check to see if ownership has been assigned using the header generation -numbers, as the buffer will not be assigned if there is no data available. +before the buffer is full, such as following a timeout; the process must +check for buffer ownership using the header generation numbers, as the buffer +will not be assigned if no data was present. .Pp -As in the read buffering mode, +As in the buffered read mode, .Xr kqueue 2 , .Xr poll 2 , and .Xr select 2 may be used to sleep awaiting the availbility of a completed buffer. -They will return a readable file descriptor once at least one buffer is -assigned to user space. +They will return a readable file descriptor when ownership of the next buffer +is assigned to user space. .Sh IOCTLS The .Xr ioctl 2 @@ -529,9 +522,7 @@ .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. +to an interface. Buffers must be of identical size, page-aligned, and an integer multiple of pages in size. The three fields @@ -547,14 +538,13 @@ As two buffers are used in zero-copy buffer mode, the limit (in practice) is twice the returned size. As zero-copy buffers consume kernel address space, conservative selection of -buffer size, especially when there are multiple +buffer size is suggested, especially when there are multiple .Nm descriptors in use on 32-bit systems. .It Dv BIOCROTZBUF Force ownership of the next buffer to be assigned to userspace, if any data present in the buffer. If no data is present, the buffer will remain owned by the kernel. -If userspace already owns the buffer, this operation will be a no-op. This allows consumers of zero-copy buffering to implement timeouts and retrieve partially filled buffers. In order to handle the case where no data is present in the buffer and
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200712242352.lBONqae7052539>