Version:  2.0.40 2.2.26 2.4.37 3.5 3.6 3.7 3.8 3.9 3.10 3.11 3.12 3.13 3.14 3.15 3.16 3.17 3.18 3.19 4.0 4.1

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          (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:
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         - Currently only RX_RING available
578 
579 -------------------------------------------------------------------------------
580 + AF_PACKET fanout mode
581 -------------------------------------------------------------------------------
582 
583 In the AF_PACKET fanout mode, packet reception can be load balanced among
584 processes. This also works in combination with mmap(2) on packet sockets.
585 
586 Currently implemented fanout policies are:
587 
588   - PACKET_FANOUT_HASH: schedule to socket by skb's packet hash
589   - PACKET_FANOUT_LB: schedule to socket by round-robin
590   - PACKET_FANOUT_CPU: schedule to socket by CPU packet arrives on
591   - PACKET_FANOUT_RND: schedule to socket by random selection
592   - PACKET_FANOUT_ROLLOVER: if one socket is full, rollover to another
593   - PACKET_FANOUT_QM: schedule to socket by skbs recorded queue_mapping
594 
595 Minimal example code by David S. Miller (try things like "./test eth0 hash",
596 "./test eth0 lb", etc.):
597 
598 #include <stddef.h>
599 #include <stdlib.h>
600 #include <stdio.h>
601 #include <string.h>
602 
603 #include <sys/types.h>
604 #include <sys/wait.h>
605 #include <sys/socket.h>
606 #include <sys/ioctl.h>
607 
608 #include <unistd.h>
609 
610 #include <linux/if_ether.h>
611 #include <linux/if_packet.h>
612 
613 #include <net/if.h>
614 
615 static const char *device_name;
616 static int fanout_type;
617 static int fanout_id;
618 
619 #ifndef PACKET_FANOUT
620 # define PACKET_FANOUT                  18
621 # define PACKET_FANOUT_HASH             0
622 # define PACKET_FANOUT_LB               1
623 #endif
624 
625 static int setup_socket(void)
626 {
627         int err, fd = socket(AF_PACKET, SOCK_RAW, htons(ETH_P_IP));
628         struct sockaddr_ll ll;
629         struct ifreq ifr;
630         int fanout_arg;
631 
632         if (fd < 0) {
633                 perror("socket");
634                 return EXIT_FAILURE;
635         }
636 
637         memset(&ifr, 0, sizeof(ifr));
638         strcpy(ifr.ifr_name, device_name);
639         err = ioctl(fd, SIOCGIFINDEX, &ifr);
640         if (err < 0) {
641                 perror("SIOCGIFINDEX");
642                 return EXIT_FAILURE;
643         }
644 
645         memset(&ll, 0, sizeof(ll));
646         ll.sll_family = AF_PACKET;
647         ll.sll_ifindex = ifr.ifr_ifindex;
648         err = bind(fd, (struct sockaddr *) &ll, sizeof(ll));
649         if (err < 0) {
650                 perror("bind");
651                 return EXIT_FAILURE;
652         }
653 
654         fanout_arg = (fanout_id | (fanout_type << 16));
655         err = setsockopt(fd, SOL_PACKET, PACKET_FANOUT,
656                          &fanout_arg, sizeof(fanout_arg));
657         if (err) {
658                 perror("setsockopt");
659                 return EXIT_FAILURE;
660         }
661 
662         return fd;
663 }
664 
665 static void fanout_thread(void)
666 {
667         int fd = setup_socket();
668         int limit = 10000;
669 
670         if (fd < 0)
671                 exit(fd);
672 
673         while (limit-- > 0) {
674                 char buf[1600];
675                 int err;
676 
677                 err = read(fd, buf, sizeof(buf));
678                 if (err < 0) {
679                         perror("read");
680                         exit(EXIT_FAILURE);
681                 }
682                 if ((limit % 10) == 0)
683                         fprintf(stdout, "(%d) \n", getpid());
684         }
685 
686         fprintf(stdout, "%d: Received 10000 packets\n", getpid());
687 
688         close(fd);
689         exit(0);
690 }
691 
692 int main(int argc, char **argp)
693 {
694         int fd, err;
695         int i;
696 
697         if (argc != 3) {
698                 fprintf(stderr, "Usage: %s INTERFACE {hash|lb}\n", argp[0]);
699                 return EXIT_FAILURE;
700         }
701 
702         if (!strcmp(argp[2], "hash"))
703                 fanout_type = PACKET_FANOUT_HASH;
704         else if (!strcmp(argp[2], "lb"))
705                 fanout_type = PACKET_FANOUT_LB;
706         else {
707                 fprintf(stderr, "Unknown fanout type [%s]\n", argp[2]);
708                 exit(EXIT_FAILURE);
709         }
710 
711         device_name = argp[1];
712         fanout_id = getpid() & 0xffff;
713 
714         for (i = 0; i < 4; i++) {
715                 pid_t pid = fork();
716 
717                 switch (pid) {
718                 case 0:
719                         fanout_thread();
720 
721                 case -1:
722                         perror("fork");
723                         exit(EXIT_FAILURE);
724                 }
725         }
726 
727         for (i = 0; i < 4; i++) {
728                 int status;
729 
730                 wait(&status);
731         }
732 
733         return 0;
734 }
735 
736 -------------------------------------------------------------------------------
737 + AF_PACKET TPACKET_V3 example
738 -------------------------------------------------------------------------------
739 
740 AF_PACKET's TPACKET_V3 ring buffer can be configured to use non-static frame
741 sizes by doing it's own memory management. It is based on blocks where polling
742 works on a per block basis instead of per ring as in TPACKET_V2 and predecessor.
743 
744 It is said that TPACKET_V3 brings the following benefits:
745  *) ~15 - 20% reduction in CPU-usage
746  *) ~20% increase in packet capture rate
747  *) ~2x increase in packet density
748  *) Port aggregation analysis
749  *) Non static frame size to capture entire packet payload
750 
751 So it seems to be a good candidate to be used with packet fanout.
752 
753 Minimal example code by Daniel Borkmann based on Chetan Loke's lolpcap (compile
754 it with gcc -Wall -O2 blob.c, and try things like "./a.out eth0", etc.):
755 
756 /* Written from scratch, but kernel-to-user space API usage
757  * dissected from lolpcap:
758  *  Copyright 2011, Chetan Loke <loke.chetan@gmail.com>
759  *  License: GPL, version 2.0
760  */
761 
762 #include <stdio.h>
763 #include <stdlib.h>
764 #include <stdint.h>
765 #include <string.h>
766 #include <assert.h>
767 #include <net/if.h>
768 #include <arpa/inet.h>
769 #include <netdb.h>
770 #include <poll.h>
771 #include <unistd.h>
772 #include <signal.h>
773 #include <inttypes.h>
774 #include <sys/socket.h>
775 #include <sys/mman.h>
776 #include <linux/if_packet.h>
777 #include <linux/if_ether.h>
778 #include <linux/ip.h>
779 
780 #ifndef likely
781 # define likely(x)              __builtin_expect(!!(x), 1)
782 #endif
783 #ifndef unlikely
784 # define unlikely(x)            __builtin_expect(!!(x), 0)
785 #endif
786 
787 struct block_desc {
788         uint32_t version;
789         uint32_t offset_to_priv;
790         struct tpacket_hdr_v1 h1;
791 };
792 
793 struct ring {
794         struct iovec *rd;
795         uint8_t *map;
796         struct tpacket_req3 req;
797 };
798 
799 static unsigned long packets_total = 0, bytes_total = 0;
800 static sig_atomic_t sigint = 0;
801 
802 static void sighandler(int num)
803 {
804         sigint = 1;
805 }
806 
807 static int setup_socket(struct ring *ring, char *netdev)
808 {
809         int err, i, fd, v = TPACKET_V3;
810         struct sockaddr_ll ll;
811         unsigned int blocksiz = 1 << 22, framesiz = 1 << 11;
812         unsigned int blocknum = 64;
813 
814         fd = socket(AF_PACKET, SOCK_RAW, htons(ETH_P_ALL));
815         if (fd < 0) {
816                 perror("socket");
817                 exit(1);
818         }
819 
820         err = setsockopt(fd, SOL_PACKET, PACKET_VERSION, &v, sizeof(v));
821         if (err < 0) {
822                 perror("setsockopt");
823                 exit(1);
824         }
825 
826         memset(&ring->req, 0, sizeof(ring->req));
827         ring->req.tp_block_size = blocksiz;
828         ring->req.tp_frame_size = framesiz;
829         ring->req.tp_block_nr = blocknum;
830         ring->req.tp_frame_nr = (blocksiz * blocknum) / framesiz;
831         ring->req.tp_retire_blk_tov = 60;
832         ring->req.tp_feature_req_word = TP_FT_REQ_FILL_RXHASH;
833 
834         err = setsockopt(fd, SOL_PACKET, PACKET_RX_RING, &ring->req,
835                          sizeof(ring->req));
836         if (err < 0) {
837                 perror("setsockopt");
838                 exit(1);
839         }
840 
841         ring->map = mmap(NULL, ring->req.tp_block_size * ring->req.tp_block_nr,
842                          PROT_READ | PROT_WRITE, MAP_SHARED | MAP_LOCKED, fd, 0);
843         if (ring->map == MAP_FAILED) {
844                 perror("mmap");
845                 exit(1);
846         }
847 
848         ring->rd = malloc(ring->req.tp_block_nr * sizeof(*ring->rd));
849         assert(ring->rd);
850         for (i = 0; i < ring->req.tp_block_nr; ++i) {
851                 ring->rd[i].iov_base = ring->map + (i * ring->req.tp_block_size);
852                 ring->rd[i].iov_len = ring->req.tp_block_size;
853         }
854 
855         memset(&ll, 0, sizeof(ll));
856         ll.sll_family = PF_PACKET;
857         ll.sll_protocol = htons(ETH_P_ALL);
858         ll.sll_ifindex = if_nametoindex(netdev);
859         ll.sll_hatype = 0;
860         ll.sll_pkttype = 0;
861         ll.sll_halen = 0;
862 
863         err = bind(fd, (struct sockaddr *) &ll, sizeof(ll));
864         if (err < 0) {
865                 perror("bind");
866                 exit(1);
867         }
868 
869         return fd;
870 }
871 
872 static void display(struct tpacket3_hdr *ppd)
873 {
874         struct ethhdr *eth = (struct ethhdr *) ((uint8_t *) ppd + ppd->tp_mac);
875         struct iphdr *ip = (struct iphdr *) ((uint8_t *) eth + ETH_HLEN);
876 
877         if (eth->h_proto == htons(ETH_P_IP)) {
878                 struct sockaddr_in ss, sd;
879                 char sbuff[NI_MAXHOST], dbuff[NI_MAXHOST];
880 
881                 memset(&ss, 0, sizeof(ss));
882                 ss.sin_family = PF_INET;
883                 ss.sin_addr.s_addr = ip->saddr;
884                 getnameinfo((struct sockaddr *) &ss, sizeof(ss),
885                             sbuff, sizeof(sbuff), NULL, 0, NI_NUMERICHOST);
886 
887                 memset(&sd, 0, sizeof(sd));
888                 sd.sin_family = PF_INET;
889                 sd.sin_addr.s_addr = ip->daddr;
890                 getnameinfo((struct sockaddr *) &sd, sizeof(sd),
891                             dbuff, sizeof(dbuff), NULL, 0, NI_NUMERICHOST);
892 
893                 printf("%s -> %s, ", sbuff, dbuff);
894         }
895 
896         printf("rxhash: 0x%x\n", ppd->hv1.tp_rxhash);
897 }
898 
899 static void walk_block(struct block_desc *pbd, const int block_num)
900 {
901         int num_pkts = pbd->h1.num_pkts, i;
902         unsigned long bytes = 0;
903         struct tpacket3_hdr *ppd;
904 
905         ppd = (struct tpacket3_hdr *) ((uint8_t *) pbd +
906                                        pbd->h1.offset_to_first_pkt);
907         for (i = 0; i < num_pkts; ++i) {
908                 bytes += ppd->tp_snaplen;
909                 display(ppd);
910 
911                 ppd = (struct tpacket3_hdr *) ((uint8_t *) ppd +
912                                                ppd->tp_next_offset);
913         }
914 
915         packets_total += num_pkts;
916         bytes_total += bytes;
917 }
918 
919 static void flush_block(struct block_desc *pbd)
920 {
921         pbd->h1.block_status = TP_STATUS_KERNEL;
922 }
923 
924 static void teardown_socket(struct ring *ring, int fd)
925 {
926         munmap(ring->map, ring->req.tp_block_size * ring->req.tp_block_nr);
927         free(ring->rd);
928         close(fd);
929 }
930 
931 int main(int argc, char **argp)
932 {
933         int fd, err;
934         socklen_t len;
935         struct ring ring;
936         struct pollfd pfd;
937         unsigned int block_num = 0, blocks = 64;
938         struct block_desc *pbd;
939         struct tpacket_stats_v3 stats;
940 
941         if (argc != 2) {
942                 fprintf(stderr, "Usage: %s INTERFACE\n", argp[0]);
943                 return EXIT_FAILURE;
944         }
945 
946         signal(SIGINT, sighandler);
947 
948         memset(&ring, 0, sizeof(ring));
949         fd = setup_socket(&ring, argp[argc - 1]);
950         assert(fd > 0);
951 
952         memset(&pfd, 0, sizeof(pfd));
953         pfd.fd = fd;
954         pfd.events = POLLIN | POLLERR;
955         pfd.revents = 0;
956 
957         while (likely(!sigint)) {
958                 pbd = (struct block_desc *) ring.rd[block_num].iov_base;
959 
960                 if ((pbd->h1.block_status & TP_STATUS_USER) == 0) {
961                         poll(&pfd, 1, -1);
962                         continue;
963                 }
964 
965                 walk_block(pbd, block_num);
966                 flush_block(pbd);
967                 block_num = (block_num + 1) % blocks;
968         }
969 
970         len = sizeof(stats);
971         err = getsockopt(fd, SOL_PACKET, PACKET_STATISTICS, &stats, &len);
972         if (err < 0) {
973                 perror("getsockopt");
974                 exit(1);
975         }
976 
977         fflush(stdout);
978         printf("\nReceived %u packets, %lu bytes, %u dropped, freeze_q_cnt: %u\n",
979                stats.tp_packets, bytes_total, stats.tp_drops,
980                stats.tp_freeze_q_cnt);
981 
982         teardown_socket(&ring, fd);
983         return 0;
984 }
985 
986 -------------------------------------------------------------------------------
987 + PACKET_QDISC_BYPASS
988 -------------------------------------------------------------------------------
989 
990 If there is a requirement to load the network with many packets in a similar
991 fashion as pktgen does, you might set the following option after socket
992 creation:
993 
994     int one = 1;
995     setsockopt(fd, SOL_PACKET, PACKET_QDISC_BYPASS, &one, sizeof(one));
996 
997 This has the side-effect, that packets sent through PF_PACKET will bypass the
998 kernel's qdisc layer and are forcedly pushed to the driver directly. Meaning,
999 packet are not buffered, tc disciplines are ignored, increased loss can occur
1000 and such packets are also not visible to other PF_PACKET sockets anymore. So,
1001 you have been warned; generally, this can be useful for stress testing various
1002 components of a system.
1003 
1004 On default, PACKET_QDISC_BYPASS is disabled and needs to be explicitly enabled
1005 on PF_PACKET sockets.
1006 
1007 -------------------------------------------------------------------------------
1008 + PACKET_TIMESTAMP
1009 -------------------------------------------------------------------------------
1010 
1011 The PACKET_TIMESTAMP setting determines the source of the timestamp in
1012 the packet meta information for mmap(2)ed RX_RING and TX_RINGs.  If your
1013 NIC is capable of timestamping packets in hardware, you can request those
1014 hardware timestamps to be used. Note: you may need to enable the generation
1015 of hardware timestamps with SIOCSHWTSTAMP (see related information from
1016 Documentation/networking/timestamping.txt).
1017 
1018 PACKET_TIMESTAMP accepts the same integer bit field as SO_TIMESTAMPING:
1019 
1020     int req = SOF_TIMESTAMPING_RAW_HARDWARE;
1021     setsockopt(fd, SOL_PACKET, PACKET_TIMESTAMP, (void *) &req, sizeof(req))
1022 
1023 For the mmap(2)ed ring buffers, such timestamps are stored in the
1024 tpacket{,2,3}_hdr structure's tp_sec and tp_{n,u}sec members. To determine
1025 what kind of timestamp has been reported, the tp_status field is binary |'ed
1026 with the following possible bits ...
1027 
1028     TP_STATUS_TS_RAW_HARDWARE
1029     TP_STATUS_TS_SOFTWARE
1030 
1031 ... that are equivalent to its SOF_TIMESTAMPING_* counterparts. For the
1032 RX_RING, if neither is set (i.e. PACKET_TIMESTAMP is not set), then a
1033 software fallback was invoked *within* PF_PACKET's processing code (less
1034 precise).
1035 
1036 Getting timestamps for the TX_RING works as follows: i) fill the ring frames,
1037 ii) call sendto() e.g. in blocking mode, iii) wait for status of relevant
1038 frames to be updated resp. the frame handed over to the application, iv) walk
1039 through the frames to pick up the individual hw/sw timestamps.
1040 
1041 Only (!) if transmit timestamping is enabled, then these bits are combined
1042 with binary | with TP_STATUS_AVAILABLE, so you must check for that in your
1043 application (e.g. !(tp_status & (TP_STATUS_SEND_REQUEST | TP_STATUS_SENDING))
1044 in a first step to see if the frame belongs to the application, and then
1045 one can extract the type of timestamp in a second step from tp_status)!
1046 
1047 If you don't care about them, thus having it disabled, checking for
1048 TP_STATUS_AVAILABLE resp. TP_STATUS_WRONG_FORMAT is sufficient. If in the
1049 TX_RING part only TP_STATUS_AVAILABLE is set, then the tp_sec and tp_{n,u}sec
1050 members do not contain a valid value. For TX_RINGs, by default no timestamp
1051 is generated!
1052 
1053 See include/linux/net_tstamp.h and Documentation/networking/timestamping
1054 for more information on hardware timestamps.
1055 
1056 -------------------------------------------------------------------------------
1057 + Miscellaneous bits
1058 -------------------------------------------------------------------------------
1059 
1060 - Packet sockets work well together with Linux socket filters, thus you also
1061   might want to have a look at Documentation/networking/filter.txt
1062 
1063 --------------------------------------------------------------------------------
1064 + THANKS
1065 --------------------------------------------------------------------------------
1066    
1067    Jesse Brandeburg, for fixing my grammathical/spelling errors
1068 

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