Version:  2.0.40 2.2.26 2.4.37 2.6.39 3.0 3.1 3.2 3.3 3.4 3.5 3.6 3.7 3.8 3.9 3.10 3.11 3.12 3.13 3.14 3.15

Linux/Documentation/networking/packet_mmap.txt

  1 --------------------------------------------------------------------------------
  2 + ABSTRACT
  3 --------------------------------------------------------------------------------
  4 
  5 This file documents the mmap() facility available with the PACKET
  6 socket interface on 2.4/2.6/3.x kernels. This type of sockets is used for
  7 i) capture network traffic with utilities like tcpdump, ii) transmit network
  8 traffic, or any other that needs raw access to network interface.
  9 
 10 You can find the latest version of this document at:
 11     http://wiki.ipxwarzone.com/index.php5?title=Linux_packet_mmap
 12 
 13 Howto can be found at:
 14     http://wiki.gnu-log.net (packet_mmap)
 15 
 16 Please send your comments to
 17     Ulisses Alonso CamarĂ³ <uaca@i.hate.spam.alumni.uv.es>
 18     Johann Baudy <johann.baudy@gnu-log.net>
 19 
 20 -------------------------------------------------------------------------------
 21 + Why use PACKET_MMAP
 22 --------------------------------------------------------------------------------
 23 
 24 In Linux 2.4/2.6/3.x if PACKET_MMAP is not enabled, the capture process is very
 25 inefficient. It uses very limited buffers and requires one system call to
 26 capture each packet, it requires two if you want to get packet's timestamp
 27 (like libpcap always does).
 28 
 29 In the other hand PACKET_MMAP is very efficient. PACKET_MMAP provides a size 
 30 configurable circular buffer mapped in user space that can be used to either
 31 send or receive packets. This way reading packets just needs to wait for them,
 32 most of the time there is no need to issue a single system call. Concerning
 33 transmission, multiple packets can be sent through one system call to get the
 34 highest bandwidth. By using a shared buffer between the kernel and the user
 35 also has the benefit of minimizing packet copies.
 36 
 37 It's fine to use PACKET_MMAP to improve the performance of the capture and
 38 transmission process, but it isn't everything. At least, if you are capturing
 39 at high speeds (this is relative to the cpu speed), you should check if the
 40 device driver of your network interface card supports some sort of interrupt
 41 load mitigation or (even better) if it supports NAPI, also make sure it is
 42 enabled. For transmission, check the MTU (Maximum Transmission Unit) used and
 43 supported by devices of your network. CPU IRQ pinning of your network interface
 44 card can also be an advantage.
 45 
 46 --------------------------------------------------------------------------------
 47 + How to use mmap() to improve capture process
 48 --------------------------------------------------------------------------------
 49 
 50 From the user standpoint, you should use the higher level libpcap library, which
 51 is a de facto standard, portable across nearly all operating systems
 52 including Win32. 
 53 
 54 Said that, at time of this writing, official libpcap 0.8.1 is out and doesn't include
 55 support for PACKET_MMAP, and also probably the libpcap included in your distribution. 
 56 
 57 I'm aware of two implementations of PACKET_MMAP in libpcap:
 58 
 59     http://wiki.ipxwarzone.com/              (by Simon Patarin, based on libpcap 0.6.2)
 60     http://public.lanl.gov/cpw/              (by Phil Wood, based on lastest libpcap)
 61 
 62 The rest of this document is intended for people who want to understand
 63 the low level details or want to improve libpcap by including PACKET_MMAP
 64 support.
 65 
 66 --------------------------------------------------------------------------------
 67 + How to use mmap() directly to improve capture process
 68 --------------------------------------------------------------------------------
 69 
 70 From the system calls stand point, the use of PACKET_MMAP involves
 71 the following process:
 72 
 73 
 74 [setup]     socket() -------> creation of the capture socket
 75             setsockopt() ---> allocation of the circular buffer (ring)
 76                               option: PACKET_RX_RING
 77             mmap() ---------> mapping of the allocated buffer to the
 78                               user process
 79 
 80 [capture]   poll() ---------> to wait for incoming packets
 81 
 82 [shutdown]  close() --------> destruction of the capture socket and
 83                               deallocation of all associated 
 84                               resources.
 85 
 86 
 87 socket creation and destruction is straight forward, and is done 
 88 the same way with or without PACKET_MMAP:
 89 
 90  int fd = socket(PF_PACKET, mode, htons(ETH_P_ALL));
 91 
 92 where mode is SOCK_RAW for the raw interface were link level
 93 information can be captured or SOCK_DGRAM for the cooked
 94 interface where link level information capture is not 
 95 supported and a link level pseudo-header is provided 
 96 by the kernel.
 97 
 98 The destruction of the socket and all associated resources
 99 is done by a simple call to close(fd).
100 
101 Similarly as without PACKET_MMAP, it is possible to use one socket
102 for capture and transmission. This can be done by mapping the
103 allocated RX and TX buffer ring with a single mmap() call.
104 See "Mapping and use of the circular buffer (ring)".
105 
106 Next I will describe PACKET_MMAP settings and its constraints,
107 also the mapping of the circular buffer in the user process and 
108 the use of this buffer.
109 
110 --------------------------------------------------------------------------------
111 + How to use mmap() directly to improve transmission process
112 --------------------------------------------------------------------------------
113 Transmission process is similar to capture as shown below.
114 
115 [setup]          socket() -------> creation of the transmission socket
116                  setsockopt() ---> allocation of the circular buffer (ring)
117                                    option: PACKET_TX_RING
118                  bind() ---------> bind transmission socket with a network interface
119                  mmap() ---------> mapping of the allocated buffer to the
120                                    user process
121 
122 [transmission]   poll() ---------> wait for free packets (optional)
123                  send() ---------> send all packets that are set as ready in
124                                    the ring
125                                    The flag MSG_DONTWAIT can be used to return
126                                    before end of transfer.
127 
128 [shutdown]  close() --------> destruction of the transmission socket and
129                               deallocation of all associated resources.
130 
131 Socket creation and destruction is also straight forward, and is done
132 the same way as in capturing described in the previous paragraph:
133 
134  int fd = socket(PF_PACKET, mode, 0);
135 
136 The protocol can optionally be 0 in case we only want to transmit
137 via this socket, which avoids an expensive call to packet_rcv().
138 In this case, you also need to bind(2) the TX_RING with sll_protocol = 0
139 set. Otherwise, htons(ETH_P_ALL) or any other protocol, for example.
140 
141 Binding the socket to your network interface is mandatory (with zero copy) to
142 know the header size of frames used in the circular buffer.
143 
144 As capture, each frame contains two parts:
145 
146  --------------------
147 | struct tpacket_hdr | Header. It contains the status of
148 |                    | of this frame
149 |--------------------|
150 | data buffer        |
151 .                    .  Data that will be sent over the network interface.
152 .                    .
153  --------------------
154 
155  bind() associates the socket to your network interface thanks to
156  sll_ifindex parameter of struct sockaddr_ll.
157 
158  Initialization example:
159 
160  struct sockaddr_ll my_addr;
161  struct ifreq s_ifr;
162  ...
163 
164  strncpy (s_ifr.ifr_name, "eth0", sizeof(s_ifr.ifr_name));
165 
166  /* get interface index of eth0 */
167  ioctl(this->socket, SIOCGIFINDEX, &s_ifr);
168 
169  /* fill sockaddr_ll struct to prepare binding */
170  my_addr.sll_family = AF_PACKET;
171  my_addr.sll_protocol = htons(ETH_P_ALL);
172  my_addr.sll_ifindex =  s_ifr.ifr_ifindex;
173 
174  /* bind socket to eth0 */
175  bind(this->socket, (struct sockaddr *)&my_addr, sizeof(struct sockaddr_ll));
176 
177  A complete tutorial is available at: http://wiki.gnu-log.net/
178 
179 By default, the user should put data at :
180  frame base + TPACKET_HDRLEN - sizeof(struct sockaddr_ll)
181 
182 So, whatever you choose for the socket mode (SOCK_DGRAM or SOCK_RAW),
183 the beginning of the user data will be at :
184  frame base + TPACKET_ALIGN(sizeof(struct tpacket_hdr))
185 
186 If you wish to put user data at a custom offset from the beginning of
187 the frame (for payload alignment with SOCK_RAW mode for instance) you
188 can set tp_net (with SOCK_DGRAM) or tp_mac (with SOCK_RAW). In order
189 to make this work it must be enabled previously with setsockopt()
190 and the PACKET_TX_HAS_OFF option.
191 
192 --------------------------------------------------------------------------------
193 + PACKET_MMAP settings
194 --------------------------------------------------------------------------------
195 
196 To setup PACKET_MMAP from user level code is done with a call like
197 
198  - Capture process
199      setsockopt(fd, SOL_PACKET, PACKET_RX_RING, (void *) &req, sizeof(req))
200  - Transmission process
201      setsockopt(fd, SOL_PACKET, PACKET_TX_RING, (void *) &req, sizeof(req))
202 
203 The most significant argument in the previous call is the req parameter, 
204 this parameter must to have the following structure:
205 
206     struct tpacket_req
207     {
208         unsigned int    tp_block_size;  /* Minimal size of contiguous block */
209         unsigned int    tp_block_nr;    /* Number of blocks */
210         unsigned int    tp_frame_size;  /* Size of frame */
211         unsigned int    tp_frame_nr;    /* Total number of frames */
212     };
213 
214 This structure is defined in /usr/include/linux/if_packet.h and establishes a 
215 circular buffer (ring) of unswappable memory.
216 Being mapped in the capture process allows reading the captured frames and 
217 related meta-information like timestamps without requiring a system call.
218 
219 Frames are grouped in blocks. Each block is a physically contiguous
220 region of memory and holds tp_block_size/tp_frame_size frames. The total number 
221 of blocks is tp_block_nr. Note that tp_frame_nr is a redundant parameter because
222 
223     frames_per_block = tp_block_size/tp_frame_size
224 
225 indeed, packet_set_ring checks that the following condition is true
226 
227     frames_per_block * tp_block_nr == tp_frame_nr
228 
229 Lets see an example, with the following values:
230 
231      tp_block_size= 4096
232      tp_frame_size= 2048
233      tp_block_nr  = 4
234      tp_frame_nr  = 8
235 
236 we will get the following buffer structure:
237 
238         block #1                 block #2         
239 +---------+---------+    +---------+---------+    
240 | frame 1 | frame 2 |    | frame 3 | frame 4 |    
241 +---------+---------+    +---------+---------+    
242 
243         block #3                 block #4
244 +---------+---------+    +---------+---------+
245 | frame 5 | frame 6 |    | frame 7 | frame 8 |
246 +---------+---------+    +---------+---------+
247 
248 A frame can be of any size with the only condition it can fit in a block. A block
249 can only hold an integer number of frames, or in other words, a frame cannot 
250 be spawned across two blocks, so there are some details you have to take into 
251 account when choosing the frame_size. See "Mapping and use of the circular 
252 buffer (ring)".
253 
254 --------------------------------------------------------------------------------
255 + PACKET_MMAP setting constraints
256 --------------------------------------------------------------------------------
257 
258 In kernel versions prior to 2.4.26 (for the 2.4 branch) and 2.6.5 (2.6 branch),
259 the PACKET_MMAP buffer could hold only 32768 frames in a 32 bit architecture or
260 16384 in a 64 bit architecture. For information on these kernel versions
261 see http://pusa.uv.es/~ulisses/packet_mmap/packet_mmap.pre-2.4.26_2.6.5.txt
262 
263  Block size limit
264 ------------------
265 
266 As stated earlier, each block is a contiguous physical region of memory. These 
267 memory regions are allocated with calls to the __get_free_pages() function. As 
268 the name indicates, this function allocates pages of memory, and the second
269 argument is "order" or a power of two number of pages, that is 
270 (for PAGE_SIZE == 4096) order=0 ==> 4096 bytes, order=1 ==> 8192 bytes, 
271 order=2 ==> 16384 bytes, etc. The maximum size of a 
272 region allocated by __get_free_pages is determined by the MAX_ORDER macro. More 
273 precisely the limit can be calculated as:
274 
275    PAGE_SIZE << MAX_ORDER
276 
277    In a i386 architecture PAGE_SIZE is 4096 bytes 
278    In a 2.4/i386 kernel MAX_ORDER is 10
279    In a 2.6/i386 kernel MAX_ORDER is 11
280 
281 So get_free_pages can allocate as much as 4MB or 8MB in a 2.4/2.6 kernel 
282 respectively, with an i386 architecture.
283 
284 User space programs can include /usr/include/sys/user.h and 
285 /usr/include/linux/mmzone.h to get PAGE_SIZE MAX_ORDER declarations.
286 
287 The pagesize can also be determined dynamically with the getpagesize (2) 
288 system call. 
289 
290  Block number limit
291 --------------------
292 
293 To understand the constraints of PACKET_MMAP, we have to see the structure 
294 used to hold the pointers to each block.
295 
296 Currently, this structure is a dynamically allocated vector with kmalloc 
297 called pg_vec, its size limits the number of blocks that can be allocated.
298 
299     +---+---+---+---+
300     | x | x | x | x |
301     +---+---+---+---+
302       |   |   |   |
303       |   |   |   v
304       |   |   v  block #4
305       |   v  block #3
306       v  block #2
307      block #1
308 
309 kmalloc allocates any number of bytes of physically contiguous memory from 
310 a pool of pre-determined sizes. This pool of memory is maintained by the slab 
311 allocator which is at the end the responsible for doing the allocation and 
312 hence which imposes the maximum memory that kmalloc can allocate. 
313 
314 In a 2.4/2.6 kernel and the i386 architecture, the limit is 131072 bytes. The 
315 predetermined sizes that kmalloc uses can be checked in the "size-<bytes>" 
316 entries of /proc/slabinfo
317 
318 In a 32 bit architecture, pointers are 4 bytes long, so the total number of 
319 pointers to blocks is
320 
321      131072/4 = 32768 blocks
322 
323  PACKET_MMAP buffer size calculator
324 ------------------------------------
325 
326 Definitions:
327 
328 <size-max>    : is the maximum size of allocable with kmalloc (see /proc/slabinfo)
329 <pointer size>: depends on the architecture -- sizeof(void *)
330 <page size>   : depends on the architecture -- PAGE_SIZE or getpagesize (2)
331 <max-order>   : is the value defined with MAX_ORDER
332 <frame size>  : it's an upper bound of frame's capture size (more on this later)
333 
334 from these definitions we will derive 
335 
336         <block number> = <size-max>/<pointer size>
337         <block size> = <pagesize> << <max-order>
338 
339 so, the max buffer size is
340 
341         <block number> * <block size>
342 
343 and, the number of frames be
344 
345         <block number> * <block size> / <frame size>
346 
347 Suppose the following parameters, which apply for 2.6 kernel and an
348 i386 architecture:
349 
350         <size-max> = 131072 bytes
351         <pointer size> = 4 bytes
352         <pagesize> = 4096 bytes
353         <max-order> = 11
354 
355 and a value for <frame size> of 2048 bytes. These parameters will yield
356 
357         <block number> = 131072/4 = 32768 blocks
358         <block size> = 4096 << 11 = 8 MiB.
359 
360 and hence the buffer will have a 262144 MiB size. So it can hold 
361 262144 MiB / 2048 bytes = 134217728 frames
362 
363 Actually, this buffer size is not possible with an i386 architecture. 
364 Remember that the memory is allocated in kernel space, in the case of 
365 an i386 kernel's memory size is limited to 1GiB.
366 
367 All memory allocations are not freed until the socket is closed. The memory 
368 allocations are done with GFP_KERNEL priority, this basically means that 
369 the allocation can wait and swap other process' memory in order to allocate 
370 the necessary memory, so normally limits can be reached.
371 
372  Other constraints
373 -------------------
374 
375 If you check the source code you will see that what I draw here as a frame
376 is not only the link level frame. At the beginning of each frame there is a 
377 header called struct tpacket_hdr used in PACKET_MMAP to hold link level's frame
378 meta information like timestamp. So what we draw here a frame it's really 
379 the following (from include/linux/if_packet.h):
380 
381 /*
382    Frame structure:
383 
384    - Start. Frame must be aligned to TPACKET_ALIGNMENT=16
385    - struct tpacket_hdr
386    - pad to TPACKET_ALIGNMENT=16
387    - struct sockaddr_ll
388    - Gap, chosen so that packet data (Start+tp_net) aligns to 
389      TPACKET_ALIGNMENT=16
390    - Start+tp_mac: [ Optional MAC header ]
391    - Start+tp_net: Packet data, aligned to TPACKET_ALIGNMENT=16.
392    - Pad to align to TPACKET_ALIGNMENT=16
393  */
394  
395  The following are conditions that are checked in packet_set_ring
396 
397    tp_block_size must be a multiple of PAGE_SIZE (1)
398    tp_frame_size must be greater than TPACKET_HDRLEN (obvious)
399    tp_frame_size must be a multiple of TPACKET_ALIGNMENT
400    tp_frame_nr   must be exactly frames_per_block*tp_block_nr
401 
402 Note that tp_block_size should be chosen to be a power of two or there will
403 be a waste of memory.
404 
405 --------------------------------------------------------------------------------
406 + Mapping and use of the circular buffer (ring)
407 --------------------------------------------------------------------------------
408 
409 The mapping of the buffer in the user process is done with the conventional 
410 mmap function. Even the circular buffer is compound of several physically
411 discontiguous blocks of memory, they are contiguous to the user space, hence
412 just one call to mmap is needed:
413 
414     mmap(0, size, PROT_READ|PROT_WRITE, MAP_SHARED, fd, 0);
415 
416 If tp_frame_size is a divisor of tp_block_size frames will be 
417 contiguously spaced by tp_frame_size bytes. If not, each
418 tp_block_size/tp_frame_size frames there will be a gap between 
419 the frames. This is because a frame cannot be spawn across two
420 blocks. 
421 
422 To use one socket for capture and transmission, the mapping of both the
423 RX and TX buffer ring has to be done with one call to mmap:
424 
425     ...
426     setsockopt(fd, SOL_PACKET, PACKET_RX_RING, &foo, sizeof(foo));
427     setsockopt(fd, SOL_PACKET, PACKET_TX_RING, &bar, sizeof(bar));
428     ...
429     rx_ring = mmap(0, size * 2, PROT_READ|PROT_WRITE, MAP_SHARED, fd, 0);
430     tx_ring = rx_ring + size;
431 
432 RX must be the first as the kernel maps the TX ring memory right
433 after the RX one.
434 
435 At the beginning of each frame there is an status field (see 
436 struct tpacket_hdr). If this field is 0 means that the frame is ready
437 to be used for the kernel, If not, there is a frame the user can read 
438 and the following flags apply:
439 
440 +++ Capture process:
441      from include/linux/if_packet.h
442 
443      #define TP_STATUS_COPY          2 
444      #define TP_STATUS_LOSING        4 
445      #define TP_STATUS_CSUMNOTREADY  8 
446 
447 TP_STATUS_COPY        : This flag indicates that the frame (and associated
448                         meta information) has been truncated because it's 
449                         larger than tp_frame_size. This packet can be 
450                         read entirely with recvfrom().
451                         
452                         In order to make this work it must to be
453                         enabled previously with setsockopt() and 
454                         the PACKET_COPY_THRESH option. 
455 
456                         The number of frames that can be buffered to
457                         be read with recvfrom is limited like a normal socket.
458                         See the SO_RCVBUF option in the socket (7) man page.
459 
460 TP_STATUS_LOSING      : indicates there were packet drops from last time 
461                         statistics where checked with getsockopt() and
462                         the PACKET_STATISTICS option.
463 
464 TP_STATUS_CSUMNOTREADY: currently it's used for outgoing IP packets which 
465                         its checksum will be done in hardware. So while
466                         reading the packet we should not try to check the 
467                         checksum. 
468 
469 for convenience there are also the following defines:
470 
471      #define TP_STATUS_KERNEL        0
472      #define TP_STATUS_USER          1
473 
474 The kernel initializes all frames to TP_STATUS_KERNEL, when the kernel
475 receives a packet it puts in the buffer and updates the status with
476 at least the TP_STATUS_USER flag. Then the user can read the packet,
477 once the packet is read the user must zero the status field, so the kernel 
478 can use again that frame buffer.
479 
480 The user can use poll (any other variant should apply too) to check if new
481 packets are in the ring:
482 
483     struct pollfd pfd;
484 
485     pfd.fd = fd;
486     pfd.revents = 0;
487     pfd.events = POLLIN|POLLRDNORM|POLLERR;
488 
489     if (status == TP_STATUS_KERNEL)
490         retval = poll(&pfd, 1, timeout);
491 
492 It doesn't incur in a race condition to first check the status value and 
493 then poll for frames.
494 
495 ++ Transmission process
496 Those defines are also used for transmission:
497 
498      #define TP_STATUS_AVAILABLE        0 // Frame is available
499      #define TP_STATUS_SEND_REQUEST     1 // Frame will be sent on next send()
500      #define TP_STATUS_SENDING          2 // Frame is currently in transmission
501      #define TP_STATUS_WRONG_FORMAT     4 // Frame format is not correct
502 
503 First, the kernel initializes all frames to TP_STATUS_AVAILABLE. To send a
504 packet, the user fills a data buffer of an available frame, sets tp_len to
505 current data buffer size and sets its status field to TP_STATUS_SEND_REQUEST.
506 This can be done on multiple frames. Once the user is ready to transmit, it
507 calls send(). Then all buffers with status equal to TP_STATUS_SEND_REQUEST are
508 forwarded to the network device. The kernel updates each status of sent
509 frames with TP_STATUS_SENDING until the end of transfer.
510 At the end of each transfer, buffer status returns to TP_STATUS_AVAILABLE.
511 
512     header->tp_len = in_i_size;
513     header->tp_status = TP_STATUS_SEND_REQUEST;
514     retval = send(this->socket, NULL, 0, 0);
515 
516 The user can also use poll() to check if a buffer is available:
517 (status == TP_STATUS_SENDING)
518 
519     struct pollfd pfd;
520     pfd.fd = fd;
521     pfd.revents = 0;
522     pfd.events = POLLOUT;
523     retval = poll(&pfd, 1, timeout);
524 
525 -------------------------------------------------------------------------------
526 + What TPACKET versions are available and when to use them?
527 -------------------------------------------------------------------------------
528 
529  int val = tpacket_version;
530  setsockopt(fd, SOL_PACKET, PACKET_VERSION, &val, sizeof(val));
531  getsockopt(fd, SOL_PACKET, PACKET_VERSION, &val, sizeof(val));
532 
533 where 'tpacket_version' can be TPACKET_V1 (default), TPACKET_V2, TPACKET_V3.
534 
535 TPACKET_V1:
536         - Default if not otherwise specified by setsockopt(2)
537         - RX_RING, TX_RING available
538 
539 TPACKET_V1 --> TPACKET_V2:
540         - Made 64 bit clean due to unsigned long usage in TPACKET_V1
541           structures, thus this also works on 64 bit kernel with 32 bit
542           userspace and the like
543         - Timestamp resolution in nanoseconds instead of microseconds
544         - RX_RING, TX_RING available
545         - VLAN metadata information available for packets
546           (TP_STATUS_VLAN_VALID, TP_STATUS_VLAN_TPID_VALID),
547           in the tpacket2_hdr structure:
548                 - TP_STATUS_VLAN_VALID bit being set into the tp_status field indicates
549                   that the tp_vlan_tci field has valid VLAN TCI value
550                 - TP_STATUS_VLAN_TPID_VALID bit being set into the tp_status field
551                   indicates that the tp_vlan_tpid field has valid VLAN TPID value
552         - How to switch to TPACKET_V2:
553                 1. Replace struct tpacket_hdr by struct tpacket2_hdr
554                 2. Query header len and save
555                 3. Set protocol version to 2, set up ring as usual
556                 4. For getting the sockaddr_ll,
557                    use (void *)hdr + TPACKET_ALIGN(hdrlen) instead of
558                    (void *)hdr + TPACKET_ALIGN(sizeof(struct tpacket_hdr))
559 
560 TPACKET_V2 --> TPACKET_V3:
561         - Flexible buffer implementation:
562                 1. Blocks can be configured with non-static frame-size
563                 2. Read/poll is at a block-level (as opposed to packet-level)
564                 3. Added poll timeout to avoid indefinite user-space wait
565                    on idle links
566                 4. Added user-configurable knobs:
567                         4.1 block::timeout
568                         4.2 tpkt_hdr::sk_rxhash
569         - RX Hash data available in user space
570         - Currently only RX_RING available
571 
572 -------------------------------------------------------------------------------
573 + AF_PACKET fanout mode
574 -------------------------------------------------------------------------------
575 
576 In the AF_PACKET fanout mode, packet reception can be load balanced among
577 processes. This also works in combination with mmap(2) on packet sockets.
578 
579 Currently implemented fanout policies are:
580 
581   - PACKET_FANOUT_HASH: schedule to socket by skb's packet hash
582   - PACKET_FANOUT_LB: schedule to socket by round-robin
583   - PACKET_FANOUT_CPU: schedule to socket by CPU packet arrives on
584   - PACKET_FANOUT_RND: schedule to socket by random selection
585   - PACKET_FANOUT_ROLLOVER: if one socket is full, rollover to another
586   - PACKET_FANOUT_QM: schedule to socket by skbs recorded queue_mapping
587 
588 Minimal example code by David S. Miller (try things like "./test eth0 hash",
589 "./test eth0 lb", etc.):
590 
591 #include <stddef.h>
592 #include <stdlib.h>
593 #include <stdio.h>
594 #include <string.h>
595 
596 #include <sys/types.h>
597 #include <sys/wait.h>
598 #include <sys/socket.h>
599 #include <sys/ioctl.h>
600 
601 #include <unistd.h>
602 
603 #include <linux/if_ether.h>
604 #include <linux/if_packet.h>
605 
606 #include <net/if.h>
607 
608 static const char *device_name;
609 static int fanout_type;
610 static int fanout_id;
611 
612 #ifndef PACKET_FANOUT
613 # define PACKET_FANOUT                  18
614 # define PACKET_FANOUT_HASH             0
615 # define PACKET_FANOUT_LB               1
616 #endif
617 
618 static int setup_socket(void)
619 {
620         int err, fd = socket(AF_PACKET, SOCK_RAW, htons(ETH_P_IP));
621         struct sockaddr_ll ll;
622         struct ifreq ifr;
623         int fanout_arg;
624 
625         if (fd < 0) {
626                 perror("socket");
627                 return EXIT_FAILURE;
628         }
629 
630         memset(&ifr, 0, sizeof(ifr));
631         strcpy(ifr.ifr_name, device_name);
632         err = ioctl(fd, SIOCGIFINDEX, &ifr);
633         if (err < 0) {
634                 perror("SIOCGIFINDEX");
635                 return EXIT_FAILURE;
636         }
637 
638         memset(&ll, 0, sizeof(ll));
639         ll.sll_family = AF_PACKET;
640         ll.sll_ifindex = ifr.ifr_ifindex;
641         err = bind(fd, (struct sockaddr *) &ll, sizeof(ll));
642         if (err < 0) {
643                 perror("bind");
644                 return EXIT_FAILURE;
645         }
646 
647         fanout_arg = (fanout_id | (fanout_type << 16));
648         err = setsockopt(fd, SOL_PACKET, PACKET_FANOUT,
649                          &fanout_arg, sizeof(fanout_arg));
650         if (err) {
651                 perror("setsockopt");
652                 return EXIT_FAILURE;
653         }
654 
655         return fd;
656 }
657 
658 static void fanout_thread(void)
659 {
660         int fd = setup_socket();
661         int limit = 10000;
662 
663         if (fd < 0)
664                 exit(fd);
665 
666         while (limit-- > 0) {
667                 char buf[1600];
668                 int err;
669 
670                 err = read(fd, buf, sizeof(buf));
671                 if (err < 0) {
672                         perror("read");
673                         exit(EXIT_FAILURE);
674                 }
675                 if ((limit % 10) == 0)
676                         fprintf(stdout, "(%d) \n", getpid());
677         }
678 
679         fprintf(stdout, "%d: Received 10000 packets\n", getpid());
680 
681         close(fd);
682         exit(0);
683 }
684 
685 int main(int argc, char **argp)
686 {
687         int fd, err;
688         int i;
689 
690         if (argc != 3) {
691                 fprintf(stderr, "Usage: %s INTERFACE {hash|lb}\n", argp[0]);
692                 return EXIT_FAILURE;
693         }
694 
695         if (!strcmp(argp[2], "hash"))
696                 fanout_type = PACKET_FANOUT_HASH;
697         else if (!strcmp(argp[2], "lb"))
698                 fanout_type = PACKET_FANOUT_LB;
699         else {
700                 fprintf(stderr, "Unknown fanout type [%s]\n", argp[2]);
701                 exit(EXIT_FAILURE);
702         }
703 
704         device_name = argp[1];
705         fanout_id = getpid() & 0xffff;
706 
707         for (i = 0; i < 4; i++) {
708                 pid_t pid = fork();
709 
710                 switch (pid) {
711                 case 0:
712                         fanout_thread();
713 
714                 case -1:
715                         perror("fork");
716                         exit(EXIT_FAILURE);
717                 }
718         }
719 
720         for (i = 0; i < 4; i++) {
721                 int status;
722 
723                 wait(&status);
724         }
725 
726         return 0;
727 }
728 
729 -------------------------------------------------------------------------------
730 + AF_PACKET TPACKET_V3 example
731 -------------------------------------------------------------------------------
732 
733 AF_PACKET's TPACKET_V3 ring buffer can be configured to use non-static frame
734 sizes by doing it's own memory management. It is based on blocks where polling
735 works on a per block basis instead of per ring as in TPACKET_V2 and predecessor.
736 
737 It is said that TPACKET_V3 brings the following benefits:
738  *) ~15 - 20% reduction in CPU-usage
739  *) ~20% increase in packet capture rate
740  *) ~2x increase in packet density
741  *) Port aggregation analysis
742  *) Non static frame size to capture entire packet payload
743 
744 So it seems to be a good candidate to be used with packet fanout.
745 
746 Minimal example code by Daniel Borkmann based on Chetan Loke's lolpcap (compile
747 it with gcc -Wall -O2 blob.c, and try things like "./a.out eth0", etc.):
748 
749 /* Written from scratch, but kernel-to-user space API usage
750  * dissected from lolpcap:
751  *  Copyright 2011, Chetan Loke <loke.chetan@gmail.com>
752  *  License: GPL, version 2.0
753  */
754 
755 #include <stdio.h>
756 #include <stdlib.h>
757 #include <stdint.h>
758 #include <string.h>
759 #include <assert.h>
760 #include <net/if.h>
761 #include <arpa/inet.h>
762 #include <netdb.h>
763 #include <poll.h>
764 #include <unistd.h>
765 #include <signal.h>
766 #include <inttypes.h>
767 #include <sys/socket.h>
768 #include <sys/mman.h>
769 #include <linux/if_packet.h>
770 #include <linux/if_ether.h>
771 #include <linux/ip.h>
772 
773 #ifndef likely
774 # define likely(x)              __builtin_expect(!!(x), 1)
775 #endif
776 #ifndef unlikely
777 # define unlikely(x)            __builtin_expect(!!(x), 0)
778 #endif
779 
780 struct block_desc {
781         uint32_t version;
782         uint32_t offset_to_priv;
783         struct tpacket_hdr_v1 h1;
784 };
785 
786 struct ring {
787         struct iovec *rd;
788         uint8_t *map;
789         struct tpacket_req3 req;
790 };
791 
792 static unsigned long packets_total = 0, bytes_total = 0;
793 static sig_atomic_t sigint = 0;
794 
795 static void sighandler(int num)
796 {
797         sigint = 1;
798 }
799 
800 static int setup_socket(struct ring *ring, char *netdev)
801 {
802         int err, i, fd, v = TPACKET_V3;
803         struct sockaddr_ll ll;
804         unsigned int blocksiz = 1 << 22, framesiz = 1 << 11;
805         unsigned int blocknum = 64;
806 
807         fd = socket(AF_PACKET, SOCK_RAW, htons(ETH_P_ALL));
808         if (fd < 0) {
809                 perror("socket");
810                 exit(1);
811         }
812 
813         err = setsockopt(fd, SOL_PACKET, PACKET_VERSION, &v, sizeof(v));
814         if (err < 0) {
815                 perror("setsockopt");
816                 exit(1);
817         }
818 
819         memset(&ring->req, 0, sizeof(ring->req));
820         ring->req.tp_block_size = blocksiz;
821         ring->req.tp_frame_size = framesiz;
822         ring->req.tp_block_nr = blocknum;
823         ring->req.tp_frame_nr = (blocksiz * blocknum) / framesiz;
824         ring->req.tp_retire_blk_tov = 60;
825         ring->req.tp_feature_req_word = TP_FT_REQ_FILL_RXHASH;
826 
827         err = setsockopt(fd, SOL_PACKET, PACKET_RX_RING, &ring->req,
828                          sizeof(ring->req));
829         if (err < 0) {
830                 perror("setsockopt");
831                 exit(1);
832         }
833 
834         ring->map = mmap(NULL, ring->req.tp_block_size * ring->req.tp_block_nr,
835                          PROT_READ | PROT_WRITE, MAP_SHARED | MAP_LOCKED, fd, 0);
836         if (ring->map == MAP_FAILED) {
837                 perror("mmap");
838                 exit(1);
839         }
840 
841         ring->rd = malloc(ring->req.tp_block_nr * sizeof(*ring->rd));
842         assert(ring->rd);
843         for (i = 0; i < ring->req.tp_block_nr; ++i) {
844                 ring->rd[i].iov_base = ring->map + (i * ring->req.tp_block_size);
845                 ring->rd[i].iov_len = ring->req.tp_block_size;
846         }
847 
848         memset(&ll, 0, sizeof(ll));
849         ll.sll_family = PF_PACKET;
850         ll.sll_protocol = htons(ETH_P_ALL);
851         ll.sll_ifindex = if_nametoindex(netdev);
852         ll.sll_hatype = 0;
853         ll.sll_pkttype = 0;
854         ll.sll_halen = 0;
855 
856         err = bind(fd, (struct sockaddr *) &ll, sizeof(ll));
857         if (err < 0) {
858                 perror("bind");
859                 exit(1);
860         }
861 
862         return fd;
863 }
864 
865 static void display(struct tpacket3_hdr *ppd)
866 {
867         struct ethhdr *eth = (struct ethhdr *) ((uint8_t *) ppd + ppd->tp_mac);
868         struct iphdr *ip = (struct iphdr *) ((uint8_t *) eth + ETH_HLEN);
869 
870         if (eth->h_proto == htons(ETH_P_IP)) {
871                 struct sockaddr_in ss, sd;
872                 char sbuff[NI_MAXHOST], dbuff[NI_MAXHOST];
873 
874                 memset(&ss, 0, sizeof(ss));
875                 ss.sin_family = PF_INET;
876                 ss.sin_addr.s_addr = ip->saddr;
877                 getnameinfo((struct sockaddr *) &ss, sizeof(ss),
878                             sbuff, sizeof(sbuff), NULL, 0, NI_NUMERICHOST);
879 
880                 memset(&sd, 0, sizeof(sd));
881                 sd.sin_family = PF_INET;
882                 sd.sin_addr.s_addr = ip->daddr;
883                 getnameinfo((struct sockaddr *) &sd, sizeof(sd),
884                             dbuff, sizeof(dbuff), NULL, 0, NI_NUMERICHOST);
885 
886                 printf("%s -> %s, ", sbuff, dbuff);
887         }
888 
889         printf("rxhash: 0x%x\n", ppd->hv1.tp_rxhash);
890 }
891 
892 static void walk_block(struct block_desc *pbd, const int block_num)
893 {
894         int num_pkts = pbd->h1.num_pkts, i;
895         unsigned long bytes = 0;
896         struct tpacket3_hdr *ppd;
897 
898         ppd = (struct tpacket3_hdr *) ((uint8_t *) pbd +
899                                        pbd->h1.offset_to_first_pkt);
900         for (i = 0; i < num_pkts; ++i) {
901                 bytes += ppd->tp_snaplen;
902                 display(ppd);
903 
904                 ppd = (struct tpacket3_hdr *) ((uint8_t *) ppd +
905                                                ppd->tp_next_offset);
906         }
907 
908         packets_total += num_pkts;
909         bytes_total += bytes;
910 }
911 
912 static void flush_block(struct block_desc *pbd)
913 {
914         pbd->h1.block_status = TP_STATUS_KERNEL;
915 }
916 
917 static void teardown_socket(struct ring *ring, int fd)
918 {
919         munmap(ring->map, ring->req.tp_block_size * ring->req.tp_block_nr);
920         free(ring->rd);
921         close(fd);
922 }
923 
924 int main(int argc, char **argp)
925 {
926         int fd, err;
927         socklen_t len;
928         struct ring ring;
929         struct pollfd pfd;
930         unsigned int block_num = 0, blocks = 64;
931         struct block_desc *pbd;
932         struct tpacket_stats_v3 stats;
933 
934         if (argc != 2) {
935                 fprintf(stderr, "Usage: %s INTERFACE\n", argp[0]);
936                 return EXIT_FAILURE;
937         }
938 
939         signal(SIGINT, sighandler);
940 
941         memset(&ring, 0, sizeof(ring));
942         fd = setup_socket(&ring, argp[argc - 1]);
943         assert(fd > 0);
944 
945         memset(&pfd, 0, sizeof(pfd));
946         pfd.fd = fd;
947         pfd.events = POLLIN | POLLERR;
948         pfd.revents = 0;
949 
950         while (likely(!sigint)) {
951                 pbd = (struct block_desc *) ring.rd[block_num].iov_base;
952 
953                 if ((pbd->h1.block_status & TP_STATUS_USER) == 0) {
954                         poll(&pfd, 1, -1);
955                         continue;
956                 }
957 
958                 walk_block(pbd, block_num);
959                 flush_block(pbd);
960                 block_num = (block_num + 1) % blocks;
961         }
962 
963         len = sizeof(stats);
964         err = getsockopt(fd, SOL_PACKET, PACKET_STATISTICS, &stats, &len);
965         if (err < 0) {
966                 perror("getsockopt");
967                 exit(1);
968         }
969 
970         fflush(stdout);
971         printf("\nReceived %u packets, %lu bytes, %u dropped, freeze_q_cnt: %u\n",
972                stats.tp_packets, bytes_total, stats.tp_drops,
973                stats.tp_freeze_q_cnt);
974 
975         teardown_socket(&ring, fd);
976         return 0;
977 }
978 
979 -------------------------------------------------------------------------------
980 + PACKET_QDISC_BYPASS
981 -------------------------------------------------------------------------------
982 
983 If there is a requirement to load the network with many packets in a similar
984 fashion as pktgen does, you might set the following option after socket
985 creation:
986 
987     int one = 1;
988     setsockopt(fd, SOL_PACKET, PACKET_QDISC_BYPASS, &one, sizeof(one));
989 
990 This has the side-effect, that packets sent through PF_PACKET will bypass the
991 kernel's qdisc layer and are forcedly pushed to the driver directly. Meaning,
992 packet are not buffered, tc disciplines are ignored, increased loss can occur
993 and such packets are also not visible to other PF_PACKET sockets anymore. So,
994 you have been warned; generally, this can be useful for stress testing various
995 components of a system.
996 
997 On default, PACKET_QDISC_BYPASS is disabled and needs to be explicitly enabled
998 on PF_PACKET sockets.
999 
1000 -------------------------------------------------------------------------------
1001 + PACKET_TIMESTAMP
1002 -------------------------------------------------------------------------------
1003 
1004 The PACKET_TIMESTAMP setting determines the source of the timestamp in
1005 the packet meta information for mmap(2)ed RX_RING and TX_RINGs.  If your
1006 NIC is capable of timestamping packets in hardware, you can request those
1007 hardware timestamps to be used. Note: you may need to enable the generation
1008 of hardware timestamps with SIOCSHWTSTAMP (see related information from
1009 Documentation/networking/timestamping.txt).
1010 
1011 PACKET_TIMESTAMP accepts the same integer bit field as
1012 SO_TIMESTAMPING.  However, only the SOF_TIMESTAMPING_SYS_HARDWARE
1013 and SOF_TIMESTAMPING_RAW_HARDWARE values are recognized by
1014 PACKET_TIMESTAMP.  SOF_TIMESTAMPING_SYS_HARDWARE takes precedence over
1015 SOF_TIMESTAMPING_RAW_HARDWARE if both bits are set.
1016 
1017     int req = 0;
1018     req |= SOF_TIMESTAMPING_SYS_HARDWARE;
1019     setsockopt(fd, SOL_PACKET, PACKET_TIMESTAMP, (void *) &req, sizeof(req))
1020 
1021 For the mmap(2)ed ring buffers, such timestamps are stored in the
1022 tpacket{,2,3}_hdr structure's tp_sec and tp_{n,u}sec members. To determine
1023 what kind of timestamp has been reported, the tp_status field is binary |'ed
1024 with the following possible bits ...
1025 
1026     TP_STATUS_TS_SYS_HARDWARE
1027     TP_STATUS_TS_RAW_HARDWARE
1028     TP_STATUS_TS_SOFTWARE
1029 
1030 ... that are equivalent to its SOF_TIMESTAMPING_* counterparts. For the
1031 RX_RING, if none of those 3 are set (i.e. PACKET_TIMESTAMP is not set),
1032 then this means that a software fallback was invoked *within* PF_PACKET's
1033 processing code (less precise).
1034 
1035 Getting timestamps for the TX_RING works as follows: i) fill the ring frames,
1036 ii) call sendto() e.g. in blocking mode, iii) wait for status of relevant
1037 frames to be updated resp. the frame handed over to the application, iv) walk
1038 through the frames to pick up the individual hw/sw timestamps.
1039 
1040 Only (!) if transmit timestamping is enabled, then these bits are combined
1041 with binary | with TP_STATUS_AVAILABLE, so you must check for that in your
1042 application (e.g. !(tp_status & (TP_STATUS_SEND_REQUEST | TP_STATUS_SENDING))
1043 in a first step to see if the frame belongs to the application, and then
1044 one can extract the type of timestamp in a second step from tp_status)!
1045 
1046 If you don't care about them, thus having it disabled, checking for
1047 TP_STATUS_AVAILABLE resp. TP_STATUS_WRONG_FORMAT is sufficient. If in the
1048 TX_RING part only TP_STATUS_AVAILABLE is set, then the tp_sec and tp_{n,u}sec
1049 members do not contain a valid value. For TX_RINGs, by default no timestamp
1050 is generated!
1051 
1052 See include/linux/net_tstamp.h and Documentation/networking/timestamping
1053 for more information on hardware timestamps.
1054 
1055 -------------------------------------------------------------------------------
1056 + Miscellaneous bits
1057 -------------------------------------------------------------------------------
1058 
1059 - Packet sockets work well together with Linux socket filters, thus you also
1060   might want to have a look at Documentation/networking/filter.txt
1061 
1062 --------------------------------------------------------------------------------
1063 + THANKS
1064 --------------------------------------------------------------------------------
1065    
1066    Jesse Brandeburg, for fixing my grammathical/spelling errors
1067 

This page was automatically generated by LXR 0.3.1 (source).  •  Linux is a registered trademark of Linus Torvalds  •  Contact us