1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 ============ 3 ============
4 Devlink Trap 4 Devlink Trap
5 ============ 5 ============
6 6
7 Background 7 Background
8 ========== 8 ==========
9 9
10 Devices capable of offloading the kernel's dat 10 Devices capable of offloading the kernel's datapath and perform functions such
11 as bridging and routing must also be able to s 11 as bridging and routing must also be able to send specific packets to the
12 kernel (i.e., the CPU) for processing. 12 kernel (i.e., the CPU) for processing.
13 13
14 For example, a device acting as a multicast-aw 14 For example, a device acting as a multicast-aware bridge must be able to send
15 IGMP membership reports to the kernel for proc 15 IGMP membership reports to the kernel for processing by the bridge module.
16 Without processing such packets, the bridge mo 16 Without processing such packets, the bridge module could never populate its
17 MDB. 17 MDB.
18 18
19 As another example, consider a device acting a 19 As another example, consider a device acting as router which has received an IP
20 packet with a TTL of 1. Upon routing the packe 20 packet with a TTL of 1. Upon routing the packet the device must send it to the
21 kernel so that it will route it as well and ge 21 kernel so that it will route it as well and generate an ICMP Time Exceeded
22 error datagram. Without letting the kernel rou 22 error datagram. Without letting the kernel route such packets itself, utilities
23 such as ``traceroute`` could never work. 23 such as ``traceroute`` could never work.
24 24
25 The fundamental ability of sending certain pac 25 The fundamental ability of sending certain packets to the kernel for processing
26 is called "packet trapping". 26 is called "packet trapping".
27 27
28 Overview 28 Overview
29 ======== 29 ========
30 30
31 The ``devlink-trap`` mechanism allows capable 31 The ``devlink-trap`` mechanism allows capable device drivers to register their
32 supported packet traps with ``devlink`` and re 32 supported packet traps with ``devlink`` and report trapped packets to
33 ``devlink`` for further analysis. 33 ``devlink`` for further analysis.
34 34
35 Upon receiving trapped packets, ``devlink`` wi 35 Upon receiving trapped packets, ``devlink`` will perform a per-trap packets and
36 bytes accounting and potentially report the pa 36 bytes accounting and potentially report the packet to user space via a netlink
37 event along with all the provided metadata (e. 37 event along with all the provided metadata (e.g., trap reason, timestamp, input
38 port). This is especially useful for drop trap 38 port). This is especially useful for drop traps (see :ref:`Trap-Types`)
39 as it allows users to obtain further visibilit 39 as it allows users to obtain further visibility into packet drops that would
40 otherwise be invisible. 40 otherwise be invisible.
41 41
42 The following diagram provides a general overv 42 The following diagram provides a general overview of ``devlink-trap``::
43 43
44 Netlink ev 44 Netlink event: Packet w/ metadata
45 45 Or a summary of recent drops
46 ^ 46 ^
47 | 47 |
48 Userspace | 48 Userspace |
49 +------------------------------------- 49 +---------------------------------------------------+
50 Kernel | 50 Kernel |
51 | 51 |
52 +-------+--------+ 52 +-------+--------+
53 | | 53 | |
54 | drop_monitor | 54 | drop_monitor |
55 | | 55 | |
56 +-------^--------+ 56 +-------^--------+
57 | 57 |
58 | Non-contro 58 | Non-control traps
59 | 59 |
60 +----+----+ 60 +----+----+
61 | | 61 | | Kernel's Rx path
62 | devlink | 62 | devlink | (non-drop traps)
63 | | 63 | |
64 +----^----+ 64 +----^----+ ^
65 | 65 | |
66 +----------- 66 +-----------+
67 | 67 |
68 +-------+-------+ 68 +-------+-------+
69 | | 69 | |
70 | Device driver | 70 | Device driver |
71 | | 71 | |
72 +-------^-------+ 72 +-------^-------+
73 Kernel | 73 Kernel |
74 +------------------------------------- 74 +---------------------------------------------------+
75 Hardware | 75 Hardware |
76 | Trapped pa 76 | Trapped packet
77 | 77 |
78 +--+---+ 78 +--+---+
79 | | 79 | |
80 | ASIC | 80 | ASIC |
81 | | 81 | |
82 +------+ 82 +------+
83 83
84 .. _Trap-Types: 84 .. _Trap-Types:
85 85
86 Trap Types 86 Trap Types
87 ========== 87 ==========
88 88
89 The ``devlink-trap`` mechanism supports the fo 89 The ``devlink-trap`` mechanism supports the following packet trap types:
90 90
91 * ``drop``: Trapped packets were dropped by 91 * ``drop``: Trapped packets were dropped by the underlying device. Packets
92 are only processed by ``devlink`` and not 92 are only processed by ``devlink`` and not injected to the kernel's Rx path.
93 The trap action (see :ref:`Trap-Actions`) 93 The trap action (see :ref:`Trap-Actions`) can be changed.
94 * ``exception``: Trapped packets were not fo 94 * ``exception``: Trapped packets were not forwarded as intended by the
95 underlying device due to an exception (e.g 95 underlying device due to an exception (e.g., TTL error, missing neighbour
96 entry) and trapped to the control plane fo 96 entry) and trapped to the control plane for resolution. Packets are
97 processed by ``devlink`` and injected to t 97 processed by ``devlink`` and injected to the kernel's Rx path. Changing the
98 action of such traps is not allowed, as it 98 action of such traps is not allowed, as it can easily break the control
99 plane. 99 plane.
100 * ``control``: Trapped packets were trapped 100 * ``control``: Trapped packets were trapped by the device because these are
101 control packets required for the correct f 101 control packets required for the correct functioning of the control plane.
102 For example, ARP request and IGMP query pa 102 For example, ARP request and IGMP query packets. Packets are injected to
103 the kernel's Rx path, but not reported to 103 the kernel's Rx path, but not reported to the kernel's drop monitor.
104 Changing the action of such traps is not a 104 Changing the action of such traps is not allowed, as it can easily break
105 the control plane. 105 the control plane.
106 106
107 .. _Trap-Actions: 107 .. _Trap-Actions:
108 108
109 Trap Actions 109 Trap Actions
110 ============ 110 ============
111 111
112 The ``devlink-trap`` mechanism supports the fo 112 The ``devlink-trap`` mechanism supports the following packet trap actions:
113 113
114 * ``trap``: The sole copy of the packet is s 114 * ``trap``: The sole copy of the packet is sent to the CPU.
115 * ``drop``: The packet is dropped by the und 115 * ``drop``: The packet is dropped by the underlying device and a copy is not
116 sent to the CPU. 116 sent to the CPU.
117 * ``mirror``: The packet is forwarded by the 117 * ``mirror``: The packet is forwarded by the underlying device and a copy is
118 sent to the CPU. 118 sent to the CPU.
119 119
120 Generic Packet Traps 120 Generic Packet Traps
121 ==================== 121 ====================
122 122
123 Generic packet traps are used to describe trap 123 Generic packet traps are used to describe traps that trap well-defined packets
124 or packets that are trapped due to well-define 124 or packets that are trapped due to well-defined conditions (e.g., TTL error).
125 Such traps can be shared by multiple device dr 125 Such traps can be shared by multiple device drivers and their description must
126 be added to the following table: 126 be added to the following table:
127 127
128 .. list-table:: List of Generic Packet Traps 128 .. list-table:: List of Generic Packet Traps
129 :widths: 5 5 90 129 :widths: 5 5 90
130 130
131 * - Name 131 * - Name
132 - Type 132 - Type
133 - Description 133 - Description
134 * - ``source_mac_is_multicast`` 134 * - ``source_mac_is_multicast``
135 - ``drop`` 135 - ``drop``
136 - Traps incoming packets that the device 136 - Traps incoming packets that the device decided to drop because of a
137 multicast source MAC 137 multicast source MAC
138 * - ``vlan_tag_mismatch`` 138 * - ``vlan_tag_mismatch``
139 - ``drop`` 139 - ``drop``
140 - Traps incoming packets that the device 140 - Traps incoming packets that the device decided to drop in case of VLAN
141 tag mismatch: The ingress bridge port i 141 tag mismatch: The ingress bridge port is not configured with a PVID and
142 the packet is untagged or prio-tagged 142 the packet is untagged or prio-tagged
143 * - ``ingress_vlan_filter`` 143 * - ``ingress_vlan_filter``
144 - ``drop`` 144 - ``drop``
145 - Traps incoming packets that the device 145 - Traps incoming packets that the device decided to drop in case they are
146 tagged with a VLAN that is not configur 146 tagged with a VLAN that is not configured on the ingress bridge port
147 * - ``ingress_spanning_tree_filter`` 147 * - ``ingress_spanning_tree_filter``
148 - ``drop`` 148 - ``drop``
149 - Traps incoming packets that the device 149 - Traps incoming packets that the device decided to drop in case the STP
150 state of the ingress bridge port is not 150 state of the ingress bridge port is not "forwarding"
151 * - ``port_list_is_empty`` 151 * - ``port_list_is_empty``
152 - ``drop`` 152 - ``drop``
153 - Traps packets that the device decided t 153 - Traps packets that the device decided to drop in case they need to be
154 flooded (e.g., unknown unicast, unregis 154 flooded (e.g., unknown unicast, unregistered multicast) and there are
155 no ports the packets should be flooded 155 no ports the packets should be flooded to
156 * - ``port_loopback_filter`` 156 * - ``port_loopback_filter``
157 - ``drop`` 157 - ``drop``
158 - Traps packets that the device decided t 158 - Traps packets that the device decided to drop in case after layer 2
159 forwarding the only port from which the 159 forwarding the only port from which they should be transmitted through
160 is the port from which they were receiv 160 is the port from which they were received
161 * - ``blackhole_route`` 161 * - ``blackhole_route``
162 - ``drop`` 162 - ``drop``
163 - Traps packets that the device decided t 163 - Traps packets that the device decided to drop in case they hit a
164 blackhole route 164 blackhole route
165 * - ``ttl_value_is_too_small`` 165 * - ``ttl_value_is_too_small``
166 - ``exception`` 166 - ``exception``
167 - Traps unicast packets that should be fo 167 - Traps unicast packets that should be forwarded by the device whose TTL
168 was decremented to 0 or less 168 was decremented to 0 or less
169 * - ``tail_drop`` 169 * - ``tail_drop``
170 - ``drop`` 170 - ``drop``
171 - Traps packets that the device decided t 171 - Traps packets that the device decided to drop because they could not be
172 enqueued to a transmission queue which 172 enqueued to a transmission queue which is full
173 * - ``non_ip`` 173 * - ``non_ip``
174 - ``drop`` 174 - ``drop``
175 - Traps packets that the device decided t 175 - Traps packets that the device decided to drop because they need to
176 undergo a layer 3 lookup, but are not I 176 undergo a layer 3 lookup, but are not IP or MPLS packets
177 * - ``uc_dip_over_mc_dmac`` 177 * - ``uc_dip_over_mc_dmac``
178 - ``drop`` 178 - ``drop``
179 - Traps packets that the device decided t 179 - Traps packets that the device decided to drop because they need to be
180 routed and they have a unicast destinat 180 routed and they have a unicast destination IP and a multicast destination
181 MAC 181 MAC
182 * - ``dip_is_loopback_address`` 182 * - ``dip_is_loopback_address``
183 - ``drop`` 183 - ``drop``
184 - Traps packets that the device decided t 184 - Traps packets that the device decided to drop because they need to be
185 routed and their destination IP is the 185 routed and their destination IP is the loopback address (i.e., 127.0.0.0/8
186 and ::1/128) 186 and ::1/128)
187 * - ``sip_is_mc`` 187 * - ``sip_is_mc``
188 - ``drop`` 188 - ``drop``
189 - Traps packets that the device decided t 189 - Traps packets that the device decided to drop because they need to be
190 routed and their source IP is multicast 190 routed and their source IP is multicast (i.e., 224.0.0.0/8 and ff::/8)
191 * - ``sip_is_loopback_address`` 191 * - ``sip_is_loopback_address``
192 - ``drop`` 192 - ``drop``
193 - Traps packets that the device decided t 193 - Traps packets that the device decided to drop because they need to be
194 routed and their source IP is the loopb 194 routed and their source IP is the loopback address (i.e., 127.0.0.0/8 and ::1/128)
195 * - ``ip_header_corrupted`` 195 * - ``ip_header_corrupted``
196 - ``drop`` 196 - ``drop``
197 - Traps packets that the device decided t 197 - Traps packets that the device decided to drop because they need to be
198 routed and their IP header is corrupted 198 routed and their IP header is corrupted: wrong checksum, wrong IP version
199 or too short Internet Header Length (IH 199 or too short Internet Header Length (IHL)
200 * - ``ipv4_sip_is_limited_bc`` 200 * - ``ipv4_sip_is_limited_bc``
201 - ``drop`` 201 - ``drop``
202 - Traps packets that the device decided t 202 - Traps packets that the device decided to drop because they need to be
203 routed and their source IP is limited b 203 routed and their source IP is limited broadcast (i.e., 255.255.255.255/32)
204 * - ``ipv6_mc_dip_reserved_scope`` 204 * - ``ipv6_mc_dip_reserved_scope``
205 - ``drop`` 205 - ``drop``
206 - Traps IPv6 packets that the device deci 206 - Traps IPv6 packets that the device decided to drop because they need to
207 be routed and their IPv6 multicast dest 207 be routed and their IPv6 multicast destination IP has a reserved scope
208 (i.e., ffx0::/16) 208 (i.e., ffx0::/16)
209 * - ``ipv6_mc_dip_interface_local_scope`` 209 * - ``ipv6_mc_dip_interface_local_scope``
210 - ``drop`` 210 - ``drop``
211 - Traps IPv6 packets that the device deci 211 - Traps IPv6 packets that the device decided to drop because they need to
212 be routed and their IPv6 multicast dest 212 be routed and their IPv6 multicast destination IP has an interface-local scope
213 (i.e., ffx1::/16) 213 (i.e., ffx1::/16)
214 * - ``mtu_value_is_too_small`` 214 * - ``mtu_value_is_too_small``
215 - ``exception`` 215 - ``exception``
216 - Traps packets that should have been rou 216 - Traps packets that should have been routed by the device, but were bigger
217 than the MTU of the egress interface 217 than the MTU of the egress interface
218 * - ``unresolved_neigh`` 218 * - ``unresolved_neigh``
219 - ``exception`` 219 - ``exception``
220 - Traps packets that did not have a match 220 - Traps packets that did not have a matching IP neighbour after routing
221 * - ``mc_reverse_path_forwarding`` 221 * - ``mc_reverse_path_forwarding``
222 - ``exception`` 222 - ``exception``
223 - Traps multicast IP packets that failed 223 - Traps multicast IP packets that failed reverse-path forwarding (RPF)
224 check during multicast routing 224 check during multicast routing
225 * - ``reject_route`` 225 * - ``reject_route``
226 - ``exception`` 226 - ``exception``
227 - Traps packets that hit reject routes (i 227 - Traps packets that hit reject routes (i.e., "unreachable", "prohibit")
228 * - ``ipv4_lpm_miss`` 228 * - ``ipv4_lpm_miss``
229 - ``exception`` 229 - ``exception``
230 - Traps unicast IPv4 packets that did not 230 - Traps unicast IPv4 packets that did not match any route
231 * - ``ipv6_lpm_miss`` 231 * - ``ipv6_lpm_miss``
232 - ``exception`` 232 - ``exception``
233 - Traps unicast IPv6 packets that did not 233 - Traps unicast IPv6 packets that did not match any route
234 * - ``non_routable_packet`` 234 * - ``non_routable_packet``
235 - ``drop`` 235 - ``drop``
236 - Traps packets that the device decided t 236 - Traps packets that the device decided to drop because they are not
237 supposed to be routed. For example, IGM 237 supposed to be routed. For example, IGMP queries can be flooded by the
238 device in layer 2 and reach the router. 238 device in layer 2 and reach the router. Such packets should not be
239 routed and instead dropped 239 routed and instead dropped
240 * - ``decap_error`` 240 * - ``decap_error``
241 - ``exception`` 241 - ``exception``
242 - Traps NVE and IPinIP packets that the d 242 - Traps NVE and IPinIP packets that the device decided to drop because of
243 failure during decapsulation (e.g., pac 243 failure during decapsulation (e.g., packet being too short, reserved
244 bits set in VXLAN header) 244 bits set in VXLAN header)
245 * - ``overlay_smac_is_mc`` 245 * - ``overlay_smac_is_mc``
246 - ``drop`` 246 - ``drop``
247 - Traps NVE packets that the device decid 247 - Traps NVE packets that the device decided to drop because their overlay
248 source MAC is multicast 248 source MAC is multicast
249 * - ``ingress_flow_action_drop`` 249 * - ``ingress_flow_action_drop``
250 - ``drop`` 250 - ``drop``
251 - Traps packets dropped during processing 251 - Traps packets dropped during processing of ingress flow action drop
252 * - ``egress_flow_action_drop`` 252 * - ``egress_flow_action_drop``
253 - ``drop`` 253 - ``drop``
254 - Traps packets dropped during processing 254 - Traps packets dropped during processing of egress flow action drop
255 * - ``stp`` 255 * - ``stp``
256 - ``control`` 256 - ``control``
257 - Traps STP packets 257 - Traps STP packets
258 * - ``lacp`` 258 * - ``lacp``
259 - ``control`` 259 - ``control``
260 - Traps LACP packets 260 - Traps LACP packets
261 * - ``lldp`` 261 * - ``lldp``
262 - ``control`` 262 - ``control``
263 - Traps LLDP packets 263 - Traps LLDP packets
264 * - ``igmp_query`` 264 * - ``igmp_query``
265 - ``control`` 265 - ``control``
266 - Traps IGMP Membership Query packets 266 - Traps IGMP Membership Query packets
267 * - ``igmp_v1_report`` 267 * - ``igmp_v1_report``
268 - ``control`` 268 - ``control``
269 - Traps IGMP Version 1 Membership Report 269 - Traps IGMP Version 1 Membership Report packets
270 * - ``igmp_v2_report`` 270 * - ``igmp_v2_report``
271 - ``control`` 271 - ``control``
272 - Traps IGMP Version 2 Membership Report 272 - Traps IGMP Version 2 Membership Report packets
273 * - ``igmp_v3_report`` 273 * - ``igmp_v3_report``
274 - ``control`` 274 - ``control``
275 - Traps IGMP Version 3 Membership Report 275 - Traps IGMP Version 3 Membership Report packets
276 * - ``igmp_v2_leave`` 276 * - ``igmp_v2_leave``
277 - ``control`` 277 - ``control``
278 - Traps IGMP Version 2 Leave Group packet 278 - Traps IGMP Version 2 Leave Group packets
279 * - ``mld_query`` 279 * - ``mld_query``
280 - ``control`` 280 - ``control``
281 - Traps MLD Multicast Listener Query pack 281 - Traps MLD Multicast Listener Query packets
282 * - ``mld_v1_report`` 282 * - ``mld_v1_report``
283 - ``control`` 283 - ``control``
284 - Traps MLD Version 1 Multicast Listener 284 - Traps MLD Version 1 Multicast Listener Report packets
285 * - ``mld_v2_report`` 285 * - ``mld_v2_report``
286 - ``control`` 286 - ``control``
287 - Traps MLD Version 2 Multicast Listener 287 - Traps MLD Version 2 Multicast Listener Report packets
288 * - ``mld_v1_done`` 288 * - ``mld_v1_done``
289 - ``control`` 289 - ``control``
290 - Traps MLD Version 1 Multicast Listener 290 - Traps MLD Version 1 Multicast Listener Done packets
291 * - ``ipv4_dhcp`` 291 * - ``ipv4_dhcp``
292 - ``control`` 292 - ``control``
293 - Traps IPv4 DHCP packets 293 - Traps IPv4 DHCP packets
294 * - ``ipv6_dhcp`` 294 * - ``ipv6_dhcp``
295 - ``control`` 295 - ``control``
296 - Traps IPv6 DHCP packets 296 - Traps IPv6 DHCP packets
297 * - ``arp_request`` 297 * - ``arp_request``
298 - ``control`` 298 - ``control``
299 - Traps ARP request packets 299 - Traps ARP request packets
300 * - ``arp_response`` 300 * - ``arp_response``
301 - ``control`` 301 - ``control``
302 - Traps ARP response packets 302 - Traps ARP response packets
303 * - ``arp_overlay`` 303 * - ``arp_overlay``
304 - ``control`` 304 - ``control``
305 - Traps NVE-decapsulated ARP packets that 305 - Traps NVE-decapsulated ARP packets that reached the overlay network.
306 This is required, for example, when the 306 This is required, for example, when the address that needs to be
307 resolved is a local address 307 resolved is a local address
308 * - ``ipv6_neigh_solicit`` 308 * - ``ipv6_neigh_solicit``
309 - ``control`` 309 - ``control``
310 - Traps IPv6 Neighbour Solicitation packe 310 - Traps IPv6 Neighbour Solicitation packets
311 * - ``ipv6_neigh_advert`` 311 * - ``ipv6_neigh_advert``
312 - ``control`` 312 - ``control``
313 - Traps IPv6 Neighbour Advertisement pack 313 - Traps IPv6 Neighbour Advertisement packets
314 * - ``ipv4_bfd`` 314 * - ``ipv4_bfd``
315 - ``control`` 315 - ``control``
316 - Traps IPv4 BFD packets 316 - Traps IPv4 BFD packets
317 * - ``ipv6_bfd`` 317 * - ``ipv6_bfd``
318 - ``control`` 318 - ``control``
319 - Traps IPv6 BFD packets 319 - Traps IPv6 BFD packets
320 * - ``ipv4_ospf`` 320 * - ``ipv4_ospf``
321 - ``control`` 321 - ``control``
322 - Traps IPv4 OSPF packets 322 - Traps IPv4 OSPF packets
323 * - ``ipv6_ospf`` 323 * - ``ipv6_ospf``
324 - ``control`` 324 - ``control``
325 - Traps IPv6 OSPF packets 325 - Traps IPv6 OSPF packets
326 * - ``ipv4_bgp`` 326 * - ``ipv4_bgp``
327 - ``control`` 327 - ``control``
328 - Traps IPv4 BGP packets 328 - Traps IPv4 BGP packets
329 * - ``ipv6_bgp`` 329 * - ``ipv6_bgp``
330 - ``control`` 330 - ``control``
331 - Traps IPv6 BGP packets 331 - Traps IPv6 BGP packets
332 * - ``ipv4_vrrp`` 332 * - ``ipv4_vrrp``
333 - ``control`` 333 - ``control``
334 - Traps IPv4 VRRP packets 334 - Traps IPv4 VRRP packets
335 * - ``ipv6_vrrp`` 335 * - ``ipv6_vrrp``
336 - ``control`` 336 - ``control``
337 - Traps IPv6 VRRP packets 337 - Traps IPv6 VRRP packets
338 * - ``ipv4_pim`` 338 * - ``ipv4_pim``
339 - ``control`` 339 - ``control``
340 - Traps IPv4 PIM packets 340 - Traps IPv4 PIM packets
341 * - ``ipv6_pim`` 341 * - ``ipv6_pim``
342 - ``control`` 342 - ``control``
343 - Traps IPv6 PIM packets 343 - Traps IPv6 PIM packets
344 * - ``uc_loopback`` 344 * - ``uc_loopback``
345 - ``control`` 345 - ``control``
346 - Traps unicast packets that need to be r 346 - Traps unicast packets that need to be routed through the same layer 3
347 interface from which they were received 347 interface from which they were received. Such packets are routed by the
348 kernel, but also cause it to potentiall 348 kernel, but also cause it to potentially generate ICMP redirect packets
349 * - ``local_route`` 349 * - ``local_route``
350 - ``control`` 350 - ``control``
351 - Traps unicast packets that hit a local 351 - Traps unicast packets that hit a local route and need to be locally
352 delivered 352 delivered
353 * - ``external_route`` 353 * - ``external_route``
354 - ``control`` 354 - ``control``
355 - Traps packets that should be routed thr 355 - Traps packets that should be routed through an external interface (e.g.,
356 management interface) that does not bel 356 management interface) that does not belong to the same device (e.g.,
357 switch ASIC) as the ingress interface 357 switch ASIC) as the ingress interface
358 * - ``ipv6_uc_dip_link_local_scope`` 358 * - ``ipv6_uc_dip_link_local_scope``
359 - ``control`` 359 - ``control``
360 - Traps unicast IPv6 packets that need to 360 - Traps unicast IPv6 packets that need to be routed and have a destination
361 IP address with a link-local scope (i.e 361 IP address with a link-local scope (i.e., fe80::/10). The trap allows
362 device drivers to avoid programming lin 362 device drivers to avoid programming link-local routes, but still receive
363 packets for local delivery 363 packets for local delivery
364 * - ``ipv6_dip_all_nodes`` 364 * - ``ipv6_dip_all_nodes``
365 - ``control`` 365 - ``control``
366 - Traps IPv6 packets that their destinati 366 - Traps IPv6 packets that their destination IP address is the "All Nodes
367 Address" (i.e., ff02::1) 367 Address" (i.e., ff02::1)
368 * - ``ipv6_dip_all_routers`` 368 * - ``ipv6_dip_all_routers``
369 - ``control`` 369 - ``control``
370 - Traps IPv6 packets that their destinati 370 - Traps IPv6 packets that their destination IP address is the "All Routers
371 Address" (i.e., ff02::2) 371 Address" (i.e., ff02::2)
372 * - ``ipv6_router_solicit`` 372 * - ``ipv6_router_solicit``
373 - ``control`` 373 - ``control``
374 - Traps IPv6 Router Solicitation packets 374 - Traps IPv6 Router Solicitation packets
375 * - ``ipv6_router_advert`` 375 * - ``ipv6_router_advert``
376 - ``control`` 376 - ``control``
377 - Traps IPv6 Router Advertisement packets 377 - Traps IPv6 Router Advertisement packets
378 * - ``ipv6_redirect`` 378 * - ``ipv6_redirect``
379 - ``control`` 379 - ``control``
380 - Traps IPv6 Redirect Message packets 380 - Traps IPv6 Redirect Message packets
381 * - ``ipv4_router_alert`` 381 * - ``ipv4_router_alert``
382 - ``control`` 382 - ``control``
383 - Traps IPv4 packets that need to be rout 383 - Traps IPv4 packets that need to be routed and include the Router Alert
384 option. Such packets need to be locally 384 option. Such packets need to be locally delivered to raw sockets that
385 have the IP_ROUTER_ALERT socket option 385 have the IP_ROUTER_ALERT socket option set
386 * - ``ipv6_router_alert`` 386 * - ``ipv6_router_alert``
387 - ``control`` 387 - ``control``
388 - Traps IPv6 packets that need to be rout 388 - Traps IPv6 packets that need to be routed and include the Router Alert
389 option in their Hop-by-Hop extension he 389 option in their Hop-by-Hop extension header. Such packets need to be
390 locally delivered to raw sockets that h 390 locally delivered to raw sockets that have the IPV6_ROUTER_ALERT socket
391 option set 391 option set
392 * - ``ptp_event`` 392 * - ``ptp_event``
393 - ``control`` 393 - ``control``
394 - Traps PTP time-critical event messages 394 - Traps PTP time-critical event messages (Sync, Delay_req, Pdelay_Req and
395 Pdelay_Resp) 395 Pdelay_Resp)
396 * - ``ptp_general`` 396 * - ``ptp_general``
397 - ``control`` 397 - ``control``
398 - Traps PTP general messages (Announce, F 398 - Traps PTP general messages (Announce, Follow_Up, Delay_Resp,
399 Pdelay_Resp_Follow_Up, management and s 399 Pdelay_Resp_Follow_Up, management and signaling)
400 * - ``flow_action_sample`` 400 * - ``flow_action_sample``
401 - ``control`` 401 - ``control``
402 - Traps packets sampled during processing 402 - Traps packets sampled during processing of flow action sample (e.g., via
403 tc's sample action) 403 tc's sample action)
404 * - ``flow_action_trap`` 404 * - ``flow_action_trap``
405 - ``control`` 405 - ``control``
406 - Traps packets logged during processing 406 - Traps packets logged during processing of flow action trap (e.g., via
407 tc's trap action) 407 tc's trap action)
408 * - ``early_drop`` 408 * - ``early_drop``
409 - ``drop`` 409 - ``drop``
410 - Traps packets dropped due to the RED (R 410 - Traps packets dropped due to the RED (Random Early Detection) algorithm
411 (i.e., early drops) 411 (i.e., early drops)
412 * - ``vxlan_parsing`` 412 * - ``vxlan_parsing``
413 - ``drop`` 413 - ``drop``
414 - Traps packets dropped due to an error i 414 - Traps packets dropped due to an error in the VXLAN header parsing which
415 might be because of packet truncation o 415 might be because of packet truncation or the I flag is not set.
416 * - ``llc_snap_parsing`` 416 * - ``llc_snap_parsing``
417 - ``drop`` 417 - ``drop``
418 - Traps packets dropped due to an error i 418 - Traps packets dropped due to an error in the LLC+SNAP header parsing
419 * - ``vlan_parsing`` 419 * - ``vlan_parsing``
420 - ``drop`` 420 - ``drop``
421 - Traps packets dropped due to an error i 421 - Traps packets dropped due to an error in the VLAN header parsing. Could
422 include unexpected packet truncation. 422 include unexpected packet truncation.
423 * - ``pppoe_ppp_parsing`` 423 * - ``pppoe_ppp_parsing``
424 - ``drop`` 424 - ``drop``
425 - Traps packets dropped due to an error i 425 - Traps packets dropped due to an error in the PPPoE+PPP header parsing.
426 This could include finding a session ID 426 This could include finding a session ID of 0xFFFF (which is reserved and
427 not for use), a PPPoE length which is l 427 not for use), a PPPoE length which is larger than the frame received or
428 any common error on this type of header 428 any common error on this type of header
429 * - ``mpls_parsing`` 429 * - ``mpls_parsing``
430 - ``drop`` 430 - ``drop``
431 - Traps packets dropped due to an error i 431 - Traps packets dropped due to an error in the MPLS header parsing which
432 could include unexpected header truncat 432 could include unexpected header truncation
433 * - ``arp_parsing`` 433 * - ``arp_parsing``
434 - ``drop`` 434 - ``drop``
435 - Traps packets dropped due to an error i 435 - Traps packets dropped due to an error in the ARP header parsing
436 * - ``ip_1_parsing`` 436 * - ``ip_1_parsing``
437 - ``drop`` 437 - ``drop``
438 - Traps packets dropped due to an error i 438 - Traps packets dropped due to an error in the first IP header parsing.
439 This packet trap could include packets 439 This packet trap could include packets which do not pass an IP checksum
440 check, a header length check (a minimum 440 check, a header length check (a minimum of 20 bytes), which might suffer
441 from packet truncation thus the total l 441 from packet truncation thus the total length field exceeds the received
442 packet length etc 442 packet length etc
443 * - ``ip_n_parsing`` 443 * - ``ip_n_parsing``
444 - ``drop`` 444 - ``drop``
445 - Traps packets dropped due to an error i 445 - Traps packets dropped due to an error in the parsing of the last IP
446 header (the inner one in case of an IP 446 header (the inner one in case of an IP over IP tunnel). The same common
447 error checking is performed here as for 447 error checking is performed here as for the ip_1_parsing trap
448 * - ``gre_parsing`` 448 * - ``gre_parsing``
449 - ``drop`` 449 - ``drop``
450 - Traps packets dropped due to an error i 450 - Traps packets dropped due to an error in the GRE header parsing
451 * - ``udp_parsing`` 451 * - ``udp_parsing``
452 - ``drop`` 452 - ``drop``
453 - Traps packets dropped due to an error i 453 - Traps packets dropped due to an error in the UDP header parsing.
454 This packet trap could include checksum 454 This packet trap could include checksum errorrs, an improper UDP
455 length detected (smaller than 8 bytes) 455 length detected (smaller than 8 bytes) or detection of header
456 truncation. 456 truncation.
457 * - ``tcp_parsing`` 457 * - ``tcp_parsing``
458 - ``drop`` 458 - ``drop``
459 - Traps packets dropped due to an error i 459 - Traps packets dropped due to an error in the TCP header parsing.
460 This could include TCP checksum errors, 460 This could include TCP checksum errors, improper combination of SYN, FIN
461 and/or RESET etc. 461 and/or RESET etc.
462 * - ``ipsec_parsing`` 462 * - ``ipsec_parsing``
463 - ``drop`` 463 - ``drop``
464 - Traps packets dropped due to an error i 464 - Traps packets dropped due to an error in the IPSEC header parsing
465 * - ``sctp_parsing`` 465 * - ``sctp_parsing``
466 - ``drop`` 466 - ``drop``
467 - Traps packets dropped due to an error i 467 - Traps packets dropped due to an error in the SCTP header parsing.
468 This would mean that port number 0 was 468 This would mean that port number 0 was used or that the header is
469 truncated. 469 truncated.
470 * - ``dccp_parsing`` 470 * - ``dccp_parsing``
471 - ``drop`` 471 - ``drop``
472 - Traps packets dropped due to an error i 472 - Traps packets dropped due to an error in the DCCP header parsing
473 * - ``gtp_parsing`` 473 * - ``gtp_parsing``
474 - ``drop`` 474 - ``drop``
475 - Traps packets dropped due to an error i 475 - Traps packets dropped due to an error in the GTP header parsing
476 * - ``esp_parsing`` 476 * - ``esp_parsing``
477 - ``drop`` 477 - ``drop``
478 - Traps packets dropped due to an error i 478 - Traps packets dropped due to an error in the ESP header parsing
479 * - ``blackhole_nexthop`` 479 * - ``blackhole_nexthop``
480 - ``drop`` 480 - ``drop``
481 - Traps packets that the device decided t 481 - Traps packets that the device decided to drop in case they hit a
482 blackhole nexthop 482 blackhole nexthop
483 * - ``dmac_filter`` 483 * - ``dmac_filter``
484 - ``drop`` 484 - ``drop``
485 - Traps incoming packets that the device 485 - Traps incoming packets that the device decided to drop because
486 the destination MAC is not configured i 486 the destination MAC is not configured in the MAC table and
487 the interface is not in promiscuous mod 487 the interface is not in promiscuous mode
488 * - ``eapol`` 488 * - ``eapol``
489 - ``control`` 489 - ``control``
490 - Traps "Extensible Authentication Protoc 490 - Traps "Extensible Authentication Protocol over LAN" (EAPOL) packets
491 specified in IEEE 802.1X 491 specified in IEEE 802.1X
492 * - ``locked_port`` 492 * - ``locked_port``
493 - ``drop`` 493 - ``drop``
494 - Traps packets that the device decided t 494 - Traps packets that the device decided to drop because they failed the
495 locked bridge port check. That is, pack 495 locked bridge port check. That is, packets that were received via a
496 locked port and whose {SMAC, VID} does 496 locked port and whose {SMAC, VID} does not correspond to an FDB entry
497 pointing to the port 497 pointing to the port
498 498
499 Driver-specific Packet Traps 499 Driver-specific Packet Traps
500 ============================ 500 ============================
501 501
502 Device drivers can register driver-specific pa 502 Device drivers can register driver-specific packet traps, but these must be
503 clearly documented. Such traps can correspond 503 clearly documented. Such traps can correspond to device-specific exceptions and
504 help debug packet drops caused by these except 504 help debug packet drops caused by these exceptions. The following list includes
505 links to the description of driver-specific tr 505 links to the description of driver-specific traps registered by various device
506 drivers: 506 drivers:
507 507
508 * Documentation/networking/devlink/netdevsim 508 * Documentation/networking/devlink/netdevsim.rst
509 * Documentation/networking/devlink/mlxsw.rst 509 * Documentation/networking/devlink/mlxsw.rst
510 * Documentation/networking/devlink/prestera. 510 * Documentation/networking/devlink/prestera.rst
511 511
512 .. _Generic-Packet-Trap-Groups: 512 .. _Generic-Packet-Trap-Groups:
513 513
514 Generic Packet Trap Groups 514 Generic Packet Trap Groups
515 ========================== 515 ==========================
516 516
517 Generic packet trap groups are used to aggrega 517 Generic packet trap groups are used to aggregate logically related packet
518 traps. These groups allow the user to batch op 518 traps. These groups allow the user to batch operations such as setting the trap
519 action of all member traps. In addition, ``dev 519 action of all member traps. In addition, ``devlink-trap`` can report aggregated
520 per-group packets and bytes statistics, in cas 520 per-group packets and bytes statistics, in case per-trap statistics are too
521 narrow. The description of these groups must b 521 narrow. The description of these groups must be added to the following table:
522 522
523 .. list-table:: List of Generic Packet Trap Gr 523 .. list-table:: List of Generic Packet Trap Groups
524 :widths: 10 90 524 :widths: 10 90
525 525
526 * - Name 526 * - Name
527 - Description 527 - Description
528 * - ``l2_drops`` 528 * - ``l2_drops``
529 - Contains packet traps for packets that 529 - Contains packet traps for packets that were dropped by the device during
530 layer 2 forwarding (i.e., bridge) 530 layer 2 forwarding (i.e., bridge)
531 * - ``l3_drops`` 531 * - ``l3_drops``
532 - Contains packet traps for packets that 532 - Contains packet traps for packets that were dropped by the device during
533 layer 3 forwarding 533 layer 3 forwarding
534 * - ``l3_exceptions`` 534 * - ``l3_exceptions``
535 - Contains packet traps for packets that 535 - Contains packet traps for packets that hit an exception (e.g., TTL
536 error) during layer 3 forwarding 536 error) during layer 3 forwarding
537 * - ``buffer_drops`` 537 * - ``buffer_drops``
538 - Contains packet traps for packets that 538 - Contains packet traps for packets that were dropped by the device due to
539 an enqueue decision 539 an enqueue decision
540 * - ``tunnel_drops`` 540 * - ``tunnel_drops``
541 - Contains packet traps for packets that 541 - Contains packet traps for packets that were dropped by the device during
542 tunnel encapsulation / decapsulation 542 tunnel encapsulation / decapsulation
543 * - ``acl_drops`` 543 * - ``acl_drops``
544 - Contains packet traps for packets that 544 - Contains packet traps for packets that were dropped by the device during
545 ACL processing 545 ACL processing
546 * - ``stp`` 546 * - ``stp``
547 - Contains packet traps for STP packets 547 - Contains packet traps for STP packets
548 * - ``lacp`` 548 * - ``lacp``
549 - Contains packet traps for LACP packets 549 - Contains packet traps for LACP packets
550 * - ``lldp`` 550 * - ``lldp``
551 - Contains packet traps for LLDP packets 551 - Contains packet traps for LLDP packets
552 * - ``mc_snooping`` 552 * - ``mc_snooping``
553 - Contains packet traps for IGMP and MLD 553 - Contains packet traps for IGMP and MLD packets required for multicast
554 snooping 554 snooping
555 * - ``dhcp`` 555 * - ``dhcp``
556 - Contains packet traps for DHCP packets 556 - Contains packet traps for DHCP packets
557 * - ``neigh_discovery`` 557 * - ``neigh_discovery``
558 - Contains packet traps for neighbour dis 558 - Contains packet traps for neighbour discovery packets (e.g., ARP, IPv6
559 ND) 559 ND)
560 * - ``bfd`` 560 * - ``bfd``
561 - Contains packet traps for BFD packets 561 - Contains packet traps for BFD packets
562 * - ``ospf`` 562 * - ``ospf``
563 - Contains packet traps for OSPF packets 563 - Contains packet traps for OSPF packets
564 * - ``bgp`` 564 * - ``bgp``
565 - Contains packet traps for BGP packets 565 - Contains packet traps for BGP packets
566 * - ``vrrp`` 566 * - ``vrrp``
567 - Contains packet traps for VRRP packets 567 - Contains packet traps for VRRP packets
568 * - ``pim`` 568 * - ``pim``
569 - Contains packet traps for PIM packets 569 - Contains packet traps for PIM packets
570 * - ``uc_loopback`` 570 * - ``uc_loopback``
571 - Contains a packet trap for unicast loop 571 - Contains a packet trap for unicast loopback packets (i.e.,
572 ``uc_loopback``). This trap is singled- 572 ``uc_loopback``). This trap is singled-out because in cases such as
573 one-armed router it will be constantly 573 one-armed router it will be constantly triggered. To limit the impact on
574 the CPU usage, a packet trap policer wi 574 the CPU usage, a packet trap policer with a low rate can be bound to the
575 group without affecting other traps 575 group without affecting other traps
576 * - ``local_delivery`` 576 * - ``local_delivery``
577 - Contains packet traps for packets that 577 - Contains packet traps for packets that should be locally delivered after
578 routing, but do not match more specific 578 routing, but do not match more specific packet traps (e.g.,
579 ``ipv4_bgp``) 579 ``ipv4_bgp``)
580 * - ``external_delivery`` 580 * - ``external_delivery``
581 - Contains packet traps for packets that 581 - Contains packet traps for packets that should be routed through an
582 external interface (e.g., management in 582 external interface (e.g., management interface) that does not belong to
583 the same device (e.g., switch ASIC) as 583 the same device (e.g., switch ASIC) as the ingress interface
584 * - ``ipv6`` 584 * - ``ipv6``
585 - Contains packet traps for various IPv6 585 - Contains packet traps for various IPv6 control packets (e.g., Router
586 Advertisements) 586 Advertisements)
587 * - ``ptp_event`` 587 * - ``ptp_event``
588 - Contains packet traps for PTP time-crit 588 - Contains packet traps for PTP time-critical event messages (Sync,
589 Delay_req, Pdelay_Req and Pdelay_Resp) 589 Delay_req, Pdelay_Req and Pdelay_Resp)
590 * - ``ptp_general`` 590 * - ``ptp_general``
591 - Contains packet traps for PTP general m 591 - Contains packet traps for PTP general messages (Announce, Follow_Up,
592 Delay_Resp, Pdelay_Resp_Follow_Up, mana 592 Delay_Resp, Pdelay_Resp_Follow_Up, management and signaling)
593 * - ``acl_sample`` 593 * - ``acl_sample``
594 - Contains packet traps for packets that 594 - Contains packet traps for packets that were sampled by the device during
595 ACL processing 595 ACL processing
596 * - ``acl_trap`` 596 * - ``acl_trap``
597 - Contains packet traps for packets that 597 - Contains packet traps for packets that were trapped (logged) by the
598 device during ACL processing 598 device during ACL processing
599 * - ``parser_error_drops`` 599 * - ``parser_error_drops``
600 - Contains packet traps for packets that 600 - Contains packet traps for packets that were marked by the device during
601 parsing as erroneous 601 parsing as erroneous
602 * - ``eapol`` 602 * - ``eapol``
603 - Contains packet traps for "Extensible A 603 - Contains packet traps for "Extensible Authentication Protocol over LAN"
604 (EAPOL) packets specified in IEEE 802.1 604 (EAPOL) packets specified in IEEE 802.1X
605 605
606 Packet Trap Policers 606 Packet Trap Policers
607 ==================== 607 ====================
608 608
609 As previously explained, the underlying device 609 As previously explained, the underlying device can trap certain packets to the
610 CPU for processing. In most cases, the underly 610 CPU for processing. In most cases, the underlying device is capable of handling
611 packet rates that are several orders of magnit 611 packet rates that are several orders of magnitude higher compared to those that
612 can be handled by the CPU. 612 can be handled by the CPU.
613 613
614 Therefore, in order to prevent the underlying 614 Therefore, in order to prevent the underlying device from overwhelming the CPU,
615 devices usually include packet trap policers t 615 devices usually include packet trap policers that are able to police the
616 trapped packets to rates that can be handled b 616 trapped packets to rates that can be handled by the CPU.
617 617
618 The ``devlink-trap`` mechanism allows capable 618 The ``devlink-trap`` mechanism allows capable device drivers to register their
619 supported packet trap policers with ``devlink` 619 supported packet trap policers with ``devlink``. The device driver can choose
620 to associate these policers with supported pac 620 to associate these policers with supported packet trap groups (see
621 :ref:`Generic-Packet-Trap-Groups`) during its 621 :ref:`Generic-Packet-Trap-Groups`) during its initialization, thereby exposing
622 its default control plane policy to user space 622 its default control plane policy to user space.
623 623
624 Device drivers should allow user space to chan 624 Device drivers should allow user space to change the parameters of the policers
625 (e.g., rate, burst size) as well as the associ 625 (e.g., rate, burst size) as well as the association between the policers and
626 trap groups by implementing the relevant callb 626 trap groups by implementing the relevant callbacks.
627 627
628 If possible, device drivers should implement a 628 If possible, device drivers should implement a callback that allows user space
629 to retrieve the number of packets that were dr 629 to retrieve the number of packets that were dropped by the policer because its
630 configured policy was violated. 630 configured policy was violated.
631 631
632 Testing 632 Testing
633 ======= 633 =======
634 634
635 See ``tools/testing/selftests/drivers/net/netd 635 See ``tools/testing/selftests/drivers/net/netdevsim/devlink_trap.sh`` for a
636 test covering the core infrastructure. Test ca 636 test covering the core infrastructure. Test cases should be added for any new
637 functionality. 637 functionality.
638 638
639 Device drivers should focus their tests on dev 639 Device drivers should focus their tests on device-specific functionality, such
640 as the triggering of supported packet traps. 640 as the triggering of supported packet traps.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.