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$ 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 /* 262 * default buf size is 2048, but it may make sense to have 263 * it shorter for better cache usage. 264 */ 265 266 #define NETMAP_BUF_SIZE (2048) 267 #define NIOCGINFO _IOWR('i', 145, struct nmreq) /* return IF info */ 268 #define NIOCREGIF _IOWR('i', 146, struct nmreq) /* interface register */ 269 #define NIOCUNREGIF _IO('i', 147) /* interface unregister */ 270 #define NIOCTXSYNC _IO('i', 148) /* sync tx queues */ 271 #define NIOCRXSYNC _IO('i', 149) /* sync rx queues */ 272 #endif /* !NIOCREGIF */ 273 274 #endif /* _NET_NETMAP_H_ */ 275