[thirdparty/linux.git] / Documentation / networking / devlink / devlink-trap.rst

.. SPDX-License-Identifier: GPL-2.0

============
Devlink Trap
============

Background
==========

Devices capable of offloading the kernel's datapath and perform functions such
as bridging and routing must also be able to send specific packets to the
kernel (i.e., the CPU) for processing.

For example, a device acting as a multicast-aware bridge must be able to send
IGMP membership reports to the kernel for processing by the bridge module.
Without processing such packets, the bridge module could never populate its
MDB.

As another example, consider a device acting as router which has received an IP
packet with a TTL of 1. Upon routing the packet the device must send it to the
kernel so that it will route it as well and generate an ICMP Time Exceeded
error datagram. Without letting the kernel route such packets itself, utilities
such as ``traceroute`` could never work.

The fundamental ability of sending certain packets to the kernel for processing
is called "packet trapping".

Overview
========

The ``devlink-trap`` mechanism allows capable device drivers to register their
supported packet traps with ``devlink`` and report trapped packets to
``devlink`` for further analysis.

Upon receiving trapped packets, ``devlink`` will perform a per-trap packets and
bytes accounting and potentially report the packet to user space via a netlink
event along with all the provided metadata (e.g., trap reason, timestamp, input
port). This is especially useful for drop traps (see :ref:`Trap-Types`)
as it allows users to obtain further visibility into packet drops that would
otherwise be invisible.

The following diagram provides a general overview of ``devlink-trap``::

                                    Netlink event: Packet w/ metadata
                                                   Or a summary of recent drops
                                  ^
                                  |
         Userspace                |
        +---------------------------------------------------+
         Kernel                   |
                                  |
                          +-------+--------+
                          |                |
                          |  drop_monitor  |
                          |                |
                          +-------^--------+
                                  |
                                  |
                                  |
                             +----+----+
                             |         |      Kernel's Rx path
                             | devlink |      (non-drop traps)
                             |         |
                             +----^----+      ^
                                  |           |
                                  +-----------+
                                  |
                          +-------+-------+
                          |               |
                          | Device driver |
                          |               |
                          +-------^-------+
         Kernel                   |
        +---------------------------------------------------+
         Hardware                 |
                                  | Trapped packet
                                  |
                               +--+---+
                               |      |
                               | ASIC |
                               |      |
                               +------+

.. _Trap-Types:

Trap Types
==========

The ``devlink-trap`` mechanism supports the following packet trap types:

  * ``drop``: Trapped packets were dropped by the underlying device. Packets
    are only processed by ``devlink`` and not injected to the kernel's Rx path.
    The trap action (see :ref:`Trap-Actions`) can be changed.
  * ``exception``: Trapped packets were not forwarded as intended by the
    underlying device due to an exception (e.g., TTL error, missing neighbour
    entry) and trapped to the control plane for resolution. Packets are
    processed by ``devlink`` and injected to the kernel's Rx path. Changing the
    action of such traps is not allowed, as it can easily break the control
    plane.

.. _Trap-Actions:

Trap Actions
============

The ``devlink-trap`` mechanism supports the following packet trap actions:

  * ``trap``: The sole copy of the packet is sent to the CPU.
  * ``drop``: The packet is dropped by the underlying device and a copy is not
    sent to the CPU.

Generic Packet Traps
====================

Generic packet traps are used to describe traps that trap well-defined packets
or packets that are trapped due to well-defined conditions (e.g., TTL error).
Such traps can be shared by multiple device drivers and their description must
be added to the following table:

.. list-table:: List of Generic Packet Traps
   :widths: 5 5 90

   * - Name
     - Type
     - Description
   * - ``source_mac_is_multicast``
     - ``drop``
     - Traps incoming packets that the device decided to drop because of a
       multicast source MAC
   * - ``vlan_tag_mismatch``
     - ``drop``
     - Traps incoming packets that the device decided to drop in case of VLAN
       tag mismatch: The ingress bridge port is not configured with a PVID and
       the packet is untagged or prio-tagged
   * - ``ingress_vlan_filter``
     - ``drop``
     - Traps incoming packets that the device decided to drop in case they are
       tagged with a VLAN that is not configured on the ingress bridge port
   * - ``ingress_spanning_tree_filter``
     - ``drop``
     - Traps incoming packets that the device decided to drop in case the STP
       state of the ingress bridge port is not "forwarding"
   * - ``port_list_is_empty``
     - ``drop``
     - Traps packets that the device decided to drop in case they need to be
       flooded (e.g., unknown unicast, unregistered multicast) and there are
       no ports the packets should be flooded to
   * - ``port_loopback_filter``
     - ``drop``
     - Traps packets that the device decided to drop in case after layer 2
       forwarding the only port from which they should be transmitted through
       is the port from which they were received
   * - ``blackhole_route``
     - ``drop``
     - Traps packets that the device decided to drop in case they hit a
       blackhole route
   * - ``ttl_value_is_too_small``
     - ``exception``
     - Traps unicast packets that should be forwarded by the device whose TTL
       was decremented to 0 or less
   * - ``tail_drop``
     - ``drop``
     - Traps packets that the device decided to drop because they could not be
       enqueued to a transmission queue which is full
   * - ``non_ip``
     - ``drop``
     - Traps packets that the device decided to drop because they need to
       undergo a layer 3 lookup, but are not IP or MPLS packets
   * - ``uc_dip_over_mc_dmac``
     - ``drop``
     - Traps packets that the device decided to drop because they need to be
       routed and they have a unicast destination IP and a multicast destination
       MAC
   * - ``dip_is_loopback_address``
     - ``drop``
     - Traps packets that the device decided to drop because they need to be
       routed and their destination IP is the loopback address (i.e., 127.0.0.0/8
       and ::1/128)
   * - ``sip_is_mc``
     - ``drop``
     - Traps packets that the device decided to drop because they need to be
       routed and their source IP is multicast (i.e., 224.0.0.0/8 and ff::/8)
   * - ``sip_is_loopback_address``
     - ``drop``
     - Traps packets that the device decided to drop because they need to be
       routed and their source IP is the loopback address (i.e., 127.0.0.0/8 and ::1/128)
   * - ``ip_header_corrupted``
     - ``drop``
     - Traps packets that the device decided to drop because they need to be
       routed and their IP header is corrupted: wrong checksum, wrong IP version
       or too short Internet Header Length (IHL)
   * - ``ipv4_sip_is_limited_bc``
     - ``drop``
     - Traps packets that the device decided to drop because they need to be
       routed and their source IP is limited broadcast (i.e., 255.255.255.255/32)
   * - ``ipv6_mc_dip_reserved_scope``
     - ``drop``
     - Traps IPv6 packets that the device decided to drop because they need to
       be routed and their IPv6 multicast destination IP has a reserved scope
       (i.e., ffx0::/16)
   * - ``ipv6_mc_dip_interface_local_scope``
     - ``drop``
     - Traps IPv6 packets that the device decided to drop because they need to
       be routed and their IPv6 multicast destination IP has an interface-local scope
       (i.e., ffx1::/16)
   * - ``mtu_value_is_too_small``
     - ``exception``
     - Traps packets that should have been routed by the device, but were bigger
       than the MTU of the egress interface
   * - ``unresolved_neigh``
     - ``exception``
     - Traps packets that did not have a matching IP neighbour after routing
   * - ``mc_reverse_path_forwarding``
     - ``exception``
     - Traps multicast IP packets that failed reverse-path forwarding (RPF)
       check during multicast routing
   * - ``reject_route``
     - ``exception``
     - Traps packets that hit reject routes (i.e., "unreachable", "prohibit")
   * - ``ipv4_lpm_miss``
     - ``exception``
     - Traps unicast IPv4 packets that did not match any route
   * - ``ipv6_lpm_miss``
     - ``exception``
     - Traps unicast IPv6 packets that did not match any route
   * - ``non_routable_packet``
     - ``drop``
     - Traps packets that the device decided to drop because they are not
       supposed to be routed. For example, IGMP queries can be flooded by the
       device in layer 2 and reach the router. Such packets should not be
       routed and instead dropped
   * - ``decap_error``
     - ``exception``
     - Traps NVE and IPinIP packets that the device decided to drop because of
       failure during decapsulation (e.g., packet being too short, reserved
       bits set in VXLAN header)
   * - ``overlay_smac_is_mc``
     - ``drop``
     - Traps NVE packets that the device decided to drop because their overlay
       source MAC is multicast
   * - ``ingress_flow_action_drop``
     - ``drop``
     - Traps packets dropped during processing of ingress flow action drop
   * - ``egress_flow_action_drop``
     - ``drop``
     - Traps packets dropped during processing of egress flow action drop

Driver-specific Packet Traps
============================

Device drivers can register driver-specific packet traps, but these must be
clearly documented. Such traps can correspond to device-specific exceptions and
help debug packet drops caused by these exceptions. The following list includes
links to the description of driver-specific traps registered by various device
drivers:

  * :doc:`netdevsim`
  * :doc:`mlxsw`

.. _Generic-Packet-Trap-Groups:

Generic Packet Trap Groups
==========================

Generic packet trap groups are used to aggregate logically related packet
traps. These groups allow the user to batch operations such as setting the trap
action of all member traps. In addition, ``devlink-trap`` can report aggregated
per-group packets and bytes statistics, in case per-trap statistics are too
narrow. The description of these groups must be added to the following table:

.. list-table:: List of Generic Packet Trap Groups
   :widths: 10 90

   * - Name
     - Description
   * - ``l2_drops``
     - Contains packet traps for packets that were dropped by the device during
       layer 2 forwarding (i.e., bridge)
   * - ``l3_drops``
     - Contains packet traps for packets that were dropped by the device or hit
       an exception (e.g., TTL error) during layer 3 forwarding
   * - ``buffer_drops``
     - Contains packet traps for packets that were dropped by the device due to
       an enqueue decision
   * - ``tunnel_drops``
     - Contains packet traps for packets that were dropped by the device during
       tunnel encapsulation / decapsulation
   * - ``acl_drops``
     - Contains packet traps for packets that were dropped by the device during
       ACL processing

Packet Trap Policers
====================

As previously explained, the underlying device can trap certain packets to the
CPU for processing. In most cases, the underlying device is capable of handling
packet rates that are several orders of magnitude higher compared to those that
can be handled by the CPU.

Therefore, in order to prevent the underlying device from overwhelming the CPU,
devices usually include packet trap policers that are able to police the
trapped packets to rates that can be handled by the CPU.

The ``devlink-trap`` mechanism allows capable device drivers to register their
supported packet trap policers with ``devlink``. The device driver can choose
to associate these policers with supported packet trap groups (see
:ref:`Generic-Packet-Trap-Groups`) during its initialization, thereby exposing
its default control plane policy to user space.

Device drivers should allow user space to change the parameters of the policers
(e.g., rate, burst size) as well as the association between the policers and
trap groups by implementing the relevant callbacks.

If possible, device drivers should implement a callback that allows user space
to retrieve the number of packets that were dropped by the policer because its
configured policy was violated.

Testing
=======

See ``tools/testing/selftests/drivers/net/netdevsim/devlink_trap.sh`` for a
test covering the core infrastructure. Test cases should be added for any new
functionality.

Device drivers should focus their tests on device-specific functionality, such
as the triggering of supported packet traps.
Commit	Line	Data
f3047ca0 IS	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
44bde514 IS	146	flooded (e.g., unknown unicast, unregistered multicast) and there are
44bde514 IS	147	no ports the packets should be flooded to
f3047ca0 IS	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
6896cc4d AC	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)
3b063ae5 AC	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
95f0ead8 AC	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
13c056ec AC	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)
c3cae491 AC	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
ecd942a0 JP	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
f3047ca0	247
9e087457 IS	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
04e4272c	257	* :doc:`netdevsim`
5b051621	258	* :doc:`mlxsw`
9e087457	259
e750b84d LR	260	.. _Generic-Packet-Trap-Groups:
e750b84d LR	261
f3047ca0 IS	262	Generic Packet Trap Groups
	263	==========================
	264
	265	Generic packet trap groups are used to aggregate logically related packet
	266	traps. These groups allow the user to batch operations such as setting the trap
	267	action of all member traps. In addition, ``devlink-trap`` can report aggregated
	268	per-group packets and bytes statistics, in case per-trap statistics are too
	269	narrow. The description of these groups must be added to the following table:
	270
	271	.. list-table:: List of Generic Packet Trap Groups
	272	:widths: 10 90
	273
	274	* - Name
	275	- Description
	276	* - ``l2_drops``
	277	- Contains packet traps for packets that were dropped by the device during
	278	layer 2 forwarding (i.e., bridge)
	279	* - ``l3_drops``
	280	- Contains packet traps for packets that were dropped by the device or hit
	281	an exception (e.g., TTL error) during layer 3 forwarding
	282	* - ``buffer_drops``
	283	- Contains packet traps for packets that were dropped by the device due to
	284	an enqueue decision
13c056ec AC	285	* - ``tunnel_drops``
	286	- Contains packet traps for packets that were dropped by the device during
	287	tunnel encapsulation / decapsulation
ecd942a0 JP	288	* - ``acl_drops``
	289	- Contains packet traps for packets that were dropped by the device during
	290	ACL processing
95766451	291
ef7d5c7d IS	292	Packet Trap Policers
	293	====================
	294
	295	As previously explained, the underlying device can trap certain packets to the
	296	CPU for processing. In most cases, the underlying device is capable of handling
	297	packet rates that are several orders of magnitude higher compared to those that
	298	can be handled by the CPU.
	299
	300	Therefore, in order to prevent the underlying device from overwhelming the CPU,
	301	devices usually include packet trap policers that are able to police the
	302	trapped packets to rates that can be handled by the CPU.
	303
	304	The ``devlink-trap`` mechanism allows capable device drivers to register their
	305	supported packet trap policers with ``devlink``. The device driver can choose
	306	to associate these policers with supported packet trap groups (see
	307	:ref:`Generic-Packet-Trap-Groups`) during its initialization, thereby exposing
	308	its default control plane policy to user space.
	309
	310	Device drivers should allow user space to change the parameters of the policers
	311	(e.g., rate, burst size) as well as the association between the policers and
	312	trap groups by implementing the relevant callbacks.
	313
	314	If possible, device drivers should implement a callback that allows user space
	315	to retrieve the number of packets that were dropped by the policer because its
	316	configured policy was violated.
	317
95766451 IS	318	Testing
	319	=======
	320
	321	See ``tools/testing/selftests/drivers/net/netdevsim/devlink_trap.sh`` for a
	322	test covering the core infrastructure. Test cases should be added for any new
	323	functionality.
	324
	325	Device drivers should focus their tests on device-specific functionality, such
	326	as the triggering of supported packet traps.