PERFORCE change 114172 for review

[Robert Watson]

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

Change 114172 by rwatson at rwatson_cinnamon on 2007/02/07 11:48:03

	Update bpf(4) man page for BIOCROTZBUF ioctl, and improve the
	documentation about buffers a bit.  The man page is not yet updated
	for the shared memory header and ACK model.

Affected files ...

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

Differences ...

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

@@ -425,20 +425,37 @@
 .Vt bz_buflen
 must be filled out.
 .It Dv BIOCGETZMAX
-.Pq Li u_int
+.Pq Li size_t
 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.
+twice the returned 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
+.It Dv BIOCROTZBUF
 .Pq Li struct bpf_zbuf
-Get the buffer pointer of the next completed zero-copy buffer and length of
-pending data, or
+Get the buffer pointer and length of the next zero-copy buffer buffer ready
+for userspace use, or
+.Dv NULL
+if there is no pending buffer.
+.Pp
+.Dv BIOCGETZNEXT
+queries for the next completely filled buffer ready for immediate use,
+returning NULL if there are only empty or partially filled buffers available.
+.Pp
+.Dv BIOCROTZBUF
+queries for a filled buffer, but in the event there is only a partially
+filled buffer, will make that buffer available for userspace to use
+immediately.
+This allows consumers of zero-copy buffering to implement timeouts and
+retrieve partially filled buffers.
+.Dv BIOCROTZBUF
+will return
 .Dv NULL
-if there is no pending completed buffer.
+only if no data is present in either of the zero-copy buffers.
+.Pp
 Only the
 .Vt bz_bufa
 and