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 | ||
7e11daa7 NB |
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 | ||
a33f3224 | 106 | Next I will describe PACKET_MMAP settings and its constraints, |
6c28f2c0 | 107 | also the mapping of the circular buffer in the user process and |
1da177e4 LT |
108 | the use of this buffer. |
109 | ||
69e3c75f | 110 | -------------------------------------------------------------------------------- |
889b8f96 | 111 | + How to use mmap() directly to improve transmission process |
69e3c75f JB |
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 | ||
66e56cd4 DB |
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 | ||
69e3c75f JB |
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; | |
30e7dfe7 | 171 | my_addr.sll_protocol = htons(ETH_P_ALL); |
69e3c75f JB |
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 | ||
5920cd3a PC |
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 | ||
1da177e4 LT |
192 | -------------------------------------------------------------------------------- |
193 | + PACKET_MMAP settings | |
194 | -------------------------------------------------------------------------------- | |
195 | ||
1da177e4 LT |
196 | To setup PACKET_MMAP from user level code is done with a call like |
197 | ||
69e3c75f | 198 | - Capture process |
1da177e4 | 199 | setsockopt(fd, SOL_PACKET, PACKET_RX_RING, (void *) &req, sizeof(req)) |
69e3c75f JB |
200 | - Transmission process |
201 | setsockopt(fd, SOL_PACKET, PACKET_TX_RING, (void *) &req, sizeof(req)) | |
1da177e4 LT |
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 | |
69e3c75f | 215 | circular buffer (ring) of unswappable memory. |
1da177e4 LT |
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 | ||
69e3c75f | 219 | Frames are grouped in blocks. Each block is a physically contiguous |
1da177e4 LT |
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 | ||
1da177e4 LT |
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 | |
25985edc | 250 | be spawned across two blocks, so there are some details you have to take into |
6c28f2c0 | 251 | account when choosing the frame_size. See "Mapping and use of the circular |
1da177e4 LT |
252 | buffer (ring)". |
253 | ||
1da177e4 LT |
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 | ||
1da177e4 LT |
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 | ||
2fe0ae78 ML |
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 | |
c30fe7f7 UZ |
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. | |
1da177e4 LT |
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 | ||
1da177e4 LT |
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 | ||
2e150f6e | 347 | Suppose the following parameters, which apply for 2.6 kernel and an |
1da177e4 LT |
348 | i386 architecture: |
349 | ||
350 | <size-max> = 131072 bytes | |
351 | <pointer size> = 4 bytes | |
352 | <pagesize> = 4096 bytes | |
353 | <max-order> = 11 | |
354 | ||
6c28f2c0 | 355 | and a value for <frame size> of 2048 bytes. These parameters will yield |
1da177e4 LT |
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 | ||
1da177e4 LT |
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 | |
992caacf | 370 | the necessary memory, so normally limits can be reached. |
1da177e4 LT |
371 | |
372 | Other constraints | |
373 | ------------------- | |
374 | ||
375 | If you check the source code you will see that what I draw here as a frame | |
5d3f083d | 376 | is not only the link level frame. At the beginning of each frame there is a |
1da177e4 LT |
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 | |
3f6dee9b | 388 | - Gap, chosen so that packet data (Start+tp_net) aligns to |
1da177e4 LT |
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 | */ | |
1da177e4 LT |
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 | ||
6c28f2c0 | 402 | Note that tp_block_size should be chosen to be a power of two or there will |
1da177e4 LT |
403 | be a waste of memory. |
404 | ||
405 | -------------------------------------------------------------------------------- | |
6c28f2c0 | 406 | + Mapping and use of the circular buffer (ring) |
1da177e4 LT |
407 | -------------------------------------------------------------------------------- |
408 | ||
6c28f2c0 | 409 | The mapping of the buffer in the user process is done with the conventional |
1da177e4 LT |
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 | |
d9195881 | 417 | contiguously spaced by tp_frame_size bytes. If not, each |
1da177e4 LT |
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 | ||
7e11daa7 NB |
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 | ||
1da177e4 LT |
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 | ||
69e3c75f | 440 | +++ Capture process: |
1da177e4 LT |
441 | from include/linux/if_packet.h |
442 | ||
682f048b AD |
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) | |
1da177e4 | 447 | |
1da177e4 LT |
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 | ||
a93c1256 | 457 | The number of frames that can be buffered to |
1da177e4 LT |
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 | ||
c30fe7f7 | 465 | TP_STATUS_CSUMNOTREADY: currently it's used for outgoing IP packets which |
a33f3224 | 466 | its checksum will be done in hardware. So while |
1da177e4 LT |
467 | reading the packet we should not try to check the |
468 | checksum. | |
469 | ||
682f048b AD |
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 | ||
1da177e4 LT |
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 | ||
69e3c75f JB |
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 | ||
d1ee40f9 DB |
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 | |
d1ee40f9 DB |
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 | |
ac7686b9 AW |
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 | |
d1ee40f9 DB |
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 | ||
7ec06da8 DB |
586 | Currently implemented fanout policies are: |
587 | ||
b0db5cdf | 588 | - PACKET_FANOUT_HASH: schedule to socket by skb's packet hash |
7ec06da8 DB |
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 | |
bb9fbe2d | 593 | - PACKET_FANOUT_QM: schedule to socket by skbs recorded queue_mapping |
7ec06da8 | 594 | |
d1ee40f9 DB |
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 | ||
4eb06148 DB |
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 | ||
d70a3f88 DB |
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 | ||
4eb06148 DB |
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 | ||
4eb06148 DB |
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 | ||
d70a3f88 | 802 | static void sighandler(int num) |
4eb06148 DB |
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; | |
d70a3f88 DB |
811 | unsigned int blocksiz = 1 << 22, framesiz = 1 << 11; |
812 | unsigned int blocknum = 64; | |
4eb06148 DB |
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)); | |
d70a3f88 DB |
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; | |
4eb06148 DB |
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, | |
d70a3f88 | 842 | PROT_READ | PROT_WRITE, MAP_SHARED | MAP_LOCKED, fd, 0); |
4eb06148 DB |
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 | ||
4eb06148 DB |
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 | { | |
d70a3f88 | 901 | int num_pkts = pbd->h1.num_pkts, i; |
4eb06148 | 902 | unsigned long bytes = 0; |
4eb06148 DB |
903 | struct tpacket3_hdr *ppd; |
904 | ||
d70a3f88 DB |
905 | ppd = (struct tpacket3_hdr *) ((uint8_t *) pbd + |
906 | pbd->h1.offset_to_first_pkt); | |
4eb06148 DB |
907 | for (i = 0; i < num_pkts; ++i) { |
908 | bytes += ppd->tp_snaplen; | |
4eb06148 DB |
909 | display(ppd); |
910 | ||
d70a3f88 DB |
911 | ppd = (struct tpacket3_hdr *) ((uint8_t *) ppd + |
912 | ppd->tp_next_offset); | |
4eb06148 DB |
913 | } |
914 | ||
4eb06148 DB |
915 | packets_total += num_pkts; |
916 | bytes_total += bytes; | |
917 | } | |
918 | ||
d70a3f88 | 919 | static void flush_block(struct block_desc *pbd) |
4eb06148 | 920 | { |
d70a3f88 | 921 | pbd->h1.block_status = TP_STATUS_KERNEL; |
4eb06148 DB |
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; | |
d70a3f88 | 937 | unsigned int block_num = 0, blocks = 64; |
4eb06148 DB |
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; | |
d70a3f88 DB |
959 | |
960 | if ((pbd->h1.block_status & TP_STATUS_USER) == 0) { | |
4eb06148 | 961 | poll(&pfd, 1, -1); |
d70a3f88 | 962 | continue; |
4eb06148 DB |
963 | } |
964 | ||
965 | walk_block(pbd, block_num); | |
966 | flush_block(pbd); | |
d70a3f88 | 967 | block_num = (block_num + 1) % blocks; |
4eb06148 DB |
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 | ||
d346a3fa DB |
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 | ||
614f60fa SM |
1007 | ------------------------------------------------------------------------------- |
1008 | + PACKET_TIMESTAMP | |
1009 | ------------------------------------------------------------------------------- | |
1010 | ||
1011 | The PACKET_TIMESTAMP setting determines the source of the timestamp in | |
2940b26b DB |
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). | |
614f60fa | 1017 | |
68a360e8 WB |
1018 | PACKET_TIMESTAMP accepts the same integer bit field as SO_TIMESTAMPING: |
1019 | ||
1020 | int req = SOF_TIMESTAMPING_RAW_HARDWARE; | |
614f60fa SM |
1021 | setsockopt(fd, SOL_PACKET, PACKET_TIMESTAMP, (void *) &req, sizeof(req)) |
1022 | ||
2940b26b DB |
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 | ||
2940b26b DB |
1028 | TP_STATUS_TS_RAW_HARDWARE |
1029 | TP_STATUS_TS_SOFTWARE | |
1030 | ||
1031 | ... that are equivalent to its SOF_TIMESTAMPING_* counterparts. For the | |
68a360e8 WB |
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). | |
2940b26b DB |
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! | |
614f60fa SM |
1052 | |
1053 | See include/linux/net_tstamp.h and Documentation/networking/timestamping | |
1054 | for more information on hardware timestamps. | |
1055 | ||
d1ee40f9 DB |
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 | ||
1da177e4 LT |
1063 | -------------------------------------------------------------------------------- |
1064 | + THANKS | |
1065 | -------------------------------------------------------------------------------- | |
1066 | ||
1067 | Jesse Brandeburg, for fixing my grammathical/spelling errors | |
1068 |