PERFORCE change 131563 for review

[Robert Watson]

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

Change 131563 by rwatson at rwatson_cinnamon on 2007/12/25 00:15:45

	More cleanup and clarification.

Affected files ...

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

Differences ...

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

@@ -141,8 +141,8 @@
 .Nm
 devices may also operate in the
 .Dv BPF_BUFMODE_ZEROCOPY
-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.
+mode, in which packet data is written directly into 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
@@ -184,27 +184,33 @@
 };
 .Ed
 .Pp
-This is followed by packet data, laid out as in buffered read mode.
+The header structure of each buffer, including all padding, should be zeroed
+before it is passed to the ioctl.
+Remaining space in the buffer will be used by the kernel to store packet
+data, laid out in the same format as with 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 the shared buffer header: the kernel sets
+The kernel and the user process follow a simple acknowledgement protocol via
+the buffer header to synchronize access to the buffer: when the header
+generation numbers,
 .Vt bzh_kernel_gen
-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 for reuse by the kernel.
+and
+.Vt bzh_user_gen ,
+hold the same value, the kernel owns the buffer, and when they differ,
+userspace owns the buffer.
+.Pp
 While the kernel owns the buffer, the contents are unstable and may change
 asynchronously; while the user process owns the buffer, its contents are
-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.
+stable and will not be changed until the buffer has been acknowledged.
+.Pp
+Initializing the buffer headers to all 0's before registering the buffer has
+the effect of assigning initial ownership of both buffers to the kernel.
+The kernel signals that a buffer has been assigned to userspace by modifying
+.Vt bzh_kernel_gen ,
+and userspace acknowledges the buffer and returns it to the kernel by setting
+the value of
+.Vt bzh_user_gen
+to the value of
+.Vt bzh_kernel_gen .
 .Pp
 In order to avoid caching and memory re-ordering effects, the user process
 must use atomic operations and memory barriers when checking for and
@@ -252,6 +258,13 @@
 may be used to sleep awaiting the availbility of a completed buffer.
 They will return a readable file descriptor when ownership of the next buffer
 is assigned to user space.
+.Pp
+In the current implementation, the kernel will assign ownership of at most
+one buffer at a time to the user process.
+The user processes must acknowledge the current buffer in order to be
+notified that the next buffer is ready for processing.
+Programs should not rely on this as an invariant, as it may change in future
+versions.
 .Sh IOCTLS
 The
 .Xr ioctl 2