Merge tag 'compiler-attributes-for-linus-v5.4' of git://github.com/ojeda/linux
[sfrench/cifs-2.6.git] / Documentation / networking / 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 and the flood list is empty
147    * - ``port_loopback_filter``
148      - ``drop``
149      - Traps packets that the device decided to drop in case after layer 2
150        forwarding the only port from which they should be transmitted through
151        is the port from which they were received
152    * - ``blackhole_route``
153      - ``drop``
154      - Traps packets that the device decided to drop in case they hit a
155        blackhole route
156    * - ``ttl_value_is_too_small``
157      - ``exception``
158      - Traps unicast packets that should be forwarded by the device whose TTL
159        was decremented to 0 or less
160    * - ``tail_drop``
161      - ``drop``
162      - Traps packets that the device decided to drop because they could not be
163        enqueued to a transmission queue which is full
164
165 Driver-specific Packet Traps
166 ============================
167
168 Device drivers can register driver-specific packet traps, but these must be
169 clearly documented. Such traps can correspond to device-specific exceptions and
170 help debug packet drops caused by these exceptions. The following list includes
171 links to the description of driver-specific traps registered by various device
172 drivers:
173
174   * :doc:`/devlink-trap-netdevsim`
175
176 Generic Packet Trap Groups
177 ==========================
178
179 Generic packet trap groups are used to aggregate logically related packet
180 traps. These groups allow the user to batch operations such as setting the trap
181 action of all member traps. In addition, ``devlink-trap`` can report aggregated
182 per-group packets and bytes statistics, in case per-trap statistics are too
183 narrow. The description of these groups must be added to the following table:
184
185 .. list-table:: List of Generic Packet Trap Groups
186    :widths: 10 90
187
188    * - Name
189      - Description
190    * - ``l2_drops``
191      - Contains packet traps for packets that were dropped by the device during
192        layer 2 forwarding (i.e., bridge)
193    * - ``l3_drops``
194      - Contains packet traps for packets that were dropped by the device or hit
195        an exception (e.g., TTL error) during layer 3 forwarding
196    * - ``buffer_drops``
197      - Contains packet traps for packets that were dropped by the device due to
198        an enqueue decision
199
200 Testing
201 =======
202
203 See ``tools/testing/selftests/drivers/net/netdevsim/devlink_trap.sh`` for a
204 test covering the core infrastructure. Test cases should be added for any new
205 functionality.
206
207 Device drivers should focus their tests on device-specific functionality, such
208 as the triggering of supported packet traps.