From owner-p4-projects@FreeBSD.ORG Tue Dec 25 00:16:04 2007 Return-Path: Delivered-To: p4-projects@freebsd.org Received: by hub.freebsd.org (Postfix, from userid 32767) id 64E1416A41B; Tue, 25 Dec 2007 00:16:04 +0000 (UTC) Delivered-To: perforce@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 0410316A417 for ; Tue, 25 Dec 2007 00:16:04 +0000 (UTC) (envelope-from bb+lists.freebsd.perforce@cyrus.watson.org) Received: from repoman.freebsd.org (repoman.freebsd.org [IPv6:2001:4f8:fff6::29]) by mx1.freebsd.org (Postfix) with ESMTP id E863C13C44B for ; Tue, 25 Dec 2007 00:16:03 +0000 (UTC) (envelope-from bb+lists.freebsd.perforce@cyrus.watson.org) Received: from repoman.freebsd.org (localhost [127.0.0.1]) by repoman.freebsd.org (8.14.1/8.14.1) with ESMTP id lBP0G3Tx057224 for ; Tue, 25 Dec 2007 00:16:03 GMT (envelope-from bb+lists.freebsd.perforce@cyrus.watson.org) Received: (from perforce@localhost) by repoman.freebsd.org (8.14.1/8.14.1/Submit) id lBP0G3TE057221 for perforce@freebsd.org; Tue, 25 Dec 2007 00:16:03 GMT (envelope-from bb+lists.freebsd.perforce@cyrus.watson.org) Date: Tue, 25 Dec 2007 00:16:03 GMT Message-Id: <200712250016.lBP0G3TE057221@repoman.freebsd.org> X-Authentication-Warning: repoman.freebsd.org: perforce set sender to bb+lists.freebsd.perforce@cyrus.watson.org using -f From: Robert Watson To: Perforce Change Reviews Cc: Subject: PERFORCE change 131563 for review X-BeenThere: p4-projects@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: p4 projects tree changes List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 25 Dec 2007 00:16:04 -0000 http://perforce.freebsd.org/chv.cgi?CH=131563 Change 131563 by rwatson@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