Documentation/networking/packet_mmap.txt

1 --------------------------------------------------------------------------------
3 --------------------------------------------------------------------------------
14     http://wiki.gnu-log.net (packet_mmap)
18     Johann Baudy <johann.baudy@gnu-log.net>
20 -------------------------------------------------------------------------------
22 --------------------------------------------------------------------------------
30 configurable circular buffer mapped in user space that can be used to either
35 By using a shared buffer between the kernel and the user also has the benefit
46 --------------------------------------------------------------------------------
48 --------------------------------------------------------------------------------
66 --------------------------------------------------------------------------------
68 --------------------------------------------------------------------------------
74 [setup]     socket() -------> creation of the capture socket
75             setsockopt() ---> allocation of the circular buffer (ring)
77             mmap() ---------> mapping of the allocated buffer to the
80 [capture]   poll() ---------> to wait for incoming packets
82 [shutdown]  close() --------> destruction of the capture socket and
97 supported and a link level pseudo-header is provided
104 also the mapping of the circular buffer in the user process and
105 the use of this buffer.
107 --------------------------------------------------------------------------------
109 --------------------------------------------------------------------------------
112 [setup]          socket() -------> creation of the transmission socket
113                  setsockopt() ---> allocation of the circular buffer (ring)
115                  bind() ---------> bind transmission socket with a network interface
116                  mmap() ---------> mapping of the allocated buffer to the
119 [transmission]   poll() ---------> wait for free packets (optional)
120                  send() ---------> send all packets that are set as ready in
125 [shutdown]  close() --------> destruction of the transmission socket and
129 know the header size of frames used in the circular buffer.
131 As capture, each frame contains two parts:
133  --------------------
135 |                    | of this frame
136 |--------------------|
137 | data buffer        |
140  --------------------
154  ioctl(this->socket, SIOCGIFINDEX, &s_ifr);
162  bind(this->socket, (struct sockaddr *)&my_addr, sizeof(struct sockaddr_ll));
164  A complete tutorial is available at: http://wiki.gnu-log.net/
166 --------------------------------------------------------------------------------
168 --------------------------------------------------------------------------------
173  - Capture process
175  - Transmission process
185         unsigned int    tp_frame_size;  /* Size of frame */
190 circular buffer (ring) of unswappable memory.
192 related meta-information like timestamps without requiring a system call.
212 we will get the following buffer structure:
215 +---------+---------+    +---------+---------+
216 | frame 1 | frame 2 |    | frame 3 | frame 4 |
217 +---------+---------+    +---------+---------+
220 +---------+---------+    +---------+---------+
221 | frame 5 | frame 6 |    | frame 7 | frame 8 |
222 +---------+---------+    +---------+---------+
224 A frame can be of any size with the only condition it can fit in a block. A block
225 can only hold an integer number of frames, or in other words, a frame cannot
228 buffer (ring)".
231 --------------------------------------------------------------------------------
233 --------------------------------------------------------------------------------
236 the PACKET_MMAP buffer could hold only 32768 frames in a 32 bit architecture or
238 see http://pusa.uv.es/~ulisses/packet_mmap/packet_mmap.pre-2.4.26_2.6.5.txt
241 ------------------
269 --------------------
277     +---+---+---+---+
279     +---+---+---+---+
289 a pool of pre-determined sizes. This pool of memory is maintained by the slab
294 predetermined sizes that kmalloc uses can be checked in the "size-<bytes>"
303  PACKET_MMAP buffer size calculator
304 ------------------------------------
308 <size-max>    : is the maximum size of allocable with kmalloc (see /proc/slabinfo)
309 <pointer size>: depends on the architecture -- sizeof(void *)
310 <page size>   : depends on the architecture -- PAGE_SIZE or getpagesize (2)
311 <max-order>   : is the value defined with MAX_ORDER
312 <frame size>  : it's an upper bound of frame's capture size (more on this later)
316 	<block number> = <size-max>/<pointer size>
317 	<block size> = <pagesize> << <max-order>
319 so, the max buffer size is
325 	<block number> * <block size> / <frame size>
330 	<size-max> = 131072 bytes
333 	<max-order> = 11
335 and a value for <frame size> of 2048 bytes. These parameters will yield
340 and hence the buffer will have a 262144 MiB size. So it can hold
344 Actually, this buffer size is not possible with an i386 architecture.
354 -------------------
356 If you check the source code you will see that what I draw here as a frame
357 is not only the link level frame. At the beginning of each frame there is a
358 header called struct tpacket_hdr used in PACKET_MMAP to hold link level's frame
359 meta information like timestamp. So what we draw here a frame it's really
363    Frame structure:
365    - Start. Frame must be aligned to TPACKET_ALIGNMENT=16
366    - struct tpacket_hdr
367    - pad to TPACKET_ALIGNMENT=16
368    - struct sockaddr_ll
369    - Gap, chosen so that packet data (Start+tp_net) aligns to
371    - Start+tp_mac: [ Optional MAC header ]
372    - Start+tp_net: Packet data, aligned to TPACKET_ALIGNMENT=16.
373    - Pad to align to TPACKET_ALIGNMENT=16
387 --------------------------------------------------------------------------------
388 + Mapping and use of the circular buffer (ring)
389 --------------------------------------------------------------------------------
391 The mapping of the buffer in the user process is done with the conventional
392 mmap function. Even the circular buffer is compound of several physically
401 the frames. This is because a frame cannot be spawn across two
404 At the beginning of each frame there is an status field (see
405 struct tpacket_hdr). If this field is 0 means that the frame is ready
406 to be used for the kernel, If not, there is a frame the user can read
417 TP_STATUS_COPY        : This flag indicates that the frame (and associated
445 receives a packet it puts in the buffer and updates the status with
448 can use again that frame buffer.
469      #define TP_STATUS_AVAILABLE        0 // Frame is available
470      #define TP_STATUS_SEND_REQUEST     1 // Frame will be sent on next send()
471      #define TP_STATUS_SENDING          2 // Frame is currently in transmission
472      #define TP_STATUS_WRONG_FORMAT     4 // Frame format is not correct
475 packet, the user fills a data buffer of an available frame, sets tp_len to
476 current data buffer size and sets its status field to TP_STATUS_SEND_REQUEST.
481 At the end of each transfer, buffer status returns to TP_STATUS_AVAILABLE.
483     header->tp_len = in_i_size;
484     header->tp_status = TP_STATUS_SEND_REQUEST;
485     retval = send(this->socket, NULL, 0, 0);
487 The user can also use poll() to check if a buffer is available:
496 -------------------------------------------------------------------------------
498 -------------------------------------------------------------------------------
522 --------------------------------------------------------------------------------
524 --------------------------------------------------------------------------------