The Design and Implementation of the FreeBSD Operating System, Second Edition
Now available: The Design and Implementation of the FreeBSD Operating System (Second Edition)


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]

FreeBSD/Linux Kernel Cross Reference
sys/net/netmap.h

Version: -  FREEBSD  -  FREEBSD-13-STABLE  -  FREEBSD-13-0  -  FREEBSD-12-STABLE  -  FREEBSD-12-0  -  FREEBSD-11-STABLE  -  FREEBSD-11-0  -  FREEBSD-10-STABLE  -  FREEBSD-10-0  -  FREEBSD-9-STABLE  -  FREEBSD-9-0  -  FREEBSD-8-STABLE  -  FREEBSD-8-0  -  FREEBSD-7-STABLE  -  FREEBSD-7-0  -  FREEBSD-6-STABLE  -  FREEBSD-6-0  -  FREEBSD-5-STABLE  -  FREEBSD-5-0  -  FREEBSD-4-STABLE  -  FREEBSD-3-STABLE  -  FREEBSD22  -  l41  -  OPENBSD  -  linux-2.6  -  MK84  -  PLAN9  -  xnu-8792 
SearchContext: -  none  -  3  -  10 

    1 /*
    2  * Copyright (C) 2011 Matteo Landi, Luigi Rizzo. 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 are
    6  * met:
    7  * 
    8  *   1. Redistributions of source code must retain the above copyright
    9  *      notice, this list of conditions and the following disclaimer.
   10  * 
   11  *   2. Redistributions in binary form must reproduce the above copyright
   12  *      notice, this list of conditions and the following disclaimer in the
   13  *      documentation and/or other materials provided with the
   14  *      distribution.
   15  * 
   16  *   3. Neither the name of the authors nor the names of their contributors
   17  *      may be used to endorse or promote products derived from this
   18  *      software without specific prior written permission.
   19  * 
   20  * THIS SOFTWARE IS PROVIDED BY MATTEO LANDI AND CONTRIBUTORS "AS IS" AND
   21  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
   22  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
   23  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL MATTEO LANDI OR CONTRIBUTORS
   24  * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
   25  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
   26  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
   27  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
   28  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
   29  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
   30  * THE POSSIBILITY OF SUCH DAMAGE.
   31  */
   32 
   33 /*
   34  * $FreeBSD: releng/8.3/sys/net/netmap.h 231717 2012-02-14 22:49:34Z luigi $
   35  * $Id: netmap.h 9753 2011-11-28 15:10:43Z luigi $
   36  *
   37  * This header contains the definitions of the constants and the
   38  * structures needed by the ``netmap'' module, both kernel and
   39  * userspace.
   40  */
   41 
   42 #ifndef _NET_NETMAP_H_
   43 #define _NET_NETMAP_H_
   44 
   45 /*
   46  * --- Netmap data structures ---
   47  *
   48  * The data structures used by netmap are shown below. Those in
   49  * capital letters are in an mmapp()ed area shared with userspace,
   50  * while others are private to the kernel.
   51  * Shared structures do not contain pointers but only relative
   52  * offsets, so that addressing is portable between kernel and userspace.
   53  *
   54  * The 'softc' of each interface is extended with a struct netmap_adapter
   55  * containing information to support netmap operation. In addition to
   56  * the fixed fields, it has two pointers to reach the arrays of
   57  * 'struct netmap_kring' which in turn reaches the various
   58  * struct netmap_ring, shared with userspace.
   59 
   60 
   61  softc
   62 +----------------+
   63 | standard fields|
   64 | if_pspare[0] ----------+
   65 +----------------+       |
   66                          |
   67 +----------------+<------+
   68 |(netmap_adapter)|
   69 |                |                             netmap_kring
   70 | tx_rings *--------------------------------->+-------------+
   71 |                |       netmap_kring         | ring *---------> ...
   72 | rx_rings *---------->+--------------+       | nr_hwcur    |
   73 +----------------+     | ring    *-------+    | nr_hwavail  |
   74                        | nr_hwcur     |  |    | selinfo     |
   75                        | nr_hwavail   |  |    +-------------+
   76                        | selinfo      |  |    |     ...     |
   77                        +--------------+  |  (na_num_rings+1 entries)
   78                        |    ....      |  |    |             |
   79                     (na_num_rings+1 entries)  +-------------+
   80                        |              |  |
   81                        +--------------+  |
   82                                          |      NETMAP_RING
   83                                          +---->+-------------+
   84                                              / | cur         |
   85    NETMAP_IF  (nifp, one per file desc.)    /  | avail       |
   86     +---------------+                      /   | buf_ofs     |
   87     | ni_num_queues |                     /    +=============+
   88     |               |                    /     | buf_idx     | slot[0]
   89     |               |                   /      | len, flags  |
   90     |               |                  /       +-------------+
   91     +===============+                 /        | buf_idx     | slot[1]
   92     | txring_ofs[0] | (rel.to nifp)--'         | len, flags  |
   93     | txring_ofs[1] |                          +-------------+
   94   (num_rings+1 entries)                     (nr_num_slots entries)
   95     | txring_ofs[n] |                          | buf_idx     | slot[n-1]
   96     +---------------+                          | len, flags  |
   97     | rxring_ofs[0] |                          +-------------+
   98     | rxring_ofs[1] |
   99   (num_rings+1 entries)
  100     | txring_ofs[n] |
  101     +---------------+
  102 
  103  * The NETMAP_RING is the shadow ring that mirrors the NIC rings.
  104  * Each slot has the index of a buffer, its length and some flags.
  105  * In user space, the buffer address is computed as
  106  *      (char *)ring + buf_ofs + index*MAX_BUF_SIZE
  107  * In the kernel, buffers do not necessarily need to be contiguous,
  108  * and the virtual and physical addresses are derived through
  109  * a lookup table. When userspace wants to use a different buffer
  110  * in a location, it must set the NS_BUF_CHANGED flag to make
  111  * sure that the kernel recomputes updates the hardware ring and
  112  * other fields (bus_dmamap, etc.) as needed.
  113  *
  114  * Normally the driver is not requested to report the result of
  115  * transmissions (this can dramatically speed up operation).
  116  * However the user may request to report completion by setting
  117  * NS_REPORT.
  118  */
  119 struct netmap_slot {
  120         uint32_t buf_idx; /* buffer index */
  121         uint16_t len;   /* packet length, to be copied to/from the hw ring */
  122         uint16_t flags; /* buf changed, etc. */
  123 #define NS_BUF_CHANGED  0x0001  /* must resync the map, buffer changed */
  124 #define NS_REPORT       0x0002  /* ask the hardware to report results
  125                                  * e.g. by generating an interrupt
  126                                  */
  127 };
  128 
  129 /*
  130  * Netmap representation of a TX or RX ring (also known as "queue").
  131  * This is a queue implemented as a fixed-size circular array.
  132  * At the software level, two fields are important: avail and cur.
  133  *
  134  * In TX rings:
  135  *      avail   indicates the number of slots available for transmission.
  136  *              It is decremented by the application when it appends a
  137  *              packet, and set to nr_hwavail (see below) on a
  138  *              NIOCTXSYNC to reflect the actual state of the queue
  139  *              (keeping track of completed transmissions).
  140  *      cur     indicates the empty slot to use for the next packet
  141  *              to send (i.e. the "tail" of the queue).
  142  *              It is incremented by the application.
  143  *
  144  *   The kernel side of netmap uses two additional fields in its own
  145  *   private ring structure, netmap_kring:
  146  *      nr_hwcur is a copy of nr_cur on an NIOCTXSYNC.
  147  *      nr_hwavail is the number of slots known as available by the
  148  *              hardware. It is updated on an INTR (inc by the
  149  *              number of packets sent) and on a NIOCTXSYNC
  150  *              (decrease by nr_cur - nr_hwcur)
  151  *              A special case, nr_hwavail is -1 if the transmit
  152  *              side is idle (no pending transmits).
  153  *
  154  * In RX rings:
  155  *      avail   is the number of packets available (possibly 0).
  156  *              It is decremented by the software when it consumes
  157  *              a packet, and set to nr_hwavail on a NIOCRXSYNC
  158  *      cur     indicates the first slot that contains a packet
  159  *              (the "head" of the queue).
  160  *              It is incremented by the software when it consumes
  161  *              a packet.
  162  *
  163  *   The kernel side of netmap uses two additional fields in the kring:
  164  *      nr_hwcur is a copy of nr_cur on an NIOCRXSYNC
  165  *      nr_hwavail is the number of packets available. It is updated
  166  *              on INTR (inc by the number of new packets arrived)
  167  *              and on NIOCRXSYNC (decreased by nr_cur - nr_hwcur).
  168  *
  169  * DATA OWNERSHIP/LOCKING:
  170  *      The netmap_ring is owned by the user program and it is only
  171  *      accessed or modified in the upper half of the kernel during
  172  *      a system call.
  173  *
  174  *      The netmap_kring is only modified by the upper half of the kernel.
  175  */
  176 struct netmap_ring {
  177         /*
  178          * nr_buf_base_ofs is meant to be used through macros.
  179          * It contains the offset of the buffer region from this
  180          * descriptor.
  181          */
  182         const ssize_t   buf_ofs;
  183         const uint32_t  num_slots;      /* number of slots in the ring. */
  184         uint32_t        avail;          /* number of usable slots */
  185         uint32_t        cur;            /* 'current' r/w position */
  186 
  187         const uint16_t  nr_buf_size;
  188         uint16_t        flags;
  189 #define NR_TIMESTAMP    0x0002          /* set timestamp on *sync() */
  190 
  191         struct timeval  ts;             /* time of last *sync() */
  192 
  193         /* the slots follow. This struct has variable size */
  194         struct netmap_slot slot[0]; /* array of slots. */
  195 };
  196 
  197 
  198 /*
  199  * Netmap representation of an interface and its queue(s).
  200  * There is one netmap_if for each file descriptor on which we want
  201  * to select/poll.  We assume that on each interface has the same number
  202  * of receive and transmit queues.
  203  * select/poll operates on one or all pairs depending on the value of
  204  * nmr_queueid passed on the ioctl.
  205  */
  206 struct netmap_if {
  207         char ni_name[IFNAMSIZ]; /* name of the interface. */
  208         const u_int ni_version; /* API version, currently unused */
  209         const u_int ni_num_queues; /* number of queue pairs (TX/RX). */
  210         const u_int ni_rx_queues;  /* if zero, use ni_num_queues */
  211         /*
  212          * the following array contains the offset of the
  213          * each netmap ring from this structure. The first num_queues+1
  214          * refer to the tx rings, the next n+1 refer to the rx rings.
  215          * The area is filled up by the kernel on NIOCREG,
  216          * and then only read by userspace code.
  217          * entries 0..ni_num_queues-1 indicate the hardware queues,
  218          * entry ni_num_queues is the queue from/to the stack.
  219          */
  220         const ssize_t   ring_ofs[0];
  221 };
  222 
  223 #ifndef IFCAP_NETMAP    /* this should go in net/if.h */
  224 #define IFCAP_NETMAP    0x100000
  225 #endif
  226 
  227 #ifndef NIOCREGIF       
  228 /*
  229  * ioctl names and related fields
  230  *
  231  * NIOCGINFO takes a struct ifreq, the interface name is the input,
  232  *      the outputs are number of queues and number of descriptor
  233  *      for each queue (useful to set number of threads etc.).
  234  *
  235  * NIOCREGIF takes an interface name within a struct ifreq,
  236  *      and activates netmap mode on the interface (if possible).
  237  *
  238  * NIOCUNREGIF unregisters the interface associated to the fd.
  239  *
  240  * NIOCTXSYNC, NIOCRXSYNC synchronize tx or rx queues,
  241  *      whose identity is set in NIOCREGIF through nr_ringid
  242  */
  243 
  244 /*
  245  * struct nmreq overlays a struct ifreq
  246  */
  247 struct nmreq {
  248         char            nr_name[IFNAMSIZ];
  249         uint32_t        nr_version;     /* API version (unused) */
  250         uint32_t        nr_offset;      /* nifp offset in the shared region */
  251         uint32_t        nr_memsize;     /* size of the shared region */
  252         uint32_t        nr_numslots;    /* descriptors per queue */
  253         uint16_t        nr_numrings;
  254         uint16_t        nr_ringid;      /* ring(s) we care about */
  255 #define NETMAP_HW_RING  0x4000          /* low bits indicate one hw ring */
  256 #define NETMAP_SW_RING  0x2000          /* we process the sw ring */
  257 #define NETMAP_NO_TX_POLL       0x1000  /* no gratuitous txsync on poll */
  258 #define NETMAP_RING_MASK 0xfff          /* the ring number */
  259 };
  260 
  261 #define NIOCGINFO       _IOWR('i', 145, struct nmreq) /* return IF info */
  262 #define NIOCREGIF       _IOWR('i', 146, struct nmreq) /* interface register */
  263 #define NIOCUNREGIF     _IO('i', 147) /* interface unregister */
  264 #define NIOCTXSYNC      _IO('i', 148) /* sync tx queues */
  265 #define NIOCRXSYNC      _IO('i', 149) /* sync rx queues */
  266 #endif /* !NIOCREGIF */
  267 
  268 #endif /* _NET_NETMAP_H_ */

Cache object: 4bbedf78756900b17954fe0e1ca3f4b5


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]


This page is part of the FreeBSD/Linux Linux Kernel Cross-Reference, and was automatically generated using a modified version of the LXR engine.