0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ============
0004 Devlink Trap
0005 ============
0006
0007 Background
0008 ==========
0009
0010 Devices capable of offloading the kernel's datapath and perform functions such
0011 as bridging and routing must also be able to send specific packets to the
0012 kernel (i.e., the CPU) for processing.
0013
0014 For example, a device acting as a multicast-aware bridge must be able to send
0015 IGMP membership reports to the kernel for processing by the bridge module.
0016 Without processing such packets, the bridge module could never populate its
0017 MDB.
0018
0019 As another example, consider a device acting as router which has received an IP
0020 packet with a TTL of 1. Upon routing the packet the device must send it to the
0021 kernel so that it will route it as well and generate an ICMP Time Exceeded
0022 error datagram. Without letting the kernel route such packets itself, utilities
0023 such as ``traceroute`` could never work.
0024
0025 The fundamental ability of sending certain packets to the kernel for processing
0026 is called "packet trapping".
0027
0028 Overview
0029 ========
0030
0031 The ``devlink-trap`` mechanism allows capable device drivers to register their
0032 supported packet traps with ``devlink`` and report trapped packets to
0033 ``devlink`` for further analysis.
0034
0035 Upon receiving trapped packets, ``devlink`` will perform a per-trap packets and
0036 bytes accounting and potentially report the packet to user space via a netlink
0037 event along with all the provided metadata (e.g., trap reason, timestamp, input
0038 port). This is especially useful for drop traps (see :ref:`Trap-Types`)
0039 as it allows users to obtain further visibility into packet drops that would
0040 otherwise be invisible.
0041
0042 The following diagram provides a general overview of ``devlink-trap``::
0043
0044 Netlink event: Packet w/ metadata
0045 Or a summary of recent drops
0046 ^
0047 |
0048 Userspace |
0049 +---------------------------------------------------+
0050 Kernel |
0051 |
0052 +-------+--------+
0053 | |
0054 | drop_monitor |
0055 | |
0056 +-------^--------+
0057 |
0058 | Non-control traps
0059 |
0060 +----+----+
0061 | | Kernel's Rx path
0062 | devlink | (non-drop traps)
0063 | |
0064 +----^----+ ^
0065 | |
0066 +-----------+
0067 |
0068 +-------+-------+
0069 | |
0070 | Device driver |
0071 | |
0072 +-------^-------+
0073 Kernel |
0074 +---------------------------------------------------+
0075 Hardware |
0076 | Trapped packet
0077 |
0078 +--+---+
0079 | |
0080 | ASIC |
0081 | |
0082 +------+
0083
0084 .. _Trap-Types:
0085
0086 Trap Types
0087 ==========
0088
0089 The ``devlink-trap`` mechanism supports the following packet trap types:
0090
0091 * ``drop``: Trapped packets were dropped by the underlying device. Packets
0092 are only processed by ``devlink`` and not injected to the kernel's Rx path.
0093 The trap action (see :ref:`Trap-Actions`) can be changed.
0094 * ``exception``: Trapped packets were not forwarded as intended by the
0095 underlying device due to an exception (e.g., TTL error, missing neighbour
0096 entry) and trapped to the control plane for resolution. Packets are
0097 processed by ``devlink`` and injected to the kernel's Rx path. Changing the
0098 action of such traps is not allowed, as it can easily break the control
0099 plane.
0100 * ``control``: Trapped packets were trapped by the device because these are
0101 control packets required for the correct functioning of the control plane.
0102 For example, ARP request and IGMP query packets. Packets are injected to
0103 the kernel's Rx path, but not reported to the kernel's drop monitor.
0104 Changing the action of such traps is not allowed, as it can easily break
0105 the control plane.
0106
0107 .. _Trap-Actions:
0108
0109 Trap Actions
0110 ============
0111
0112 The ``devlink-trap`` mechanism supports the following packet trap actions:
0113
0114 * ``trap``: The sole copy of the packet is sent to the CPU.
0115 * ``drop``: The packet is dropped by the underlying device and a copy is not
0116 sent to the CPU.
0117 * ``mirror``: The packet is forwarded by the underlying device and a copy is
0118 sent to the CPU.
0119
0120 Generic Packet Traps
0121 ====================
0122
0123 Generic packet traps are used to describe traps that trap well-defined packets
0124 or packets that are trapped due to well-defined conditions (e.g., TTL error).
0125 Such traps can be shared by multiple device drivers and their description must
0126 be added to the following table:
0127
0128 .. list-table:: List of Generic Packet Traps
0129 :widths: 5 5 90
0130
0131 * - Name
0132 - Type
0133 - Description
0134 * - ``source_mac_is_multicast``
0135 - ``drop``
0136 - Traps incoming packets that the device decided to drop because of a
0137 multicast source MAC
0138 * - ``vlan_tag_mismatch``
0139 - ``drop``
0140 - Traps incoming packets that the device decided to drop in case of VLAN
0141 tag mismatch: The ingress bridge port is not configured with a PVID and
0142 the packet is untagged or prio-tagged
0143 * - ``ingress_vlan_filter``
0144 - ``drop``
0145 - Traps incoming packets that the device decided to drop in case they are
0146 tagged with a VLAN that is not configured on the ingress bridge port
0147 * - ``ingress_spanning_tree_filter``
0148 - ``drop``
0149 - Traps incoming packets that the device decided to drop in case the STP
0150 state of the ingress bridge port is not "forwarding"
0151 * - ``port_list_is_empty``
0152 - ``drop``
0153 - Traps packets that the device decided to drop in case they need to be
0154 flooded (e.g., unknown unicast, unregistered multicast) and there are
0155 no ports the packets should be flooded to
0156 * - ``port_loopback_filter``
0157 - ``drop``
0158 - Traps packets that the device decided to drop in case after layer 2
0159 forwarding the only port from which they should be transmitted through
0160 is the port from which they were received
0161 * - ``blackhole_route``
0162 - ``drop``
0163 - Traps packets that the device decided to drop in case they hit a
0164 blackhole route
0165 * - ``ttl_value_is_too_small``
0166 - ``exception``
0167 - Traps unicast packets that should be forwarded by the device whose TTL
0168 was decremented to 0 or less
0169 * - ``tail_drop``
0170 - ``drop``
0171 - Traps packets that the device decided to drop because they could not be
0172 enqueued to a transmission queue which is full
0173 * - ``non_ip``
0174 - ``drop``
0175 - Traps packets that the device decided to drop because they need to
0176 undergo a layer 3 lookup, but are not IP or MPLS packets
0177 * - ``uc_dip_over_mc_dmac``
0178 - ``drop``
0179 - Traps packets that the device decided to drop because they need to be
0180 routed and they have a unicast destination IP and a multicast destination
0181 MAC
0182 * - ``dip_is_loopback_address``
0183 - ``drop``
0184 - Traps packets that the device decided to drop because they need to be
0185 routed and their destination IP is the loopback address (i.e., 127.0.0.0/8
0186 and ::1/128)
0187 * - ``sip_is_mc``
0188 - ``drop``
0189 - Traps packets that the device decided to drop because they need to be
0190 routed and their source IP is multicast (i.e., 224.0.0.0/8 and ff::/8)
0191 * - ``sip_is_loopback_address``
0192 - ``drop``
0193 - Traps packets that the device decided to drop because they need to be
0194 routed and their source IP is the loopback address (i.e., 127.0.0.0/8 and ::1/128)
0195 * - ``ip_header_corrupted``
0196 - ``drop``
0197 - Traps packets that the device decided to drop because they need to be
0198 routed and their IP header is corrupted: wrong checksum, wrong IP version
0199 or too short Internet Header Length (IHL)
0200 * - ``ipv4_sip_is_limited_bc``
0201 - ``drop``
0202 - Traps packets that the device decided to drop because they need to be
0203 routed and their source IP is limited broadcast (i.e., 255.255.255.255/32)
0204 * - ``ipv6_mc_dip_reserved_scope``
0205 - ``drop``
0206 - Traps IPv6 packets that the device decided to drop because they need to
0207 be routed and their IPv6 multicast destination IP has a reserved scope
0208 (i.e., ffx0::/16)
0209 * - ``ipv6_mc_dip_interface_local_scope``
0210 - ``drop``
0211 - Traps IPv6 packets that the device decided to drop because they need to
0212 be routed and their IPv6 multicast destination IP has an interface-local scope
0213 (i.e., ffx1::/16)
0214 * - ``mtu_value_is_too_small``
0215 - ``exception``
0216 - Traps packets that should have been routed by the device, but were bigger
0217 than the MTU of the egress interface
0218 * - ``unresolved_neigh``
0219 - ``exception``
0220 - Traps packets that did not have a matching IP neighbour after routing
0221 * - ``mc_reverse_path_forwarding``
0222 - ``exception``
0223 - Traps multicast IP packets that failed reverse-path forwarding (RPF)
0224 check during multicast routing
0225 * - ``reject_route``
0226 - ``exception``
0227 - Traps packets that hit reject routes (i.e., "unreachable", "prohibit")
0228 * - ``ipv4_lpm_miss``
0229 - ``exception``
0230 - Traps unicast IPv4 packets that did not match any route
0231 * - ``ipv6_lpm_miss``
0232 - ``exception``
0233 - Traps unicast IPv6 packets that did not match any route
0234 * - ``non_routable_packet``
0235 - ``drop``
0236 - Traps packets that the device decided to drop because they are not
0237 supposed to be routed. For example, IGMP queries can be flooded by the
0238 device in layer 2 and reach the router. Such packets should not be
0239 routed and instead dropped
0240 * - ``decap_error``
0241 - ``exception``
0242 - Traps NVE and IPinIP packets that the device decided to drop because of
0243 failure during decapsulation (e.g., packet being too short, reserved
0244 bits set in VXLAN header)
0245 * - ``overlay_smac_is_mc``
0246 - ``drop``
0247 - Traps NVE packets that the device decided to drop because their overlay
0248 source MAC is multicast
0249 * - ``ingress_flow_action_drop``
0250 - ``drop``
0251 - Traps packets dropped during processing of ingress flow action drop
0252 * - ``egress_flow_action_drop``
0253 - ``drop``
0254 - Traps packets dropped during processing of egress flow action drop
0255 * - ``stp``
0256 - ``control``
0257 - Traps STP packets
0258 * - ``lacp``
0259 - ``control``
0260 - Traps LACP packets
0261 * - ``lldp``
0262 - ``control``
0263 - Traps LLDP packets
0264 * - ``igmp_query``
0265 - ``control``
0266 - Traps IGMP Membership Query packets
0267 * - ``igmp_v1_report``
0268 - ``control``
0269 - Traps IGMP Version 1 Membership Report packets
0270 * - ``igmp_v2_report``
0271 - ``control``
0272 - Traps IGMP Version 2 Membership Report packets
0273 * - ``igmp_v3_report``
0274 - ``control``
0275 - Traps IGMP Version 3 Membership Report packets
0276 * - ``igmp_v2_leave``
0277 - ``control``
0278 - Traps IGMP Version 2 Leave Group packets
0279 * - ``mld_query``
0280 - ``control``
0281 - Traps MLD Multicast Listener Query packets
0282 * - ``mld_v1_report``
0283 - ``control``
0284 - Traps MLD Version 1 Multicast Listener Report packets
0285 * - ``mld_v2_report``
0286 - ``control``
0287 - Traps MLD Version 2 Multicast Listener Report packets
0288 * - ``mld_v1_done``
0289 - ``control``
0290 - Traps MLD Version 1 Multicast Listener Done packets
0291 * - ``ipv4_dhcp``
0292 - ``control``
0293 - Traps IPv4 DHCP packets
0294 * - ``ipv6_dhcp``
0295 - ``control``
0296 - Traps IPv6 DHCP packets
0297 * - ``arp_request``
0298 - ``control``
0299 - Traps ARP request packets
0300 * - ``arp_response``
0301 - ``control``
0302 - Traps ARP response packets
0303 * - ``arp_overlay``
0304 - ``control``
0305 - Traps NVE-decapsulated ARP packets that reached the overlay network.
0306 This is required, for example, when the address that needs to be
0307 resolved is a local address
0308 * - ``ipv6_neigh_solicit``
0309 - ``control``
0310 - Traps IPv6 Neighbour Solicitation packets
0311 * - ``ipv6_neigh_advert``
0312 - ``control``
0313 - Traps IPv6 Neighbour Advertisement packets
0314 * - ``ipv4_bfd``
0315 - ``control``
0316 - Traps IPv4 BFD packets
0317 * - ``ipv6_bfd``
0318 - ``control``
0319 - Traps IPv6 BFD packets
0320 * - ``ipv4_ospf``
0321 - ``control``
0322 - Traps IPv4 OSPF packets
0323 * - ``ipv6_ospf``
0324 - ``control``
0325 - Traps IPv6 OSPF packets
0326 * - ``ipv4_bgp``
0327 - ``control``
0328 - Traps IPv4 BGP packets
0329 * - ``ipv6_bgp``
0330 - ``control``
0331 - Traps IPv6 BGP packets
0332 * - ``ipv4_vrrp``
0333 - ``control``
0334 - Traps IPv4 VRRP packets
0335 * - ``ipv6_vrrp``
0336 - ``control``
0337 - Traps IPv6 VRRP packets
0338 * - ``ipv4_pim``
0339 - ``control``
0340 - Traps IPv4 PIM packets
0341 * - ``ipv6_pim``
0342 - ``control``
0343 - Traps IPv6 PIM packets
0344 * - ``uc_loopback``
0345 - ``control``
0346 - Traps unicast packets that need to be routed through the same layer 3
0347 interface from which they were received. Such packets are routed by the
0348 kernel, but also cause it to potentially generate ICMP redirect packets
0349 * - ``local_route``
0350 - ``control``
0351 - Traps unicast packets that hit a local route and need to be locally
0352 delivered
0353 * - ``external_route``
0354 - ``control``
0355 - Traps packets that should be routed through an external interface (e.g.,
0356 management interface) that does not belong to the same device (e.g.,
0357 switch ASIC) as the ingress interface
0358 * - ``ipv6_uc_dip_link_local_scope``
0359 - ``control``
0360 - Traps unicast IPv6 packets that need to be routed and have a destination
0361 IP address with a link-local scope (i.e., fe80::/10). The trap allows
0362 device drivers to avoid programming link-local routes, but still receive
0363 packets for local delivery
0364 * - ``ipv6_dip_all_nodes``
0365 - ``control``
0366 - Traps IPv6 packets that their destination IP address is the "All Nodes
0367 Address" (i.e., ff02::1)
0368 * - ``ipv6_dip_all_routers``
0369 - ``control``
0370 - Traps IPv6 packets that their destination IP address is the "All Routers
0371 Address" (i.e., ff02::2)
0372 * - ``ipv6_router_solicit``
0373 - ``control``
0374 - Traps IPv6 Router Solicitation packets
0375 * - ``ipv6_router_advert``
0376 - ``control``
0377 - Traps IPv6 Router Advertisement packets
0378 * - ``ipv6_redirect``
0379 - ``control``
0380 - Traps IPv6 Redirect Message packets
0381 * - ``ipv4_router_alert``
0382 - ``control``
0383 - Traps IPv4 packets that need to be routed and include the Router Alert
0384 option. Such packets need to be locally delivered to raw sockets that
0385 have the IP_ROUTER_ALERT socket option set
0386 * - ``ipv6_router_alert``
0387 - ``control``
0388 - Traps IPv6 packets that need to be routed and include the Router Alert
0389 option in their Hop-by-Hop extension header. Such packets need to be
0390 locally delivered to raw sockets that have the IPV6_ROUTER_ALERT socket
0391 option set
0392 * - ``ptp_event``
0393 - ``control``
0394 - Traps PTP time-critical event messages (Sync, Delay_req, Pdelay_Req and
0395 Pdelay_Resp)
0396 * - ``ptp_general``
0397 - ``control``
0398 - Traps PTP general messages (Announce, Follow_Up, Delay_Resp,
0399 Pdelay_Resp_Follow_Up, management and signaling)
0400 * - ``flow_action_sample``
0401 - ``control``
0402 - Traps packets sampled during processing of flow action sample (e.g., via
0403 tc's sample action)
0404 * - ``flow_action_trap``
0405 - ``control``
0406 - Traps packets logged during processing of flow action trap (e.g., via
0407 tc's trap action)
0408 * - ``early_drop``
0409 - ``drop``
0410 - Traps packets dropped due to the RED (Random Early Detection) algorithm
0411 (i.e., early drops)
0412 * - ``vxlan_parsing``
0413 - ``drop``
0414 - Traps packets dropped due to an error in the VXLAN header parsing which
0415 might be because of packet truncation or the I flag is not set.
0416 * - ``llc_snap_parsing``
0417 - ``drop``
0418 - Traps packets dropped due to an error in the LLC+SNAP header parsing
0419 * - ``vlan_parsing``
0420 - ``drop``
0421 - Traps packets dropped due to an error in the VLAN header parsing. Could
0422 include unexpected packet truncation.
0423 * - ``pppoe_ppp_parsing``
0424 - ``drop``
0425 - Traps packets dropped due to an error in the PPPoE+PPP header parsing.
0426 This could include finding a session ID of 0xFFFF (which is reserved and
0427 not for use), a PPPoE length which is larger than the frame received or
0428 any common error on this type of header
0429 * - ``mpls_parsing``
0430 - ``drop``
0431 - Traps packets dropped due to an error in the MPLS header parsing which
0432 could include unexpected header truncation
0433 * - ``arp_parsing``
0434 - ``drop``
0435 - Traps packets dropped due to an error in the ARP header parsing
0436 * - ``ip_1_parsing``
0437 - ``drop``
0438 - Traps packets dropped due to an error in the first IP header parsing.
0439 This packet trap could include packets which do not pass an IP checksum
0440 check, a header length check (a minimum of 20 bytes), which might suffer
0441 from packet truncation thus the total length field exceeds the received
0442 packet length etc
0443 * - ``ip_n_parsing``
0444 - ``drop``
0445 - Traps packets dropped due to an error in the parsing of the last IP
0446 header (the inner one in case of an IP over IP tunnel). The same common
0447 error checking is performed here as for the ip_1_parsing trap
0448 * - ``gre_parsing``
0449 - ``drop``
0450 - Traps packets dropped due to an error in the GRE header parsing
0451 * - ``udp_parsing``
0452 - ``drop``
0453 - Traps packets dropped due to an error in the UDP header parsing.
0454 This packet trap could include checksum errorrs, an improper UDP
0455 length detected (smaller than 8 bytes) or detection of header
0456 truncation.
0457 * - ``tcp_parsing``
0458 - ``drop``
0459 - Traps packets dropped due to an error in the TCP header parsing.
0460 This could include TCP checksum errors, improper combination of SYN, FIN
0461 and/or RESET etc.
0462 * - ``ipsec_parsing``
0463 - ``drop``
0464 - Traps packets dropped due to an error in the IPSEC header parsing
0465 * - ``sctp_parsing``
0466 - ``drop``
0467 - Traps packets dropped due to an error in the SCTP header parsing.
0468 This would mean that port number 0 was used or that the header is
0469 truncated.
0470 * - ``dccp_parsing``
0471 - ``drop``
0472 - Traps packets dropped due to an error in the DCCP header parsing
0473 * - ``gtp_parsing``
0474 - ``drop``
0475 - Traps packets dropped due to an error in the GTP header parsing
0476 * - ``esp_parsing``
0477 - ``drop``
0478 - Traps packets dropped due to an error in the ESP header parsing
0479 * - ``blackhole_nexthop``
0480 - ``drop``
0481 - Traps packets that the device decided to drop in case they hit a
0482 blackhole nexthop
0483 * - ``dmac_filter``
0484 - ``drop``
0485 - Traps incoming packets that the device decided to drop because
0486 the destination MAC is not configured in the MAC table and
0487 the interface is not in promiscuous mode
0488
0489 Driver-specific Packet Traps
0490 ============================
0491
0492 Device drivers can register driver-specific packet traps, but these must be
0493 clearly documented. Such traps can correspond to device-specific exceptions and
0494 help debug packet drops caused by these exceptions. The following list includes
0495 links to the description of driver-specific traps registered by various device
0496 drivers:
0497
0498 * Documentation/networking/devlink/netdevsim.rst
0499 * Documentation/networking/devlink/mlxsw.rst
0500 * Documentation/networking/devlink/prestera.rst
0501
0502 .. _Generic-Packet-Trap-Groups:
0503
0504 Generic Packet Trap Groups
0505 ==========================
0506
0507 Generic packet trap groups are used to aggregate logically related packet
0508 traps. These groups allow the user to batch operations such as setting the trap
0509 action of all member traps. In addition, ``devlink-trap`` can report aggregated
0510 per-group packets and bytes statistics, in case per-trap statistics are too
0511 narrow. The description of these groups must be added to the following table:
0512
0513 .. list-table:: List of Generic Packet Trap Groups
0514 :widths: 10 90
0515
0516 * - Name
0517 - Description
0518 * - ``l2_drops``
0519 - Contains packet traps for packets that were dropped by the device during
0520 layer 2 forwarding (i.e., bridge)
0521 * - ``l3_drops``
0522 - Contains packet traps for packets that were dropped by the device during
0523 layer 3 forwarding
0524 * - ``l3_exceptions``
0525 - Contains packet traps for packets that hit an exception (e.g., TTL
0526 error) during layer 3 forwarding
0527 * - ``buffer_drops``
0528 - Contains packet traps for packets that were dropped by the device due to
0529 an enqueue decision
0530 * - ``tunnel_drops``
0531 - Contains packet traps for packets that were dropped by the device during
0532 tunnel encapsulation / decapsulation
0533 * - ``acl_drops``
0534 - Contains packet traps for packets that were dropped by the device during
0535 ACL processing
0536 * - ``stp``
0537 - Contains packet traps for STP packets
0538 * - ``lacp``
0539 - Contains packet traps for LACP packets
0540 * - ``lldp``
0541 - Contains packet traps for LLDP packets
0542 * - ``mc_snooping``
0543 - Contains packet traps for IGMP and MLD packets required for multicast
0544 snooping
0545 * - ``dhcp``
0546 - Contains packet traps for DHCP packets
0547 * - ``neigh_discovery``
0548 - Contains packet traps for neighbour discovery packets (e.g., ARP, IPv6
0549 ND)
0550 * - ``bfd``
0551 - Contains packet traps for BFD packets
0552 * - ``ospf``
0553 - Contains packet traps for OSPF packets
0554 * - ``bgp``
0555 - Contains packet traps for BGP packets
0556 * - ``vrrp``
0557 - Contains packet traps for VRRP packets
0558 * - ``pim``
0559 - Contains packet traps for PIM packets
0560 * - ``uc_loopback``
0561 - Contains a packet trap for unicast loopback packets (i.e.,
0562 ``uc_loopback``). This trap is singled-out because in cases such as
0563 one-armed router it will be constantly triggered. To limit the impact on
0564 the CPU usage, a packet trap policer with a low rate can be bound to the
0565 group without affecting other traps
0566 * - ``local_delivery``
0567 - Contains packet traps for packets that should be locally delivered after
0568 routing, but do not match more specific packet traps (e.g.,
0569 ``ipv4_bgp``)
0570 * - ``external_delivery``
0571 - Contains packet traps for packets that should be routed through an
0572 external interface (e.g., management interface) that does not belong to
0573 the same device (e.g., switch ASIC) as the ingress interface
0574 * - ``ipv6``
0575 - Contains packet traps for various IPv6 control packets (e.g., Router
0576 Advertisements)
0577 * - ``ptp_event``
0578 - Contains packet traps for PTP time-critical event messages (Sync,
0579 Delay_req, Pdelay_Req and Pdelay_Resp)
0580 * - ``ptp_general``
0581 - Contains packet traps for PTP general messages (Announce, Follow_Up,
0582 Delay_Resp, Pdelay_Resp_Follow_Up, management and signaling)
0583 * - ``acl_sample``
0584 - Contains packet traps for packets that were sampled by the device during
0585 ACL processing
0586 * - ``acl_trap``
0587 - Contains packet traps for packets that were trapped (logged) by the
0588 device during ACL processing
0589 * - ``parser_error_drops``
0590 - Contains packet traps for packets that were marked by the device during
0591 parsing as erroneous
0592
0593 Packet Trap Policers
0594 ====================
0595
0596 As previously explained, the underlying device can trap certain packets to the
0597 CPU for processing. In most cases, the underlying device is capable of handling
0598 packet rates that are several orders of magnitude higher compared to those that
0599 can be handled by the CPU.
0600
0601 Therefore, in order to prevent the underlying device from overwhelming the CPU,
0602 devices usually include packet trap policers that are able to police the
0603 trapped packets to rates that can be handled by the CPU.
0604
0605 The ``devlink-trap`` mechanism allows capable device drivers to register their
0606 supported packet trap policers with ``devlink``. The device driver can choose
0607 to associate these policers with supported packet trap groups (see
0608 :ref:`Generic-Packet-Trap-Groups`) during its initialization, thereby exposing
0609 its default control plane policy to user space.
0610
0611 Device drivers should allow user space to change the parameters of the policers
0612 (e.g., rate, burst size) as well as the association between the policers and
0613 trap groups by implementing the relevant callbacks.
0614
0615 If possible, device drivers should implement a callback that allows user space
0616 to retrieve the number of packets that were dropped by the policer because its
0617 configured policy was violated.
0618
0619 Testing
0620 =======
0621
0622 See ``tools/testing/selftests/drivers/net/netdevsim/devlink_trap.sh`` for a
0623 test covering the core infrastructure. Test cases should be added for any new
0624 functionality.
0625
0626 Device drivers should focus their tests on device-specific functionality, such
0627 as the triggering of supported packet traps.
