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