share/man/man4/netmap.4

   1 .\" Copyright (c) 2011 Matteo Landi, Luigi Rizzo, Universita` di Pisa
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" This document is derived in part from the enet man page (enet.4)
  26 .\" distributed with 4.3BSD Unix.
  27 .\"
  28 .\" $FreeBSD$
  29 .\" $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 $
  30 .\"
  31 .Dd September 23, 2013
  32 .Dt NETMAP 4
  33 .Os
  34 .Sh NAME
  35 .Nm netmap
  36 .Nd a framework for fast packet I/O
  37 .Sh SYNOPSIS
  38 .Cd device netmap
  39 .Sh DESCRIPTION
  40 .Nm
  41 is a framework for fast and safe access to network devices
  42 (reaching 14.88 Mpps at less than 1 GHz).
  43 .Nm
  44 uses memory mapped buffers and metadata
  45 (buffer indexes and lengths) to communicate with the kernel,
  46 which is in charge of validating information through
  47 .Pa ioctl()
  48 and
  49 .Pa select()/poll().
  50 .Nm
  51 can exploit the parallelism in multiqueue devices and
  52 multicore systems.
  53 .Pp
  54 .Nm
  55 requires explicit support in device drivers.
  56 For a list of supported devices, see the end of this manual page.
  57 .Sh OPERATION
  58 .Nm
  59 clients must first open the
  60 .Pa open("/dev/netmap") ,
  61 and then issue an
  62 .Pa ioctl(...,NIOCREGIF,...)
  63 to bind the file descriptor to a network device.
  64 .Pp
  65 When a device is put in
  66 .Nm
  67 mode, its data path is disconnected from the host stack.
  68 The processes owning the file descriptor
  69 can exchange packets with the device, or with the host stack,
  70 through an mmapped memory region that contains pre-allocated
  71 buffers and metadata.
  72 .Pp
  73 Non blocking I/O is done with special
  74 .Pa ioctl()'s ,
  75 whereas the file descriptor can be passed to
  76 .Pa select()/poll()
  77 to be notified about incoming packet or available transmit buffers.
  78 .Ss Data structures
  79 All data structures for all devices in
  80 .Nm
  81 mode are in a memory
  82 region shared by the kernel and all processes
  83 who open
  84 .Pa /dev/netmap
  85 (NOTE: visibility may be restricted in future implementations).
  86 All references between the shared data structure
  87 are relative (offsets or indexes). Some macros help converting
  88 them into actual pointers.
  89 .Pp
  90 The data structures in shared memory are the following:
  91 .Bl -tag -width XXX
  92 .It Dv struct netmap_if (one per interface)
  93 indicates the number of rings supported by an interface, their
  94 sizes, and the offsets of the
  95 .Pa netmap_rings
  96 associated to the interface.
  97 The offset of a
  98 .Pa struct netmap_if
  99 in the shared memory region is indicated by the
 100 .Pa nr_offset
 101 field in the structure returned by the
 102 .Pa NIOCREGIF
 103 (see below).
 104 .Bd -literal
 105 struct netmap_if {
 106     char ni_name[IFNAMSIZ]; /* name of the interface. */
 107     const u_int ni_num_queues; /* number of hw ring pairs */
 108     const ssize_t   ring_ofs[]; /* offset of tx and rx rings */
 109 };
 110 .Ed
 111 .It Dv struct netmap_ring (one per ring)
 112 contains the index of the current read or write slot (cur),
 113 the number of slots available for reception or transmission (avail),
 114 and an array of
 115 .Pa slots
 116 describing the buffers.
 117 There is one ring pair for each of the N hardware ring pairs
 118 supported by the card (numbered 0..N-1), plus
 119 one ring pair (numbered N) for packets from/to the host stack.
 120 .Bd -literal
 121 struct netmap_ring {
 122     const ssize_t buf_ofs;
 123     const uint32_t num_slots; /* number of slots in the ring. */
 124     uint32_t avail;           /* number of usable slots */
 125     uint32_t cur;             /* 'current' index for the user side */
 126     uint32_t reserved;        /* not refilled before current */
 127
 128     const uint16_t nr_buf_size;
 129     uint16_t flags;
 130     struct netmap_slot slot[0]; /* array of slots. */
 131 }
 132 .Ed
 133 .It Dv struct netmap_slot (one per packet)
 134 contains the metadata for a packet: a buffer index (buf_idx),
 135 a buffer length (len), and some flags.
 136 .Bd -literal
 137 struct netmap_slot {
 138     uint32_t buf_idx; /* buffer index */
 139     uint16_t len;   /* packet length */
 140     uint16_t flags; /* buf changed, etc. */
 141 #define NS_BUF_CHANGED  0x0001  /* must resync, buffer changed */
 142 #define NS_REPORT       0x0002  /* tell hw to report results
 143                                  * e.g. by generating an interrupt
 144                                  */
 145 };
 146 .Ed
 147 .It Dv packet buffers
 148 are fixed size (approximately 2k) buffers allocated by the kernel
 149 that contain packet data. Buffers addresses are computed through
 150 macros.
 151 .El
 152 .Pp
 153 Some macros support the access to objects in the shared memory
 154 region. In particular:
 155 .Bd -literal
 156 struct netmap_if *nifp;
 157 struct netmap_ring *txring = NETMAP_TXRING(nifp, i);
 158 struct netmap_ring *rxring = NETMAP_RXRING(nifp, i);
 159 int i = txring->slot[txring->cur].buf_idx;
 160 char *buf = NETMAP_BUF(txring, i);
 161 .Ed
 162 .Sh IOCTLS
 163 .Nm
 164 supports some ioctl() to synchronize the state of the rings
 165 between the kernel and the user processes, plus some
 166 to query and configure the interface.
 167 The former do not require any argument, whereas the latter
 168 use a
 169 .Pa struct netmap_req
 170 defined as follows:
 171 .Bd -literal
 172 struct nmreq {
 173         char      nr_name[IFNAMSIZ];
 174         uint32_t  nr_version;     /* API version */
 175 #define NETMAP_API      3         /* current version */
 176         uint32_t  nr_offset;      /* nifp offset in the shared region */
 177         uint32_t  nr_memsize;     /* size of the shared region */
 178         uint32_t  nr_tx_slots;    /* slots in tx rings */
 179         uint32_t  nr_rx_slots;    /* slots in rx rings */
 180         uint16_t  nr_tx_rings;    /* number of tx rings */
 181         uint16_t  nr_rx_rings;    /* number of tx rings */
 182         uint16_t  nr_ringid;      /* ring(s) we care about */
 183 #define NETMAP_HW_RING  0x4000    /* low bits indicate one hw ring */
 184 #define NETMAP_SW_RING  0x2000    /* we process the sw ring */
 185 #define NETMAP_NO_TX_POLL 0x1000  /* no gratuitous txsync on poll */
 186 #define NETMAP_RING_MASK 0xfff    /* the actual ring number */
 187         uint16_t        spare1;
 188         uint32_t        spare2[4];
 189 };
 190
 191 .Ed
 192 A device descriptor obtained through
 193 .Pa /dev/netmap
 194 also supports the ioctl supported by network devices.
 195 .Pp
 196 The netmap-specific
 197 .Xr ioctl 2
 198 command codes below are defined in
 199 .In net/netmap.h
 200 and are:
 201 .Bl -tag -width XXXX
 202 .It Dv NIOCGINFO
 203 returns information about the interface named in nr_name.
 204 On return, nr_memsize indicates the size of the shared netmap
 205 memory region (this is device-independent),
 206 nr_tx_slots and nr_rx_slots indicates how many buffers are in a
 207 transmit and receive ring,
 208 nr_tx_rings and nr_rx_rings indicates the number of transmit
 209 and receive rings supported by the hardware.
 210 .Pp
 211 If the device does not support netmap, the ioctl returns EINVAL.
 212 .It Dv NIOCREGIF
 213 puts the interface named in nr_name into netmap mode, disconnecting
 214 it from the host stack, and/or defines which rings are controlled
 215 through this file descriptor.
 216 On return, it gives the same info as NIOCGINFO, and nr_ringid
 217 indicates the identity of the rings controlled through the file
 218 descriptor.
 219 .Pp
 220 Possible values for nr_ringid are
 221 .Bl -tag -width XXXXX
 222 .It 0
 223 default, all hardware rings
 224 .It NETMAP_SW_RING
 225 the ``host rings'' connecting to the host stack
 226 .It NETMAP_HW_RING + i
 227 the i-th hardware ring
 228 .El
 229 By default, a
 230 .Nm poll
 231 or
 232 .Nm select
 233 call pushes out any pending packets on the transmit ring, even if
 234 no write events are specified.
 235 The feature can be disabled by or-ing
 236 .Nm NETMAP_NO_TX_SYNC
 237 to nr_ringid.
 238 But normally you should keep this feature unless you are using
 239 separate file descriptors for the send and receive rings, because
 240 otherwise packets are pushed out only if NETMAP_TXSYNC is called,
 241 or the send queue is full.
 242 .Pp
 243 .Pa NIOCREGIF
 244 can be used multiple times to change the association of a
 245 file descriptor to a ring pair, always within the same device.
 246 .It Dv NIOCUNREGIF
 247 brings an interface back to normal mode.
 248 .It Dv NIOCTXSYNC
 249 tells the hardware of new packets to transmit, and updates the
 250 number of slots available for transmission.
 251 .It Dv NIOCRXSYNC
 252 tells the hardware of consumed packets, and asks for newly available
 253 packets.
 254 .El
 255 .Sh SYSTEM CALLS
 256 .Nm
 257 uses
 258 .Nm select
 259 and
 260 .Nm poll
 261 to wake up processes when significant events occur.
 262 .Sh EXAMPLES
 263 The following code implements a traffic generator
 264 .Pp
 265 .Bd -literal -compact
 266 #include <net/netmap.h>
 267 #include <net/netmap_user.h>
 268 struct netmap_if *nifp;
 269 struct netmap_ring *ring;
 270 struct nmreq nmr;
 271
 272 fd = open("/dev/netmap", O_RDWR);
 273 bzero(&nmr, sizeof(nmr));
 274 strcpy(nmr.nr_name, "ix0");
 275 nmr.nr_version = NETMAP_API;
 276 ioctl(fd, NIOCREG, &nmr);
 277 p = mmap(0, nmr.nr_memsize, fd);
 278 nifp = NETMAP_IF(p, nmr.offset);
 279 ring = NETMAP_TXRING(nifp, 0);
 280 fds.fd = fd;
 281 fds.events = POLLOUT;
 282 for (;;) {
 283     poll(list, 1, -1);
 284     for ( ; ring->avail > 0 ; ring->avail--) {
 285         i = ring->cur;
 286         buf = NETMAP_BUF(ring, ring->slot[i].buf_index);
 287         ... prepare packet in buf ...
 288         ring->slot[i].len = ... packet length ...
 289         ring->cur = NETMAP_RING_NEXT(ring, i);
 290     }
 291 }
 292 .Ed
 293 .Sh SUPPORTED INTERFACES
 294 .Nm
 295 supports the following interfaces:
 296 .Xr em 4 ,
 297 .Xr igb 4 ,
 298 .Xr ixgbe 4 ,
 299 .Xr lem 4 ,
 300 .Xr re 4
 301 .Sh SEE ALSO
 302 .Xr vale 4
 303 .Pp
 304 http://info.iet.unipi.it/~luigi/netmap/
 305 .Pp
 306 Luigi Rizzo, Revisiting network I/O APIs: the netmap framework,
 307 Communications of the ACM, 55 (3), pp.45-51, March 2012
 308 .Pp
 309 Luigi Rizzo, netmap: a novel framework for fast packet I/O,
 310 Usenix ATC'12, June 2012, Boston
 311 .Sh AUTHORS
 312 .An -nosplit
 313 The
 314 .Nm
 315 framework has been designed and implemented at the
 316 Universita` di Pisa in 2011 by
 317 .An Luigi Rizzo ,
 318 with help from
 319 .An Matteo Landi ,
 320 .An Gaetano Catalli ,
 321 .An Giuseppe Lettieri .
 322 .Pp
 323 .Nm
 324 has been funded by the European Commission within FP7 Project CHANGE (257422).