Documentation/networking/devlink/devlink-trap.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ============
   4 Devlink Trap
   5 ============
   6
   7 Background
   8 ==========
   9
  10 Devices capable of offloading the kernel's datapath and perform functions such
  11 as bridging and routing must also be able to send specific packets to the
  12 kernel (i.e., the CPU) for processing.
  13
  14 For example, a device acting as a multicast-aware bridge must be able to send
  15 IGMP membership reports to the kernel for processing by the bridge module.
  16 Without processing such packets, the bridge module could never populate its
  17 MDB.
  18
  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 packet the device must send it to the
  21 kernel so that it will route it as well and generate an ICMP Time Exceeded
  22 error datagram. Without letting the kernel route such packets itself, utilities
  23 such as ``traceroute`` could never work.
  24
  25 The fundamental ability of sending certain packets to the kernel for processing
  26 is called "packet trapping".
  27
  28 Overview
  29 ========
  30
  31 The ``devlink-trap`` mechanism allows capable device drivers to register their
  32 supported packet traps with ``devlink`` and report trapped packets to
  33 ``devlink`` for further analysis.
  34
  35 Upon receiving trapped packets, ``devlink`` will perform a per-trap packets and
  36 bytes accounting and potentially report the packet to user space via a netlink
  37 event along with all the provided metadata (e.g., trap reason, timestamp, input
  38 port). This is especially useful for drop traps (see :ref:`Trap-Types`)
  39 as it allows users to obtain further visibility into packet drops that would
  40 otherwise be invisible.
  41
  42 The following diagram provides a general overview of ``devlink-trap``::
  43
  44                                     Netlink event: Packet w/ metadata
  45                                                    Or a summary of recent drops
  46                                   ^
  47                                   |
  48          Userspace                |
  49         +---------------------------------------------------+
  50          Kernel                   |
  51                                   |
  52                           +-------+--------+
  53                           |                |
  54                           |  drop_monitor  |
  55                           |                |
  56                           +-------^--------+
  57                                   |
  58                                   |
  59                                   |
  60                              +----+----+
  61                              |         |      Kernel's Rx path
  62                              | devlink |      (non-drop traps)
  63                              |         |
  64                              +----^----+      ^
  65                                   |           |
  66                                   +-----------+
  67                                   |
  68                           +-------+-------+
  69                           |               |
  70                           | Device driver |
  71                           |               |
  72                           +-------^-------+
  73          Kernel                   |
  74         +---------------------------------------------------+
  75          Hardware                 |
  76                                   | Trapped packet
  77                                   |
  78                                +--+---+
  79                                |      |
  80                                | ASIC |
  81                                |      |
  82                                +------+
  83
  84 .. _Trap-Types:
  85
  86 Trap Types
  87 ==========
  88
  89 The ``devlink-trap`` mechanism supports the following packet trap types:
  90
  91   * ``drop``: Trapped packets were dropped by the underlying device. Packets
  92     are only processed by ``devlink`` and not injected to the kernel's Rx path.
  93     The trap action (see :ref:`Trap-Actions`) can be changed.
  94   * ``exception``: Trapped packets were not forwarded as intended by the
  95     underlying device due to an exception (e.g., TTL error, missing neighbour
  96     entry) and trapped to the control plane for resolution. Packets are
  97     processed by ``devlink`` and injected to the kernel's Rx path. Changing the
  98     action of such traps is not allowed, as it can easily break the control
  99     plane.
 100
 101 .. _Trap-Actions:
 102
 103 Trap Actions
 104 ============
 105
 106 The ``devlink-trap`` mechanism supports the following packet trap actions:
 107
 108   * ``trap``: The sole copy of the packet is sent to the CPU.
 109   * ``drop``: The packet is dropped by the underlying device and a copy is not
 110     sent to the CPU.
 111
 112 Generic Packet Traps
 113 ====================
 114
 115 Generic packet traps are used to describe traps that trap well-defined packets
 116 or packets that are trapped due to well-defined conditions (e.g., TTL error).
 117 Such traps can be shared by multiple device drivers and their description must
 118 be added to the following table:
 119
 120 .. list-table:: List of Generic Packet Traps
 121    :widths: 5 5 90
 122
 123    * - Name
 124      - Type
 125      - Description
 126    * - ``source_mac_is_multicast``
 127      - ``drop``
 128      - Traps incoming packets that the device decided to drop because of a
 129        multicast source MAC
 130    * - ``vlan_tag_mismatch``
 131      - ``drop``
 132      - Traps incoming packets that the device decided to drop in case of VLAN
 133        tag mismatch: The ingress bridge port is not configured with a PVID and
 134        the packet is untagged or prio-tagged
 135    * - ``ingress_vlan_filter``
 136      - ``drop``
 137      - Traps incoming packets that the device decided to drop in case they are
 138        tagged with a VLAN that is not configured on the ingress bridge port
 139    * - ``ingress_spanning_tree_filter``
 140      - ``drop``
 141      - Traps incoming packets that the device decided to drop in case the STP
 142        state of the ingress bridge port is not "forwarding"
 143    * - ``port_list_is_empty``
 144      - ``drop``
 145      - Traps packets that the device decided to drop in case they need to be
 146        flooded (e.g., unknown unicast, unregistered multicast) and there are
 147        no ports the packets should be flooded to
 148    * - ``port_loopback_filter``
 149      - ``drop``
 150      - Traps packets that the device decided to drop in case after layer 2
 151        forwarding the only port from which they should be transmitted through
 152        is the port from which they were received
 153    * - ``blackhole_route``
 154      - ``drop``
 155      - Traps packets that the device decided to drop in case they hit a
 156        blackhole route
 157    * - ``ttl_value_is_too_small``
 158      - ``exception``
 159      - Traps unicast packets that should be forwarded by the device whose TTL
 160        was decremented to 0 or less
 161    * - ``tail_drop``
 162      - ``drop``
 163      - Traps packets that the device decided to drop because they could not be
 164        enqueued to a transmission queue which is full
 165    * - ``non_ip``
 166      - ``drop``
 167      - Traps packets that the device decided to drop because they need to
 168        undergo a layer 3 lookup, but are not IP or MPLS packets
 169    * - ``uc_dip_over_mc_dmac``
 170      - ``drop``
 171      - Traps packets that the device decided to drop because they need to be
 172        routed and they have a unicast destination IP and a multicast destination
 173        MAC
 174    * - ``dip_is_loopback_address``
 175      - ``drop``
 176      - Traps packets that the device decided to drop because they need to be
 177        routed and their destination IP is the loopback address (i.e., 127.0.0.0/8
 178        and ::1/128)
 179    * - ``sip_is_mc``
 180      - ``drop``
 181      - Traps packets that the device decided to drop because they need to be
 182        routed and their source IP is multicast (i.e., 224.0.0.0/8 and ff::/8)
 183    * - ``sip_is_loopback_address``
 184      - ``drop``
 185      - Traps packets that the device decided to drop because they need to be
 186        routed and their source IP is the loopback address (i.e., 127.0.0.0/8 and ::1/128)
 187    * - ``ip_header_corrupted``
 188      - ``drop``
 189      - Traps packets that the device decided to drop because they need to be
 190        routed and their IP header is corrupted: wrong checksum, wrong IP version
 191        or too short Internet Header Length (IHL)
 192    * - ``ipv4_sip_is_limited_bc``
 193      - ``drop``
 194      - Traps packets that the device decided to drop because they need to be
 195        routed and their source IP is limited broadcast (i.e., 255.255.255.255/32)
 196    * - ``ipv6_mc_dip_reserved_scope``
 197      - ``drop``
 198      - Traps IPv6 packets that the device decided to drop because they need to
 199        be routed and their IPv6 multicast destination IP has a reserved scope
 200        (i.e., ffx0::/16)
 201    * - ``ipv6_mc_dip_interface_local_scope``
 202      - ``drop``
 203      - Traps IPv6 packets that the device decided to drop because they need to
 204        be routed and their IPv6 multicast destination IP has an interface-local scope
 205        (i.e., ffx1::/16)
 206    * - ``mtu_value_is_too_small``
 207      - ``exception``
 208      - Traps packets that should have been routed by the device, but were bigger
 209        than the MTU of the egress interface
 210    * - ``unresolved_neigh``
 211      - ``exception``
 212      - Traps packets that did not have a matching IP neighbour after routing
 213    * - ``mc_reverse_path_forwarding``
 214      - ``exception``
 215      - Traps multicast IP packets that failed reverse-path forwarding (RPF)
 216        check during multicast routing
 217    * - ``reject_route``
 218      - ``exception``
 219      - Traps packets that hit reject routes (i.e., "unreachable", "prohibit")
 220    * - ``ipv4_lpm_miss``
 221      - ``exception``
 222      - Traps unicast IPv4 packets that did not match any route
 223    * - ``ipv6_lpm_miss``
 224      - ``exception``
 225      - Traps unicast IPv6 packets that did not match any route
 226    * - ``non_routable_packet``
 227      - ``drop``
 228      - Traps packets that the device decided to drop because they are not
 229        supposed to be routed. For example, IGMP queries can be flooded by the
 230        device in layer 2 and reach the router. Such packets should not be
 231        routed and instead dropped
 232    * - ``decap_error``
 233      - ``exception``
 234      - Traps NVE and IPinIP packets that the device decided to drop because of
 235        failure during decapsulation (e.g., packet being too short, reserved
 236        bits set in VXLAN header)
 237    * - ``overlay_smac_is_mc``
 238      - ``drop``
 239      - Traps NVE packets that the device decided to drop because their overlay
 240        source MAC is multicast
 241    * - ``ingress_flow_action_drop``
 242      - ``drop``
 243      - Traps packets dropped during processing of ingress flow action drop
 244    * - ``egress_flow_action_drop``
 245      - ``drop``
 246      - Traps packets dropped during processing of egress flow action drop
 247
 248 Driver-specific Packet Traps
 249 ============================
 250
 251 Device drivers can register driver-specific packet traps, but these must be
 252 clearly documented. Such traps can correspond to device-specific exceptions and
 253 help debug packet drops caused by these exceptions. The following list includes
 254 links to the description of driver-specific traps registered by various device
 255 drivers:
 256
 257   * :doc:`netdevsim`
 258   * :doc:`mlxsw`
 259
 260 Generic Packet Trap Groups
 261 ==========================
 262
 263 Generic packet trap groups are used to aggregate logically related packet
 264 traps. These groups allow the user to batch operations such as setting the trap
 265 action of all member traps. In addition, ``devlink-trap`` can report aggregated
 266 per-group packets and bytes statistics, in case per-trap statistics are too
 267 narrow. The description of these groups must be added to the following table:
 268
 269 .. list-table:: List of Generic Packet Trap Groups
 270    :widths: 10 90
 271
 272    * - Name
 273      - Description
 274    * - ``l2_drops``
 275      - Contains packet traps for packets that were dropped by the device during
 276        layer 2 forwarding (i.e., bridge)
 277    * - ``l3_drops``
 278      - Contains packet traps for packets that were dropped by the device or hit
 279        an exception (e.g., TTL error) during layer 3 forwarding
 280    * - ``buffer_drops``
 281      - Contains packet traps for packets that were dropped by the device due to
 282        an enqueue decision
 283    * - ``tunnel_drops``
 284      - Contains packet traps for packets that were dropped by the device during
 285        tunnel encapsulation / decapsulation
 286    * - ``acl_drops``
 287      - Contains packet traps for packets that were dropped by the device during
 288        ACL processing
 289
 290 Packet Trap Policers
 291 ====================
 292
 293 As previously explained, the underlying device can trap certain packets to the
 294 CPU for processing. In most cases, the underlying device is capable of handling
 295 packet rates that are several orders of magnitude higher compared to those that
 296 can be handled by the CPU.
 297
 298 Therefore, in order to prevent the underlying device from overwhelming the CPU,
 299 devices usually include packet trap policers that are able to police the
 300 trapped packets to rates that can be handled by the CPU.
 301
 302 The ``devlink-trap`` mechanism allows capable device drivers to register their
 303 supported packet trap policers with ``devlink``. The device driver can choose
 304 to associate these policers with supported packet trap groups (see
 305 :ref:`Generic-Packet-Trap-Groups`) during its initialization, thereby exposing
 306 its default control plane policy to user space.
 307
 308 Device drivers should allow user space to change the parameters of the policers
 309 (e.g., rate, burst size) as well as the association between the policers and
 310 trap groups by implementing the relevant callbacks.
 311
 312 If possible, device drivers should implement a callback that allows user space
 313 to retrieve the number of packets that were dropped by the policer because its
 314 configured policy was violated.
 315
 316 Testing
 317 =======
 318
 319 See ``tools/testing/selftests/drivers/net/netdevsim/devlink_trap.sh`` for a
 320 test covering the core infrastructure. Test cases should be added for any new
 321 functionality.
 322
 323 Device drivers should focus their tests on device-specific functionality, such
 324 as the triggering of supported packet traps.