PERFORCE change 137243 for review

[Robert Watson]

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

Change 137243 by rwatson at rwatson_cinnamon on 2008/03/09 18:46:30

	Minor wording tweaks.

Affected files ...

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

Differences ...

==== //depot/projects/zcopybpf/src/share/man/man4/bpf.4#9 (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 user memory buffers by
-the kernel, avoiding both system call and copying overhead.
+mode, in which packet data is written directly into two 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
@@ -170,8 +170,7 @@
 .Vt bz_bufb
 is a pointer to the second buffer.
 .Nm
-will then cycle between the two buffers starting with
-.Vt bz_bufa.
+will then cycle between the two buffers as they fill and are acknowledged.
 .Pp
 Each buffer begins with a fixed-length header to hold synchronization and
 data length information for the buffer:
@@ -185,7 +184,8 @@
 .Ed
 .Pp
 The header structure of each buffer, including all padding, should be zeroed
-before it is passed to the ioctl.
+before it is configured using
+.Dv BIOCSETZBUF .
 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
@@ -247,8 +247,8 @@
 ioctl.
 This allows the user process to retrieve data in a partially filled buffer
 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.
+recheck for buffer ownership using the header generation numbers, as the
+buffer will not be assigned to userspace if no data was present.
 .Pp
 As in the buffered read mode,
 .Xr kqueue 2 ,
@@ -264,7 +264,9 @@
 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.
+versions; in particular, they must maintain their own notion of which buffer
+is "next" so that if both buffers are owned by userspace, it can process them
+in the correct order.
 .Sh IOCTLS
 The
 .Xr ioctl 2