Update netmap page, fixing the API documentation and usage example.

Add a new manpage for the vale switch

1 files changed, 38 insertions, 15 deletions

diff --git a/share/man/man4/netmap.4 b/share/man/man4/netmap.4
index 9ac9fd0..d2dd591 100644
--- a/share/man/man4/netmap.4
+++ b/share/man/man4/netmap.4
@@ -21,12 +21,12 @@
 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
-.\"
+.\" 
 .\" This document is derived in part from the enet man page (enet.4)
 .\" distributed with 4.3BSD Unix.
 .\"
 .\" $FreeBSD$
-.\" $Id: netmap.4 9662 2011-11-16 13:18:06Z luigi $: stable/8/share/man/man4/bpf.4 181694 2008-08-13 17:45:06Z ed $
+.\" $Id: netmap.4 11563 2012-08-02 08:59:12Z luigi $: stable/8/share/man/man4/bpf.4 181694 2008-08-13 17:45:06Z ed $
 .\"
 .Dd February 27, 2012
 .Dt NETMAP 4
@@ -43,14 +43,15 @@ is a framework for fast and safe access to network devices
 .Nm
 uses memory mapped buffers and metadata
 (buffer indexes and lengths) to communicate with the kernel,
-which is in charge of validating information through
+which is in charge of validating information through 
 .Pa ioctl()
 and
-.Pa select()/poll() .
+.Pa select()/poll().
 .Nm
 can exploit the parallelism in multiqueue devices and
 multicore systems.
 .Pp
+.Pp
 .Nm
 requires explicit support in device drivers.
 For a list of supported devices, see the end of this manual page.
@@ -65,7 +66,7 @@ to bind the file descriptor to a network device.
 When a device is put in
 .Nm
 mode, its data path is disconnected from the host stack.
-The processes owning the file descriptor
+The processes owning the file descriptor 
 can exchange packets with the device, or with the host stack,
 through an mmapped memory region that contains pre-allocated
 buffers and metadata.
@@ -88,6 +89,7 @@ are relative (offsets or indexes). Some macros help converting
 them into actual pointers.
 .Pp
 The data structures in shared memory are the following:
+.Pp
 .Bl -tag -width XXX
 .It Dv struct netmap_if (one per interface)
 indicates the number of rings supported by an interface, their
@@ -159,7 +161,8 @@ struct netmap_ring *rxring = NETMAP_RXRING(nifp, i);
 int i = txring->slot[txring->cur].buf_idx;
 char *buf = NETMAP_BUF(txring, i);
 .Ed
-.Ss IOCTLS
+.Sh IOCTLS
+.Pp
 .Nm
 supports some ioctl() to synchronize the state of the rings
 between the kernel and the user processes, plus some
@@ -172,7 +175,7 @@ defined as follows:
 struct nmreq {
         char      nr_name[IFNAMSIZ];
         uint32_t  nr_version;     /* API version */
-#define NETMAP_API      2         /* current version */
+#define NETMAP_API      3         /* current version */
         uint32_t  nr_offset;      /* nifp offset in the shared region */
         uint32_t  nr_memsize;     /* size of the shared region */
         uint32_t  nr_tx_slots;    /* slots in tx rings */
@@ -184,6 +187,8 @@ struct nmreq {
 #define NETMAP_SW_RING  0x2000    /* we process the sw ring */
 #define NETMAP_NO_TX_POLL 0x1000  /* no gratuitous txsync on poll */
 #define NETMAP_RING_MASK 0xfff    /* the actual ring number */
+        uint16_t        spare1;
+        uint32_t        spare2[4];
 };
 
 .Ed
@@ -250,7 +255,7 @@ number of slots available for transmission.
 tells the hardware of consumed packets, and asks for newly available
 packets.
 .El
-.Ss SYSTEM CALLS
+.Sh SYSTEM CALLS
 .Nm
 uses
 .Nm select
@@ -279,7 +284,7 @@ fds.fd = fd;
 fds.events = POLLOUT;
 for (;;) {
     poll(list, 1, -1);
-    while (ring->avail-- > 0) {
+    for ( ; ring->avail > 0 ; ring->avail--) {
         i = ring->cur;
         buf = NETMAP_BUF(ring, ring->slot[i].buf_index);
         ... prepare packet in buf ...
@@ -292,13 +297,31 @@ for (;;) {
 .Nm
 supports the following interfaces:
 .Xr em 4 ,
+.Xr igb 4 ,
 .Xr ixgbe 4 ,
-.Xr re 4 ,
+.Xr lem 4 ,
+.Xr re 4
+.Sh SEE ALSO
+.Xr vale 4
+.Pp
+http://info.iet.unipi.it/~luigi/netmap/
+.Pp
+Luigi Rizzo, Revisiting network I/O APIs: the netmap framework,
+Communications of the ACM, 55 (3), pp.45-51, March 2012
+.Pp
+Luigi Rizzo, netmap: a novel framework for fast packet I/O,
+Usenix ATC'12, June 2012, Boston
 .Sh AUTHORS
+.An -nosplit
 The
 .Nm
-framework has been designed and implemented by
-.An Luigi Rizzo
-and
-.An Matteo Landi
-in 2011 at the Universita` di Pisa.
+framework has been designed and implemented at the
+Universita` di Pisa in 2011 by
+.An Luigi Rizzo ,
+with help from
+.An Matteo Landi ,
+.An Gaetano Catalli ,
+.An Giuseppe Lettieri .
+.Pp
+.Nm
+has been funded by the European Commission within FP7 Project CHANGE (257422).