code:
.. SPDX-License-Identifier: GPL-2.0
.. include:: <isonum.txt>

==============================================
Intel(R) PRO/Wireless 2915ABG Driver for Linux
==============================================

Support for:

- Intel(R) PRO/Wireless 2200BG Network Connection
- Intel(R) PRO/Wireless 2915ABG Network Connection

Note: The Intel(R) PRO/Wireless 2915ABG Driver for Linux and Intel(R)
PRO/Wireless 2200BG Driver for Linux is a unified driver that works on
both hardware adapters listed above. In this document the Intel(R)
PRO/Wireless 2915ABG Driver for Linux will be used to reference the
unified driver.

Copyright |copy| 2004-2006, Intel Corporation

README.ipw2200

:Version: 1.1.2
:Date: March 30, 2006

.. Index

    0.   IMPORTANT INFORMATION BEFORE USING THIS DRIVER
    1.   Introduction
    1.1. Overview of features
    1.2. Module parameters
    1.3. Wireless Extension Private Methods
    1.4. Sysfs Helper Files
    1.5. Supported channels
    2.   Ad-Hoc Networking
    3.   Interacting with Wireless Tools
    3.1. iwconfig mode
    3.2. iwconfig sens
    4.   About the Version Numbers
    5.   Firmware installation
    6.   Support
    7.   License

0. IMPORTANT INFORMATION BEFORE USING THIS DRIVER
=================================================

Important Notice FOR ALL USERS OR DISTRIBUTORS!!!!

Intel wireless LAN adapters are engineered, manufactured, tested, and
quality checked to ensure that they meet all necessary local and
governmental regulatory agency requirements for the regions that they
are designated and/or marked to ship into. Since wireless LANs are
generally unlicensed devices that share spectrum with radars,
satellites, and other licensed and unlicensed devices, it is sometimes
necessary to dynamically detect, avoid, and limit usage to avoid
interference with these devices. In many instances Intel is required to
provide test data to prove regional and local compliance to regional and
governmental regulations before certification or approval to use the
product is granted. Intel's wireless LAN's EEPROM, firmware, and
software driver are designed to carefully control parameters that affect
radio operation and to ensure electromagnetic compliance (EMC). These
parameters include, without limitation, RF power, spectrum usage,
channel scanning, and human exposure.

For these reasons Intel cannot permit any manipulation by third parties
of the software provided in binary format with the wireless WLAN
adapters (e.g., the EEPROM and firmware). Furthermore, if you use any
patches, utilities, or code with the Intel wireless LAN adapters that
have been manipulated by an unauthorized party (i.e., patches,
utilities, or code (including open source code modifications) which have
not been validated by Intel), (i) you will be solely responsible for
ensuring the regulatory compliance of the products, (ii) Intel will bear
no liability, under any theory of liability for any issues associated
with the modified products, including without limitation, claims under
the warranty and/or issues arising from regulatory non-compliance, and
(iii) Intel will not provide or be required to assist in providing
support to any third parties for such modified products.

Note: Many regulatory agencies consider Wireless LAN adapters to be
modules, and accordingly, condition system-level regulatory approval
upon receipt and review of test data documenting that the antennas and
system configuration do not cause the EMC and radio operation to be
non-compliant.

The drivers available for download from SourceForge are provided as a
part of a development project.  Conformance to local regulatory
requirements is the responsibility of the individual developer.  As
such, if you are interested in deploying or shipping a driver as part of
solution intended to be used for purposes other than development, please
obtain a tested driver from Intel Customer Support at:

http://support.intel.com

1. Introduction
===============

The following sections attempt to provide a brief introduction to using
the Intel(R) PRO/Wireless 2915ABG Driver for Linux.

This document is not meant to be a comprehensive manual on
understanding or using wireless technologies, but should be sufficient
to get you moving without wires on Linux.

For information on building and installing the driver, see the INSTALL
file.

1.1. Overview of Features
-------------------------
The current release (1.1.2) supports the following features:

+ BSS mode (Infrastructure, Managed)
+ IBSS mode (Ad-Hoc)
+ WEP (OPEN and SHARED KEY mode)
+ 802.1x EAP via wpa_supplicant and xsupplicant
+ Wireless Extension support
+ Full B and G rate support (2200 and 2915)
+ Full A rate support (2915 only)
+ Transmit power control
+ S state support (ACPI suspend/resume)

The following features are currently enabled, but not officially
supported:

+ WPA
+ long/short preamble support
+ Monitor mode (aka RFMon)

The distinction between officially supported and enabled is a reflection
on the amount of validation and interoperability testing that has been
performed on a given feature.

1.2. Command Line Parameters
----------------------------

Like many modules used in the Linux kernel, the Intel(R) PRO/Wireless
2915ABG Driver for Linux allows configuration options to be provided
as module parameters.  The most common way to specify a module parameter
is via the command line.

The general form is::

    % modprobe ipw2200 parameter=value

Where the supported parameter are:

  associate
	Set to 0 to disable the auto scan-and-associate functionality of the
	driver.  If disabled, the driver will not attempt to scan
	for and associate to a network until it has been configured with
	one or more properties for the target network, for example configuring
	the network SSID.  Default is 0 (do not auto-associate)

	Example: % modprobe ipw2200 associate=0

  auto_create
	Set to 0 to disable the auto creation of an Ad-Hoc network
	matching the channel and network name parameters provided.
	Default is 1.

  channel
	channel number for association.  The normal method for setting
	the channel would be to use the standard wireless tools
	(i.e. `iwconfig eth1 channel 10`), but it is useful sometimes
	to set this while debugging.  Channel 0 means 'ANY'

  debug
	If using a debug build, this is used to control the amount of debug
	info is logged.  See the 'dvals' and 'load' script for more info on
	how to use this (the dvals and load scripts are provided as part
	of the ipw2200 development snapshot releases available from the
	SourceForge project at http://ipw2200.sf.net)

  led
	Can be used to turn on experimental LED code.
	0 = Off, 1 = On.  Default is 1.

  mode
	Can be used to set the default mode of the adapter.
	0 = Managed, 1 = Ad-Hoc, 2 = Monitor

1.3. Wireless Extension Private Methods
---------------------------------------

As an interface designed to handle generic hardware, there are certain
capabilities not exposed through the normal Wireless Tool interface.  As
such, a provision is provided for a driver to declare custom, or
private, methods.  The Intel(R) PRO/Wireless 2915ABG Driver for Linux
defines several of these to configure various settings.

The general form of using the private wireless methods is::

	% iwpriv $IFNAME method parameters

Where $IFNAME is the interface name the device is registered with
(typically eth1, customized via one of the various network interface
name managers, such as ifrename)

The supported private methods are:

  get_mode
	Can be used to report out which IEEE mode the driver is
	configured to support.  Example:

	% iwpriv eth1 get_mode
	eth1	get_mode:802.11bg (6)

  set_mode
	Can be used to configure which IEEE mode the driver will
	support.

	Usage::

	    % iwpriv eth1 set_mode {mode}

	Where {mode} is a number in the range 1-7:

	==	=====================
	1	802.11a (2915 only)
	2	802.11b
	3	802.11ab (2915 only)
	4	802.11g
	5	802.11ag (2915 only)
	6	802.11bg
	7	802.11abg (2915 only)
	==	=====================

  get_preamble
	Can be used to report configuration of preamble length.

  set_preamble
	Can be used to set the configuration of preamble length:

	Usage::

	    % iwpriv eth1 set_preamble {mode}

	Where {mode} is one of:

	==	========================================
	1	Long preamble only
	0	Auto (long or short based on connection)
	==	========================================

1.4. Sysfs Helper Files
-----------------------

The Linux kernel provides a pseudo file system that can be used to
access various components of the operating system.  The Intel(R)
PRO/Wireless 2915ABG Driver for Linux exposes several configuration
parameters through this mechanism.

An entry in the sysfs can support reading and/or writing.  You can
typically query the contents of a sysfs entry through the use of cat,
and can set the contents via echo.  For example::

    % cat /sys/bus/pci/drivers/ipw2200/debug_level

Will report the current debug level of the driver's logging subsystem
(only available if CONFIG_IPW2200_DEBUG was configured when the driver
was built).

You can set the debug level via::

    % echo $VALUE > /sys/bus/pci/drivers/ipw2200/debug_level

Where $VALUE would be a number in the case of this sysfs entry.  The
input to sysfs files does not have to be a number.  For example, the
firmware loader used by hotplug utilizes sysfs entries for transferring
the firmware image from user space into the driver.

The Intel(R) PRO/Wireless 2915ABG Driver for Linux exposes sysfs entries
at two levels -- driver level, which apply to all instances of the driver
(in the event that there are more than one device installed) and device
level, which applies only to the single specific instance.

1.4.1 Driver Level Sysfs Helper Files
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

For the driver level files, look in /sys/bus/pci/drivers/ipw2200/

  debug_level
	This controls the same global as the 'debug' module parameter

1.4.2 Device Level Sysfs Helper Files
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

For the device level files, look in::

	/sys/bus/pci/drivers/ipw2200/{PCI-ID}/

For example:::

	/sys/bus/pci/drivers/ipw2200/0000:02:01.0

For the device level files, see /sys/bus/pci/drivers/ipw2200:

  rf_kill
	read -

	==  =========================================
	0   RF kill not enabled (radio on)
	1   SW based RF kill active (radio off)
	2   HW based RF kill active (radio off)
	3   Both HW and SW RF kill active (radio off)
	==  =========================================

	write -

	==  ==================================================
	0   If SW based RF kill active, turn the radio back on
	1   If radio is on, activate SW based RF kill
	==  ==================================================

	.. note::

	   If you enable the SW based RF kill and then toggle the HW
	   based RF kill from ON -> OFF -> ON, the radio will NOT come back on

  ucode
	read-only access to the ucode version number

  led
	read -

	==  =================
	0   LED code disabled
	1   LED code enabled
	==  =================

	write -

	==  ================
	0   Disable LED code
	1   Enable LED code
	==  ================

	.. note::

	   The LED code has been reported to hang some systems when
	   running ifconfig and is therefore disabled by default.

1.5. Supported channels
-----------------------

Upon loading the Intel(R) PRO/Wireless 2915ABG Driver for Linux, a
message stating the detected geography code and the number of 802.11
channels supported by the card will be displayed in the log.

The geography code corresponds to a regulatory domain as shown in the
table below.

	+------+----------------------------+--------------------+
	|      |			    | Supported channels |
	| Code |        Geography	    +----------+---------+
	|      |			    | 802.11bg | 802.11a |
	+======+============================+==========+=========+
	| ---  | Restricted 		    |  11      |   0     |
	+------+----------------------------+----------+---------+
	| ZZF  | Custom US/Canada 	    |  11      |   8     |
	+------+----------------------------+----------+---------+
	| ZZD  | Rest of World 		    |  13      |   0     |
	+------+----------------------------+----------+---------+
	| ZZA  | Custom USA & Europe & High |  11      |  13     |
	+------+----------------------------+----------+---------+
	| ZZB  | Custom NA & Europe	    |  11      |  13     |
	+------+----------------------------+----------+---------+
	| ZZC  | Custom Japan 		    |  11      |   4     |
	+------+----------------------------+----------+---------+
	| ZZM  | Custom  		    |  11      |   0     |
	+------+----------------------------+----------+---------+
	| ZZE  | Europe 		    |  13      |  19     |
	+------+----------------------------+----------+---------+
	| ZZJ  | Custom Japan 		    |  14      |   4     |
	+------+----------------------------+----------+---------+
	| ZZR  | Rest of World		    |  14      |   0     |
	+------+----------------------------+----------+---------+
	| ZZH  | High Band		    |  13      |   4     |
	+------+----------------------------+----------+---------+
	| ZZG  | Custom Europe		    |  13      |   4     |
	+------+----------------------------+----------+---------+
	| ZZK  | Europe 		    |  13      |  24     |
	+------+----------------------------+----------+---------+
	| ZZL  | Europe 		    |  11      |  13     |
	+------+----------------------------+----------+---------+

2.  Ad-Hoc Networking
=====================

When using a device in an Ad-Hoc network, it is useful to understand the
sequence and requirements for the driver to be able to create, join, or
merge networks.

The following attempts to provide enough information so that you can
have a consistent experience while using the driver as a member of an
Ad-Hoc network.

2.1. Joining an Ad-Hoc Network
------------------------------

The easiest way to get onto an Ad-Hoc network is to join one that
already exists.

2.2. Creating an Ad-Hoc Network
-------------------------------

An Ad-Hoc networks is created using the syntax of the Wireless tool.

For Example:
iwconfig eth1 mode ad-hoc essid testing channel 2

2.3. Merging Ad-Hoc Networks
----------------------------

3. Interaction with Wireless Tools
==================================

3.1 iwconfig mode
-----------------

When configuring the mode of the adapter, all run-time configured parameters
are reset to the value used when the module was loaded.  This includes
channels, rates, ESSID, etc.

3.2 iwconfig sens
-----------------

The 'iwconfig ethX sens XX' command will not set the signal sensitivity
threshold, as described in iwconfig documentation, but rather the number
of consecutive missed beacons that will trigger handover, i.e. roaming
to another access point. At the same time, it will set the disassociation
threshold to 3 times the given value.

4.  About the Version Numbers
=============================

Due to the nature of open source development projects, there are
frequently changes being incorporated that have not gone through
a complete validation process.  These changes are incorporated into
development snapshot releases.

Releases are numbered with a three level scheme:

	major.minor.development

Any version where the 'development' portion is 0 (for example
1.0.0, 1.1.0, etc.) indicates a stable version that will be made
available for kernel inclusion.

Any version where the 'development' portion is not a 0 (for
example 1.0.1, 1.1.5, etc.) indicates a development version that is
being made available for testing and cutting edge users.  The stability
and functionality of the development releases are not know.  We make
efforts to try and keep all snapshots reasonably stable, but due to the
frequency of their release, and the desire to get those releases
available as quickly as possible, unknown anomalies should be expected.

The major version number will be incremented when significant changes
are made to the driver.  Currently, there are no major changes planned.

5. Firmware installation
========================

The driver requires a firmware image, download it and extract the
files under /lib/firmware (or wherever your hotplug's firmware.agent
will look for firmware files)

The firmware can be downloaded from the following URL:

    http://ipw2200.sf.net/

6. Support
==========

For direct support of the 1.0.0 version, you can contact
http://supportmail.intel.com, or you can use the open source project
support.

For general information and support, go to:

    http://ipw2200.sf.net/

7. License
==========

  Copyright |copy| 2003 - 2006 Intel Corporation. All rights reserved.

  This program is free software; you can redistribute it and/or modify it
  under the terms of the GNU General Public License version 2 as
  published by the Free Software Foundation.

  This program is distributed in the hope that it will be useful, but WITHOUT
  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
  more details.

  You should have received a copy of the GNU General Public License along with
  this program; if not, write to the Free Software Foundation, Inc., 59
  Temple Place - Suite 330, Boston, MA  02111-1307, USA.

  The full GNU General Public License is included in this distribution in the
  file called LICENSE.

  Contact Information:

  James P. Ketrenos <ipw2100-admin@linux.intel.com>

  Intel Corporation, 5200 N.E. Elam Young Parkway, Hillsboro, OR 97124-6497


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

.. include:: <isonum.txt>

=========================
Raylink wireless LAN card
=========================

September 21, 1999

Copyright |copy| 1998  Corey Thomas (corey@world.std.com)

This file is the documentation for the Raylink Wireless LAN card driver for
Linux.  The Raylink wireless LAN card is a PCMCIA card which provides IEEE
802.11 compatible wireless network connectivity at 1 and 2 megabits/second.
See http://www.raytheon.com/micro/raylink/ for more information on the Raylink
card.  This driver is in early development and does have bugs.  See the known
bugs and limitations at the end of this document for more information.
This driver also works with WebGear's Aviator 2.4 and Aviator Pro
wireless LAN cards.

As of kernel 2.3.18, the ray_cs driver is part of the Linux kernel
source.  My web page for the development of ray_cs is at
http://web.ralinktech.com/ralink/Home/Support/Linux.html
and I can be emailed at corey@world.std.com

The kernel driver is based on ray_cs-1.62.tgz

The driver at my web page is intended to be used as an add on to
David Hinds pcmcia package.  All the command line parameters are
available when compiled as a module.  When built into the kernel, only
the essid= string parameter is available via the kernel command line.
This will change after the method of sorting out parameters for all
the PCMCIA drivers is agreed upon.  If you must have a built in driver
with nondefault parameters, they can be edited in
/usr/src/linux/drivers/net/pcmcia/ray_cs.c.  Searching for module_param
will find them all.

Information on card services is available at:

	http://pcmcia-cs.sourceforge.net/

Card services user programs are still required for PCMCIA devices.
pcmcia-cs-3.1.1 or greater is required for the kernel version of
the driver.

Currently, ray_cs is not part of David Hinds card services package,
so the following magic is required.

At the end of the /etc/pcmcia/config.opts file, add the line:
source ./ray_cs.opts
This will make card services read the ray_cs.opts file
when starting.  Create the file /etc/pcmcia/ray_cs.opts containing the
following::

  #### start of /etc/pcmcia/ray_cs.opts ###################
  # Configuration options for Raylink Wireless LAN PCMCIA card
  device "ray_cs"
    class "network" module "misc/ray_cs"

  card "RayLink PC Card WLAN Adapter"
    manfid 0x01a6, 0x0000
    bind "ray_cs"

  module "misc/ray_cs" opts ""
  #### end of /etc/pcmcia/ray_cs.opts #####################

To join an existing network with
different parameters, contact the network administrator for the
configuration information, and edit /etc/pcmcia/ray_cs.opts.
Add the parameters below between the empty quotes.

Parameters for ray_cs driver which may be specified in ray_cs.opts:

=============== =============== =============================================
bc              integer         0 = normal mode (802.11 timing),
				1 = slow down inter frame timing to allow
				operation with older breezecom access
				points.

beacon_period	integer         beacon period in Kilo-microseconds,

				legal values = must be integer multiple
				of hop dwell

				default = 256

country         integer         1 = USA (default),
				2 = Europe,
				3 = Japan,
				4 = Korea,
				5 = Spain,
				6 = France,
				7 = Israel,
				8 = Australia

essid		string		ESS ID - network name to join

				string with maximum length of 32 chars
				default value = "ADHOC_ESSID"

hop_dwell	integer         hop dwell time in Kilo-microseconds

				legal values = 16,32,64,128(default),256

irq_mask	integer         linux standard 16 bit value 1bit/IRQ

				lsb is IRQ 0, bit 1 is IRQ 1 etc.
				Used to restrict choice of IRQ's to use.
				Recommended method for controlling
				interrupts is in /etc/pcmcia/config.opts

net_type	integer		0 (default) = adhoc network,
				1 = infrastructure

phy_addr	string          string containing new MAC address in
				hex, must start with x eg
				x00008f123456

psm		integer         0 = continuously active,
				1 = power save mode (not useful yet)

pc_debug	integer		(0-5) larger values for more verbose
				logging.  Replaces ray_debug.

ray_debug	integer		Replaced with pc_debug

ray_mem_speed   integer         defaults to 500

sniffer         integer         0 = not sniffer (default),
				1 = sniffer which can be used to record all
				network traffic using tcpdump or similar,
				but no normal network use is allowed.

translate	integer		0 = no translation (encapsulate frames),
				1 = translation    (RFC1042/802.1)
=============== =============== =============================================

More on sniffer mode:

tcpdump does not understand 802.11 headers, so it can't
interpret the contents, but it can record to a file.  This is only
useful for debugging 802.11 lowlevel protocols that are not visible to
linux.  If you want to watch ftp xfers, or do similar things, you
don't need to use sniffer mode.  Also, some packet types are never
sent up by the card, so you will never see them (ack, rts, cts, probe
etc.)  There is a simple program (showcap) included in the ray_cs
package which parses the 802.11 headers.

Known Problems and missing features

	Does not work with non x86

	Does not work with SMP

	Support for defragmenting frames is not yet debugged, and in
	fact is known to not work.  I have never encountered a net set
	up to fragment, but still, it should be fixed.

	The ioctl support is incomplete.  The hardware address cannot be set
	using ifconfig yet.  If a different hardware address is needed, it may
	be set using the phy_addr parameter in ray_cs.opts.  This requires
	a card insertion to take effect.

repo_name: angery/linux


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

WWAN Device Drivers
===================

Contents:

.. toctree::
   :maxdepth: 2

   iosm
   t7xx

.. only::  subproject and html

   Indices
   =======

   * :ref:`genindex`


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

.. Copyright (C) 2020-21 Intel Corporation

.. _iosm_driver_doc:

===========================================
IOSM Driver for Intel M.2 PCIe based Modems
===========================================
The IOSM (IPC over Shared Memory) driver is a WWAN PCIe host driver developed
for linux or chrome platform for data exchange over PCIe interface between
Host platform & Intel M.2 Modem. The driver exposes interface conforming to the
MBIM protocol [1]. Any front end application ( eg: Modem Manager) could easily
manage the MBIM interface to enable data communication towards WWAN.

Basic usage
===========
MBIM functions are inactive when unmanaged. The IOSM driver only provides a
userspace interface MBIM "WWAN PORT" representing MBIM control channel and does
not play any role in managing the functionality. It is the job of a userspace
application to detect port enumeration and enable MBIM functionality.

Examples of few such userspace application are:
- mbimcli (included with the libmbim [2] library), and
- Modem Manager [3]

Management Applications to carry out below required actions for establishing
MBIM IP session:
- open the MBIM control channel
- configure network connection settings
- connect to network
- configure IP network interface

Management application development
==================================
The driver and userspace interfaces are described below. The MBIM protocol is
described in [1] Mobile Broadband Interface Model v1.0 Errata-1.

MBIM control channel userspace ABI
----------------------------------

/dev/wwan0mbim0 character device
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The driver exposes an MBIM interface to the MBIM function by implementing
MBIM WWAN Port. The userspace end of the control channel pipe is a
/dev/wwan0mbim0 character device. Application shall use this interface for
MBIM protocol communication.

Fragmentation
~~~~~~~~~~~~~
The userspace application is responsible for all control message fragmentation
and defragmentation as per MBIM specification.

/dev/wwan0mbim0 write()
~~~~~~~~~~~~~~~~~~~~~~~
The MBIM control messages from the management application must not exceed the
negotiated control message size.

/dev/wwan0mbim0 read()
~~~~~~~~~~~~~~~~~~~~~~
The management application must accept control messages of up the negotiated
control message size.

MBIM data channel userspace ABI
-------------------------------

wwan0-X network device
~~~~~~~~~~~~~~~~~~~~~~
The IOSM driver exposes IP link interface "wwan0-X" of type "wwan" for IP
traffic. Iproute network utility is used for creating "wwan0-X" network
interface and for associating it with MBIM IP session. The Driver supports
upto 8 IP sessions for simultaneous IP communication.

The userspace management application is responsible for creating new IP link
prior to establishing MBIM IP session where the SessionId is greater than 0.

For example, creating new IP link for a MBIM IP session with SessionId 1:

  ip link add dev wwan0-1 parentdev-name wwan0 type wwan linkid 1

The driver will automatically map the "wwan0-1" network device to MBIM IP
session 1.

References
==========
[1] "MBIM (Mobile Broadband Interface Model) Errata-1"
      - https://www.usb.org/document-library/

[2] libmbim - "a glib-based library for talking to WWAN modems and
      devices which speak the Mobile Interface Broadband Model (MBIM)
      protocol"
      - http://www.freedesktop.org/wiki/Software/libmbim/

[3] Modem Manager - "a DBus-activated daemon which controls mobile
      broadband (2G/3G/4G) devices and connections"
      - http://www.freedesktop.org/wiki/Software/ModemManager/


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

.. Copyright (C) 2020-21 Intel Corporation

.. _t7xx_driver_doc:

============================================
t7xx driver for MTK PCIe based T700 5G modem
============================================
The t7xx driver is a WWAN PCIe host driver developed for linux or Chrome OS platforms
for data exchange over PCIe interface between Host platform & MediaTek's T700 5G modem.
The driver exposes an interface conforming to the MBIM protocol [1]. Any front end
application (e.g. Modem Manager) could easily manage the MBIM interface to enable
data communication towards WWAN. The driver also provides an interface to interact
with the MediaTek's modem via AT commands.

Basic usage
===========
MBIM & AT functions are inactive when unmanaged. The t7xx driver provides
WWAN port userspace interfaces representing MBIM & AT control channels and does
not play any role in managing their functionality. It is the job of a userspace
application to detect port enumeration and enable MBIM & AT functionalities.

Examples of few such userspace applications are:

- mbimcli (included with the libmbim [2] library), and
- Modem Manager [3]

Management Applications to carry out below required actions for establishing
MBIM IP session:

- open the MBIM control channel
- configure network connection settings
- connect to network
- configure IP network interface

Management Applications to carry out below required actions for send an AT
command and receive response:

- open the AT control channel using a UART tool or a special user tool

Management application development
==================================
The driver and userspace interfaces are described below. The MBIM protocol is
described in [1] Mobile Broadband Interface Model v1.0 Errata-1.

MBIM control channel userspace ABI
----------------------------------

/dev/wwan0mbim0 character device
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The driver exposes an MBIM interface to the MBIM function by implementing
MBIM WWAN Port. The userspace end of the control channel pipe is a
/dev/wwan0mbim0 character device. Application shall use this interface for
MBIM protocol communication.

Fragmentation
~~~~~~~~~~~~~
The userspace application is responsible for all control message fragmentation
and defragmentation as per MBIM specification.

/dev/wwan0mbim0 write()
~~~~~~~~~~~~~~~~~~~~~~~
The MBIM control messages from the management application must not exceed the
negotiated control message size.

/dev/wwan0mbim0 read()
~~~~~~~~~~~~~~~~~~~~~~
The management application must accept control messages of up the negotiated
control message size.

MBIM data channel userspace ABI
-------------------------------

wwan0-X network device
~~~~~~~~~~~~~~~~~~~~~~
The t7xx driver exposes IP link interface "wwan0-X" of type "wwan" for IP
traffic. Iproute network utility is used for creating "wwan0-X" network
interface and for associating it with MBIM IP session.

The userspace management application is responsible for creating new IP link
prior to establishing MBIM IP session where the SessionId is greater than 0.

For example, creating new IP link for a MBIM IP session with SessionId 1:

  ip link add dev wwan0-1 parentdev wwan0 type wwan linkid 1

The driver will automatically map the "wwan0-1" network device to MBIM IP
session 1.

AT port userspace ABI
----------------------------------

/dev/wwan0at0 character device
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The driver exposes an AT port by implementing AT WWAN Port.
The userspace end of the control port is a /dev/wwan0at0 character
device. Application shall use this interface to issue AT commands.

The MediaTek's T700 modem supports the 3GPP TS 27.007 [4] specification.

References
==========
[1] *MBIM (Mobile Broadband Interface Model) Errata-1*

- https://www.usb.org/document-library/

[2] *libmbim "a glib-based library for talking to WWAN modems and devices which
speak the Mobile Interface Broadband Model (MBIM) protocol"*

- http://www.freedesktop.org/wiki/Software/libmbim/

[3] *Modem Manager "a DBus-activated daemon which controls mobile broadband
(2G/3G/4G/5G) devices and connections"*

- http://www.freedesktop.org/wiki/Software/ModemManager/

[4] *Specification # 27.007 - 3GPP*

- https://www.3gpp.org/DynaReport/27007.htm


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

==============================
am65-cpsw-nuss devlink support
==============================

This document describes the devlink features implemented by the ``am65-cpsw-nuss``
device driver.

Parameters
==========

The ``am65-cpsw-nuss`` driver implements the following driver-specific
parameters.

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

   * - Name
     - Type
     - Mode
     - Description
   * - ``switch_mode``
     - Boolean
     - runtime
     - Enable switch mode


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

====================
bnxt devlink support
====================

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

Parameters
==========

.. list-table:: Generic parameters implemented

   * - Name
     - Mode
   * - ``enable_sriov``
     - Permanent
   * - ``ignore_ari``
     - Permanent
   * - ``msix_vec_per_pf_max``
     - Permanent
   * - ``msix_vec_per_pf_min``
     - Permanent
   * - ``enable_remote_dev_reset``
     - Runtime

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

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

   * - Name
     - Type
     - Mode
     - Description
   * - ``gre_ver_check``
     - Boolean
     - Permanent
     - Generic Routing Encapsulation (GRE) version check will be enabled in
       the device. If disabled, the device will skip the version check for
       incoming packets.

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

The ``bnxt_en`` 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
   * - ``asic.id``
     - fixed
     - ASIC design identifier
   * - ``asic.rev``
     - fixed
     - ASIC design revision
   * - ``fw.psid``
     - stored, running
     - Firmware parameter set version of the board
   * - ``fw``
     - stored, running
     - Overall board firmware version
   * - ``fw.mgmt``
     - stored, running
     - NIC hardware resource management firmware version
   * - ``fw.mgmt.api``
     - running
     - Minimum firmware interface spec version supported between driver and firmware
   * - ``fw.nsci``
     - stored, running
     - General platform management firmware version
   * - ``fw.roce``
     - stored, running
     - RoCE management firmware version


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

=============
Devlink DPIPE
=============

Background
==========

While performing the hardware offloading process, much of the hardware
specifics cannot be presented. These details are useful for debugging, and
``devlink-dpipe`` provides a standardized way to provide visibility into the
offloading process.

For example, the routing longest prefix match (LPM) algorithm used by the
Linux kernel may differ from the hardware implementation. The pipeline debug
API (DPIPE) is aimed at providing the user visibility into the ASIC's
pipeline in a generic way.

The hardware offload process is expected to be done in a way that the user
should not be able to distinguish between the hardware vs. software
implementation. In this process, hardware specifics are neglected. In
reality those details can have lots of meaning and should be exposed in some
standard way.

This problem is made even more complex when one wishes to offload the
control path of the whole networking stack to a switch ASIC. Due to
differences in the hardware and software models some processes cannot be
represented correctly.

One example is the kernel's LPM algorithm which in many cases differs
greatly to the hardware implementation. The configuration API is the same,
but one cannot rely on the Forward Information Base (FIB) to look like the
Level Path Compression trie (LPC-trie) in hardware.

In many situations trying to analyze systems failure solely based on the
kernel's dump may not be enough. By combining this data with complementary
information about the underlying hardware, this debugging can be made
easier; additionally, the information can be useful when debugging
performance issues.

Overview
========

The ``devlink-dpipe`` interface closes this gap. The hardware's pipeline is
modeled as a graph of match/action tables. Each table represents a specific
hardware block. This model is not new, first being used by the P4 language.

Traditionally it has been used as an alternative model for hardware
configuration, but the ``devlink-dpipe`` interface uses it for visibility
purposes as a standard complementary tool. The system's view from
``devlink-dpipe`` should change according to the changes done by the
standard configuration tools.

For example, it’s quite common to  implement Access Control Lists (ACL)
using Ternary Content Addressable Memory (TCAM). The TCAM memory can be
divided into TCAM regions. Complex TC filters can have multiple rules with
different priorities and different lookup keys. On the other hand hardware
TCAM regions have a predefined lookup key. Offloading the TC filter rules
using TCAM engine can result in multiple TCAM regions being interconnected
in a chain (which may affect the data path latency). In response to a new TC
filter new tables should be created describing those regions.

Model
=====

The ``DPIPE`` model introduces several objects:

  * headers
  * tables
  * entries

A ``header`` describes packet formats and provides names for fields within
the packet. A ``table`` describes hardware blocks. An ``entry`` describes
the actual content of a specific table.

The hardware pipeline is not port specific, but rather describes the whole
ASIC. Thus it is tied to the top of the ``devlink`` infrastructure.

Drivers can register and unregister tables at run time, in order to support
dynamic behavior. This dynamic behavior is mandatory for describing hardware
blocks like TCAM regions which can be allocated and freed dynamically.

``devlink-dpipe`` generally is not intended for configuration. The exception
is hardware counting for a specific table.

The following commands are used to obtain the ``dpipe`` objects from
userspace:

  * ``table_get``: Receive a table's description.
  * ``headers_get``: Receive a device's supported headers.
  * ``entries_get``: Receive a table's current entries.
  * ``counters_set``: Enable or disable counters on a table.

Table
-----

The driver should implement the following operations for each table:

  * ``matches_dump``: Dump the supported matches.
  * ``actions_dump``: Dump the supported actions.
  * ``entries_dump``: Dump the actual content of the table.
  * ``counters_set_update``: Synchronize hardware with counters enabled or
    disabled.

Header/Field
------------

In a similar way to P4 headers and fields are used to describe a table's
behavior. There is a slight difference between the standard protocol headers
and specific ASIC metadata. The protocol headers should be declared in the
``devlink`` core API. On the other hand ASIC meta data is driver specific
and should be defined in the driver. Additionally, each driver-specific
devlink documentation file should document the driver-specific ``dpipe``
headers it implements. The headers and fields are identified by enumeration.

In order to provide further visibility some ASIC metadata fields could be
mapped to kernel objects. For example, internal router interface indexes can
be directly mapped to the net device ifindex. FIB table indexes used by
different Virtual Routing and Forwarding (VRF) tables can be mapped to
internal routing table indexes.

Match
-----

Matches are kept primitive and close to hardware operation. Match types like
LPM are not supported due to the fact that this is exactly a process we wish
to describe in full detail. Example of matches:

  * ``field_exact``: Exact match on a specific field.
  * ``field_exact_mask``: Exact match on a specific field after masking.
  * ``field_range``: Match on a specific range.

The id's of the header and the field should be specified in order to
identify the specific field. Furthermore, the header index should be
specified in order to distinguish multiple headers of the same type in a
packet (tunneling).

Action
------

Similar to match, the actions are kept primitive and close to hardware
operation. For example:

  * ``field_modify``: Modify the field value.
  * ``field_inc``: Increment the field value.
  * ``push_header``: Add a header.
  * ``pop_header``: Remove a header.

Entry
-----

Entries of a specific table can be dumped on demand. Each eentry is
identified with an index and its properties are described by a list of
match/action values and specific counter. By dumping the tables content the
interactions between tables can be resolved.

Abstraction Example
===================

The following is an example of the abstraction model of the L3 part of
Mellanox Spectrum ASIC. The blocks are described in the order they appear in
the pipeline. The table sizes in the following examples are not real
hardware sizes and are provided for demonstration purposes.

LPM
---

The LPM algorithm can be implemented as a list of hash tables. Each hash
table contains routes with the same prefix length. The root of the list is
/32, and in case of a miss the hardware will continue to the next hash
table. The depth of the search will affect the data path latency.

In case of a hit the entry contains information about the next stage of the
pipeline which resolves the MAC address. The next stage can be either local
host table for directly connected routes, or adjacency table for next-hops.
The ``meta.lpm_prefix`` field is used to connect two LPM tables.

.. code::

    table lpm_prefix_16 {
      size: 4096,
      counters_enabled: true,
      match: { meta.vr_id: exact,
               ipv4.dst_addr: exact_mask,
               ipv6.dst_addr: exact_mask,
               meta.lpm_prefix: exact },
      action: { meta.adj_index: set,
                meta.adj_group_size: set,
                meta.rif_port: set,
                meta.lpm_prefix: set },
    }

Local Host
----------

In the case of local routes the LPM lookup already resolves the egress
router interface (RIF), yet the exact MAC address is not known. The local
host table is a hash table combining the output interface id with
destination IP address as a key. The result is the MAC address.

.. code::

    table local_host {
      size: 4096,
      counters_enabled: true,
      match: { meta.rif_port: exact,
               ipv4.dst_addr: exact},
      action: { ethernet.daddr: set }
    }

Adjacency
---------

In case of remote routes this table does the ECMP. The LPM lookup results in
ECMP group size and index that serves as a global offset into this table.
Concurrently a hash of the packet is generated. Based on the ECMP group size
and the packet's hash a local offset is generated. Multiple LPM entries can
point to the same adjacency group.

.. code::

    table adjacency {
      size: 4096,
      counters_enabled: true,
      match: { meta.adj_index: exact,
               meta.adj_group_size: exact,
               meta.packet_hash_index: exact },
      action: { ethernet.daddr: set,
                meta.erif: set }
    }

ERIF
----

In case the egress RIF and destination MAC have been resolved by previous
tables this table does multiple operations like TTL decrease and MTU check.
Then the decision of forward/drop is taken and the port L3 statistics are
updated based on the packet's type (broadcast, unicast, multicast).

.. code::

    table erif {
      size: 800,
      counters_enabled: true,
      match: { meta.rif_port: exact,
               meta.is_l3_unicast: exact,
               meta.is_l3_broadcast: exact,
               meta.is_l3_multicast, exact },
      action: { meta.l3_drop: set,
                meta.l3_forward: set }
    }


code:
.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)

.. _devlink_flash:

=============
Devlink Flash
=============

The ``devlink-flash`` API allows updating device firmware. It replaces the
older ``ethtool-flash`` mechanism, and doesn't require taking any
networking locks in the kernel to perform the flash update. Example use::

  $ devlink dev flash pci/0000:05:00.0 file flash-boot.bin

Note that the file name is a path relative to the firmware loading path
(usually ``/lib/firmware/``). Drivers may send status updates to inform
user space about the progress of the update operation.

Overwrite Mask
==============

The ``devlink-flash`` command allows optionally specifying a mask indicating
how the device should handle subsections of flash components when updating.
This mask indicates the set of sections which are allowed to be overwritten.

.. list-table:: List of overwrite mask bits
   :widths: 5 95

   * - Name
     - Description
   * - ``DEVLINK_FLASH_OVERWRITE_SETTINGS``
     - Indicates that the device should overwrite settings in the components
       being updated with the settings found in the provided image.
   * - ``DEVLINK_FLASH_OVERWRITE_IDENTIFIERS``
     - Indicates that the device should overwrite identifiers in the
       components being updated with the identifiers found in the provided
       image. This includes MAC addresses, serial IDs, and similar device
       identifiers.

Multiple overwrite bits may be combined and requested together. If no bits
are provided, it is expected that the device only update firmware binaries
in the components being updated. Settings and identifiers are expected to be
preserved across the update. A device may not support every combination and
the driver for such a device must reject any combination which cannot be
faithfully implemented.

Firmware Loading
================

Devices which require firmware to operate usually store it in non-volatile
memory on the board, e.g. flash. Some devices store only basic firmware on
the board, and the driver loads the rest from disk during probing.
``devlink-info`` allows users to query firmware information (loaded
components and versions).

In other cases the device can both store the image on the board, load from
disk, or automatically flash a new image from disk. The ``fw_load_policy``
devlink parameter can be used to control this behavior
(:ref:`Documentation/networking/devlink/devlink-params.rst <devlink_params_generic>`).

On-disk firmware files are usually stored in ``/lib/firmware/``.

Firmware Version Management
===========================

Drivers are expected to implement ``devlink-flash`` and ``devlink-info``
functionality, which together allow for implementing vendor-independent
automated firmware update facilities.

``devlink-info`` exposes the ``driver`` name and three version groups
(``fixed``, ``running``, ``stored``).

The ``driver`` attribute and ``fixed`` group identify the specific device
design, e.g. for looking up applicable firmware updates. This is why
``serial_number`` is not part of the ``fixed`` versions (even though it
is fixed) - ``fixed`` versions should identify the design, not a single
device.

``running`` and ``stored`` firmware versions identify the firmware running
on the device, and firmware which will be activated after reboot or device
reset.

The firmware update agent is supposed to be able to follow this simple
algorithm to update firmware contents, regardless of the device vendor:

.. code-block:: sh

  # Get unique HW design identifier
  $hw_id = devlink-dev-info['fixed']

  # Find out which FW flash we want to use for this NIC
  $want_flash_vers = some-db-backed.lookup($hw_id, 'flash')

  # Update flash if necessary
  if $want_flash_vers != devlink-dev-info['stored']:
      $file = some-db-backed.download($hw_id, 'flash')
      devlink-dev-flash($file)

  # Find out the expected overall firmware versions
  $want_fw_vers = some-db-backed.lookup($hw_id, 'all')

  # Update on-disk file if necessary
  if $want_fw_vers != devlink-dev-info['running']:
      $file = some-db-backed.download($hw_id, 'disk')
      write($file, '/lib/firmware/')

  # Try device reset, if available
  if $want_fw_vers != devlink-dev-info['running']:
     devlink-reset()

  # Reboot, if reset wasn't enough
  if $want_fw_vers != devlink-dev-info['running']:
     reboot()

Note that each reference to ``devlink-dev-info`` in this pseudo-code
is expected to fetch up-to-date information from the kernel.

For the convenience of identifying firmware files some vendors add
``bundle_id`` information to the firmware versions. This meta-version covers
multiple per-component versions and can be used e.g. in firmware file names
(all component versions could get rather long.)


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

==============
Devlink Health
==============

Background
==========

The ``devlink`` health mechanism is targeted for Real Time Alerting, in
order to know when something bad happened to a PCI device.

  * Provide alert debug information.
  * Self healing.
  * If problem needs vendor support, provide a way to gather all needed
    debugging information.

Overview
========

The main idea is to unify and centralize driver health reports in the
generic ``devlink`` instance and allow the user to set different
attributes of the health reporting and recovery procedures.

The ``devlink`` health reporter:
Device driver creates a "health reporter" per each error/health type.
Error/Health type can be a known/generic (e.g. PCI error, fw error, rx/tx error)
or unknown (driver specific).
For each registered health reporter a driver can issue error/health reports
asynchronously. All health reports handling is done by ``devlink``.
Device driver can provide specific callbacks for each "health reporter", e.g.:

  * Recovery procedures
  * Diagnostics procedures
  * Object dump procedures
  * OOB initial parameters

Different parts of the driver can register different types of health reporters
with different handlers.

Actions
=======

Once an error is reported, devlink health will perform the following actions:

  * A log is being send to the kernel trace events buffer
  * Health status and statistics are being updated for the reporter instance
  * Object dump is being taken and saved at the reporter instance (as long as
    there is no other dump which is already stored)
  * Auto recovery attempt is being done. Depends on:

    - Auto-recovery configuration
    - Grace period vs. time passed since last recover

User Interface
==============

User can access/change each reporter's parameters and driver specific callbacks
via ``devlink``, e.g per error type (per health reporter):

  * Configure reporter's generic parameters (like: disable/enable auto recovery)
  * Invoke recovery procedure
  * Run diagnostics
  * Object dump

.. list-table:: List of devlink health interfaces
   :widths: 10 90

   * - Name
     - Description
   * - ``DEVLINK_CMD_HEALTH_REPORTER_GET``
     - Retrieves status and configuration info per DEV and reporter.
   * - ``DEVLINK_CMD_HEALTH_REPORTER_SET``
     - Allows reporter-related configuration setting.
   * - ``DEVLINK_CMD_HEALTH_REPORTER_RECOVER``
     - Triggers reporter's recovery procedure.
   * - ``DEVLINK_CMD_HEALTH_REPORTER_TEST``
     - Triggers a fake health event on the reporter. The effects of the test
       event in terms of recovery flow should follow closely that of a real
       event.
   * - ``DEVLINK_CMD_HEALTH_REPORTER_DIAGNOSE``
     - Retrieves current device state related to the reporter.
   * - ``DEVLINK_CMD_HEALTH_REPORTER_DUMP_GET``
     - Retrieves the last stored dump. Devlink health
       saves a single dump. If an dump is not already stored by devlink
       for this reporter, devlink generates a new dump.
       Dump output is defined by the reporter.
   * - ``DEVLINK_CMD_HEALTH_REPORTER_DUMP_CLEAR``
     - Clears the last saved dump file for the specified reporter.

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

                                                   netlink
                                          +--------------------------+
                                          |                          |
                                          |            +             |
                                          |            |             |
                                          +--------------------------+
                                                       |request for ops
                                                       |(diagnose,
      driver                               devlink     |recover,
                                                       |dump)
    +--------+                            +--------------------------+
    |        |                            |    reporter|             |
    |        |                            |  +---------v----------+  |
    |        |   ops execution            |  |                    |  |
    |     <----------------------------------+                    |  |
    |        |                            |  |                    |  |
    |        |                            |  + ^------------------+  |
    |        |                            |    | request for ops     |
    |        |                            |    | (recover, dump)     |
    |        |                            |    |                     |
    |        |                            |  +-+------------------+  |
    |        |     health report          |  | health handler     |  |
    |        +------------------------------->                    |  |
    |        |                            |  +--------------------+  |
    |        |     health reporter create |                          |
    |        +---------------------------->                          |
    +--------+                            +--------------------------+


code:
.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)

============
Devlink Info
============

The ``devlink-info`` mechanism enables device drivers to report device
(hardware and firmware) information in a standard, extensible fashion.

The original motivation for the ``devlink-info`` API was twofold:

 - making it possible to automate device and firmware management in a fleet
   of machines in a vendor-independent fashion (see also
   :ref:`Documentation/networking/devlink/devlink-flash.rst <devlink_flash>`);
 - name the per component FW versions (as opposed to the crowded ethtool
   version string).

``devlink-info`` supports reporting multiple types of objects. Reporting driver
versions is generally discouraged - here, and via any other Linux API.

.. list-table:: List of top level info objects
   :widths: 5 95

   * - Name
     - Description
   * - ``driver``
     - Name of the currently used device driver, also available through sysfs.

   * - ``serial_number``
     - Serial number of the device.

       This is usually the serial number of the ASIC, also often available
       in PCI config space of the device in the *Device Serial Number*
       capability.

       The serial number should be unique per physical device.
       Sometimes the serial number of the device is only 48 bits long (the
       length of the Ethernet MAC address), and since PCI DSN is 64 bits long
       devices pad or encode additional information into the serial number.
       One example is adding port ID or PCI interface ID in the extra two bytes.
       Drivers should make sure to strip or normalize any such padding
       or interface ID, and report only the part of the serial number
       which uniquely identifies the hardware. In other words serial number
       reported for two ports of the same device or on two hosts of
       a multi-host device should be identical.

   * - ``board.serial_number``
     - Board serial number of the device.

       This is usually the serial number of the board, often available in
       PCI *Vital Product Data*.

   * - ``fixed``
     - Group for hardware identifiers, and versions of components
       which are not field-updatable.

       Versions in this section identify the device design. For example,
       component identifiers or the board version reported in the PCI VPD.
       Data in ``devlink-info`` should be broken into the smallest logical
       components, e.g. PCI VPD may concatenate various information
       to form the Part Number string, while in ``devlink-info`` all parts
       should be reported as separate items.

       This group must not contain any frequently changing identifiers,
       such as serial numbers. See
       :ref:`Documentation/networking/devlink/devlink-flash.rst <devlink_flash>`
       to understand why.

   * - ``running``
     - Group for information about currently running software/firmware.
       These versions often only update after a reboot, sometimes device reset.

   * - ``stored``
     - Group for software/firmware versions in device flash.

       Stored values must update to reflect changes in the flash even
       if reboot has not yet occurred. If device is not capable of updating
       ``stored`` versions when new software is flashed, it must not report
       them.

Each version can be reported at most once in each version group. Firmware
components stored on the flash should feature in both the ``running`` and
``stored`` sections, if device is capable of reporting ``stored`` versions
(see :ref:`Documentation/networking/devlink/devlink-flash.rst <devlink_flash>`).
In case software/firmware components are loaded from the disk (e.g.
``/lib/firmware``) only the running version should be reported via
the kernel API.

Generic Versions
================

It is expected that drivers use the following generic names for exporting
version information. If a generic name for a given component doesn't exist yet,
driver authors should consult existing driver-specific versions and attempt
reuse. As last resort, if a component is truly unique, using driver-specific
names is allowed, but these should be documented in the driver-specific file.

All versions should try to use the following terminology:

.. list-table:: List of common version suffixes
   :widths: 10 90

   * - Name
     - Description
   * - ``id``, ``revision``
     - Identifiers of designs and revision, mostly used for hardware versions.

   * - ``api``
     - Version of API between components. API items are usually of limited
       value to the user, and can be inferred from other versions by the vendor,
       so adding API versions is generally discouraged as noise.

   * - ``bundle_id``
     - Identifier of a distribution package which was flashed onto the device.
       This is an attribute of a firmware package which covers multiple versions
       for ease of managing firmware images (see
       :ref:`Documentation/networking/devlink/devlink-flash.rst <devlink_flash>`).

       ``bundle_id`` can appear in both ``running`` and ``stored`` versions,
       but it must not be reported if any of the components covered by the
       ``bundle_id`` was changed and no longer matches the version from
       the bundle.

board.id
--------

Unique identifier of the board design.

board.rev
---------

Board design revision.

asic.id
-------

ASIC design identifier.

asic.rev
--------

ASIC design revision/stepping.

board.manufacture
-----------------

An identifier of the company or the facility which produced the part.

fw
--

Overall firmware version, often representing the collection of
fw.mgmt, fw.app, etc.

fw.mgmt
-------

Control unit firmware version. This firmware is responsible for house
keeping tasks, PHY control etc. but not the packet-by-packet data path
operation.

fw.mgmt.api
-----------

Firmware interface specification version of the software interfaces between
driver and firmware.

fw.app
------

Data path microcode controlling high-speed packet processing.

fw.undi
-------

UNDI software, may include the UEFI driver, firmware or both.

fw.ncsi
-------

Version of the software responsible for supporting/handling the
Network Controller Sideband Interface.

fw.psid
-------

Unique identifier of the firmware parameter set. These are usually
parameters of a particular board, defined at manufacturing time.

fw.roce
-------

RoCE firmware version which is responsible for handling roce
management.

fw.bundle_id
------------

Unique identifier of the entire firmware bundle.

fw.bootloader
-------------

Version of the bootloader.

Future work
===========

The following extensions could be useful:

 - on-disk firmware file names - drivers list the file names of firmware they
   may need to load onto devices via the ``MODULE_FIRMWARE()`` macro. These,
   however, are per module, rather than per device. It'd be useful to list
   the names of firmware files the driver will try to load for a given device,
   in order of priority.


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

=================
Devlink Line card
=================

Background
==========

The ``devlink-linecard`` mechanism is targeted for manipulation of
line cards that serve as a detachable PHY modules for modular switch
system. Following operations are provided:

  * Get a list of supported line card types.
  * Provision of a slot with specific line card type.
  * Get and monitor of line card state and its change.

Line card according to the type may contain one or more gearboxes
to mux the lanes with certain speed to multiple ports with lanes
of different speed. Line card ensures N:M mapping between
the switch ASIC modules and physical front panel ports.

Overview
========

Each line card devlink object is created by device driver,
according to the physical line card slots available on the device.

Similar to splitter cable, where the device might have no way
of detection of the splitter cable geometry, the device
might not have a way to detect line card type. For that devices,
concept of provisioning is introduced. It allows the user to:

  * Provision a line card slot with certain line card type

    - Device driver would instruct the ASIC to prepare all
      resources accordingly. The device driver would
      create all instances, namely devlink port and netdevices
      that reside on the line card, according to the line card type
  * Manipulate of line card entities even without line card
    being physically connected or powered-up
  * Setup splitter cable on line card ports

    - As on the ordinary ports, user may provision a splitter
      cable of a certain type, without the need to
      be physically connected to the port
  * Configure devlink ports and netdevices

Netdevice carrier is decided as follows:

  * Line card is not inserted or powered-down

    - The carrier is always down
  * Line card is inserted and powered up

    - The carrier is decided as for ordinary port netdevice

Line card state
===============

The ``devlink-linecard`` mechanism supports the following line card states:

  * ``unprovisioned``: Line card is not provisioned on the slot.
  * ``unprovisioning``: Line card slot is currently being unprovisioned.
  * ``provisioning``: Line card slot is currently in a process of being provisioned
    with a line card type.
  * ``provisioning_failed``: Provisioning was not successful.
  * ``provisioned``: Line card slot is provisioned with a type.
  * ``active``: Line card is powered-up and active.

The following diagram provides a general overview of ``devlink-linecard``
state transitions::

                                          +-------------------------+
                                          |                         |
       +---------------------------------->      unprovisioned      |
       |                                  |                         |
       |                                  +--------|-------^--------+
       |                                           |       |
       |                                           |       |
       |                                  +--------v-------|--------+
       |                                  |                         |
       |                                  |       provisioning      |
       |                                  |                         |
       |                                  +------------|------------+
       |                                               |
       |                 +-----------------------------+
       |                 |                             |
       |    +------------v------------+   +------------v------------+   +-------------------------+
       |    |                         |   |                         ---->                         |
       +-----   provisioning_failed   |   |       provisioned       |   |         active          |
       |    |                         |   |                         <----                         |
       |    +------------^------------+   +------------|------------+   +-------------------------+
       |                 |                             |
       |                 |                             |
       |                 |                +------------v------------+
       |                 |                |                         |
       |                 |                |     unprovisioning      |
       |                 |                |                         |
       |                 |                +------------|------------+
       |                 |                             |
       |                 +-----------------------------+
       |                                               |
       +-----------------------------------------------+

Example usage
=============

.. code:: shell

    $ devlink lc show [ DEV [ lc LC_INDEX ] ]
    $ devlink lc set DEV lc LC_INDEX [ { type LC_TYPE | notype } ]

    # Show current line card configuration and status for all slots:
    $ devlink lc

    # Set slot 8 to be provisioned with type "16x100G":
    $ devlink lc set pci/0000:01:00.0 lc 8 type 16x100G

    # Set slot 8 to be unprovisioned:
    $ devlink lc set pci/0000:01:00.0 lc 8 notype


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

==============
Devlink Params
==============

``devlink`` provides capability for a driver to expose device parameters for low
level device functionality. Since devlink can operate at the device-wide
level, it can be used to provide configuration that may affect multiple
ports on a single device.

This document describes a number of generic parameters that are supported
across multiple drivers. Each driver is also free to add their own
parameters. Each driver must document the specific parameters they support,
whether generic or not.

Configuration modes
===================

Parameters may be set in different configuration modes.

.. list-table:: Possible configuration modes
   :widths: 5 90

   * - Name
     - Description
   * - ``runtime``
     - set while the driver is running, and takes effect immediately. No
       reset is required.
   * - ``driverinit``
     - applied while the driver initializes. Requires the user to restart
       the driver using the ``devlink`` reload command.
   * - ``permanent``
     - written to the device's non-volatile memory. A hard reset is required
       for it to take effect.

Reloading
---------

In order for ``driverinit`` parameters to take effect, the driver must
support reloading via the ``devlink-reload`` command. This command will
request a reload of the device driver.

.. _devlink_params_generic:

Generic configuration parameters
================================
The following is a list of generic configuration parameters that drivers may
add. Use of generic parameters is preferred over each driver creating their
own name.

.. list-table:: List of generic parameters
   :widths: 5 5 90

   * - Name
     - Type
     - Description
   * - ``enable_sriov``
     - Boolean
     - Enable Single Root I/O Virtualization (SRIOV) in the device.
   * - ``ignore_ari``
     - Boolean
     - Ignore Alternative Routing-ID Interpretation (ARI) capability. If
       enabled, the adapter will ignore ARI capability even when the
       platform has support enabled. The device will create the same number
       of partitions as when the platform does not support ARI.
   * - ``msix_vec_per_pf_max``
     - u32
     - Provides the maximum number of MSI-X interrupts that a device can
       create. Value is the same across all physical functions (PFs) in the
       device.
   * - ``msix_vec_per_pf_min``
     - u32
     - Provides the minimum number of MSI-X interrupts required for the
       device to initialize. Value is the same across all physical functions
       (PFs) in the device.
   * - ``fw_load_policy``
     - u8
     - Control the device's firmware loading policy.
        - ``DEVLINK_PARAM_FW_LOAD_POLICY_VALUE_DRIVER`` (0)
          Load firmware version preferred by the driver.
        - ``DEVLINK_PARAM_FW_LOAD_POLICY_VALUE_FLASH`` (1)
          Load firmware currently stored in flash.
        - ``DEVLINK_PARAM_FW_LOAD_POLICY_VALUE_DISK`` (2)
          Load firmware currently available on host's disk.
   * - ``reset_dev_on_drv_probe``
     - u8
     - Controls the device's reset policy on driver probe.
        - ``DEVLINK_PARAM_RESET_DEV_ON_DRV_PROBE_VALUE_UNKNOWN`` (0)
          Unknown or invalid value.
        - ``DEVLINK_PARAM_RESET_DEV_ON_DRV_PROBE_VALUE_ALWAYS`` (1)
          Always reset device on driver probe.
        - ``DEVLINK_PARAM_RESET_DEV_ON_DRV_PROBE_VALUE_NEVER`` (2)
          Never reset device on driver probe.
        - ``DEVLINK_PARAM_RESET_DEV_ON_DRV_PROBE_VALUE_DISK`` (3)
          Reset the device only if firmware can be found in the filesystem.
   * - ``enable_roce``
     - Boolean
     - Enable handling of RoCE traffic in the device.
   * - ``enable_eth``
     - Boolean
     - When enabled, the device driver will instantiate Ethernet specific
       auxiliary device of the devlink device.
   * - ``enable_rdma``
     - Boolean
     - When enabled, the device driver will instantiate RDMA specific
       auxiliary device of the devlink device.
   * - ``enable_vnet``
     - Boolean
     - When enabled, the device driver will instantiate VDPA networking
       specific auxiliary device of the devlink device.
   * - ``enable_iwarp``
     - Boolean
     - Enable handling of iWARP traffic in the device.
   * - ``internal_err_reset``
     - Boolean
     - When enabled, the device driver will reset the device on internal
       errors.
   * - ``max_macs``
     - u32
     - Typically macvlan, vlan net devices mac are also programmed in their
       parent netdevice's Function rx filter. This parameter limit the
       maximum number of unicast mac address filters to receive traffic from
       per ethernet port of this device.
   * - ``region_snapshot_enable``
     - Boolean
     - Enable capture of ``devlink-region`` snapshots.
   * - ``enable_remote_dev_reset``
     - Boolean
     - Enable device reset by remote host. When cleared, the device driver
       will NACK any attempt of other host to reset the device. This parameter
       is useful for setups where a device is shared by different hosts, such
       as multi-host setup.
   * - ``io_eq_size``
     - u32
     - Control the size of I/O completion EQs.
   * - ``event_eq_size``
     - u32
     - Control the size of asynchronous control events EQ.


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

.. _devlink_port:

============
Devlink Port
============

``devlink-port`` is a port that exists on the device. It has a logically
separate ingress/egress point of the device. A devlink port can be any one
of many flavours. A devlink port flavour along with port attributes
describe what a port represents.

A device driver that intends to publish a devlink port sets the
devlink port attributes and registers the devlink port.

Devlink port flavours are described below.

.. list-table:: List of devlink port flavours
   :widths: 33 90

   * - Flavour
     - Description
   * - ``DEVLINK_PORT_FLAVOUR_PHYSICAL``
     - Any kind of physical port. This can be an eswitch physical port or any
       other physical port on the device.
   * - ``DEVLINK_PORT_FLAVOUR_DSA``
     - This indicates a DSA interconnect port.
   * - ``DEVLINK_PORT_FLAVOUR_CPU``
     - This indicates a CPU port applicable only to DSA.
   * - ``DEVLINK_PORT_FLAVOUR_PCI_PF``
     - This indicates an eswitch port representing a port of PCI
       physical function (PF).
   * - ``DEVLINK_PORT_FLAVOUR_PCI_VF``
     - This indicates an eswitch port representing a port of PCI
       virtual function (VF).
   * - ``DEVLINK_PORT_FLAVOUR_PCI_SF``
     - This indicates an eswitch port representing a port of PCI
       subfunction (SF).
   * - ``DEVLINK_PORT_FLAVOUR_VIRTUAL``
     - This indicates a virtual port for the PCI virtual function.

Devlink port can have a different type based on the link layer described below.

.. list-table:: List of devlink port types
   :widths: 23 90

   * - Type
     - Description
   * - ``DEVLINK_PORT_TYPE_ETH``
     - Driver should set this port type when a link layer of the port is
       Ethernet.
   * - ``DEVLINK_PORT_TYPE_IB``
     - Driver should set this port type when a link layer of the port is
       InfiniBand.
   * - ``DEVLINK_PORT_TYPE_AUTO``
     - This type is indicated by the user when driver should detect the port
       type automatically.

PCI controllers
---------------
In most cases a PCI device has only one controller. A controller consists of
potentially multiple physical, virtual functions and subfunctions. A function
consists of one or more ports. This port is represented by the devlink eswitch
port.

A PCI device connected to multiple CPUs or multiple PCI root complexes or a
SmartNIC, however, may have multiple controllers. For a device with multiple
controllers, each controller is distinguished by a unique controller number.
An eswitch is on the PCI device which supports ports of multiple controllers.

An example view of a system with two controllers::

                 ---------------------------------------------------------
                 |                                                       |
                 |           --------- ---------         ------- ------- |
    -----------  |           | vf(s) | | sf(s) |         |vf(s)| |sf(s)| |
    | server  |  | -------   ----/---- ---/----- ------- ---/--- ---/--- |
    | pci rc  |=== | pf0 |______/________/       | pf1 |___/_______/     |
    | connect |  | -------                       -------                 |
    -----------  |     | controller_num=1 (no eswitch)                   |
                 ------|--------------------------------------------------
                 (internal wire)
                       |
                 ---------------------------------------------------------
                 | devlink eswitch ports and reps                        |
                 | ----------------------------------------------------- |
                 | |ctrl-0 | ctrl-0 | ctrl-0 | ctrl-0 | ctrl-0 |ctrl-0 | |
                 | |pf0    | pf0vfN | pf0sfN | pf1    | pf1vfN |pf1sfN | |
                 | ----------------------------------------------------- |
                 | |ctrl-1 | ctrl-1 | ctrl-1 | ctrl-1 | ctrl-1 |ctrl-1 | |
                 | |pf0    | pf0vfN | pf0sfN | pf1    | pf1vfN |pf1sfN | |
                 | ----------------------------------------------------- |
                 |                                                       |
                 |                                                       |
    -----------  |           --------- ---------         ------- ------- |
    | smartNIC|  |           | vf(s) | | sf(s) |         |vf(s)| |sf(s)| |
    | pci rc  |==| -------   ----/---- ---/----- ------- ---/--- ---/--- |
    | connect |  | | pf0 |______/________/       | pf1 |___/_______/     |
    -----------  | -------                       -------                 |
                 |                                                       |
                 |  local controller_num=0 (eswitch)                     |
                 ---------------------------------------------------------

In the above example, the external controller (identified by controller number = 1)
doesn't have the eswitch. Local controller (identified by controller number = 0)
has the eswitch. The Devlink instance on the local controller has eswitch
devlink ports for both the controllers.

Function configuration
======================

Users can configure one or more function attributes before enumerating the PCI
function. Usually it means, user should configure function attribute
before a bus specific device for the function is created. However, when
SRIOV is enabled, virtual function devices are created on the PCI bus.
Hence, function attribute should be configured before binding virtual
function device to the driver. For subfunctions, this means user should
configure port function attribute before activating the port function.

A user may set the hardware address of the function using
`devlink port function set hw_addr` command. For Ethernet port function
this means a MAC address.

Users may also set the RoCE capability of the function using
`devlink port function set roce` command.

Users may also set the function as migratable using
'devlink port function set migratable' command.

Function attributes
===================

MAC address setup
-----------------
The configured MAC address of the PCI VF/SF will be used by netdevice and rdma
device created for the PCI VF/SF.

- Get the MAC address of the VF identified by its unique devlink port index::

    $ devlink port show pci/0000:06:00.0/2
    pci/0000:06:00.0/2: type eth netdev enp6s0pf0vf1 flavour pcivf pfnum 0 vfnum 1
      function:
        hw_addr 00:00:00:00:00:00

- Set the MAC address of the VF identified by its unique devlink port index::

    $ devlink port function set pci/0000:06:00.0/2 hw_addr 00:11:22:33:44:55

    $ devlink port show pci/0000:06:00.0/2
    pci/0000:06:00.0/2: type eth netdev enp6s0pf0vf1 flavour pcivf pfnum 0 vfnum 1
      function:
        hw_addr 00:11:22:33:44:55

- Get the MAC address of the SF identified by its unique devlink port index::

    $ devlink port show pci/0000:06:00.0/32768
    pci/0000:06:00.0/32768: type eth netdev enp6s0pf0sf88 flavour pcisf pfnum 0 sfnum 88
      function:
        hw_addr 00:00:00:00:00:00

- Set the MAC address of the SF identified by its unique devlink port index::

    $ devlink port function set pci/0000:06:00.0/32768 hw_addr 00:00:00:00:88:88

    $ devlink port show pci/0000:06:00.0/32768
    pci/0000:06:00.0/32768: type eth netdev enp6s0pf0sf88 flavour pcisf pfnum 0 sfnum 88
      function:
        hw_addr 00:00:00:00:88:88

RoCE capability setup
---------------------
Not all PCI VFs/SFs require RoCE capability.

When RoCE capability is disabled, it saves system memory per PCI VF/SF.

When user disables RoCE capability for a VF/SF, user application cannot send or
receive any RoCE packets through this VF/SF and RoCE GID table for this PCI
will be empty.

When RoCE capability is disabled in the device using port function attribute,
VF/SF driver cannot override it.

- Get RoCE capability of the VF device::

    $ devlink port show pci/0000:06:00.0/2
    pci/0000:06:00.0/2: type eth netdev enp6s0pf0vf1 flavour pcivf pfnum 0 vfnum 1
        function:
            hw_addr 00:00:00:00:00:00 roce enable

- Set RoCE capability of the VF device::

    $ devlink port function set pci/0000:06:00.0/2 roce disable

    $ devlink port show pci/0000:06:00.0/2
    pci/0000:06:00.0/2: type eth netdev enp6s0pf0vf1 flavour pcivf pfnum 0 vfnum 1
        function:
            hw_addr 00:00:00:00:00:00 roce disable

migratable capability setup
---------------------------
Live migration is the process of transferring a live virtual machine
from one physical host to another without disrupting its normal
operation.

User who want PCI VFs to be able to perform live migration need to
explicitly enable the VF migratable capability.

When user enables migratable capability for a VF, and the HV binds the VF to VFIO driver
with migration support, the user can migrate the VM with this VF from one HV to a
different one.

However, when migratable capability is enable, device will disable features which cannot
be migrated. Thus migratable cap can impose limitations on a VF so let the user decide.

Example of LM with migratable function configuration:
- Get migratable capability of the VF device::

    $ devlink port show pci/0000:06:00.0/2
    pci/0000:06:00.0/2: type eth netdev enp6s0pf0vf1 flavour pcivf pfnum 0 vfnum 1
        function:
            hw_addr 00:00:00:00:00:00 migratable disable

- Set migratable capability of the VF device::

    $ devlink port function set pci/0000:06:00.0/2 migratable enable

    $ devlink port show pci/0000:06:00.0/2
    pci/0000:06:00.0/2: type eth netdev enp6s0pf0vf1 flavour pcivf pfnum 0 vfnum 1
        function:
            hw_addr 00:00:00:00:00:00 migratable enable

- Bind VF to VFIO driver with migration support::

    $ echo <pci_id> > /sys/bus/pci/devices/0000:08:00.0/driver/unbind
    $ echo mlx5_vfio_pci > /sys/bus/pci/devices/0000:08:00.0/driver_override
    $ echo <pci_id> > /sys/bus/pci/devices/0000:08:00.0/driver/bind

Attach VF to the VM.
Start the VM.
Perform live migration.

Subfunction
============

Subfunction is a lightweight function that has a parent PCI function on which
it is deployed. Subfunction is created and deployed in unit of 1. Unlike
SRIOV VFs, a subfunction doesn't require its own PCI virtual function.
A subfunction communicates with the hardware through the parent PCI function.

To use a subfunction, 3 steps setup sequence is followed:

1) create - create a subfunction;
2) configure - configure subfunction attributes;
3) deploy - deploy the subfunction;

Subfunction management is done using devlink port user interface.
User performs setup on the subfunction management device.

(1) Create
----------
A subfunction is created using a devlink port interface. A user adds the
subfunction by adding a devlink port of subfunction flavour. The devlink
kernel code calls down to subfunction management driver (devlink ops) and asks
it to create a subfunction devlink port. Driver then instantiates the
subfunction port and any associated objects such as health reporters and
representor netdevice.

(2) Configure
-------------
A subfunction devlink port is created but it is not active yet. That means the
entities are created on devlink side, the e-switch port representor is created,
but the subfunction device itself is not created. A user might use e-switch port
representor to do settings, putting it into bridge, adding TC rules, etc. A user
might as well configure the hardware address (such as MAC address) of the
subfunction while subfunction is inactive.

(3) Deploy
----------
Once a subfunction is configured, user must activate it to use it. Upon
activation, subfunction management driver asks the subfunction management
device to instantiate the subfunction device on particular PCI function.
A subfunction device is created on the :ref:`Documentation/driver-api/auxiliary_bus.rst <auxiliary_bus>`.
At this point a matching subfunction driver binds to the subfunction's auxiliary device.

Rate object management
======================

Devlink provides API to manage tx rates of single devlink port or a group.
This is done through rate objects, which can be one of the two types:

``leaf``
  Represents a single devlink port; created/destroyed by the driver. Since leaf
  have 1to1 mapping to its devlink port, in user space it is referred as
  ``pci/<bus_addr>/<port_index>``;

``node``
  Represents a group of rate objects (leafs and/or nodes); created/deleted by
  request from the userspace; initially empty (no rate objects added). In
  userspace it is referred as ``pci/<bus_addr>/<node_name>``, where
  ``node_name`` can be any identifier, except decimal number, to avoid
  collisions with leafs.

API allows to configure following rate object's parameters:

``tx_share``
  Minimum TX rate value shared among all other rate objects, or rate objects
  that parts of the parent group, if it is a part of the same group.

``tx_max``
  Maximum TX rate value.

``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. The higher the
  priority the higher the probability that the node will get selected for
  scheduling.

``tx_weight``
  Allows for usage of Weighted Fair Queuing arbitration scheme among
  siblings. This arbitration scheme can be used simultaneously with the
  strict priority. As a node is configured with a higher rate it gets more
  BW relative to it's siblings. Values are relative like a percentage
  points, they basically tell how much BW should node take relative to
  it's siblings.

``parent``
  Parent node name. Parent node rate limits are considered as additional limits
  to all node children limits. ``tx_max`` is an upper limit for children.
  ``tx_share`` is a total bandwidth distributed among children.

``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.

Arbitration flow from the high level:

#. Choose a node, or group of nodes with the highest priority that stays
   within the BW limit and are not blocked. Use ``tx_priority`` as a
   parameter for this arbitration.

#. If group of nodes have the same priority perform WFQ arbitration on
   that subgroup. Use ``tx_weight`` as a parameter for this arbitration.

#. Select the winner node, and continue arbitration flow among it's children,
   until leaf node is reached, and the winner is established.

#. If all the nodes from the highest priority sub-group are satisfied, or
   overused their assigned BW, move to the lower priority nodes.

Driver implementations are allowed to support both or either rate object types
and setting methods of their parameters. Additionally driver implementation
may export nodes/leafs and their child-parent relationships.

Terms and Definitions
=====================

.. list-table:: Terms and Definitions
   :widths: 22 90

   * - Term
     - Definitions
   * - ``PCI device``
     - A physical PCI device having one or more PCI buses consists of one or
       more PCI controllers.
   * - ``PCI controller``
     -  A controller consists of potentially multiple physical functions,
        virtual functions and subfunctions.
   * - ``Port function``
     -  An object to manage the function of a port.
   * - ``Subfunction``
     -  A lightweight function that has parent PCI function on which it is
        deployed.
   * - ``Subfunction device``
     -  A bus device of the subfunction, usually on a auxiliary bus.
   * - ``Subfunction driver``
     -  A device driver for the subfunction auxiliary device.
   * - ``Subfunction management device``
     -  A PCI physical function that supports subfunction management.
   * - ``Subfunction management driver``
     -  A device driver for PCI physical function that supports
        subfunction management using devlink port interface.
   * - ``Subfunction host driver``
     -  A device driver for PCI physical function that hosts subfunction
        devices. In most cases it is same as subfunction management driver. When
        subfunction is used on external controller, subfunction management and
        host drivers are different.


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

==============
Devlink Region
==============

``devlink`` regions enable access to driver defined address regions using
devlink.

Each device can create and register its own supported address regions. The
region can then be accessed via the devlink region interface.

Region snapshots are collected by the driver, and can be accessed via read
or dump commands. This allows future analysis on the created snapshots.
Regions may optionally support triggering snapshots on demand.

Snapshot identifiers are scoped to the devlink instance, not a region.
All snapshots with the same snapshot id within a devlink instance
correspond to the same event.

The major benefit to creating a region is to provide access to internal
address regions that are otherwise inaccessible to the user.

Regions may also be used to provide an additional way to debug complex error
states, but see also Documentation/networking/devlink/devlink-health.rst

Regions may optionally support capturing a snapshot on demand via the
``DEVLINK_CMD_REGION_NEW`` netlink message. A driver wishing to allow
requested snapshots must implement the ``.snapshot`` callback for the region
in its ``devlink_region_ops`` structure. If snapshot id is not set in
the ``DEVLINK_CMD_REGION_NEW`` request kernel will allocate one and send
the snapshot information to user space.

Regions may optionally allow directly reading from their contents without a
snapshot. Direct read requests are not atomic. In particular a read request
of size 256 bytes or larger will be split into multiple chunks. If atomic
access is required, use a snapshot. A driver wishing to enable this for a
region should implement the ``.read`` callback in the ``devlink_region_ops``
structure. User space can request a direct read by using the
``DEVLINK_ATTR_REGION_DIRECT`` attribute instead of specifying a snapshot
id.

example usage
-------------

.. code:: shell

    $ devlink region help
    $ devlink region show [ DEV/REGION ]
    $ devlink region del DEV/REGION snapshot SNAPSHOT_ID
    $ devlink region dump DEV/REGION [ snapshot SNAPSHOT_ID ]
    $ devlink region read DEV/REGION [ snapshot SNAPSHOT_ID ] address ADDRESS length length

    # Show all of the exposed regions with region sizes:
    $ devlink region show
    pci/0000:00:05.0/cr-space: size 1048576 snapshot [1 2] max 8
    pci/0000:00:05.0/fw-health: size 64 snapshot [1 2] max 8

    # Delete a snapshot using:
    $ devlink region del pci/0000:00:05.0/cr-space snapshot 1

    # Request an immediate snapshot, if supported by the region
    $ devlink region new pci/0000:00:05.0/cr-space
    pci/0000:00:05.0/cr-space: snapshot 5

    # Dump a snapshot:
    $ devlink region dump pci/0000:00:05.0/fw-health 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

    # Read a specific part of a snapshot:
    $ devlink region read pci/0000:00:05.0/fw-health snapshot 1 address 0 length 16
    0000000000000000 0014 95dc 0014 9514 0035 1670 0034 db30

    # Read from the region without a snapshot
    $ devlink region read pci/0000:00:05.0/fw-health address 16 length 16
    0000000000000010 0000 0000 ffff ff04 0029 8c00 0028 8cc8

As regions are likely very device or driver specific, no generic regions are
defined. See the driver-specific documentation files for information on the
specific regions a driver supports.


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

==============
Devlink Reload
==============

``devlink-reload`` provides mechanism to reinit driver entities, applying
``devlink-params`` and ``devlink-resources`` new values. It also provides
mechanism to activate firmware.

Reload Actions
==============

User may select a reload action.
By default ``driver_reinit`` action is selected.

.. list-table:: Possible reload actions
   :widths: 5 90

   * - Name
     - Description
   * - ``driver-reinit``
     - Devlink driver entities re-initialization, including applying
       new values to devlink entities which are used during driver
       load such as ``devlink-params`` in configuration mode
       ``driverinit`` or ``devlink-resources``
   * - ``fw_activate``
     - Firmware activate. Activates new firmware if such image is stored and
       pending activation. If no limitation specified this action may involve
       firmware reset. If no new image pending this action will reload current
       firmware image.

Note that even though user asks for a specific action, the driver
implementation might require to perform another action alongside with
it. For example, some driver do not support driver reinitialization
being performed without fw activation. Therefore, the devlink reload
command returns the list of actions which were actrually performed.

Reload Limits
=============

By default reload actions are not limited and driver implementation may
include reset or downtime as needed to perform the actions.

However, some drivers support action limits, which limit the action
implementation to specific constraints.

.. list-table:: Possible reload limits
   :widths: 5 90

   * - Name
     - Description
   * - ``no_reset``
     - No reset allowed, no down time allowed, no link flap and no
       configuration is lost.

Change Namespace
================

The netns option allows user to be able to move devlink instances into
namespaces during devlink reload operation.
By default all devlink instances are created in init_net and stay there.

example usage
-------------

.. code:: shell

    $ devlink dev reload help
    $ devlink dev reload DEV [ netns { PID | NAME | ID } ] [ action { driver_reinit | fw_activate } ] [ limit no_reset ]

    # Run reload command for devlink driver entities re-initialization:
    $ devlink dev reload pci/0000:82:00.0 action driver_reinit
    reload_actions_performed:
      driver_reinit

    # Run reload command to activate firmware:
    # Note that mlx5 driver reloads the driver while activating firmware
    $ devlink dev reload pci/0000:82:00.0 action fw_activate
    reload_actions_performed:
      driver_reinit fw_activate


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

================
Devlink Resource
================

``devlink`` provides the ability for drivers to register resources, which
can allow administrators to see the device restrictions for a given
resource, as well as how much of the given resource is currently
in use. Additionally, these resources can optionally have configurable size.
This could enable the administrator to limit the number of resources that
are used.

For example, the ``netdevsim`` driver enables ``/IPv4/fib`` and
``/IPv4/fib-rules`` as resources to limit the number of IPv4 FIB entries and
rules for a given device.

Resource Ids
============

Each resource is represented by an id, and contains information about its
current size and related sub resources. To access a sub resource, you
specify the path of the resource. For example ``/IPv4/fib`` is the id for
the ``fib`` sub-resource under the ``IPv4`` resource.

Generic Resources
=================

Generic resources are used to describe resources that can be shared by multiple
device drivers and their description must be added to the following table:

.. list-table:: List of Generic Resources
   :widths: 10 90

   * - Name
     - Description
   * - ``physical_ports``
     - A limited capacity of physical ports that the switch ASIC can support

example usage
-------------

The resources exposed by the driver can be observed, for example:

.. code:: shell

    $devlink resource show pci/0000:03:00.0
    pci/0000:03:00.0:
      name kvd size 245760 unit entry
        resources:
          name linear size 98304 occ 0 unit entry size_min 0 size_max 147456 size_gran 128
          name hash_double size 60416 unit entry size_min 32768 size_max 180224 size_gran 128
          name hash_single size 87040 unit entry size_min 65536 size_max 212992 size_gran 128

Some resource's size can be changed. Examples:

.. code:: shell

    $devlink resource set pci/0000:03:00.0 path /kvd/hash_single size 73088
    $devlink resource set pci/0000:03:00.0 path /kvd/hash_double size 74368

The changes do not apply immediately, this can be validated by the 'size_new'
attribute, which represents the pending change in size. For example:

.. code:: shell

    $devlink resource show pci/0000:03:00.0
    pci/0000:03:00.0:
      name kvd size 245760 unit entry size_valid false
      resources:
        name linear size 98304 size_new 147456 occ 0 unit entry size_min 0 size_max 147456 size_gran 128
        name hash_double size 60416 unit entry size_min 32768 size_max 180224 size_gran 128
        name hash_single size 87040 unit entry size_min 65536 size_max 212992 size_gran 128

Note that changes in resource size may require a device reload to properly
take effect.


code:
.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)

=================
Devlink Selftests
=================

The ``devlink-selftests`` API allows executing selftests on the device.

Tests Mask
==========
The ``devlink-selftests`` command should be run with a mask indicating
the tests to be executed.

Tests Description
=================
The following is a list of tests that drivers may execute.

.. list-table:: List of tests
   :widths: 5 90

   * - Name
     - Description
   * - ``DEVLINK_SELFTEST_FLASH``
     - Devices may have the firmware on non-volatile memory on the board, e.g.
       flash. This particular test helps to run a flash selftest on the device.
       Implementation of the test is left to the driver/firmware.

example usage
-------------

.. code:: shell

    # Query selftests supported on the devlink device
    $ devlink dev selftests show DEV
    # Query selftests supported on all devlink devices
    $ devlink dev selftests show
    # Executes selftests on the device
    $ devlink dev selftests run DEV id flash