GNU Linux-libre 4.14.266-gnu1
[releases.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 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          (1 << 1)
444      #define TP_STATUS_LOSING        (1 << 2)
445      #define TP_STATUS_CSUMNOTREADY  (1 << 3)
446      #define TP_STATUS_CSUM_VALID    (1 << 7)
447
448 TP_STATUS_COPY        : This flag indicates that the frame (and associated
449                         meta information) has been truncated because it's 
450                         larger than tp_frame_size. This packet can be 
451                         read entirely with recvfrom().
452                         
453                         In order to make this work it must to be
454                         enabled previously with setsockopt() and 
455                         the PACKET_COPY_THRESH option. 
456
457                         The number of frames that can be buffered to
458                         be read with recvfrom is limited like a normal socket.
459                         See the SO_RCVBUF option in the socket (7) man page.
460
461 TP_STATUS_LOSING      : indicates there were packet drops from last time 
462                         statistics where checked with getsockopt() and
463                         the PACKET_STATISTICS option.
464
465 TP_STATUS_CSUMNOTREADY: currently it's used for outgoing IP packets which 
466                         its checksum will be done in hardware. So while
467                         reading the packet we should not try to check the 
468                         checksum. 
469
470 TP_STATUS_CSUM_VALID  : This flag indicates that at least the transport
471                         header checksum of the packet has been already
472                         validated on the kernel side. If the flag is not set
473                         then we are free to check the checksum by ourselves
474                         provided that TP_STATUS_CSUMNOTREADY is also not set.
475
476 for convenience there are also the following defines:
477
478      #define TP_STATUS_KERNEL        0
479      #define TP_STATUS_USER          1
480
481 The kernel initializes all frames to TP_STATUS_KERNEL, when the kernel
482 receives a packet it puts in the buffer and updates the status with
483 at least the TP_STATUS_USER flag. Then the user can read the packet,
484 once the packet is read the user must zero the status field, so the kernel 
485 can use again that frame buffer.
486
487 The user can use poll (any other variant should apply too) to check if new
488 packets are in the ring:
489
490     struct pollfd pfd;
491
492     pfd.fd = fd;
493     pfd.revents = 0;
494     pfd.events = POLLIN|POLLRDNORM|POLLERR;
495
496     if (status == TP_STATUS_KERNEL)
497         retval = poll(&pfd, 1, timeout);
498
499 It doesn't incur in a race condition to first check the status value and 
500 then poll for frames.
501
502 ++ Transmission process
503 Those defines are also used for transmission:
504
505      #define TP_STATUS_AVAILABLE        0 // Frame is available
506      #define TP_STATUS_SEND_REQUEST     1 // Frame will be sent on next send()
507      #define TP_STATUS_SENDING          2 // Frame is currently in transmission
508      #define TP_STATUS_WRONG_FORMAT     4 // Frame format is not correct
509
510 First, the kernel initializes all frames to TP_STATUS_AVAILABLE. To send a
511 packet, the user fills a data buffer of an available frame, sets tp_len to
512 current data buffer size and sets its status field to TP_STATUS_SEND_REQUEST.
513 This can be done on multiple frames. Once the user is ready to transmit, it
514 calls send(). Then all buffers with status equal to TP_STATUS_SEND_REQUEST are
515 forwarded to the network device. The kernel updates each status of sent
516 frames with TP_STATUS_SENDING until the end of transfer.
517 At the end of each transfer, buffer status returns to TP_STATUS_AVAILABLE.
518
519     header->tp_len = in_i_size;
520     header->tp_status = TP_STATUS_SEND_REQUEST;
521     retval = send(this->socket, NULL, 0, 0);
522
523 The user can also use poll() to check if a buffer is available:
524 (status == TP_STATUS_SENDING)
525
526     struct pollfd pfd;
527     pfd.fd = fd;
528     pfd.revents = 0;
529     pfd.events = POLLOUT;
530     retval = poll(&pfd, 1, timeout);
531
532 -------------------------------------------------------------------------------
533 + What TPACKET versions are available and when to use them?
534 -------------------------------------------------------------------------------
535
536  int val = tpacket_version;
537  setsockopt(fd, SOL_PACKET, PACKET_VERSION, &val, sizeof(val));
538  getsockopt(fd, SOL_PACKET, PACKET_VERSION, &val, sizeof(val));
539
540 where 'tpacket_version' can be TPACKET_V1 (default), TPACKET_V2, TPACKET_V3.
541
542 TPACKET_V1:
543         - Default if not otherwise specified by setsockopt(2)
544         - RX_RING, TX_RING available
545
546 TPACKET_V1 --> TPACKET_V2:
547         - Made 64 bit clean due to unsigned long usage in TPACKET_V1
548           structures, thus this also works on 64 bit kernel with 32 bit
549           userspace and the like
550         - Timestamp resolution in nanoseconds instead of microseconds
551         - RX_RING, TX_RING available
552         - VLAN metadata information available for packets
553           (TP_STATUS_VLAN_VALID, TP_STATUS_VLAN_TPID_VALID),
554           in the tpacket2_hdr structure:
555                 - TP_STATUS_VLAN_VALID bit being set into the tp_status field indicates
556                   that the tp_vlan_tci field has valid VLAN TCI value
557                 - TP_STATUS_VLAN_TPID_VALID bit being set into the tp_status field
558                   indicates that the tp_vlan_tpid field has valid VLAN TPID value
559         - How to switch to TPACKET_V2:
560                 1. Replace struct tpacket_hdr by struct tpacket2_hdr
561                 2. Query header len and save
562                 3. Set protocol version to 2, set up ring as usual
563                 4. For getting the sockaddr_ll,
564                    use (void *)hdr + TPACKET_ALIGN(hdrlen) instead of
565                    (void *)hdr + TPACKET_ALIGN(sizeof(struct tpacket_hdr))
566
567 TPACKET_V2 --> TPACKET_V3:
568         - Flexible buffer implementation for RX_RING:
569                 1. Blocks can be configured with non-static frame-size
570                 2. Read/poll is at a block-level (as opposed to packet-level)
571                 3. Added poll timeout to avoid indefinite user-space wait
572                    on idle links
573                 4. Added user-configurable knobs:
574                         4.1 block::timeout
575                         4.2 tpkt_hdr::sk_rxhash
576         - RX Hash data available in user space
577         - TX_RING semantics are conceptually similar to TPACKET_V2;
578           use tpacket3_hdr instead of tpacket2_hdr, and TPACKET3_HDRLEN
579           instead of TPACKET2_HDRLEN. In the current implementation,
580           the tp_next_offset field in the tpacket3_hdr MUST be set to
581           zero, indicating that the ring does not hold variable sized frames.
582           Packets with non-zero values of tp_next_offset will be dropped.
583
584 -------------------------------------------------------------------------------
585 + AF_PACKET fanout mode
586 -------------------------------------------------------------------------------
587
588 In the AF_PACKET fanout mode, packet reception can be load balanced among
589 processes. This also works in combination with mmap(2) on packet sockets.
590
591 Currently implemented fanout policies are:
592
593   - PACKET_FANOUT_HASH: schedule to socket by skb's packet hash
594   - PACKET_FANOUT_LB: schedule to socket by round-robin
595   - PACKET_FANOUT_CPU: schedule to socket by CPU packet arrives on
596   - PACKET_FANOUT_RND: schedule to socket by random selection
597   - PACKET_FANOUT_ROLLOVER: if one socket is full, rollover to another
598   - PACKET_FANOUT_QM: schedule to socket by skbs recorded queue_mapping
599
600 Minimal example code by David S. Miller (try things like "./test eth0 hash",
601 "./test eth0 lb", etc.):
602
603 #include <stddef.h>
604 #include <stdlib.h>
605 #include <stdio.h>
606 #include <string.h>
607
608 #include <sys/types.h>
609 #include <sys/wait.h>
610 #include <sys/socket.h>
611 #include <sys/ioctl.h>
612
613 #include <unistd.h>
614
615 #include <linux/if_ether.h>
616 #include <linux/if_packet.h>
617
618 #include <net/if.h>
619
620 static const char *device_name;
621 static int fanout_type;
622 static int fanout_id;
623
624 #ifndef PACKET_FANOUT
625 # define PACKET_FANOUT                  18
626 # define PACKET_FANOUT_HASH             0
627 # define PACKET_FANOUT_LB               1
628 #endif
629
630 static int setup_socket(void)
631 {
632         int err, fd = socket(AF_PACKET, SOCK_RAW, htons(ETH_P_IP));
633         struct sockaddr_ll ll;
634         struct ifreq ifr;
635         int fanout_arg;
636
637         if (fd < 0) {
638                 perror("socket");
639                 return EXIT_FAILURE;
640         }
641
642         memset(&ifr, 0, sizeof(ifr));
643         strcpy(ifr.ifr_name, device_name);
644         err = ioctl(fd, SIOCGIFINDEX, &ifr);
645         if (err < 0) {
646                 perror("SIOCGIFINDEX");
647                 return EXIT_FAILURE;
648         }
649
650         memset(&ll, 0, sizeof(ll));
651         ll.sll_family = AF_PACKET;
652         ll.sll_ifindex = ifr.ifr_ifindex;
653         err = bind(fd, (struct sockaddr *) &ll, sizeof(ll));
654         if (err < 0) {
655                 perror("bind");
656                 return EXIT_FAILURE;
657         }
658
659         fanout_arg = (fanout_id | (fanout_type << 16));
660         err = setsockopt(fd, SOL_PACKET, PACKET_FANOUT,
661                          &fanout_arg, sizeof(fanout_arg));
662         if (err) {
663                 perror("setsockopt");
664                 return EXIT_FAILURE;
665         }
666
667         return fd;
668 }
669
670 static void fanout_thread(void)
671 {
672         int fd = setup_socket();
673         int limit = 10000;
674
675         if (fd < 0)
676                 exit(fd);
677
678         while (limit-- > 0) {
679                 char buf[1600];
680                 int err;
681
682                 err = read(fd, buf, sizeof(buf));
683                 if (err < 0) {
684                         perror("read");
685                         exit(EXIT_FAILURE);
686                 }
687                 if ((limit % 10) == 0)
688                         fprintf(stdout, "(%d) \n", getpid());
689         }
690
691         fprintf(stdout, "%d: Received 10000 packets\n", getpid());
692
693         close(fd);
694         exit(0);
695 }
696
697 int main(int argc, char **argp)
698 {
699         int fd, err;
700         int i;
701
702         if (argc != 3) {
703                 fprintf(stderr, "Usage: %s INTERFACE {hash|lb}\n", argp[0]);
704                 return EXIT_FAILURE;
705         }
706
707         if (!strcmp(argp[2], "hash"))
708                 fanout_type = PACKET_FANOUT_HASH;
709         else if (!strcmp(argp[2], "lb"))
710                 fanout_type = PACKET_FANOUT_LB;
711         else {
712                 fprintf(stderr, "Unknown fanout type [%s]\n", argp[2]);
713                 exit(EXIT_FAILURE);
714         }
715
716         device_name = argp[1];
717         fanout_id = getpid() & 0xffff;
718
719         for (i = 0; i < 4; i++) {
720                 pid_t pid = fork();
721
722                 switch (pid) {
723                 case 0:
724                         fanout_thread();
725
726                 case -1:
727                         perror("fork");
728                         exit(EXIT_FAILURE);
729                 }
730         }
731
732         for (i = 0; i < 4; i++) {
733                 int status;
734
735                 wait(&status);
736         }
737
738         return 0;
739 }
740
741 -------------------------------------------------------------------------------
742 + AF_PACKET TPACKET_V3 example
743 -------------------------------------------------------------------------------
744
745 AF_PACKET's TPACKET_V3 ring buffer can be configured to use non-static frame
746 sizes by doing it's own memory management. It is based on blocks where polling
747 works on a per block basis instead of per ring as in TPACKET_V2 and predecessor.
748
749 It is said that TPACKET_V3 brings the following benefits:
750  *) ~15 - 20% reduction in CPU-usage
751  *) ~20% increase in packet capture rate
752  *) ~2x increase in packet density
753  *) Port aggregation analysis
754  *) Non static frame size to capture entire packet payload
755
756 So it seems to be a good candidate to be used with packet fanout.
757
758 Minimal example code by Daniel Borkmann based on Chetan Loke's lolpcap (compile
759 it with gcc -Wall -O2 blob.c, and try things like "./a.out eth0", etc.):
760
761 /* Written from scratch, but kernel-to-user space API usage
762  * dissected from lolpcap:
763  *  Copyright 2011, Chetan Loke <loke.chetan@gmail.com>
764  *  License: GPL, version 2.0
765  */
766
767 #include <stdio.h>
768 #include <stdlib.h>
769 #include <stdint.h>
770 #include <string.h>
771 #include <assert.h>
772 #include <net/if.h>
773 #include <arpa/inet.h>
774 #include <netdb.h>
775 #include <poll.h>
776 #include <unistd.h>
777 #include <signal.h>
778 #include <inttypes.h>
779 #include <sys/socket.h>
780 #include <sys/mman.h>
781 #include <linux/if_packet.h>
782 #include <linux/if_ether.h>
783 #include <linux/ip.h>
784
785 #ifndef likely
786 # define likely(x)              __builtin_expect(!!(x), 1)
787 #endif
788 #ifndef unlikely
789 # define unlikely(x)            __builtin_expect(!!(x), 0)
790 #endif
791
792 struct block_desc {
793         uint32_t version;
794         uint32_t offset_to_priv;
795         struct tpacket_hdr_v1 h1;
796 };
797
798 struct ring {
799         struct iovec *rd;
800         uint8_t *map;
801         struct tpacket_req3 req;
802 };
803
804 static unsigned long packets_total = 0, bytes_total = 0;
805 static sig_atomic_t sigint = 0;
806
807 static void sighandler(int num)
808 {
809         sigint = 1;
810 }
811
812 static int setup_socket(struct ring *ring, char *netdev)
813 {
814         int err, i, fd, v = TPACKET_V3;
815         struct sockaddr_ll ll;
816         unsigned int blocksiz = 1 << 22, framesiz = 1 << 11;
817         unsigned int blocknum = 64;
818
819         fd = socket(AF_PACKET, SOCK_RAW, htons(ETH_P_ALL));
820         if (fd < 0) {
821                 perror("socket");
822                 exit(1);
823         }
824
825         err = setsockopt(fd, SOL_PACKET, PACKET_VERSION, &v, sizeof(v));
826         if (err < 0) {
827                 perror("setsockopt");
828                 exit(1);
829         }
830
831         memset(&ring->req, 0, sizeof(ring->req));
832         ring->req.tp_block_size = blocksiz;
833         ring->req.tp_frame_size = framesiz;
834         ring->req.tp_block_nr = blocknum;
835         ring->req.tp_frame_nr = (blocksiz * blocknum) / framesiz;
836         ring->req.tp_retire_blk_tov = 60;
837         ring->req.tp_feature_req_word = TP_FT_REQ_FILL_RXHASH;
838
839         err = setsockopt(fd, SOL_PACKET, PACKET_RX_RING, &ring->req,
840                          sizeof(ring->req));
841         if (err < 0) {
842                 perror("setsockopt");
843                 exit(1);
844         }
845
846         ring->map = mmap(NULL, ring->req.tp_block_size * ring->req.tp_block_nr,
847                          PROT_READ | PROT_WRITE, MAP_SHARED | MAP_LOCKED, fd, 0);
848         if (ring->map == MAP_FAILED) {
849                 perror("mmap");
850                 exit(1);
851         }
852
853         ring->rd = malloc(ring->req.tp_block_nr * sizeof(*ring->rd));
854         assert(ring->rd);
855         for (i = 0; i < ring->req.tp_block_nr; ++i) {
856                 ring->rd[i].iov_base = ring->map + (i * ring->req.tp_block_size);
857                 ring->rd[i].iov_len = ring->req.tp_block_size;
858         }
859
860         memset(&ll, 0, sizeof(ll));
861         ll.sll_family = PF_PACKET;
862         ll.sll_protocol = htons(ETH_P_ALL);
863         ll.sll_ifindex = if_nametoindex(netdev);
864         ll.sll_hatype = 0;
865         ll.sll_pkttype = 0;
866         ll.sll_halen = 0;
867
868         err = bind(fd, (struct sockaddr *) &ll, sizeof(ll));
869         if (err < 0) {
870                 perror("bind");
871                 exit(1);
872         }
873
874         return fd;
875 }
876
877 static void display(struct tpacket3_hdr *ppd)
878 {
879         struct ethhdr *eth = (struct ethhdr *) ((uint8_t *) ppd + ppd->tp_mac);
880         struct iphdr *ip = (struct iphdr *) ((uint8_t *) eth + ETH_HLEN);
881
882         if (eth->h_proto == htons(ETH_P_IP)) {
883                 struct sockaddr_in ss, sd;
884                 char sbuff[NI_MAXHOST], dbuff[NI_MAXHOST];
885
886                 memset(&ss, 0, sizeof(ss));
887                 ss.sin_family = PF_INET;
888                 ss.sin_addr.s_addr = ip->saddr;
889                 getnameinfo((struct sockaddr *) &ss, sizeof(ss),
890                             sbuff, sizeof(sbuff), NULL, 0, NI_NUMERICHOST);
891
892                 memset(&sd, 0, sizeof(sd));
893                 sd.sin_family = PF_INET;
894                 sd.sin_addr.s_addr = ip->daddr;
895                 getnameinfo((struct sockaddr *) &sd, sizeof(sd),
896                             dbuff, sizeof(dbuff), NULL, 0, NI_NUMERICHOST);
897
898                 printf("%s -> %s, ", sbuff, dbuff);
899         }
900
901         printf("rxhash: 0x%x\n", ppd->hv1.tp_rxhash);
902 }
903
904 static void walk_block(struct block_desc *pbd, const int block_num)
905 {
906         int num_pkts = pbd->h1.num_pkts, i;
907         unsigned long bytes = 0;
908         struct tpacket3_hdr *ppd;
909
910         ppd = (struct tpacket3_hdr *) ((uint8_t *) pbd +
911                                        pbd->h1.offset_to_first_pkt);
912         for (i = 0; i < num_pkts; ++i) {
913                 bytes += ppd->tp_snaplen;
914                 display(ppd);
915
916                 ppd = (struct tpacket3_hdr *) ((uint8_t *) ppd +
917                                                ppd->tp_next_offset);
918         }
919
920         packets_total += num_pkts;
921         bytes_total += bytes;
922 }
923
924 static void flush_block(struct block_desc *pbd)
925 {
926         pbd->h1.block_status = TP_STATUS_KERNEL;
927 }
928
929 static void teardown_socket(struct ring *ring, int fd)
930 {
931         munmap(ring->map, ring->req.tp_block_size * ring->req.tp_block_nr);
932         free(ring->rd);
933         close(fd);
934 }
935
936 int main(int argc, char **argp)
937 {
938         int fd, err;
939         socklen_t len;
940         struct ring ring;
941         struct pollfd pfd;
942         unsigned int block_num = 0, blocks = 64;
943         struct block_desc *pbd;
944         struct tpacket_stats_v3 stats;
945
946         if (argc != 2) {
947                 fprintf(stderr, "Usage: %s INTERFACE\n", argp[0]);
948                 return EXIT_FAILURE;
949         }
950
951         signal(SIGINT, sighandler);
952
953         memset(&ring, 0, sizeof(ring));
954         fd = setup_socket(&ring, argp[argc - 1]);
955         assert(fd > 0);
956
957         memset(&pfd, 0, sizeof(pfd));
958         pfd.fd = fd;
959         pfd.events = POLLIN | POLLERR;
960         pfd.revents = 0;
961
962         while (likely(!sigint)) {
963                 pbd = (struct block_desc *) ring.rd[block_num].iov_base;
964
965                 if ((pbd->h1.block_status & TP_STATUS_USER) == 0) {
966                         poll(&pfd, 1, -1);
967                         continue;
968                 }
969
970                 walk_block(pbd, block_num);
971                 flush_block(pbd);
972                 block_num = (block_num + 1) % blocks;
973         }
974
975         len = sizeof(stats);
976         err = getsockopt(fd, SOL_PACKET, PACKET_STATISTICS, &stats, &len);
977         if (err < 0) {
978                 perror("getsockopt");
979                 exit(1);
980         }
981
982         fflush(stdout);
983         printf("\nReceived %u packets, %lu bytes, %u dropped, freeze_q_cnt: %u\n",
984                stats.tp_packets, bytes_total, stats.tp_drops,
985                stats.tp_freeze_q_cnt);
986
987         teardown_socket(&ring, fd);
988         return 0;
989 }
990
991 -------------------------------------------------------------------------------
992 + PACKET_QDISC_BYPASS
993 -------------------------------------------------------------------------------
994
995 If there is a requirement to load the network with many packets in a similar
996 fashion as pktgen does, you might set the following option after socket
997 creation:
998
999     int one = 1;
1000     setsockopt(fd, SOL_PACKET, PACKET_QDISC_BYPASS, &one, sizeof(one));
1001
1002 This has the side-effect, that packets sent through PF_PACKET will bypass the
1003 kernel's qdisc layer and are forcedly pushed to the driver directly. Meaning,
1004 packet are not buffered, tc disciplines are ignored, increased loss can occur
1005 and such packets are also not visible to other PF_PACKET sockets anymore. So,
1006 you have been warned; generally, this can be useful for stress testing various
1007 components of a system.
1008
1009 On default, PACKET_QDISC_BYPASS is disabled and needs to be explicitly enabled
1010 on PF_PACKET sockets.
1011
1012 -------------------------------------------------------------------------------
1013 + PACKET_TIMESTAMP
1014 -------------------------------------------------------------------------------
1015
1016 The PACKET_TIMESTAMP setting determines the source of the timestamp in
1017 the packet meta information for mmap(2)ed RX_RING and TX_RINGs.  If your
1018 NIC is capable of timestamping packets in hardware, you can request those
1019 hardware timestamps to be used. Note: you may need to enable the generation
1020 of hardware timestamps with SIOCSHWTSTAMP (see related information from
1021 Documentation/networking/timestamping.txt).
1022
1023 PACKET_TIMESTAMP accepts the same integer bit field as SO_TIMESTAMPING:
1024
1025     int req = SOF_TIMESTAMPING_RAW_HARDWARE;
1026     setsockopt(fd, SOL_PACKET, PACKET_TIMESTAMP, (void *) &req, sizeof(req))
1027
1028 For the mmap(2)ed ring buffers, such timestamps are stored in the
1029 tpacket{,2,3}_hdr structure's tp_sec and tp_{n,u}sec members. To determine
1030 what kind of timestamp has been reported, the tp_status field is binary |'ed
1031 with the following possible bits ...
1032
1033     TP_STATUS_TS_RAW_HARDWARE
1034     TP_STATUS_TS_SOFTWARE
1035
1036 ... that are equivalent to its SOF_TIMESTAMPING_* counterparts. For the
1037 RX_RING, if neither is set (i.e. PACKET_TIMESTAMP is not set), then a
1038 software fallback was invoked *within* PF_PACKET's processing code (less
1039 precise).
1040
1041 Getting timestamps for the TX_RING works as follows: i) fill the ring frames,
1042 ii) call sendto() e.g. in blocking mode, iii) wait for status of relevant
1043 frames to be updated resp. the frame handed over to the application, iv) walk
1044 through the frames to pick up the individual hw/sw timestamps.
1045
1046 Only (!) if transmit timestamping is enabled, then these bits are combined
1047 with binary | with TP_STATUS_AVAILABLE, so you must check for that in your
1048 application (e.g. !(tp_status & (TP_STATUS_SEND_REQUEST | TP_STATUS_SENDING))
1049 in a first step to see if the frame belongs to the application, and then
1050 one can extract the type of timestamp in a second step from tp_status)!
1051
1052 If you don't care about them, thus having it disabled, checking for
1053 TP_STATUS_AVAILABLE resp. TP_STATUS_WRONG_FORMAT is sufficient. If in the
1054 TX_RING part only TP_STATUS_AVAILABLE is set, then the tp_sec and tp_{n,u}sec
1055 members do not contain a valid value. For TX_RINGs, by default no timestamp
1056 is generated!
1057
1058 See include/linux/net_tstamp.h and Documentation/networking/timestamping
1059 for more information on hardware timestamps.
1060
1061 -------------------------------------------------------------------------------
1062 + Miscellaneous bits
1063 -------------------------------------------------------------------------------
1064
1065 - Packet sockets work well together with Linux socket filters, thus you also
1066   might want to have a look at Documentation/networking/filter.txt
1067
1068 --------------------------------------------------------------------------------
1069 + THANKS
1070 --------------------------------------------------------------------------------
1071    
1072    Jesse Brandeburg, for fixing my grammathical/spelling errors
1073