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