devlink-trap.rst 24 KB

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