code:
.. 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  |
                          |                |
                          +-------^--------+
                                  |
                                  | Non-control traps
                                  |
                             +----+----+
                             |         |      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.
  * ``control``: Trapped packets were trapped by the device because these are
    control packets required for the correct functioning of the control plane.
    For example, ARP request and IGMP query packets. Packets are injected to
    the kernel's Rx path, but not reported to the kernel's drop monitor.
    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.
  * ``mirror``: The packet is forwarded by the underlying device and a copy is
    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
   * - ``stp``
     - ``control``
     - Traps STP packets
   * - ``lacp``
     - ``control``
     - Traps LACP packets
   * - ``lldp``
     - ``control``
     - Traps LLDP packets
   * - ``igmp_query``
     - ``control``
     - Traps IGMP Membership Query packets
   * - ``igmp_v1_report``
     - ``control``
     - Traps IGMP Version 1 Membership Report packets
   * - ``igmp_v2_report``
     - ``control``
     - Traps IGMP Version 2 Membership Report packets
   * - ``igmp_v3_report``
     - ``control``
     - Traps IGMP Version 3 Membership Report packets
   * - ``igmp_v2_leave``
     - ``control``
     - Traps IGMP Version 2 Leave Group packets
   * - ``mld_query``
     - ``control``
     - Traps MLD Multicast Listener Query packets
   * - ``mld_v1_report``
     - ``control``
     - Traps MLD Version 1 Multicast Listener Report packets
   * - ``mld_v2_report``
     - ``control``
     - Traps MLD Version 2 Multicast Listener Report packets
   * - ``mld_v1_done``
     - ``control``
     - Traps MLD Version 1 Multicast Listener Done packets
   * - ``ipv4_dhcp``
     - ``control``
     - Traps IPv4 DHCP packets
   * - ``ipv6_dhcp``
     - ``control``
     - Traps IPv6 DHCP packets
   * - ``arp_request``
     - ``control``
     - Traps ARP request packets
   * - ``arp_response``
     - ``control``
     - Traps ARP response packets
   * - ``arp_overlay``
     - ``control``
     - Traps NVE-decapsulated ARP packets that reached the overlay network.
       This is required, for example, when the address that needs to be
       resolved is a local address
   * - ``ipv6_neigh_solicit``
     - ``control``
     - Traps IPv6 Neighbour Solicitation packets
   * - ``ipv6_neigh_advert``
     - ``control``
     - Traps IPv6 Neighbour Advertisement packets
   * - ``ipv4_bfd``
     - ``control``
     - Traps IPv4 BFD packets
   * - ``ipv6_bfd``
     - ``control``
     - Traps IPv6 BFD packets
   * - ``ipv4_ospf``
     - ``control``
     - Traps IPv4 OSPF packets
   * - ``ipv6_ospf``
     - ``control``
     - Traps IPv6 OSPF packets
   * - ``ipv4_bgp``
     - ``control``
     - Traps IPv4 BGP packets
   * - ``ipv6_bgp``
     - ``control``
     - Traps IPv6 BGP packets
   * - ``ipv4_vrrp``
     - ``control``
     - Traps IPv4 VRRP packets
   * - ``ipv6_vrrp``
     - ``control``
     - Traps IPv6 VRRP packets
   * - ``ipv4_pim``
     - ``control``
     - Traps IPv4 PIM packets
   * - ``ipv6_pim``
     - ``control``
     - Traps IPv6 PIM packets
   * - ``uc_loopback``
     - ``control``
     - Traps unicast packets that need to be routed through the same layer 3
       interface from which they were received. Such packets are routed by the
       kernel, but also cause it to potentially generate ICMP redirect packets
   * - ``local_route``
     - ``control``
     - Traps unicast packets that hit a local route and need to be locally
       delivered
   * - ``external_route``
     - ``control``
     - Traps packets that should be routed through an external interface (e.g.,
       management interface) that does not belong to the same device (e.g.,
       switch ASIC) as the ingress interface
   * - ``ipv6_uc_dip_link_local_scope``
     - ``control``
     - Traps unicast IPv6 packets that need to be routed and have a destination
       IP address with a link-local scope (i.e., fe80::/10). The trap allows
       device drivers to avoid programming link-local routes, but still receive
       packets for local delivery
   * - ``ipv6_dip_all_nodes``
     - ``control``
     - Traps IPv6 packets that their destination IP address is the "All Nodes
       Address" (i.e., ff02::1)
   * - ``ipv6_dip_all_routers``
     - ``control``
     - Traps IPv6 packets that their destination IP address is the "All Routers
       Address" (i.e., ff02::2)
   * - ``ipv6_router_solicit``
     - ``control``
     - Traps IPv6 Router Solicitation packets
   * - ``ipv6_router_advert``
     - ``control``
     - Traps IPv6 Router Advertisement packets
   * - ``ipv6_redirect``
     - ``control``
     - Traps IPv6 Redirect Message packets
   * - ``ipv4_router_alert``
     - ``control``
     - Traps IPv4 packets that need to be routed and include the Router Alert
       option. Such packets need to be locally delivered to raw sockets that
       have the IP_ROUTER_ALERT socket option set
   * - ``ipv6_router_alert``
     - ``control``
     - Traps IPv6 packets that need to be routed and include the Router Alert
       option in their Hop-by-Hop extension header. Such packets need to be
       locally delivered to raw sockets that have the IPV6_ROUTER_ALERT socket
       option set
   * - ``ptp_event``
     - ``control``
     - Traps PTP time-critical event messages (Sync, Delay_req, Pdelay_Req and
       Pdelay_Resp)
   * - ``ptp_general``
     - ``control``
     - Traps PTP general messages (Announce, Follow_Up, Delay_Resp,
       Pdelay_Resp_Follow_Up, management and signaling)
   * - ``flow_action_sample``
     - ``control``
     - Traps packets sampled during processing of flow action sample (e.g., via
       tc's sample action)
   * - ``flow_action_trap``
     - ``control``
     - Traps packets logged during processing of flow action trap (e.g., via
       tc's trap action)
   * - ``early_drop``
     - ``drop``
     - Traps packets dropped due to the RED (Random Early Detection) algorithm
       (i.e., early drops)
   * - ``vxlan_parsing``
     - ``drop``
     - Traps packets dropped due to an error in the VXLAN header parsing which
       might be because of packet truncation or the I flag is not set.
   * - ``llc_snap_parsing``
     - ``drop``
     - Traps packets dropped due to an error in the LLC+SNAP header parsing
   * - ``vlan_parsing``
     - ``drop``
     - Traps packets dropped due to an error in the VLAN header parsing. Could
       include unexpected packet truncation.
   * - ``pppoe_ppp_parsing``
     - ``drop``
     - Traps packets dropped due to an error in the PPPoE+PPP header parsing.
       This could include finding a session ID of 0xFFFF (which is reserved and
       not for use), a PPPoE length which is larger than the frame received or
       any common error on this type of header
   * - ``mpls_parsing``
     - ``drop``
     - Traps packets dropped due to an error in the MPLS header parsing which
       could include unexpected header truncation
   * - ``arp_parsing``
     - ``drop``
     - Traps packets dropped due to an error in the ARP header parsing
   * - ``ip_1_parsing``
     - ``drop``
     - Traps packets dropped due to an error in the first IP header parsing.
       This packet trap could include packets which do not pass an IP checksum
       check, a header length check (a minimum of 20 bytes), which might suffer
       from packet truncation thus the total length field exceeds the received
       packet length etc
   * - ``ip_n_parsing``
     - ``drop``
     - Traps packets dropped due to an error in the parsing of the last IP
       header (the inner one in case of an IP over IP tunnel). The same common
       error checking is performed here as for the ip_1_parsing trap
   * - ``gre_parsing``
     - ``drop``
     - Traps packets dropped due to an error in the GRE header parsing
   * - ``udp_parsing``
     - ``drop``
     - Traps packets dropped due to an error in the UDP header parsing.
       This packet trap could include checksum errorrs, an improper UDP
       length detected (smaller than 8 bytes) or detection of header
       truncation.
   * - ``tcp_parsing``
     - ``drop``
     - Traps packets dropped due to an error in the TCP header parsing.
       This could include TCP checksum errors, improper combination of SYN, FIN
       and/or RESET etc.
   * - ``ipsec_parsing``
     - ``drop``
     - Traps packets dropped due to an error in the IPSEC header parsing
   * - ``sctp_parsing``
     - ``drop``
     - Traps packets dropped due to an error in the SCTP header parsing.
       This would mean that port number 0 was used or that the header is
       truncated.
   * - ``dccp_parsing``
     - ``drop``
     - Traps packets dropped due to an error in the DCCP header parsing
   * - ``gtp_parsing``
     - ``drop``
     - Traps packets dropped due to an error in the GTP header parsing
   * - ``esp_parsing``
     - ``drop``
     - Traps packets dropped due to an error in the ESP header parsing
   * - ``blackhole_nexthop``
     - ``drop``
     - Traps packets that the device decided to drop in case they hit a
       blackhole nexthop
   * - ``dmac_filter``
     - ``drop``
     - Traps incoming packets that the device decided to drop because
       the destination MAC is not configured in the MAC table and
       the interface is not in promiscuous mode
   * - ``eapol``
     - ``control``
     - Traps "Extensible Authentication Protocol over LAN" (EAPOL) packets
       specified in IEEE 802.1X
   * - ``locked_port``
     - ``drop``
     - Traps packets that the device decided to drop because they failed the
       locked bridge port check. That is, packets that were received via a
       locked port and whose {SMAC, VID} does not correspond to an FDB entry
       pointing to the port

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:

  * Documentation/networking/devlink/netdevsim.rst
  * Documentation/networking/devlink/mlxsw.rst
  * Documentation/networking/devlink/prestera.rst

.. _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 during
       layer 3 forwarding
   * - ``l3_exceptions``
     - Contains packet traps for packets that 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
   * - ``stp``
     - Contains packet traps for STP packets
   * - ``lacp``
     - Contains packet traps for LACP packets
   * - ``lldp``
     - Contains packet traps for LLDP packets
   * - ``mc_snooping``
     - Contains packet traps for IGMP and MLD packets required for multicast
       snooping
   * - ``dhcp``
     - Contains packet traps for DHCP packets
   * - ``neigh_discovery``
     - Contains packet traps for neighbour discovery packets (e.g., ARP, IPv6
       ND)
   * - ``bfd``
     - Contains packet traps for BFD packets
   * - ``ospf``
     - Contains packet traps for OSPF packets
   * - ``bgp``
     - Contains packet traps for BGP packets
   * - ``vrrp``
     - Contains packet traps for VRRP packets
   * - ``pim``
     - Contains packet traps for PIM packets
   * - ``uc_loopback``
     - Contains a packet trap for unicast loopback packets (i.e.,
       ``uc_loopback``). This trap is singled-out because in cases such as
       one-armed router it will be constantly triggered. To limit the impact on
       the CPU usage, a packet trap policer with a low rate can be bound to the
       group without affecting other traps
   * - ``local_delivery``
     - Contains packet traps for packets that should be locally delivered after
       routing, but do not match more specific packet traps (e.g.,
       ``ipv4_bgp``)
   * - ``external_delivery``
     - Contains packet traps for packets that should be routed through an
       external interface (e.g., management interface) that does not belong to
       the same device (e.g., switch ASIC) as the ingress interface
   * - ``ipv6``
     - Contains packet traps for various IPv6 control packets (e.g., Router
       Advertisements)
   * - ``ptp_event``
     - Contains packet traps for PTP time-critical event messages (Sync,
       Delay_req, Pdelay_Req and Pdelay_Resp)
   * - ``ptp_general``
     - Contains packet traps for PTP general messages (Announce, Follow_Up,
       Delay_Resp, Pdelay_Resp_Follow_Up, management and signaling)
   * - ``acl_sample``
     - Contains packet traps for packets that were sampled by the device during
       ACL processing
   * - ``acl_trap``
     - Contains packet traps for packets that were trapped (logged) by the
       device during ACL processing
   * - ``parser_error_drops``
     - Contains packet traps for packets that were marked by the device during
       parsing as erroneous
   * - ``eapol``
     - Contains packet traps for "Extensible Authentication Protocol over LAN"
       (EAPOL) packets specified in IEEE 802.1X

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.


code:
.. SPDX-License-Identifier: GPL-2.0

==========================
etas_es58x devlink support
==========================

This document describes the devlink features implemented by the
``etas_es58x`` device driver.

Info versions
=============

The ``etas_es58x`` driver reports the following versions

.. list-table:: devlink info versions implemented
   :widths: 5 5 90

   * - Name
     - Type
     - Description
   * - ``fw``
     - running
     - Version of the firmware running on the device. Also available
       through ``ethtool -i`` as the first member of the
       ``firmware-version``.
   * - ``fw.bootloader``
     - running
     - Version of the bootloader running on the device. Also available
       through ``ethtool -i`` as the second member of the
       ``firmware-version``.
   * - ``board.rev``
     - fixed
     - The hardware revision of the device.
   * - ``serial_number``
     - fixed
     - The USB serial number. Also available through ``lsusb -v``.

repo_name: angery/linux


code:
.. SPDX-License-Identifier: GPL-2.0

====================
hns3 devlink support
====================

This document describes the devlink features implemented by the ``hns3``
device driver.

The ``hns3`` driver supports reloading via ``DEVLINK_CMD_RELOAD``.

Info versions
=============

The ``hns3`` driver reports the following versions

.. list-table:: devlink info versions implemented
   :widths: 10 10 80

   * - Name
     - Type
     - Description
   * - ``fw``
     - running
     - Used to represent the firmware version.


code:
.. SPDX-License-Identifier: GPL-2.0

===================
ice devlink support
===================

This document describes the devlink features implemented by the ``ice``
device driver.

Info versions
=============

The ``ice`` driver reports the following versions

.. list-table:: devlink info versions implemented
    :widths: 5 5 5 90

    * - Name
      - Type
      - Example
      - Description
    * - ``board.id``
      - fixed
      - K65390-000
      - The Product Board Assembly (PBA) identifier of the board.
    * - ``fw.mgmt``
      - running
      - 2.1.7
      - 3-digit version number of the management firmware running on the
        Embedded Management Processor of the device. It controls the PHY,
        link, access to device resources, etc. Intel documentation refers to
        this as the EMP firmware.
    * - ``fw.mgmt.api``
      - running
      - 1.5.1
      - 3-digit version number (major.minor.patch) of the API exported over
        the AdminQ by the management firmware. Used by the driver to
        identify what commands are supported. Historical versions of the
        kernel only displayed a 2-digit version number (major.minor).
    * - ``fw.mgmt.build``
      - running
      - 0x305d955f
      - Unique identifier of the source for the management firmware.
    * - ``fw.undi``
      - running
      - 1.2581.0
      - Version of the Option ROM containing the UEFI driver. The version is
        reported in ``major.minor.patch`` format. The major version is
        incremented whenever a major breaking change occurs, or when the
        minor version would overflow. The minor version is incremented for
        non-breaking changes and reset to 1 when the major version is
        incremented. The patch version is normally 0 but is incremented when
        a fix is delivered as a patch against an older base Option ROM.
    * - ``fw.psid.api``
      - running
      - 0.80
      - Version defining the format of the flash contents.
    * - ``fw.bundle_id``
      - running
      - 0x80002ec0
      - Unique identifier of the firmware image file that was loaded onto
        the device. Also referred to as the EETRACK identifier of the NVM.
    * - ``fw.app.name``
      - running
      - ICE OS Default Package
      - The name of the DDP package that is active in the device. The DDP
        package is loaded by the driver during initialization. Each
        variation of the DDP package has a unique name.
    * - ``fw.app``
      - running
      - 1.3.1.0
      - The version of the DDP package that is active in the device. Note
        that both the name (as reported by ``fw.app.name``) and version are
        required to uniquely identify the package.
    * - ``fw.app.bundle_id``
      - running
      - 0xc0000001
      - Unique identifier for the DDP package loaded in the device. Also
        referred to as the DDP Track ID. Can be used to uniquely identify
        the specific DDP package.
    * - ``fw.netlist``
      - running
      - 1.1.2000-6.7.0
      - The version of the netlist module. This module defines the device's
        Ethernet capabilities and default settings, and is used by the
        management firmware as part of managing link and device
        connectivity.
    * - ``fw.netlist.build``
      - running
      - 0xee16ced7
      - The first 4 bytes of the hash of the netlist module contents.

Flash Update
============

The ``ice`` driver implements support for flash update using the
``devlink-flash`` interface. It supports updating the device flash using a
combined flash image that contains the ``fw.mgmt``, ``fw.undi``, and
``fw.netlist`` components.

.. list-table:: List of supported overwrite modes
   :widths: 5 95

   * - Bits
     - Behavior
   * - ``DEVLINK_FLASH_OVERWRITE_SETTINGS``
     - Do not preserve settings stored in the flash components being
       updated. This includes overwriting the port configuration that
       determines the number of physical functions the device will
       initialize with.
   * - ``DEVLINK_FLASH_OVERWRITE_SETTINGS`` and ``DEVLINK_FLASH_OVERWRITE_IDENTIFIERS``
     - Do not preserve either settings or identifiers. Overwrite everything
       in the flash with the contents from the provided image, without
       performing any preservation. This includes overwriting device
       identifying fields such as the MAC address, VPD area, and device
       serial number. It is expected that this combination be used with an
       image customized for the specific device.

The ice hardware does not support overwriting only identifiers while
preserving settings, and thus ``DEVLINK_FLASH_OVERWRITE_IDENTIFIERS`` on its
own will be rejected. If no overwrite mask is provided, the firmware will be
instructed to preserve all settings and identifying fields when updating.

Reload
======

The ``ice`` driver supports activating new firmware after a flash update
using ``DEVLINK_CMD_RELOAD`` with the ``DEVLINK_RELOAD_ACTION_FW_ACTIVATE``
action.

.. code:: shell

    $ devlink dev reload pci/0000:01:00.0 reload action fw_activate

The new firmware is activated by issuing a device specific Embedded
Management Processor reset which requests the device to reset and reload the
EMP firmware image.

The driver does not currently support reloading the driver via
``DEVLINK_RELOAD_ACTION_DRIVER_REINIT``.

Port split
==========

The ``ice`` driver supports port splitting only for port 0, as the FW has
a predefined set of available port split options for the whole device.

A system reboot is required for port split to be applied.

The following command will select the port split option with 4 ports:

.. code:: shell

    $ devlink port split pci/0000:16:00.0/0 count 4

The list of all available port options will be printed to dynamic debug after
each ``split`` and ``unsplit`` command. The first option is the default.

.. code:: shell

    ice 0000:16:00.0: Available port split options and max port speeds (Gbps):
    ice 0000:16:00.0: Status  Split      Quad 0          Quad 1
    ice 0000:16:00.0:         count  L0  L1  L2  L3  L4  L5  L6  L7
    ice 0000:16:00.0: Active  2     100   -   -   - 100   -   -   -
    ice 0000:16:00.0:         2      50   -  50   -   -   -   -   -
    ice 0000:16:00.0: Pending 4      25  25  25  25   -   -   -   -
    ice 0000:16:00.0:         4      25  25   -   -  25  25   -   -
    ice 0000:16:00.0:         8      10  10  10  10  10  10  10  10
    ice 0000:16:00.0:         1     100   -   -   -   -   -   -   -

There could be multiple FW port options with the same port split count. When
the same port split count request is issued again, the next FW port option with
the same port split count will be selected.

``devlink port unsplit`` will select the option with a split count of 1. If
there is no FW option available with split count 1, you will receive an error.

Regions
=======

The ``ice`` driver implements the following regions for accessing internal
device data.

.. list-table:: regions implemented
    :widths: 15 85

    * - Name
      - Description
    * - ``nvm-flash``
      - The contents of the entire flash chip, sometimes referred to as
        the device's Non Volatile Memory.
    * - ``shadow-ram``
      - The contents of the Shadow RAM, which is loaded from the beginning
        of the flash. Although the contents are primarily from the flash,
        this area also contains data generated during device boot which is
        not stored in flash.
    * - ``device-caps``
      - The contents of the device firmware's capabilities buffer. Useful to
        determine the current state and configuration of the device.

Both the ``nvm-flash`` and ``shadow-ram`` regions can be accessed without a
snapshot. The ``device-caps`` region requires a snapshot as the contents are
sent by firmware and can't be split into separate reads.

Users can request an immediate capture of a snapshot for all three regions
via the ``DEVLINK_CMD_REGION_NEW`` command.

.. code:: shell

    $ devlink region show
    pci/0000:01:00.0/nvm-flash: size 10485760 snapshot [] max 1
    pci/0000:01:00.0/device-caps: size 4096 snapshot [] max 10

    $ devlink region new pci/0000:01:00.0/nvm-flash snapshot 1
    $ devlink region dump pci/0000:01:00.0/nvm-flash snapshot 1

    $ devlink region dump pci/0000:01:00.0/nvm-flash snapshot 1
    0000000000000000 0014 95dc 0014 9514 0035 1670 0034 db30
    0000000000000010 0000 0000 ffff ff04 0029 8c00 0028 8cc8
    0000000000000020 0016 0bb8 0016 1720 0000 0000 c00f 3ffc
    0000000000000030 bada cce5 bada cce5 bada cce5 bada cce5

    $ devlink region read pci/0000:01:00.0/nvm-flash snapshot 1 address 0 length 16
    0000000000000000 0014 95dc 0014 9514 0035 1670 0034 db30

    $ devlink region delete pci/0000:01:00.0/nvm-flash snapshot 1

    $ devlink region new pci/0000:01:00.0/device-caps snapshot 1
    $ devlink region dump pci/0000:01:00.0/device-caps snapshot 1
    0000000000000000 01 00 01 00 00 00 00 00 01 00 00 00 00 00 00 00
    0000000000000010 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
    0000000000000020 02 00 02 01 32 03 00 00 0a 00 00 00 25 00 00 00
    0000000000000030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
    0000000000000040 04 00 01 00 01 00 00 00 00 00 00 00 00 00 00 00
    0000000000000050 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
    0000000000000060 05 00 01 00 03 00 00 00 00 00 00 00 00 00 00 00
    0000000000000070 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
    0000000000000080 06 00 01 00 01 00 00 00 00 00 00 00 00 00 00 00
    0000000000000090 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
    00000000000000a0 08 00 01 00 00 00 00 00 00 00 00 00 00 00 00 00
    00000000000000b0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
    00000000000000c0 12 00 01 00 01 00 00 00 01 00 01 00 00 00 00 00
    00000000000000d0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
    00000000000000e0 13 00 01 00 00 01 00 00 00 00 00 00 00 00 00 00
    00000000000000f0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
    0000000000000100 14 00 01 00 01 00 00 00 00 00 00 00 00 00 00 00
    0000000000000110 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
    0000000000000120 15 00 01 00 01 00 00 00 00 00 00 00 00 00 00 00
    0000000000000130 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
    0000000000000140 16 00 01 00 01 00 00 00 00 00 00 00 00 00 00 00
    0000000000000150 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
    0000000000000160 17 00 01 00 06 00 00 00 00 00 00 00 00 00 00 00
    0000000000000170 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
    0000000000000180 18 00 01 00 01 00 00 00 01 00 00 00 08 00 00 00
    0000000000000190 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
    00000000000001a0 22 00 01 00 01 00 00 00 00 00 00 00 00 00 00 00
    00000000000001b0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
    00000000000001c0 40 00 01 00 00 08 00 00 08 00 00 00 00 00 00 00
    00000000000001d0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
    00000000000001e0 41 00 01 00 00 08 00 00 00 00 00 00 00 00 00 00
    00000000000001f0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
    0000000000000200 42 00 01 00 00 08 00 00 00 00 00 00 00 00 00 00
    0000000000000210 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00

    $ devlink region delete pci/0000:01:00.0/device-caps snapshot 1

Devlink Rate
============

The ``ice`` driver implements devlink-rate API. It allows for offload of
the Hierarchical QoS to the hardware. It enables user to group Virtual
Functions in a tree structure and assign supported parameters: tx_share,
tx_max, tx_priority and tx_weight to each node in a tree. So effectively
user gains an ability to control how much bandwidth is allocated for each
VF group. This is later enforced by the HW.

It is assumed that this feature is mutually exclusive with DCB performed
in FW and ADQ, or any driver feature that would trigger changes in QoS,
for example creation of the new traffic class. The driver will prevent DCB
or ADQ configuration if user started making any changes to the nodes using
devlink-rate API. To configure those features a driver reload is necessary.
Correspondingly if ADQ or DCB will get configured the driver won't export
hierarchy at all, or will remove the untouched hierarchy if those
features are enabled after the hierarchy is exported, but before any
changes are made.

This feature is also dependent on switchdev being enabled in the system.
It's required bacause devlink-rate requires devlink-port objects to be
present, and those objects are only created in switchdev mode.

If the driver is set to the switchdev mode, it will export internal
hierarchy the moment VF's are created. Root of the tree is always
represented by the node_0. This node can't be deleted by the user. Leaf
nodes and nodes with children also can't be deleted.

.. list-table:: Attributes supported
    :widths: 15 85

    * - Name
      - Description
    * - ``tx_max``
      - maximum bandwidth to be consumed by the tree Node. Rate Limit is
        an absolute number specifying a maximum amount of bytes a Node may
        consume during the course of one second. Rate limit guarantees
        that a link will not oversaturate the receiver on the remote end
        and also enforces an SLA between the subscriber and network
        provider.
    * - ``tx_share``
      - minimum bandwidth allocated to a tree node when it is not blocked.
        It specifies an absolute BW. While tx_max defines the maximum
        bandwidth the node may consume, the tx_share marks committed BW
        for the Node.
    * - ``tx_priority``
      - allows for usage of strict priority arbiter among siblings. This
        arbitration scheme attempts to schedule nodes based on their
        priority as long as the nodes remain within their bandwidth limit.
        Range 0-7. Nodes with priority 7 have the highest priority and are
        selected first, while nodes with priority 0 have the lowest
        priority. Nodes that have the same priority are treated equally.
    * - ``tx_weight``
      - allows for usage of Weighted Fair Queuing arbitration scheme among
        siblings. This arbitration scheme can be used simultaneously with
        the strict priority. Range 1-200. Only relative values mater for
        arbitration.

``tx_priority`` and ``tx_weight`` can be used simultaneously. In that case
nodes with the same priority form a WFQ subgroup in the sibling group
and arbitration among them is based on assigned weights.

.. code:: shell

    # enable switchdev
    $ devlink dev eswitch set pci/0000:4b:00.0 mode switchdev

    # at this point driver should export internal hierarchy
    $ echo 2 > /sys/class/net/ens785np0/device/sriov_numvfs

    $ devlink port function rate show
    pci/0000:4b:00.0/node_25: type node parent node_24
    pci/0000:4b:00.0/node_24: type node parent node_0
    pci/0000:4b:00.0/node_32: type node parent node_31
    pci/0000:4b:00.0/node_31: type node parent node_30
    pci/0000:4b:00.0/node_30: type node parent node_16
    pci/0000:4b:00.0/node_19: type node parent node_18
    pci/0000:4b:00.0/node_18: type node parent node_17
    pci/0000:4b:00.0/node_17: type node parent node_16
    pci/0000:4b:00.0/node_14: type node parent node_5
    pci/0000:4b:00.0/node_5: type node parent node_3
    pci/0000:4b:00.0/node_13: type node parent node_4
    pci/0000:4b:00.0/node_12: type node parent node_4
    pci/0000:4b:00.0/node_11: type node parent node_4
    pci/0000:4b:00.0/node_10: type node parent node_4
    pci/0000:4b:00.0/node_9: type node parent node_4
    pci/0000:4b:00.0/node_8: type node parent node_4
    pci/0000:4b:00.0/node_7: type node parent node_4
    pci/0000:4b:00.0/node_6: type node parent node_4
    pci/0000:4b:00.0/node_4: type node parent node_3
    pci/0000:4b:00.0/node_3: type node parent node_16
    pci/0000:4b:00.0/node_16: type node parent node_15
    pci/0000:4b:00.0/node_15: type node parent node_0
    pci/0000:4b:00.0/node_2: type node parent node_1
    pci/0000:4b:00.0/node_1: type node parent node_0
    pci/0000:4b:00.0/node_0: type node
    pci/0000:4b:00.0/1: type leaf parent node_25
    pci/0000:4b:00.0/2: type leaf parent node_25

    # let's create some custom node
    $ devlink port function rate add pci/0000:4b:00.0/node_custom parent node_0

    # second custom node
    $ devlink port function rate add pci/0000:4b:00.0/node_custom_1 parent node_custom

    # reassign second VF to newly created branch
    $ devlink port function rate set pci/0000:4b:00.0/2 parent node_custom_1

    # assign tx_weight to the VF
    $ devlink port function rate set pci/0000:4b:00.0/2 tx_weight 5

    # assign tx_share to the VF
    $ devlink port function rate set pci/0000:4b:00.0/2 tx_share 500Mbps


code:
Linux Devlink Documentation
===========================

devlink is an API to expose device information and resources not directly
related to any device class, such as chip-wide/switch-ASIC-wide configuration.

Locking
-------

Driver facing APIs are currently transitioning to allow more explicit
locking. Drivers can use the existing ``devlink_*`` set of APIs, or
new APIs prefixed by ``devl_*``. The older APIs handle all the locking
in devlink core, but don't allow registration of most sub-objects once
the main devlink object is itself registered. The newer ``devl_*`` APIs assume
the devlink instance lock is already held. Drivers can take the instance
lock by calling ``devl_lock()``. It is also held all callbacks of devlink
netlink commands.

Drivers are encouraged to use the devlink instance lock for their own needs.

Interface documentation
-----------------------

The following pages describe various interfaces available through devlink in
general.

.. toctree::
   :maxdepth: 1

   devlink-dpipe
   devlink-health
   devlink-info
   devlink-flash
   devlink-params
   devlink-port
   devlink-region
   devlink-resource
   devlink-reload
   devlink-selftests
   devlink-trap
   devlink-linecard

Driver-specific documentation
-----------------------------

Each driver that implements ``devlink`` is expected to document what
parameters, info versions, and other features it supports.

.. toctree::
   :maxdepth: 1

   bnxt
   hns3
   ionic
   ice
   mlx4
   mlx5
   mlxsw
   mv88e6xxx
   netdevsim
   nfp
   qed
   ti-cpsw-switch
   am65-nuss-cpsw-switch
   prestera
   iosm
   octeontx2


code:
.. SPDX-License-Identifier: GPL-2.0

=====================
ionic devlink support
=====================

This document describes the devlink features implemented by the ``ionic``
device driver.

Info versions
=============

The ``ionic`` driver reports the following versions

.. list-table:: devlink info versions implemented
   :widths: 5 5 90

   * - Name
     - Type
     - Description
   * - ``fw``
     - running
     - Version of firmware running on the device
   * - ``asic.id``
     - fixed
     - The ASIC type for this device
   * - ``asic.rev``
     - fixed
     - The revision of the ASIC for this device


code:
.. SPDX-License-Identifier: GPL-2.0

====================
iosm devlink support
====================

This document describes the devlink features implemented by the ``iosm``
device driver.

Parameters
==========

The ``iosm`` driver implements the following driver-specific parameters.

.. list-table:: Driver-specific parameters implemented
   :widths: 5 5 5 85

   * - Name
     - Type
     - Mode
     - Description
   * - ``erase_full_flash``
     - u8
     - runtime
     - erase_full_flash parameter is used to check if full erase is required for
       the device during firmware flashing.
       If set, Full nand erase command will be sent to the device. By default,
       only conditional erase support is enabled.

Flash Update
============

The ``iosm`` driver implements support for flash update using the
``devlink-flash`` interface.

It supports updating the device flash using a combined flash image which contains
the Bootloader images and other modem software images.

The driver uses DEVLINK_SUPPORT_FLASH_UPDATE_COMPONENT to identify type of
firmware image that need to be flashed as requested by user space application.
Supported firmware image types.

.. list-table:: Firmware Image types
    :widths: 15 85

    * - Name
      - Description
    * - ``PSI RAM``
      - Primary Signed Image
    * - ``EBL``
      - External Bootloader
    * - ``FLS``
      - Modem Software Image

PSI RAM and EBL are the RAM images which are injected to the device when the
device is in BOOT ROM stage. Once this is successful, the actual modem firmware
image is flashed to the device. The modem software image contains multiple files
each having one secure bin file and at least one Loadmap/Region file. For flashing
these files, appropriate commands are sent to the modem device along with the
data required for flashing. The data like region count and address of each region
has to be passed to the driver using the devlink param command.

If the device has to be fully erased before firmware flashing, user application
need to set the erase_full_flash parameter using devlink param command.
By default, conditional erase feature is supported.

Flash Commands:
===============
1) When modem is in Boot ROM stage, user can use below command to inject PSI RAM
image using devlink flash command.

$ devlink dev flash pci/0000:02:00.0 file <PSI_RAM_File_name>

2) If user want to do a full erase, below command need to be issued to set the
erase full flash param (To be set only if full erase required).

$ devlink dev param set pci/0000:02:00.0 name erase_full_flash value true cmode runtime

3) Inject EBL after the modem is in PSI stage.

$ devlink dev flash pci/0000:02:00.0 file <EBL_File_name>

4) Once EBL is injected successfully, then the actual firmware flashing takes
place. Below is the sequence of commands used for each of the firmware images.

a) Flash secure bin file.

$ devlink dev flash pci/0000:02:00.0 file <Secure_bin_file_name>

b) Flashing the Loadmap/Region file

$ devlink dev flash pci/0000:02:00.0 file <Load_map_file_name>

Regions
=======

The ``iosm`` driver supports dumping the coredump logs.

In case a firmware encounters an exception, a snapshot will be taken by the
driver. Following regions are accessed for device internal data.

.. list-table:: Regions implemented
    :widths: 15 85

    * - Name
      - Description
    * - ``report.json``
      - The summary of exception details logged as part of this region.
    * - ``coredump.fcd``
      - This region contains the details related to the exception occurred in the
        device (RAM dump).
    * - ``cdd.log``
      - This region contains the logs related to the modem CDD driver.
    * - ``eeprom.bin``
      - This region contains the eeprom logs.
    * - ``bootcore_trace.bin``
      -  This region contains the current instance of bootloader logs.
    * - ``bootcore_prev_trace.bin``
      - This region contains the previous instance of bootloader logs.

Region commands
===============

$ devlink region show

$ devlink region new pci/0000:02:00.0/report.json

$ devlink region dump pci/0000:02:00.0/report.json snapshot 0

$ devlink region del pci/0000:02:00.0/report.json snapshot 0

$ devlink region new pci/0000:02:00.0/coredump.fcd

$ devlink region dump pci/0000:02:00.0/coredump.fcd snapshot 1

$ devlink region del pci/0000:02:00.0/coredump.fcd snapshot 1

$ devlink region new pci/0000:02:00.0/cdd.log

$ devlink region dump pci/0000:02:00.0/cdd.log snapshot 2

$ devlink region del pci/0000:02:00.0/cdd.log snapshot 2

$ devlink region new pci/0000:02:00.0/eeprom.bin

$ devlink region dump pci/0000:02:00.0/eeprom.bin snapshot 3

$ devlink region del pci/0000:02:00.0/eeprom.bin snapshot 3

$ devlink region new pci/0000:02:00.0/bootcore_trace.bin

$ devlink region dump pci/0000:02:00.0/bootcore_trace.bin snapshot 4

$ devlink region del pci/0000:02:00.0/bootcore_trace.bin snapshot 4

$ devlink region new pci/0000:02:00.0/bootcore_prev_trace.bin

$ devlink region dump pci/0000:02:00.0/bootcore_prev_trace.bin snapshot 5

$ devlink region del pci/0000:02:00.0/bootcore_prev_trace.bin snapshot 5


code:
.. SPDX-License-Identifier: GPL-2.0

====================
mlx4 devlink support
====================

This document describes the devlink features implemented by the ``mlx4``
device driver.

Parameters
==========

.. list-table:: Generic parameters implemented

   * - Name
     - Mode
   * - ``internal_err_reset``
     - driverinit, runtime
   * - ``max_macs``
     - driverinit
   * - ``region_snapshot_enable``
     - driverinit, runtime

The ``mlx4`` driver also implements the following driver-specific
parameters.

.. list-table:: Driver-specific parameters implemented
   :widths: 5 5 5 85

   * - Name
     - Type
     - Mode
     - Description
   * - ``enable_64b_cqe_eqe``
     - Boolean
     - driverinit
     - Enable 64 byte CQEs/EQEs, if the FW supports it.
   * - ``enable_4k_uar``
     - Boolean
     - driverinit
     - Enable using the 4k UAR.

The ``mlx4`` driver supports reloading via ``DEVLINK_CMD_RELOAD``

Regions
=======

The ``mlx4`` driver supports dumping the firmware PCI crspace and health
buffer during a critical firmware issue.

In case a firmware command times out, firmware getting stuck, or a non zero
value on the catastrophic buffer, a snapshot will be taken by the driver.

The ``cr-space`` region will contain the firmware PCI crspace contents. The
``fw-health`` region will contain the device firmware's health buffer.
Snapshots for both of these regions are taken on the same event triggers.


code:
.. SPDX-License-Identifier: GPL-2.0

====================
mlx5 devlink support
====================

This document describes the devlink features implemented by the ``mlx5``
device driver.

Parameters
==========

.. list-table:: Generic parameters implemented

   * - Name
     - Mode
     - Validation
   * - ``enable_roce``
     - driverinit
     - Type: Boolean
   * - ``io_eq_size``
     - driverinit
     - The range is between 64 and 4096.
   * - ``event_eq_size``
     - driverinit
     - The range is between 64 and 4096.
   * - ``max_macs``
     - driverinit
     - The range is between 1 and 2^31. Only power of 2 values are supported.

The ``mlx5`` driver also implements the following driver-specific
parameters.

.. list-table:: Driver-specific parameters implemented
   :widths: 5 5 5 85

   * - Name
     - Type
     - Mode
     - Description
   * - ``flow_steering_mode``
     - string
     - runtime
     - Controls the flow steering mode of the driver

       * ``dmfs`` Device managed flow steering. In DMFS mode, the HW
         steering entities are created and managed through firmware.
       * ``smfs`` Software managed flow steering. In SMFS mode, the HW
         steering entities are created and manage through the driver without
         firmware intervention.
   * - ``fdb_large_groups``
     - u32
     - driverinit
     - Control the number of large groups (size > 1) in the FDB table.

       * The default value is 15, and the range is between 1 and 1024.

The ``mlx5`` driver supports reloading via ``DEVLINK_CMD_RELOAD``

Info versions
=============

The ``mlx5`` driver reports the following versions

.. list-table:: devlink info versions implemented
   :widths: 5 5 90

   * - Name
     - Type
     - Description
   * - ``fw.psid``
     - fixed
     - Used to represent the board id of the device.
   * - ``fw.version``
     - stored, running
     - Three digit major.minor.subminor firmware version number.


code:
.. SPDX-License-Identifier: GPL-2.0

=====================
mlxsw devlink support
=====================

This document describes the devlink features implemented by the ``mlxsw``
device driver.

Parameters
==========

.. list-table:: Generic parameters implemented

   * - Name
     - Mode
   * - ``fw_load_policy``
     - driverinit

The ``mlxsw`` driver also implements the following driver-specific
parameters.

.. list-table:: Driver-specific parameters implemented
   :widths: 5 5 5 85

   * - Name
     - Type
     - Mode
     - Description
   * - ``acl_region_rehash_interval``
     - u32
     - runtime
     - Sets an interval for periodic ACL region rehashes. The value is
       specified in milliseconds, with a minimum of ``3000``. The value of
       ``0`` disables periodic work entirely. The first rehash will be run
       immediately after the value is set.

The ``mlxsw`` driver supports reloading via ``DEVLINK_CMD_RELOAD``

Info versions
=============

The ``mlxsw`` driver reports the following versions

.. list-table:: devlink info versions implemented
   :widths: 5 5 90

   * - Name
     - Type
     - Description
   * - ``hw.revision``
     - fixed
     - The hardware revision for this board
   * - ``fw.psid``
     - fixed
     - Firmware PSID
   * - ``fw.version``
     - running
     - Three digit firmware version

Line card auxiliary device info versions
========================================

The ``mlxsw`` driver reports the following versions for line card auxiliary device

.. list-table:: devlink info versions implemented
   :widths: 5 5 90

   * - Name
     - Type
     - Description
   * - ``hw.revision``
     - fixed
     - The hardware revision for this line card
   * - ``ini.version``
     - running
     - Version of line card INI loaded
   * - ``fw.psid``
     - fixed
     - Line card device PSID
   * - ``fw.version``
     - running
     - Three digit firmware version of line card device

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

.. list-table:: List of Driver-specific Traps Registered by ``mlxsw``
   :widths: 5 5 90

   * - Name
     - Type
     - Description
   * - ``irif_disabled``
     - ``drop``
     - Traps packets that the device decided to drop because they need to be
       routed from a disabled router interface (RIF). This can happen during
       RIF dismantle, when the RIF is first disabled before being removed
       completely
   * - ``erif_disabled``
     - ``drop``
     - Traps packets that the device decided to drop because they need to be
       routed through a disabled router interface (RIF). This can happen during
       RIF dismantle, when the RIF is first disabled before being removed
       completely


code:
.. SPDX-License-Identifier: GPL-2.0

=========================
mv88e6xxx devlink support
=========================

This document describes the devlink features implemented by the ``mv88e6xxx``
device driver.

Parameters
==========

The ``mv88e6xxx`` driver implements the following driver-specific parameters.

.. list-table:: Driver-specific parameters implemented
   :widths: 5 5 5 85

   * - Name
     - Type
     - Mode
     - Description
   * - ``ATU_hash``
     - u8
     - runtime
     - Select one of four possible hashing algorithms for MAC addresses in
       the Address Translation Unit. A value of 3 may work better than the
       default of 1 when many MAC addresses have the same OUI. Only the
       values 0 to 3 are valid for this parameter.


code:
.. SPDX-License-Identifier: GPL-2.0

=========================
netdevsim devlink support
=========================

This document describes the ``devlink`` features supported by the
``netdevsim`` device driver.

Parameters
==========

.. list-table:: Generic parameters implemented

   * - Name
     - Mode
   * - ``max_macs``
     - driverinit

The ``netdevsim`` driver also implements the following driver-specific
parameters.

.. list-table:: Driver-specific parameters implemented
   :widths: 5 5 5 85

   * - Name
     - Type
     - Mode
     - Description
   * - ``test1``
     - Boolean
     - driverinit
     - Test parameter used to show how a driver-specific devlink parameter
       can be implemented.

The ``netdevsim`` driver supports reloading via ``DEVLINK_CMD_RELOAD``

Regions
=======

The ``netdevsim`` driver exposes a ``dummy`` region as an example of how the
devlink-region interfaces work. A snapshot is taken whenever the
``take_snapshot`` debugfs file is written to.

Resources
=========

The ``netdevsim`` driver exposes resources to control the number of FIB
entries, FIB rule entries and nexthops that the driver will allow.

.. code:: shell

    $ devlink resource set netdevsim/netdevsim0 path /IPv4/fib size 96
    $ devlink resource set netdevsim/netdevsim0 path /IPv4/fib-rules size 16
    $ devlink resource set netdevsim/netdevsim0 path /IPv6/fib size 64
    $ devlink resource set netdevsim/netdevsim0 path /IPv6/fib-rules size 16
    $ devlink resource set netdevsim/netdevsim0 path /nexthops size 16
    $ devlink dev reload netdevsim/netdevsim0

Rate objects
============

The ``netdevsim`` driver supports rate objects management, which includes:

- registerging/unregistering leaf rate objects per VF devlink port;
- creation/deletion node rate objects;
- setting tx_share and tx_max rate values for any rate object type;
- setting parent node for any rate object type.

Rate nodes and their parameters are exposed in ``netdevsim`` debugfs in RO mode.
For example created rate node with name ``some_group``:

.. code:: shell

    $ ls /sys/kernel/debug/netdevsim/netdevsim0/rate_groups/some_group
    rate_parent  tx_max  tx_share

Same parameters are exposed for leaf objects in corresponding ports directories.
For ex.:

.. code:: shell

    $ ls /sys/kernel/debug/netdevsim/netdevsim0/ports/1
    dev  ethtool  rate_parent  tx_max  tx_share

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

.. list-table:: List of Driver-specific Traps Registered by ``netdevsim``
   :widths: 5 5 90

   * - Name
     - Type
     - Description
   * - ``fid_miss``
     - ``exception``
     - When a packet enters the device it is classified to a filtering
       indentifier (FID) based on the ingress port and VLAN. This trap is used
       to trap packets for which a FID could not be found


code:
.. SPDX-License-Identifier: GPL-2.0

===================
nfp devlink support
===================

This document describes the devlink features implemented by the ``nfp``
device driver.

Parameters
==========

.. list-table:: Generic parameters implemented

   * - Name
     - Mode
   * - ``fw_load_policy``
     - permanent
   * - ``reset_dev_on_drv_probe``
     - permanent

Info versions
=============

The ``nfp`` driver reports the following versions

.. list-table:: devlink info versions implemented
   :widths: 5 5 90

   * - Name
     - Type
     - Description
   * - ``board.id``
     - fixed
     - Part number identifying the board design
   * - ``board.rev``
     - fixed
     - Revision of the board design
   * - ``board.manufacture``
     - fixed
     - Vendor of the board design
   * - ``board.model``
     - fixed
     - Model name of the board design
   * - ``fw.bundle_id``
     - stored, running
     - Firmware bundle id
   * - ``fw.mgmt``
     - stored, running
     - Version of the management firmware
   * - ``fw.cpld``
     - stored, running
     - The CPLD firmware component version
   * - ``fw.app``
     - stored, running
     - The APP firmware component version
   * - ``fw.undi``
     - stored, running
     - The UNDI firmware component version
   * - ``fw.ncsi``
     - stored, running
     - The NSCI firmware component version
   * - ``chip.init``
     - stored, running
     - The CFGR firmware component version


code:
.. SPDX-License-Identifier: GPL-2.0

=========================
octeontx2 devlink support
=========================

This document describes the devlink features implemented by the ``octeontx2 AF, PF and VF``
device drivers.

Parameters
==========

The ``octeontx2 PF and VF`` drivers implement the following driver-specific parameters.

.. list-table:: Driver-specific parameters implemented
   :widths: 5 5 5 85

   * - Name
     - Type
     - Mode
     - Description
   * - ``mcam_count``
     - u16
     - runtime
     - Select number of match CAM entries to be allocated for an interface.
       The same is used for ntuple filters of the interface. Supported by
       PF and VF drivers.

The ``octeontx2 AF`` driver implements the following driver-specific parameters.

.. list-table:: Driver-specific parameters implemented
   :widths: 5 5 5 85

   * - Name
     - Type
     - Mode
     - Description
   * - ``dwrr_mtu``
     - u32
     - runtime
     - Use to set the quantum which hardware uses for scheduling among transmit queues.
       Hardware uses weighted DWRR algorithm to schedule among all transmit queues.


code:
.. SPDX-License-Identifier: GPL-2.0

========================
prestera devlink support
========================

This document describes the devlink features implemented by the ``prestera``
device driver.

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

.. list-table:: List of Driver-specific Traps Registered by ``prestera``
   :widths: 5 5 90

   * - Name
     - Type
     - Description
.. list-table:: List of Driver-specific Traps Registered by ``prestera``
   :widths: 5 5 90

   * - Name
     - Type
     - Description
   * - ``arp_bc``
     - ``trap``
     - Traps ARP broadcast packets (both requests/responses)
   * - ``is_is``
     - ``trap``
     - Traps IS-IS packets
   * - ``ospf``
     - ``trap``
     - Traps OSPF packets
   * - ``ip_bc_mac``
     - ``trap``
     - Traps IPv4 packets with broadcast DA Mac address
   * - ``stp``
     - ``trap``
     - Traps STP BPDU
   * - ``lacp``
     - ``trap``
     - Traps LACP packets
   * - ``lldp``
     - ``trap``
     - Traps LLDP packets
   * - ``router_mc``
     - ``trap``
     - Traps multicast packets
   * - ``vrrp``
     - ``trap``
     - Traps VRRP packets
   * - ``dhcp``
     - ``trap``
     - Traps DHCP packets
   * - ``mtu_error``
     - ``trap``
     - Traps (exception) packets that exceeded port's MTU
   * - ``mac_to_me``
     - ``trap``
     -  Traps packets with switch-port's DA Mac address
   * - ``ttl_error``
     - ``trap``
     - Traps (exception) IPv4 packets whose TTL exceeded
   * - ``ipv4_options``
     - ``trap``
     - Traps (exception) packets due to the malformed IPV4 header options
   * - ``ip_default_route``
     - ``trap``
     - Traps packets that have no specific IP interface (IP to me) and no forwarding prefix
   * - ``local_route``
     - ``trap``
     - Traps packets that have been send to one of switch IP interfaces addresses
   * - ``ipv4_icmp_redirect``
     - ``trap``
     - Traps (exception) IPV4 ICMP redirect packets
   * - ``arp_response``
     - ``trap``
     - Traps ARP replies packets that have switch-port's DA Mac address
   * - ``acl_code_0``
     - ``trap``
     - Traps packets that have ACL priority set to 0 (tc pref 0)
   * - ``acl_code_1``
     - ``trap``
     - Traps packets that have ACL priority set to 1 (tc pref 1)
   * - ``acl_code_2``
     - ``trap``
     - Traps packets that have ACL priority set to 2 (tc pref 2)
   * - ``acl_code_3``
     - ``trap``
     - Traps packets that have ACL priority set to 3 (tc pref 3)
   * - ``acl_code_4``
     - ``trap``
     - Traps packets that have ACL priority set to 4 (tc pref 4)
   * - ``acl_code_5``
     - ``trap``
     - Traps packets that have ACL priority set to 5 (tc pref 5)
   * - ``acl_code_6``
     - ``trap``
     - Traps packets that have ACL priority set to 6 (tc pref 6)
   * - ``acl_code_7``
     - ``trap``
     - Traps packets that have ACL priority set to 7 (tc pref 7)
   * - ``ipv4_bgp``
     - ``trap``
     - Traps IPv4 BGP packets
   * - ``ssh``
     - ``trap``
     - Traps SSH packets
   * - ``telnet``
     - ``trap``
     - Traps Telnet packets
   * - ``icmp``
     - ``trap``
     - Traps ICMP packets
   * - ``rxdma_drop``
     - ``drop``
     - Drops packets (RxDMA) due to the lack of ingress buffers etc.
   * - ``port_no_vlan``
     - ``drop``
     - Drops packets due to faulty-configured network or due to internal bug (config issue).
   * - ``local_port``
     - ``drop``
     - Drops packets whose decision (FDB entry) is to bridge packet back to the incoming port/trunk.
   * - ``invalid_sa``
     - ``drop``
     - Drops packets with multicast source MAC address.
   * - ``illegal_ip_addr``
     - ``drop``
     - Drops packets with illegal SIP/DIP multicast/unicast addresses.
   * - ``illegal_ipv4_hdr``
     - ``drop``
     - Drops packets with illegal IPV4 header.
   * - ``ip_uc_dip_da_mismatch``
     - ``drop``
     - Drops packets with destination MAC being unicast, but destination IP address being multicast.
   * - ``ip_sip_is_zero``
     - ``drop``
     - Drops packets with zero (0) IPV4 source address.
   * - ``met_red``
     - ``drop``
     - Drops non-conforming packets (dropped by Ingress policer, metering drop), e.g. packet rate exceeded configured bandwith.


code:
.. SPDX-License-Identifier: GPL-2.0

===================
qed devlink support
===================

This document describes the devlink features implemented by the ``qed`` core
device driver.

Parameters
==========

The ``qed`` driver implements the following driver-specific parameters.

.. list-table:: Driver-specific parameters implemented
   :widths: 5 5 5 85

   * - Name
     - Type
     - Mode
     - Description
   * - ``iwarp_cmt``
     - Boolean
     - runtime
     - Enable iWARP functionality for 100g devices. Note that this impacts
       L2 performance, and is therefore not enabled by default.


code:
.. SPDX-License-Identifier: GPL-2.0

==============================
ti-cpsw-switch devlink support
==============================

This document describes the devlink features implemented by the ``ti-cpsw-switch``
device driver.

Parameters
==========

The ``ti-cpsw-switch`` driver implements the following driver-specific
parameters.

.. list-table:: Driver-specific parameters implemented
   :widths: 5 5 5 85

   * - Name
     - Type
     - Mode
     - Description
   * - ``ale_bypass``
     - Boolean
     - runtime
     - Enables ALE_CONTROL(4).BYPASS mode for debugging purposes. In this
       mode, all packets will be sent to the host port only.
   * - ``switch_mode``
     - Boolean
     - runtime
     - Enable switch mode


code:
.. SPDX-License-Identifier: GPL-2.0

===================
DNS Resolver Module
===================

.. Contents:

 - Overview.
 - Compilation.
 - Setting up.
 - Usage.
 - Mechanism.
 - Debugging.

Overview
========

The DNS resolver module provides a way for kernel services to make DNS queries
by way of requesting a key of key type dns_resolver.  These queries are
upcalled to userspace through /sbin/request-key.

These routines must be supported by userspace tools dns.upcall, cifs.upcall and
request-key.  It is under development and does not yet provide the full feature
set.  The features it does support include:

 (*) Implements the dns_resolver key_type to contact userspace.

It does not yet support the following AFS features:

 (*) Dns query support for AFSDB resource record.

This code is extracted from the CIFS filesystem.

Compilation
===========

The module should be enabled by turning on the kernel configuration options::

	CONFIG_DNS_RESOLVER	- tristate "DNS Resolver support"

Setting up
==========

To set up this facility, the /etc/request-key.conf file must be altered so that
/sbin/request-key can appropriately direct the upcalls.  For example, to handle
basic dname to IPv4/IPv6 address resolution, the following line should be
added::

	#OP	TYPE		DESC	CO-INFO	PROGRAM ARG1 ARG2 ARG3 ...
	#======	============	=======	=======	==========================
	create	dns_resolver  	*	*	/usr/sbin/cifs.upcall %k

To direct a query for query type 'foo', a line of the following should be added
before the more general line given above as the first match is the one taken::

	create	dns_resolver  	foo:*	*	/usr/sbin/dns.foo %k

Usage
=====

To make use of this facility, one of the following functions that are
implemented in the module can be called after doing::

	#include <linux/dns_resolver.h>

     ::

	int dns_query(const char *type, const char *name, size_t namelen,
		     const char *options, char **_result, time_t *_expiry);

     This is the basic access function.  It looks for a cached DNS query and if
     it doesn't find it, it upcalls to userspace to make a new DNS query, which
     may then be cached.  The key description is constructed as a string of the
     form::

		[<type>:]<name>

     where <type> optionally specifies the particular upcall program to invoke,
     and thus the type of query to do, and <name> specifies the string to be
     looked up.  The default query type is a straight hostname to IP address
     set lookup.

     The name parameter is not required to be a NUL-terminated string, and its
     length should be given by the namelen argument.

     The options parameter may be NULL or it may be a set of options
     appropriate to the query type.

     The return value is a string appropriate to the query type.  For instance,
     for the default query type it is just a list of comma-separated IPv4 and
     IPv6 addresses.  The caller must free the result.

     The length of the result string is returned on success, and a negative
     error code is returned otherwise.  -EKEYREJECTED will be returned if the
     DNS lookup failed.

     If _expiry is non-NULL, the expiry time (TTL) of the result will be
     returned also.

The kernel maintains an internal keyring in which it caches looked up keys.
This can be cleared by any process that has the CAP_SYS_ADMIN capability by
the use of KEYCTL_KEYRING_CLEAR on the keyring ID.

Reading DNS Keys from Userspace
===============================

Keys of dns_resolver type can be read from userspace using keyctl_read() or
"keyctl read/print/pipe".

Mechanism
=========

The dnsresolver module registers a key type called "dns_resolver".  Keys of
this type are used to transport and cache DNS lookup results from userspace.

When dns_query() is invoked, it calls request_key() to search the local
keyrings for a cached DNS result.  If that fails to find one, it upcalls to
userspace to get a new result.

Upcalls to userspace are made through the request_key() upcall vector, and are
directed by means of configuration lines in /etc/request-key.conf that tell
/sbin/request-key what program to run to instantiate the key.

The upcall handler program is responsible for querying the DNS, processing the
result into a form suitable for passing to the keyctl_instantiate_key()
routine.  This then passes the data to dns_resolver_instantiate() which strips
off and processes any options included in the data, and then attaches the
remainder of the string to the key as its payload.

The upcall handler program should set the expiry time on the key to that of the
lowest TTL of all the records it has extracted a result from.  This means that
the key will be discarded and recreated when the data it holds has expired.

dns_query() returns a copy of the value attached to the key, or an error if
that is indicated instead.

See <file:Documentation/security/keys/request-key.rst> for further
information about request-key function.

Debugging
=========

Debugging messages can be turned on dynamically by writing a 1 into the
following file::

	/sys/module/dnsresolver/parameters/debug


code:
.. SPDX-License-Identifier: GPL-2.0

=====================
Softnet Driver Issues
=====================

Transmit path guidelines:

1) The ndo_start_xmit method must not return NETDEV_TX_BUSY under
   any normal circumstances.  It is considered a hard error unless
   there is no way your device can tell ahead of time when its
   transmit function will become busy.

   Instead it must maintain the queue properly.  For example,
   for a driver implementing scatter-gather this means::

	static netdev_tx_t drv_hard_start_xmit(struct sk_buff *skb,
					       struct net_device *dev)
	{
		struct drv *dp = netdev_priv(dev);

		lock_tx(dp);
		...
		/* This is a hard error log it. */
		if (TX_BUFFS_AVAIL(dp) <= (skb_shinfo(skb)->nr_frags + 1)) {
			netif_stop_queue(dev);
			unlock_tx(dp);
			printk(KERN_ERR PFX "%s: BUG! Tx Ring full when queue awake!\n",
			       dev->name);
			return NETDEV_TX_BUSY;
		}

		... queue packet to card ...
		... update tx consumer index ...

		if (TX_BUFFS_AVAIL(dp) <= (MAX_SKB_FRAGS + 1))
			netif_stop_queue(dev);

		...
		unlock_tx(dp);
		...
		return NETDEV_TX_OK;
	}

   And then at the end of your TX reclamation event handling::

	if (netif_queue_stopped(dp->dev) &&
	    TX_BUFFS_AVAIL(dp) > (MAX_SKB_FRAGS + 1))
		netif_wake_queue(dp->dev);

   For a non-scatter-gather supporting card, the three tests simply become::

		/* This is a hard error log it. */
		if (TX_BUFFS_AVAIL(dp) <= 0)

   and::

		if (TX_BUFFS_AVAIL(dp) == 0)

   and::

	if (netif_queue_stopped(dp->dev) &&
	    TX_BUFFS_AVAIL(dp) > 0)
		netif_wake_queue(dp->dev);

2) An ndo_start_xmit method must not modify the shared parts of a
   cloned SKB.

3) Do not forget that once you return NETDEV_TX_OK from your
   ndo_start_xmit method, it is your driver's responsibility to free
   up the SKB and in some finite amount of time.

   For example, this means that it is not allowed for your TX
   mitigation scheme to let TX packets "hang out" in the TX
   ring unreclaimed forever if no new TX packets are sent.
   This error can deadlock sockets waiting for send buffer room
   to be freed up.

   If you return NETDEV_TX_BUSY from the ndo_start_xmit method, you
   must not keep any reference to that SKB and you must not attempt
   to free it up.

Probing guidelines:

1) Any hardware layer address you obtain for your device should
   be verified.  For example, for ethernet check it with
   linux/etherdevice.h:is_valid_ether_addr()

Close/stop guidelines:

1) After the ndo_stop routine has been called, the hardware must
   not receive or transmit any data.  All in flight packets must
   be aborted. If necessary, poll or wait for completion of
   any reset commands.

2) The ndo_stop routine will be called by unregister_netdevice
   if device is still UP.


code:
.. SPDX-License-Identifier: GPL-2.0

==========================================
Broadcom RoboSwitch Ethernet switch driver
==========================================

The Broadcom RoboSwitch Ethernet switch family is used in quite a range of
xDSL router, cable modems and other multimedia devices.

The actual implementation supports the devices BCM5325E, BCM5365, BCM539x,
BCM53115 and BCM53125 as well as BCM63XX.

Implementation details
======================

The driver is located in ``drivers/net/dsa/b53/`` and is implemented as a
DSA driver; see ``Documentation/networking/dsa/dsa.rst`` for details on the
subsystem and what it provides.

The switch is, if possible, configured to enable a Broadcom specific 4-bytes
switch tag which gets inserted by the switch for every packet forwarded to the
CPU interface, conversely, the CPU network interface should insert a similar
tag for packets entering the CPU port. The tag format is described in
``net/dsa/tag_brcm.c``.

The configuration of the device depends on whether or not tagging is
supported.

The interface names and example network configuration are used according the
configuration described in the :ref:`dsa-config-showcases`.

Configuration with tagging support
----------------------------------

The tagging based configuration is desired. It is not specific to the b53
DSA driver and will work like all DSA drivers which supports tagging.

See :ref:`dsa-tagged-configuration`.

Configuration without tagging support
-------------------------------------

Older models (5325, 5365) support a different tag format that is not supported
yet. 539x and 531x5 require managed mode and some special handling, which is
also not yet supported. The tagging support is disabled in these cases and the
switch need a different configuration.

The configuration slightly differ from the :ref:`dsa-vlan-configuration`.

The b53 tags the CPU port in all VLANs, since otherwise any PVID untagged
VLAN programming would basically change the CPU port's default PVID and make
it untagged, undesirable.

In difference to the configuration described in :ref:`dsa-vlan-configuration`
the default VLAN 1 has to be removed from the slave interface configuration in
single port and gateway configuration, while there is no need to add an extra
VLAN configuration in the bridge showcase.

single port
~~~~~~~~~~~
The configuration can only be set up via VLAN tagging and bridge setup.
By default packages are tagged with vid 1:

.. code-block:: sh

  # tag traffic on CPU port
  ip link add link eth0 name eth0.1 type vlan id 1
  ip link add link eth0 name eth0.2 type vlan id 2
  ip link add link eth0 name eth0.3 type vlan id 3

  # The master interface needs to be brought up before the slave ports.
  ip link set eth0 up
  ip link set eth0.1 up
  ip link set eth0.2 up
  ip link set eth0.3 up

  # bring up the slave interfaces
  ip link set wan up
  ip link set lan1 up
  ip link set lan2 up

  # create bridge
  ip link add name br0 type bridge

  # activate VLAN filtering
  ip link set dev br0 type bridge vlan_filtering 1

  # add ports to bridges
  ip link set dev wan master br0
  ip link set dev lan1 master br0
  ip link set dev lan2 master br0

  # tag traffic on ports
  bridge vlan add dev lan1 vid 2 pvid untagged
  bridge vlan del dev lan1 vid 1
  bridge vlan add dev lan2 vid 3 pvid untagged
  bridge vlan del dev lan2 vid 1

  # configure the VLANs
  ip addr add 192.0.2.1/30 dev eth0.1
  ip addr add 192.0.2.5/30 dev eth0.2
  ip addr add 192.0.2.9/30 dev eth0.3

  # bring up the bridge devices
  ip link set br0 up

bridge
~~~~~~

.. code-block:: sh

  # tag traffic on CPU port
  ip link add link eth0 name eth0.1 type vlan id 1

  # The master interface needs to be brought up before the slave ports.
  ip link set eth0 up
  ip link set eth0.1 up

  # bring up the slave interfaces
  ip link set wan up
  ip link set lan1 up
  ip link set lan2 up

  # create bridge
  ip link add name br0 type bridge

  # activate VLAN filtering
  ip link set dev br0 type bridge vlan_filtering 1

  # add ports to bridge
  ip link set dev wan master br0
  ip link set dev lan1 master br0
  ip link set dev lan2 master br0
  ip link set eth0.1 master br0

  # configure the bridge
  ip addr add 192.0.2.129/25 dev br0

  # bring up the bridge
  ip link set dev br0 up

gateway
~~~~~~~

.. code-block:: sh

  # tag traffic on CPU port
  ip link add link eth0 name eth0.1 type vlan id 1
  ip link add link eth0 name eth0.2 type vlan id 2

  # The master interface needs to be brought up before the slave ports.
  ip link set eth0 up
  ip link set eth0.1 up
  ip link set eth0.2 up

  # bring up the slave interfaces
  ip link set wan up
  ip link set lan1 up
  ip link set lan2 up

  # create bridge
  ip link add name br0 type bridge

  # activate VLAN filtering
  ip link set dev br0 type bridge vlan_filtering 1

  # add ports to bridges
  ip link set dev wan master br0
  ip link set eth0.1 master br0
  ip link set dev lan1 master br0
  ip link set dev lan2 master br0

  # tag traffic on ports
  bridge vlan add dev wan vid 2 pvid untagged
  bridge vlan del dev wan vid 1

  # configure the VLANs
  ip addr add 192.0.2.1/30 dev eth0.2
  ip addr add 192.0.2.129/25 dev br0

  # bring up the bridge devices
  ip link set br0 up


code:
=============================================
Broadcom Starfighter 2 Ethernet switch driver
=============================================

Broadcom's Starfighter 2 Ethernet switch hardware block is commonly found and
deployed in the following products:

- xDSL gateways such as BCM63138
- streaming/multimedia Set Top Box such as BCM7445
- Cable Modem/residential gateways such as BCM7145/BCM3390

The switch is typically deployed in a configuration involving between 5 to 13
ports, offering a range of built-in and customizable interfaces:

- single integrated Gigabit PHY
- quad integrated Gigabit PHY
- quad external Gigabit PHY w/ MDIO multiplexer
- integrated MoCA PHY
- several external MII/RevMII/GMII/RGMII interfaces

The switch also supports specific congestion control features which allow MoCA
fail-over not to lose packets during a MoCA role re-election, as well as out of
band back-pressure to the host CPU network interface when downstream interfaces
are connected at a lower speed.

The switch hardware block is typically interfaced using MMIO accesses and
contains a bunch of sub-blocks/registers:

- ``SWITCH_CORE``: common switch registers
- ``SWITCH_REG``: external interfaces switch register
- ``SWITCH_MDIO``: external MDIO bus controller (there is another one in SWITCH_CORE,
  which is used for indirect PHY accesses)
- ``SWITCH_INDIR_RW``: 64-bits wide register helper block
- ``SWITCH_INTRL2_0/1``: Level-2 interrupt controllers
- ``SWITCH_ACB``: Admission control block
- ``SWITCH_FCB``: Fail-over control block

Implementation details
======================

The driver is located in ``drivers/net/dsa/bcm_sf2.c`` and is implemented as a DSA
driver; see ``Documentation/networking/dsa/dsa.rst`` for details on the subsystem
and what it provides.

The SF2 switch is configured to enable a Broadcom specific 4-bytes switch tag
which gets inserted by the switch for every packet forwarded to the CPU
interface, conversely, the CPU network interface should insert a similar tag for
packets entering the CPU port. The tag format is described in
``net/dsa/tag_brcm.c``.

Overall, the SF2 driver is a fairly regular DSA driver; there are a few
specifics covered below.

Device Tree probing
-------------------

The DSA platform device driver is probed using a specific compatible string
provided in ``net/dsa/dsa.c``. The reason for that is because the DSA subsystem gets
registered as a platform device driver currently. DSA will provide the needed
device_node pointers which are then accessible by the switch driver setup
function to setup resources such as register ranges and interrupts. This
currently works very well because none of the of_* functions utilized by the
driver require a struct device to be bound to a struct device_node, but things
may change in the future.

MDIO indirect accesses
----------------------

Due to a limitation in how Broadcom switches have been designed, external
Broadcom switches connected to a SF2 require the use of the DSA slave MDIO bus
in order to properly configure them. By default, the SF2 pseudo-PHY address, and
an external switch pseudo-PHY address will both be snooping for incoming MDIO
transactions, since they are at the same address (30), resulting in some kind of
"double" programming. Using DSA, and setting ``ds->phys_mii_mask`` accordingly, we
selectively divert reads and writes towards external Broadcom switches
pseudo-PHY addresses. Newer revisions of the SF2 hardware have introduced a
configurable pseudo-PHY address which circumvents the initial design limitation.

Multimedia over CoAxial (MoCA) interfaces
-----------------------------------------

MoCA interfaces are fairly specific and require the use of a firmware blob which
gets loaded onto the MoCA processor(s) for packet processing. The switch
hardware contains logic which will assert/de-assert link states accordingly for
the MoCA interface whenever the MoCA coaxial cable gets disconnected or the
firmware gets reloaded. The SF2 driver relies on such events to properly set its
MoCA interface carrier state and properly report this to the networking stack.

The MoCA interfaces are supported using the PHY library's fixed PHY/emulated PHY
device and the switch driver registers a ``fixed_link_update`` callback for such
PHYs which reflects the link state obtained from the interrupt handler.

Power Management
----------------

Whenever possible, the SF2 driver tries to minimize the overall switch power
consumption by applying a combination of:

- turning off internal buffers/memories
- disabling packet processing logic
- putting integrated PHYs in IDDQ/low-power
- reducing the switch core clock based on the active port count
- enabling and advertising EEE
- turning off RGMII data processing logic when the link goes down

Wake-on-LAN
-----------

Wake-on-LAN is currently implemented by utilizing the host processor Ethernet
MAC controller wake-on logic. Whenever Wake-on-LAN is requested, an intersection
between the user request and the supported host Ethernet interface WoL
capabilities is done and the intersection result gets configured. During
system-wide suspend/resume, only ports not participating in Wake-on-LAN are
disabled.