* [PATCH 01/17] devlink: add macro for "fw.psid"
2020-01-09 22:46 [PATCH 00/17] devlink documentation refactor Jacob Keller
@ 2020-01-09 22:46 ` Jacob Keller
2020-01-09 22:46 ` [PATCH 02/17] devlink: move devlink documentation to subfolder Jacob Keller
` (16 subsequent siblings)
17 siblings, 0 replies; 22+ messages in thread
From: Jacob Keller @ 2020-01-09 22:46 UTC (permalink / raw)
To: netdev; +Cc: Jiri Pirko, Jacob Keller
The "fw.psid" devlink info version is documented in devlink-info.rst,
and used by one driver. However, there is no associated macro for this
firmware version like there is for others. Add one now.
Signed-off-by: Jacob Keller <jacob.e.keller@intel.com>
---
include/net/devlink.h | 2 ++
1 file changed, 2 insertions(+)
diff --git a/include/net/devlink.h b/include/net/devlink.h
index fd59214c1264..55fc1e0e6513 100644
--- a/include/net/devlink.h
+++ b/include/net/devlink.h
@@ -485,6 +485,8 @@ enum devlink_param_generic_id {
#define DEVLINK_INFO_VERSION_GENERIC_FW_UNDI "fw.undi"
/* NCSI support/handler version */
#define DEVLINK_INFO_VERSION_GENERIC_FW_NCSI "fw.ncsi"
+/* FW parameter set id */
+#define DEVLINK_INFO_VERSION_GENERIC_FW_PSID "fw.psid"
struct devlink_region;
struct devlink_info_req;
--
2.25.0.rc1
^ permalink raw reply related [flat|nested] 22+ messages in thread* [PATCH 02/17] devlink: move devlink documentation to subfolder
2020-01-09 22:46 [PATCH 00/17] devlink documentation refactor Jacob Keller
2020-01-09 22:46 ` [PATCH 01/17] devlink: add macro for "fw.psid" Jacob Keller
@ 2020-01-09 22:46 ` Jacob Keller
2020-01-09 22:46 ` [PATCH 03/17] devlink: convert devlink-health.txt to rst format Jacob Keller
` (15 subsequent siblings)
17 siblings, 0 replies; 22+ messages in thread
From: Jacob Keller @ 2020-01-09 22:46 UTC (permalink / raw)
To: netdev; +Cc: Jiri Pirko, Jacob Keller
Combine the documentation for devlink into a subfolder, and provide an
index.rst file that can be used to generally describe devlink.
Signed-off-by: Jacob Keller <jacob.e.keller@intel.com>
---
.../networking/{ => devlink}/devlink-health.txt | 0
.../{ => devlink}/devlink-info-versions.rst | 0
.../{ => devlink}/devlink-params-bnxt.txt | 0
.../{ => devlink}/devlink-params-mlx5.txt | 0
.../{ => devlink}/devlink-params-mlxsw.txt | 0
.../{ => devlink}/devlink-params-mv88e6xxx.txt | 0
.../{ => devlink}/devlink-params-nfp.txt | 0
.../devlink-params-ti-cpsw-switch.txt | 0
.../networking/{ => devlink}/devlink-params.txt | 0
.../{ => devlink}/devlink-trap-netdevsim.rst | 0
.../networking/{ => devlink}/devlink-trap.rst | 0
Documentation/networking/devlink/index.rst | 14 ++++++++++++++
Documentation/networking/index.rst | 4 +---
MAINTAINERS | 1 +
drivers/net/netdevsim/dev.c | 2 +-
include/net/devlink.h | 4 ++--
16 files changed, 19 insertions(+), 6 deletions(-)
rename Documentation/networking/{ => devlink}/devlink-health.txt (100%)
rename Documentation/networking/{ => devlink}/devlink-info-versions.rst (100%)
rename Documentation/networking/{ => devlink}/devlink-params-bnxt.txt (100%)
rename Documentation/networking/{ => devlink}/devlink-params-mlx5.txt (100%)
rename Documentation/networking/{ => devlink}/devlink-params-mlxsw.txt (100%)
rename Documentation/networking/{ => devlink}/devlink-params-mv88e6xxx.txt (100%)
rename Documentation/networking/{ => devlink}/devlink-params-nfp.txt (100%)
rename Documentation/networking/{ => devlink}/devlink-params-ti-cpsw-switch.txt (100%)
rename Documentation/networking/{ => devlink}/devlink-params.txt (100%)
rename Documentation/networking/{ => devlink}/devlink-trap-netdevsim.rst (100%)
rename Documentation/networking/{ => devlink}/devlink-trap.rst (100%)
create mode 100644 Documentation/networking/devlink/index.rst
diff --git a/Documentation/networking/devlink-health.txt b/Documentation/networking/devlink/devlink-health.txt
similarity index 100%
rename from Documentation/networking/devlink-health.txt
rename to Documentation/networking/devlink/devlink-health.txt
diff --git a/Documentation/networking/devlink-info-versions.rst b/Documentation/networking/devlink/devlink-info-versions.rst
similarity index 100%
rename from Documentation/networking/devlink-info-versions.rst
rename to Documentation/networking/devlink/devlink-info-versions.rst
diff --git a/Documentation/networking/devlink-params-bnxt.txt b/Documentation/networking/devlink/devlink-params-bnxt.txt
similarity index 100%
rename from Documentation/networking/devlink-params-bnxt.txt
rename to Documentation/networking/devlink/devlink-params-bnxt.txt
diff --git a/Documentation/networking/devlink-params-mlx5.txt b/Documentation/networking/devlink/devlink-params-mlx5.txt
similarity index 100%
rename from Documentation/networking/devlink-params-mlx5.txt
rename to Documentation/networking/devlink/devlink-params-mlx5.txt
diff --git a/Documentation/networking/devlink-params-mlxsw.txt b/Documentation/networking/devlink/devlink-params-mlxsw.txt
similarity index 100%
rename from Documentation/networking/devlink-params-mlxsw.txt
rename to Documentation/networking/devlink/devlink-params-mlxsw.txt
diff --git a/Documentation/networking/devlink-params-mv88e6xxx.txt b/Documentation/networking/devlink/devlink-params-mv88e6xxx.txt
similarity index 100%
rename from Documentation/networking/devlink-params-mv88e6xxx.txt
rename to Documentation/networking/devlink/devlink-params-mv88e6xxx.txt
diff --git a/Documentation/networking/devlink-params-nfp.txt b/Documentation/networking/devlink/devlink-params-nfp.txt
similarity index 100%
rename from Documentation/networking/devlink-params-nfp.txt
rename to Documentation/networking/devlink/devlink-params-nfp.txt
diff --git a/Documentation/networking/devlink-params-ti-cpsw-switch.txt b/Documentation/networking/devlink/devlink-params-ti-cpsw-switch.txt
similarity index 100%
rename from Documentation/networking/devlink-params-ti-cpsw-switch.txt
rename to Documentation/networking/devlink/devlink-params-ti-cpsw-switch.txt
diff --git a/Documentation/networking/devlink-params.txt b/Documentation/networking/devlink/devlink-params.txt
similarity index 100%
rename from Documentation/networking/devlink-params.txt
rename to Documentation/networking/devlink/devlink-params.txt
diff --git a/Documentation/networking/devlink-trap-netdevsim.rst b/Documentation/networking/devlink/devlink-trap-netdevsim.rst
similarity index 100%
rename from Documentation/networking/devlink-trap-netdevsim.rst
rename to Documentation/networking/devlink/devlink-trap-netdevsim.rst
diff --git a/Documentation/networking/devlink-trap.rst b/Documentation/networking/devlink/devlink-trap.rst
similarity index 100%
rename from Documentation/networking/devlink-trap.rst
rename to Documentation/networking/devlink/devlink-trap.rst
diff --git a/Documentation/networking/devlink/index.rst b/Documentation/networking/devlink/index.rst
new file mode 100644
index 000000000000..1252c2a1b680
--- /dev/null
+++ b/Documentation/networking/devlink/index.rst
@@ -0,0 +1,14 @@
+Linux Devlink Documentation
+===========================
+
+devlink is an API to expose device information and resources not directly
+related to any device class, such as chip-wide/switch-ASIC-wide configuration.
+
+Contents:
+
+.. toctree::
+ :maxdepth: 1
+
+ devlink-info-versions
+ devlink-trap
+ devlink-trap-netdevsim
diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst
index bee73be7af93..d07d9855dcd3 100644
--- a/Documentation/networking/index.rst
+++ b/Documentation/networking/index.rst
@@ -13,9 +13,7 @@ Contents:
can_ucan_protocol
device_drivers/index
dsa/index
- devlink-info-versions
- devlink-trap
- devlink-trap-netdevsim
+ devlink/index
ethtool-netlink
ieee802154
j1939
diff --git a/MAINTAINERS b/MAINTAINERS
index 66a2e5e07117..b4512918d33e 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -4848,6 +4848,7 @@ S: Supported
F: net/core/devlink.c
F: include/net/devlink.h
F: include/uapi/linux/devlink.h
+F: Documentation/networking/devlink
DIALOG SEMICONDUCTOR DRIVERS
M: Support Opensource <support.opensource@diasemi.com>
diff --git a/drivers/net/netdevsim/dev.c b/drivers/net/netdevsim/dev.c
index 4ed9c8d8de7c..2eb4ca564745 100644
--- a/drivers/net/netdevsim/dev.c
+++ b/drivers/net/netdevsim/dev.c
@@ -287,7 +287,7 @@ struct nsim_trap_data {
};
/* All driver-specific traps must be documented in
- * Documentation/networking/devlink-trap-netdevsim.rst
+ * Documentation/networking/devlink/devlink-trap-netdevsim.rst
*/
enum {
NSIM_TRAP_ID_BASE = DEVLINK_TRAP_GENERIC_ID_MAX,
diff --git a/include/net/devlink.h b/include/net/devlink.h
index 55fc1e0e6513..4622ae37785a 100644
--- a/include/net/devlink.h
+++ b/include/net/devlink.h
@@ -568,7 +568,7 @@ struct devlink_trap {
};
/* All traps must be documented in
- * Documentation/networking/devlink-trap.rst
+ * Documentation/networking/devlink/devlink-trap.rst
*/
enum devlink_trap_generic_id {
DEVLINK_TRAP_GENERIC_ID_SMAC_MC,
@@ -602,7 +602,7 @@ enum devlink_trap_generic_id {
};
/* All trap groups must be documented in
- * Documentation/networking/devlink-trap.rst
+ * Documentation/networking/devlink/devlink-trap.rst
*/
enum devlink_trap_group_generic_id {
DEVLINK_TRAP_GROUP_GENERIC_ID_L2_DROPS,
--
2.25.0.rc1
^ permalink raw reply related [flat|nested] 22+ messages in thread* [PATCH 03/17] devlink: convert devlink-health.txt to rst format
2020-01-09 22:46 [PATCH 00/17] devlink documentation refactor Jacob Keller
2020-01-09 22:46 ` [PATCH 01/17] devlink: add macro for "fw.psid" Jacob Keller
2020-01-09 22:46 ` [PATCH 02/17] devlink: move devlink documentation to subfolder Jacob Keller
@ 2020-01-09 22:46 ` Jacob Keller
2020-01-09 22:46 ` [PATCH 04/17] devlink: rename devlink-info-versions.rst and add a header Jacob Keller
` (14 subsequent siblings)
17 siblings, 0 replies; 22+ messages in thread
From: Jacob Keller @ 2020-01-09 22:46 UTC (permalink / raw)
To: netdev; +Cc: Jiri Pirko, Jacob Keller
Update the devlink-health documentation to use the newer
ReStructuredText format.
Note that it's unclear what OOB stood for, and it has been left as-is
without a proper first-use expansion of the acronym.
Signed-off-by: Jacob Keller <jacob.e.keller@intel.com>
---
.../networking/devlink/devlink-health.rst | 114 ++++++++++++++++++
.../networking/devlink/devlink-health.txt | 86 -------------
Documentation/networking/devlink/index.rst | 1 +
3 files changed, 115 insertions(+), 86 deletions(-)
create mode 100644 Documentation/networking/devlink/devlink-health.rst
delete mode 100644 Documentation/networking/devlink/devlink-health.txt
diff --git a/Documentation/networking/devlink/devlink-health.rst b/Documentation/networking/devlink/devlink-health.rst
new file mode 100644
index 000000000000..0c99b11f05f9
--- /dev/null
+++ b/Documentation/networking/devlink/devlink-health.rst
@@ -0,0 +1,114 @@
+.. 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 (eg 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 a reporter's recovery procedure.
+ * - ``DEVLINK_CMD_HEALTH_REPORTER_DIAGNOSE``
+ - Retrieves diagnostics data from a reporter on a device.
+ * - ``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 the 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,
+ mlx5_core devlink |recover,
+ |dump)
+ +--------+ +--------------------------+
+ | | | reporter| |
+ | | | +---------v----------+ |
+ | | ops execution | | | |
+ | <----------------------------------+ | |
+ | | | | | |
+ | | | + ^------------------+ |
+ | | | | request for ops |
+ | | | | (recover, dump) |
+ | | | | |
+ | | | +-+------------------+ |
+ | | health report | | health handler | |
+ | +-------------------------------> | |
+ | | | +--------------------+ |
+ | | health reporter create | |
+ | +----------------------------> |
+ +--------+ +--------------------------+
diff --git a/Documentation/networking/devlink/devlink-health.txt b/Documentation/networking/devlink/devlink-health.txt
deleted file mode 100644
index 1db3fbea0831..000000000000
--- a/Documentation/networking/devlink/devlink-health.txt
+++ /dev/null
@@ -1,86 +0,0 @@
-The health mechanism is targeted for Real Time Alerting, in order to know when
-something bad had 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.
-
-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 (eg 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 and object dump procedures
- - OOB initial parameters
-Different parts of the driver can register different types of health reporters
-with different handlers.
-
-Once an error is reported, devlink health will do 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
-
-The 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
-
-The devlink health interface (via netlink):
-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 a reporter's recovery procedure.
-DEVLINK_CMD_HEALTH_REPORTER_DIAGNOSE
- Retrieves diagnostics data from a reporter on a device.
-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 the 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.
-
-
- netlink
- +--------------------------+
- | |
- | + |
- | | |
- +--------------------------+
- |request for ops
- |(diagnose,
- mlx5_core devlink |recover,
- |dump)
-+--------+ +--------------------------+
-| | | reporter| |
-| | | +---------v----------+ |
-| | ops execution | | | |
-| <----------------------------------+ | |
-| | | | | |
-| | | + ^------------------+ |
-| | | | request for ops |
-| | | | (recover, dump) |
-| | | | |
-| | | +-+------------------+ |
-| | health report | | health handler | |
-| +-------------------------------> | |
-| | | +--------------------+ |
-| | health reporter create | |
-| +----------------------------> |
-+--------+ +--------------------------+
diff --git a/Documentation/networking/devlink/index.rst b/Documentation/networking/devlink/index.rst
index 1252c2a1b680..71d9d0e859eb 100644
--- a/Documentation/networking/devlink/index.rst
+++ b/Documentation/networking/devlink/index.rst
@@ -9,6 +9,7 @@ Contents:
.. toctree::
:maxdepth: 1
+ devlink-health
devlink-info-versions
devlink-trap
devlink-trap-netdevsim
--
2.25.0.rc1
^ permalink raw reply related [flat|nested] 22+ messages in thread* [PATCH 04/17] devlink: rename devlink-info-versions.rst and add a header
2020-01-09 22:46 [PATCH 00/17] devlink documentation refactor Jacob Keller
` (2 preceding siblings ...)
2020-01-09 22:46 ` [PATCH 03/17] devlink: convert devlink-health.txt to rst format Jacob Keller
@ 2020-01-09 22:46 ` Jacob Keller
2020-01-09 22:46 ` [PATCH 05/17] devlink: convert devlink-params.txt to reStructuredText Jacob Keller
` (13 subsequent siblings)
17 siblings, 0 replies; 22+ messages in thread
From: Jacob Keller @ 2020-01-09 22:46 UTC (permalink / raw)
To: netdev; +Cc: Jiri Pirko, Jacob Keller
Rename the devlink-info-versions.rst file to a plain devlink-info.rst
file. Add additional paragraphs explaining what devlink-info is for,
and the expectation that drivers use the generic names where plausible.
Note that drivers which use non-standard info version names ought to
document these in a driver-specific info-versions.rst file.
Signed-off-by: Jacob Keller <jacob.e.keller@intel.com>
---
.../devlink/devlink-info-versions.rst | 64 -------------
.../networking/devlink/devlink-info.rst | 94 +++++++++++++++++++
Documentation/networking/devlink/index.rst | 2 +-
3 files changed, 95 insertions(+), 65 deletions(-)
delete mode 100644 Documentation/networking/devlink/devlink-info-versions.rst
create mode 100644 Documentation/networking/devlink/devlink-info.rst
diff --git a/Documentation/networking/devlink/devlink-info-versions.rst b/Documentation/networking/devlink/devlink-info-versions.rst
deleted file mode 100644
index 4914f581b1fd..000000000000
--- a/Documentation/networking/devlink/devlink-info-versions.rst
+++ /dev/null
@@ -1,64 +0,0 @@
-.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
-
-=====================
-Devlink info versions
-=====================
-
-board.id
-========
-
-Unique identifier of the board design.
-
-board.rev
-=========
-
-Board design revision.
-
-asic.id
-=======
-
-ASIC design identifier.
-
-asic.rev
-========
-
-ASIC design revision.
-
-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.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.
diff --git a/Documentation/networking/devlink/devlink-info.rst b/Documentation/networking/devlink/devlink-info.rst
new file mode 100644
index 000000000000..0385f15028b1
--- /dev/null
+++ b/Documentation/networking/devlink/devlink-info.rst
@@ -0,0 +1,94 @@
+.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+
+============
+Devlink Info
+============
+
+The ``devlink-info`` mechanism enables device drivers to report device
+information in a generic fashion. It is extensible, and enables exporting
+even device or driver specific information.
+
+devlink supports representing the following types of versions
+
+.. list-table:: List of version types
+ :widths: 5 95
+
+ * - Type
+ - Description
+ * - ``fixed``
+ - Represents fixed versions, which cannot change. For example,
+ component identifiers or the board version reported in the PCI VPD.
+ * - ``running``
+ - Represents the version of the currently running component. For
+ example the running version of firmware. These versions generally
+ only update after a reboot.
+ * - ``stored``
+ - Represents the version of a component as stored, such as after a
+ flash update. Stored values should update to reflect changes in the
+ flash even if a reboot has not yet occurred.
+
+Generic Versions
+================
+
+It is expected that drivers use the following generic names for exporting
+version information. Other information may be exposed using driver-specific
+names, but these should be documented in the driver-specific file.
+
+board.id
+--------
+
+Unique identifier of the board design.
+
+board.rev
+---------
+
+Board design revision.
+
+asic.id
+-------
+
+ASIC design identifier.
+
+asic.rev
+--------
+
+ASIC design revision.
+
+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.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.
diff --git a/Documentation/networking/devlink/index.rst b/Documentation/networking/devlink/index.rst
index 71d9d0e859eb..687bb6e51fca 100644
--- a/Documentation/networking/devlink/index.rst
+++ b/Documentation/networking/devlink/index.rst
@@ -10,6 +10,6 @@ Contents:
:maxdepth: 1
devlink-health
- devlink-info-versions
+ devlink-info
devlink-trap
devlink-trap-netdevsim
--
2.25.0.rc1
^ permalink raw reply related [flat|nested] 22+ messages in thread* [PATCH 05/17] devlink: convert devlink-params.txt to reStructuredText
2020-01-09 22:46 [PATCH 00/17] devlink documentation refactor Jacob Keller
` (3 preceding siblings ...)
2020-01-09 22:46 ` [PATCH 04/17] devlink: rename devlink-info-versions.rst and add a header Jacob Keller
@ 2020-01-09 22:46 ` Jacob Keller
2020-01-09 22:46 ` [PATCH 06/17] devlink: add documentation for generic devlink parameters Jacob Keller
` (12 subsequent siblings)
17 siblings, 0 replies; 22+ messages in thread
From: Jacob Keller @ 2020-01-09 22:46 UTC (permalink / raw)
To: netdev; +Cc: Jiri Pirko, Jacob Keller
Convert the generic parameters descriptions into the reStructuredText
format.
Signed-off-by: Jacob Keller <jacob.e.keller@intel.com>
---
.../networking/devlink/devlink-params.rst | 90 +++++++++++++++++++
.../networking/devlink/devlink-params.txt | 71 ---------------
Documentation/networking/devlink/index.rst | 1 +
3 files changed, 91 insertions(+), 71 deletions(-)
create mode 100644 Documentation/networking/devlink/devlink-params.rst
delete mode 100644 Documentation/networking/devlink/devlink-params.txt
diff --git a/Documentation/networking/devlink/devlink-params.rst b/Documentation/networking/devlink/devlink-params.rst
new file mode 100644
index 000000000000..b51b91f807f7
--- /dev/null
+++ b/Documentation/networking/devlink/devlink-params.rst
@@ -0,0 +1,90 @@
+.. 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.
+
+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.
diff --git a/Documentation/networking/devlink/devlink-params.txt b/Documentation/networking/devlink/devlink-params.txt
deleted file mode 100644
index 04e234e9acc9..000000000000
--- a/Documentation/networking/devlink/devlink-params.txt
+++ /dev/null
@@ -1,71 +0,0 @@
-Devlink configuration parameters
-================================
-Following is the list of configuration parameters via devlink interface.
-Each parameter can be generic or driver specific and are device level
-parameters.
-
-Note that the driver-specific files should contain the generic params
-they support to, with supported config modes.
-
-Each parameter can be set in different configuration modes:
- runtime - set while driver is running, no reset required.
- driverinit - applied while driver initializes, requires restart
- driver by devlink reload command.
- permanent - written to device's non-volatile memory, hard reset
- required.
-
-Following is the list of parameters:
-====================================
-enable_sriov [DEVICE, GENERIC]
- Enable Single Root I/O Virtualisation (SRIOV) in
- the device.
- Type: Boolean
-
-ignore_ari [DEVICE, GENERIC]
- Ignore Alternative Routing-ID Interpretation (ARI)
- capability. If enabled, adapter will ignore ARI
- capability even when platforms has the support
- enabled and creates same number of partitions when
- platform does not support ARI.
- Type: Boolean
-
-msix_vec_per_pf_max [DEVICE, GENERIC]
- Provides the maximum number of MSIX interrupts that
- a device can create. Value is same across all
- physical functions (PFs) in the device.
- Type: u32
-
-msix_vec_per_pf_min [DEVICE, GENERIC]
- Provides the minimum number of MSIX interrupts required
- for the device initialization. Value is same across all
- physical functions (PFs) in the device.
- Type: u32
-
-fw_load_policy [DEVICE, GENERIC]
- Controls the device's firmware loading policy.
- Valid values:
- * 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.
- Type: u8
-
-reset_dev_on_drv_probe [DEVICE, GENERIC]
- Controls the device's reset policy on driver probe.
- Valid values:
- * 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 only if device firmware can be found in the
- filesystem.
- Type: u8
-
-enable_roce [DEVICE, GENERIC]
- Enable handling of RoCE traffic in the device.
- Type: Boolean
diff --git a/Documentation/networking/devlink/index.rst b/Documentation/networking/devlink/index.rst
index 687bb6e51fca..ae3f20919d22 100644
--- a/Documentation/networking/devlink/index.rst
+++ b/Documentation/networking/devlink/index.rst
@@ -11,5 +11,6 @@ Contents:
devlink-health
devlink-info
+ devlink-params
devlink-trap
devlink-trap-netdevsim
--
2.25.0.rc1
^ permalink raw reply related [flat|nested] 22+ messages in thread* [PATCH 06/17] devlink: add documentation for generic devlink parameters
2020-01-09 22:46 [PATCH 00/17] devlink documentation refactor Jacob Keller
` (4 preceding siblings ...)
2020-01-09 22:46 ` [PATCH 05/17] devlink: convert devlink-params.txt to reStructuredText Jacob Keller
@ 2020-01-09 22:46 ` Jacob Keller
2020-01-09 22:46 ` [PATCH 07/17] devlink: mention reloading in devlink-params.rst Jacob Keller
` (11 subsequent siblings)
17 siblings, 0 replies; 22+ messages in thread
From: Jacob Keller @ 2020-01-09 22:46 UTC (permalink / raw)
To: netdev; +Cc: Jiri Pirko, Jacob Keller
A few generic devlink parameters have been added, but never documented.
Fix that now.
Signed-off-by: Jacob Keller <jacob.e.keller@intel.com>
---
Documentation/networking/devlink/devlink-params.rst | 11 +++++++++++
1 file changed, 11 insertions(+)
diff --git a/Documentation/networking/devlink/devlink-params.rst b/Documentation/networking/devlink/devlink-params.rst
index b51b91f807f7..7106c79e29be 100644
--- a/Documentation/networking/devlink/devlink-params.rst
+++ b/Documentation/networking/devlink/devlink-params.rst
@@ -88,3 +88,14 @@ own name.
* - ``enable_roce``
- Boolean
- Enable handling of RoCE traffic in the device.
+ * - ``internal_err_reset``
+ - Boolean
+ - When enabled, the device driver will reset the device on internal
+ errors.
+ * - ``max_macs``
+ - u32
+ - Specifies the maximum number of MAC addresses per ethernet port of
+ this device.
+ * - ``region_snapshot_enable``
+ - Boolean
+ - Enable capture of ``devlink-region`` snapshots.
--
2.25.0.rc1
^ permalink raw reply related [flat|nested] 22+ messages in thread* [PATCH 07/17] devlink: mention reloading in devlink-params.rst
2020-01-09 22:46 [PATCH 00/17] devlink documentation refactor Jacob Keller
` (5 preceding siblings ...)
2020-01-09 22:46 ` [PATCH 06/17] devlink: add documentation for generic devlink parameters Jacob Keller
@ 2020-01-09 22:46 ` Jacob Keller
2020-01-09 22:46 ` [PATCH 08/17] devlink: convert driver-specific files to reStructuredText Jacob Keller
` (10 subsequent siblings)
17 siblings, 0 replies; 22+ messages in thread
From: Jacob Keller @ 2020-01-09 22:46 UTC (permalink / raw)
To: netdev; +Cc: Jiri Pirko, Jacob Keller
Mention that drivers must support devlink-reload in order for driverinit
parameters to function properly
Signed-off-by: Jacob Keller <jacob.e.keller@intel.com>
---
Documentation/networking/devlink/devlink-params.rst | 7 +++++++
1 file changed, 7 insertions(+)
diff --git a/Documentation/networking/devlink/devlink-params.rst b/Documentation/networking/devlink/devlink-params.rst
index 7106c79e29be..da2f85c0fa21 100644
--- a/Documentation/networking/devlink/devlink-params.rst
+++ b/Documentation/networking/devlink/devlink-params.rst
@@ -34,6 +34,13 @@ Parameters may be set in different configuration modes.
- 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.
+
Generic configuration parameters
================================
The following is a list of generic configuration parameters that drivers may
--
2.25.0.rc1
^ permalink raw reply related [flat|nested] 22+ messages in thread* [PATCH 08/17] devlink: convert driver-specific files to reStructuredText
2020-01-09 22:46 [PATCH 00/17] devlink documentation refactor Jacob Keller
` (6 preceding siblings ...)
2020-01-09 22:46 ` [PATCH 07/17] devlink: mention reloading in devlink-params.rst Jacob Keller
@ 2020-01-09 22:46 ` Jacob Keller
2020-01-09 22:46 ` [PATCH 09/17] devlink: document info versions for each driver Jacob Keller
` (9 subsequent siblings)
17 siblings, 0 replies; 22+ messages in thread
From: Jacob Keller @ 2020-01-09 22:46 UTC (permalink / raw)
To: netdev
Cc: Jiri Pirko, Jacob Keller, Tariq Toukan, Saeed Mahameed,
Leon Romanovsky, Michael Chan, Andrew Lunn, Vivien Didelot,
Ido Schimmel, Jakub Kicinski, Grygorii Strashko
Several drivers document what parameters they support in
a devlink-params-*.txt file. This file is supposed to contain both the
list of generic parameters implemented by the driver, as well as a list
of driver-specific parameters and their descriptions.
It would also be good if the driver documentation included other
driver-specific implementations, such as info versions, devlink
regions, and so forth.
Convert all of these documentation files to reStructuredText, and rename
them to just the driver name. Future changes will include other
driver-specific implementations. Each file will contain a table for the
generic parameters implemented, as well as a separate table for the
driver-specific parameters.
Future sections such as for devlink info versions will be added to these
files. This avoids creating additional devlink-<feature>-<driver> files
for each devlink feature, reducing clutter in the documentation folder.
Signed-off-by: Jacob Keller <jacob.e.keller@intel.com>
Cc: Tariq Toukan <tariqt@mellanox.com>
Cc: Saeed Mahameed <saeedm@mellanox.com>
Cc: Leon Romanovsky <leonro@mellanox.com>
Cc: Michael Chan <michael.chan@broadcom.com>
Cc: Andrew Lunn <andrew@lunn.ch>
Cc: Vivien Didelot <vivien.didelot@gmail.com>
Cc: Jiri Pirko <jiri@mellanox.com>
Cc: Ido Schimmel <idosch@mellanox.com>
Cc: Jakub Kicinski <jakub.kicinski@netronome.com>
Cc: Grygorii Strashko <grygorii.strashko@ti.com>
---
.../device_drivers/ti/cpsw_switchdev.txt | 2 +-
Documentation/networking/devlink/bnxt.rst | 41 +++++++++++++++++++
.../devlink/devlink-params-bnxt.txt | 18 --------
.../devlink/devlink-params-mlx5.txt | 17 --------
.../devlink/devlink-params-mlxsw.txt | 10 -----
.../devlink/devlink-params-mv88e6xxx.txt | 7 ----
.../networking/devlink/devlink-params-nfp.txt | 5 ---
.../devlink/devlink-params-ti-cpsw-switch.txt | 10 -----
Documentation/networking/devlink/index.rst | 22 +++++++++-
Documentation/networking/devlink/mlx5.rst | 41 +++++++++++++++++++
Documentation/networking/devlink/mlxsw.rst | 38 +++++++++++++++++
.../networking/devlink/mv88e6xxx.rst | 28 +++++++++++++
Documentation/networking/devlink/nfp.rst | 20 +++++++++
.../networking/devlink/ti-cpsw-switch.rst | 31 ++++++++++++++
MAINTAINERS | 2 +-
15 files changed, 222 insertions(+), 70 deletions(-)
create mode 100644 Documentation/networking/devlink/bnxt.rst
delete mode 100644 Documentation/networking/devlink/devlink-params-bnxt.txt
delete mode 100644 Documentation/networking/devlink/devlink-params-mlx5.txt
delete mode 100644 Documentation/networking/devlink/devlink-params-mlxsw.txt
delete mode 100644 Documentation/networking/devlink/devlink-params-mv88e6xxx.txt
delete mode 100644 Documentation/networking/devlink/devlink-params-nfp.txt
delete mode 100644 Documentation/networking/devlink/devlink-params-ti-cpsw-switch.txt
create mode 100644 Documentation/networking/devlink/mlx5.rst
create mode 100644 Documentation/networking/devlink/mlxsw.rst
create mode 100644 Documentation/networking/devlink/mv88e6xxx.rst
create mode 100644 Documentation/networking/devlink/nfp.rst
create mode 100644 Documentation/networking/devlink/ti-cpsw-switch.rst
diff --git a/Documentation/networking/device_drivers/ti/cpsw_switchdev.txt b/Documentation/networking/device_drivers/ti/cpsw_switchdev.txt
index 5c8cee17fca9..12855ab268b8 100644
--- a/Documentation/networking/device_drivers/ti/cpsw_switchdev.txt
+++ b/Documentation/networking/device_drivers/ti/cpsw_switchdev.txt
@@ -39,7 +39,7 @@ but without enabling "switch" mode, or to different bridges.
Devlink configuration parameters
====================
-See Documentation/networking/devlink-params-ti-cpsw-switch.txt
+See Documentation/networking/devlink/ti-cpsw-switch.rst
====================
# Bridging in dual mac mode
diff --git a/Documentation/networking/devlink/bnxt.rst b/Documentation/networking/devlink/bnxt.rst
new file mode 100644
index 000000000000..79e746d22a53
--- /dev/null
+++ b/Documentation/networking/devlink/bnxt.rst
@@ -0,0 +1,41 @@
+.. 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
+
+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.
diff --git a/Documentation/networking/devlink/devlink-params-bnxt.txt b/Documentation/networking/devlink/devlink-params-bnxt.txt
deleted file mode 100644
index 481aa303d5b4..000000000000
--- a/Documentation/networking/devlink/devlink-params-bnxt.txt
+++ /dev/null
@@ -1,18 +0,0 @@
-enable_sriov [DEVICE, GENERIC]
- Configuration mode: Permanent
-
-ignore_ari [DEVICE, GENERIC]
- Configuration mode: Permanent
-
-msix_vec_per_pf_max [DEVICE, GENERIC]
- Configuration mode: Permanent
-
-msix_vec_per_pf_min [DEVICE, GENERIC]
- Configuration mode: Permanent
-
-gre_ver_check [DEVICE, DRIVER-SPECIFIC]
- Generic Routing Encapsulation (GRE) version check will
- be enabled in the device. If disabled, device skips
- version checking for incoming packets.
- Type: Boolean
- Configuration mode: Permanent
diff --git a/Documentation/networking/devlink/devlink-params-mlx5.txt b/Documentation/networking/devlink/devlink-params-mlx5.txt
deleted file mode 100644
index 5071467118bd..000000000000
--- a/Documentation/networking/devlink/devlink-params-mlx5.txt
+++ /dev/null
@@ -1,17 +0,0 @@
-flow_steering_mode [DEVICE, DRIVER-SPECIFIC]
- Controls the flow steering mode of the driver.
- Two modes are supported:
- 1. 'dmfs' - Device managed flow steering.
- 2. 'smfs - Software/Driver managed flow steering.
- In DMFS mode, the HW steering entities are created and
- managed through the Firmware.
- In SMFS mode, the HW steering entities are created and
- managed though by the driver directly into Hardware
- without firmware intervention.
- Type: String
- Configuration mode: runtime
-
-enable_roce [DEVICE, GENERIC]
- Enable handling of RoCE traffic in the device.
- Defaultly enabled.
- Configuration mode: driverinit
diff --git a/Documentation/networking/devlink/devlink-params-mlxsw.txt b/Documentation/networking/devlink/devlink-params-mlxsw.txt
deleted file mode 100644
index c63ea9fc7009..000000000000
--- a/Documentation/networking/devlink/devlink-params-mlxsw.txt
+++ /dev/null
@@ -1,10 +0,0 @@
-fw_load_policy [DEVICE, GENERIC]
- Configuration mode: driverinit
-
-acl_region_rehash_interval [DEVICE, DRIVER-SPECIFIC]
- Sets an interval for periodic ACL region rehashes.
- The value is in milliseconds, minimal value is "3000".
- Value "0" disables the periodic work.
- The first rehash will be run right after value is set.
- Type: u32
- Configuration mode: runtime
diff --git a/Documentation/networking/devlink/devlink-params-mv88e6xxx.txt b/Documentation/networking/devlink/devlink-params-mv88e6xxx.txt
deleted file mode 100644
index 21c4b3556ef2..000000000000
--- a/Documentation/networking/devlink/devlink-params-mv88e6xxx.txt
+++ /dev/null
@@ -1,7 +0,0 @@
-ATU_hash [DEVICE, DRIVER-SPECIFIC]
- Select one of four possible hashing algorithms for
- MAC addresses in the Address Translation Unit.
- A value of 3 seems to work better than the default of
- 1 when many MAC addresses have the same OUI.
- Configuration mode: runtime
- Type: u8. 0-3 valid.
diff --git a/Documentation/networking/devlink/devlink-params-nfp.txt b/Documentation/networking/devlink/devlink-params-nfp.txt
deleted file mode 100644
index 43e4d4034865..000000000000
--- a/Documentation/networking/devlink/devlink-params-nfp.txt
+++ /dev/null
@@ -1,5 +0,0 @@
-fw_load_policy [DEVICE, GENERIC]
- Configuration mode: permanent
-
-reset_dev_on_drv_probe [DEVICE, GENERIC]
- Configuration mode: permanent
diff --git a/Documentation/networking/devlink/devlink-params-ti-cpsw-switch.txt b/Documentation/networking/devlink/devlink-params-ti-cpsw-switch.txt
deleted file mode 100644
index 4037458499f7..000000000000
--- a/Documentation/networking/devlink/devlink-params-ti-cpsw-switch.txt
+++ /dev/null
@@ -1,10 +0,0 @@
-ale_bypass [DEVICE, DRIVER-SPECIFIC]
- Allows to enable ALE_CONTROL(4).BYPASS mode for debug purposes.
- All packets will be sent to the Host port only if enabled.
- Type: bool
- Configuration mode: runtime
-
-switch_mode [DEVICE, DRIVER-SPECIFIC]
- Enable switch mode
- Type: bool
- Configuration mode: runtime
diff --git a/Documentation/networking/devlink/index.rst b/Documentation/networking/devlink/index.rst
index ae3f20919d22..4035cbefda7c 100644
--- a/Documentation/networking/devlink/index.rst
+++ b/Documentation/networking/devlink/index.rst
@@ -4,7 +4,11 @@ Linux Devlink Documentation
devlink is an API to expose device information and resources not directly
related to any device class, such as chip-wide/switch-ASIC-wide configuration.
-Contents:
+Interface documentation
+-----------------------
+
+The following pages describe various interfaces available through devlink in
+general.
.. toctree::
:maxdepth: 1
@@ -14,3 +18,19 @@ Contents:
devlink-params
devlink-trap
devlink-trap-netdevsim
+
+Driver-specific documentation
+-----------------------------
+
+Each driver that implements ``devlink`` is expected to document what
+parameters, info versions, and other features it supports.
+
+.. toctree::
+ :maxdepth: 1
+
+ bnxt
+ mlx5
+ mlxsw
+ mv88e6xxx
+ nfp
+ ti-cpsw-switch
diff --git a/Documentation/networking/devlink/mlx5.rst b/Documentation/networking/devlink/mlx5.rst
new file mode 100644
index 000000000000..cf2e19665e5c
--- /dev/null
+++ b/Documentation/networking/devlink/mlx5.rst
@@ -0,0 +1,41 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====================
+mlx5 devlink support
+====================
+
+This document describes the devlink features implemented by the ``mlx5``
+device driver.
+
+Parameters
+==========
+
+.. list-table:: Generic parameters implemented
+
+ * - Name
+ - Mode
+ * - ``enable_roce``
+ - driverinit
+
+The ``mlx5`` driver also implements the following driver-specific
+parameters.
+
+.. list-table:: Driver-specific parameters implemented
+ :widths: 5 5 5 85
+
+ * - Name
+ - Type
+ - Mode
+ - Description
+ * - ``flow_steering_mode``
+ - string
+ - runtime
+ - Controls the flow steering mode of the driver
+
+ * ``dmfs`` Device managed flow steering. In DMFS mode, the HW
+ steering entities are created and managed through firmware.
+ * ``smfs`` Software managed flow steering. In SMFS mode, the HW
+ steering entities are created and manage through the driver without
+ firmware intervention.
+
+The ``mlx5`` driver supports reloading via ``DEVLINK_CMD_RELOAD``
diff --git a/Documentation/networking/devlink/mlxsw.rst b/Documentation/networking/devlink/mlxsw.rst
new file mode 100644
index 000000000000..dfb245f0c17d
--- /dev/null
+++ b/Documentation/networking/devlink/mlxsw.rst
@@ -0,0 +1,38 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=====================
+mlxsw devlink support
+=====================
+
+This document describes the devlink features implemented by the ``mlxsw``
+device driver.
+
+Parameters
+==========
+
+.. list-table:: Generic parameters implemented
+
+ * - Name
+ - Mode
+ * - ``fw_load_policy``
+ - driverinit
+
+The ``mlxsw`` driver also implements the following driver-specific
+parameters.
+
+.. list-table:: Driver-specific parameters implemented
+ :widths: 5 5 5 85
+
+ * - Name
+ - Type
+ - Mode
+ - Description
+ * - ``acl_region_rehash_interval``
+ - u32
+ - runtime
+ - Sets an interval for periodic ACL region rehashes. The value is
+ specified in milliseconds, with a minimum of ``3000``. The value of
+ ``0`` disables periodic work entirely. The first rehash will be run
+ immediately after the value is set.
+
+The ``mlxsw`` driver supports reloading via ``DEVLINK_CMD_RELOAD``
diff --git a/Documentation/networking/devlink/mv88e6xxx.rst b/Documentation/networking/devlink/mv88e6xxx.rst
new file mode 100644
index 000000000000..c621212a47a1
--- /dev/null
+++ b/Documentation/networking/devlink/mv88e6xxx.rst
@@ -0,0 +1,28 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=========================
+mv88e6xxx devlink support
+=========================
+
+This document describes the devlink features implemented by the ``mv88e6xxx``
+device driver.
+
+Parameters
+==========
+
+The ``mv88e6xxx`` driver implements the following driver-specific parameters.
+
+.. list-table:: Driver-specific parameters implemented
+ :widths: 5 5 5 85
+
+ * - Name
+ - Type
+ - Mode
+ - Description
+ * - ``ATU_hash``
+ - u8
+ - runtime
+ - Select one of four possible hashing algorithms for MAC addresses in
+ the Address Translation Unit. A value of 3 may work better than the
+ default of 1 when many MAC addresses have the same OUI. Only the
+ values 0 to 3 are valid for this parameter.
diff --git a/Documentation/networking/devlink/nfp.rst b/Documentation/networking/devlink/nfp.rst
new file mode 100644
index 000000000000..bbb3c6b2280c
--- /dev/null
+++ b/Documentation/networking/devlink/nfp.rst
@@ -0,0 +1,20 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===================
+nfp devlink support
+===================
+
+This document describes the devlink features implemented by the ``nfp``
+device driver.
+
+Parameters
+==========
+
+.. list-table:: Generic parameters implemented
+
+ * - Name
+ - Mode
+ * - ``fw_load_policy``
+ - permanent
+ * - ``reset_dev_on_drv_probe``
+ - permanent
diff --git a/Documentation/networking/devlink/ti-cpsw-switch.rst b/Documentation/networking/devlink/ti-cpsw-switch.rst
new file mode 100644
index 000000000000..dc399e32abaa
--- /dev/null
+++ b/Documentation/networking/devlink/ti-cpsw-switch.rst
@@ -0,0 +1,31 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==============================
+ti-cpsw-switch devlink support
+==============================
+
+This document describes the devlink features implemented by the ``ti-cpsw-switch``
+device driver.
+
+Parameters
+==========
+
+The ``ti-cpsw-switch`` driver implements the following driver-specific
+parameters.
+
+.. list-table:: Driver-specific parameters implemented
+ :widths: 5 5 5 85
+
+ * - Name
+ - Type
+ - Mode
+ - Description
+ * - ``ale_bypass``
+ - Boolean
+ - runtime
+ - Enables ALE_CONTROL(4).BYPASS mode for debugging purposes. In this
+ mode, all packets will be sent to the host port only.
+ * - ``switch_mode``
+ - Boolean
+ - runtime
+ - Enable switch mode
diff --git a/MAINTAINERS b/MAINTAINERS
index b4512918d33e..9b277c3ac1eb 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -9890,7 +9890,7 @@ S: Maintained
F: drivers/net/dsa/mv88e6xxx/
F: include/linux/platform_data/mv88e6xxx.h
F: Documentation/devicetree/bindings/net/dsa/marvell.txt
-F: Documentation/networking/devlink-params-mv88e6xxx.txt
+F: Documentation/networking/devlink/mv88e6xxx.rst
MARVELL ARMADA DRM SUPPORT
M: Russell King <linux@armlinux.org.uk>
--
2.25.0.rc1
^ permalink raw reply related [flat|nested] 22+ messages in thread* [PATCH 09/17] devlink: document info versions for each driver
2020-01-09 22:46 [PATCH 00/17] devlink documentation refactor Jacob Keller
` (7 preceding siblings ...)
2020-01-09 22:46 ` [PATCH 08/17] devlink: convert driver-specific files to reStructuredText Jacob Keller
@ 2020-01-09 22:46 ` Jacob Keller
2020-01-09 22:46 ` [PATCH 10/17] devlink: add parameter documentation for the mlx4 driver Jacob Keller
` (8 subsequent siblings)
17 siblings, 0 replies; 22+ messages in thread
From: Jacob Keller @ 2020-01-09 22:46 UTC (permalink / raw)
To: netdev
Cc: Jiri Pirko, Jacob Keller, Tariq Toukan, Saeed Mahameed,
Leon Romanovsky, Michael Chan, Jakub Kicinski
Add the set of info versions reported by each device driver, including
a description of what the version represents, and what modes (fixed,
running, stored) it reports.
Signed-off-by: Jacob Keller <jacob.e.keller@intel.com>
Cc: Tariq Toukan <tariqt@mellanox.com>
Cc: Saeed Mahameed <saeedm@mellanox.com>
Cc: Leon Romanovsky <leonro@mellanox.com>
Cc: Michael Chan <michael.chan@broadcom.com>
Cc: Jiri Pirko <jiri@mellanox.com>
Cc: Jakub Kicinski <jakub.kicinski@netronome.com>
---
Documentation/networking/devlink/mlx5.rst | 18 +++++++++
Documentation/networking/devlink/mlxsw.rst | 21 ++++++++++
Documentation/networking/devlink/nfp.rst | 45 ++++++++++++++++++++++
3 files changed, 84 insertions(+)
diff --git a/Documentation/networking/devlink/mlx5.rst b/Documentation/networking/devlink/mlx5.rst
index cf2e19665e5c..629a6e69c036 100644
--- a/Documentation/networking/devlink/mlx5.rst
+++ b/Documentation/networking/devlink/mlx5.rst
@@ -39,3 +39,21 @@ parameters.
firmware intervention.
The ``mlx5`` driver supports reloading via ``DEVLINK_CMD_RELOAD``
+
+Info versions
+=============
+
+The ``mlx5`` driver reports the following versions
+
+.. list-table:: devlink info versions implemented
+ :widths: 5 5 90
+
+ * - Name
+ - Type
+ - Description
+ * - ``fw.psid``
+ - fixed
+ - Used to represent the board id of the device.
+ * - ``fw.version``
+ - stored, running
+ - Three digit major.minor.subminor firmware version number.
diff --git a/Documentation/networking/devlink/mlxsw.rst b/Documentation/networking/devlink/mlxsw.rst
index dfb245f0c17d..ccba9769c651 100644
--- a/Documentation/networking/devlink/mlxsw.rst
+++ b/Documentation/networking/devlink/mlxsw.rst
@@ -36,3 +36,24 @@ parameters.
immediately after the value is set.
The ``mlxsw`` driver supports reloading via ``DEVLINK_CMD_RELOAD``
+
+Info versions
+=============
+
+The ``mlx5`` driver reports the following versions
+
+.. list-table:: devlink info versions implemented
+ :widths: 5 5 90
+
+ * - Name
+ - Type
+ - Description
+ * - ``hw.revision``
+ - fixed
+ - The hardware revision for this board
+ * - ``fw.psid``
+ - fixed
+ - Firmware PSID
+ * - ``fw.version``
+ - running
+ - Three digit firmware version
diff --git a/Documentation/networking/devlink/nfp.rst b/Documentation/networking/devlink/nfp.rst
index bbb3c6b2280c..a1717db0dfcc 100644
--- a/Documentation/networking/devlink/nfp.rst
+++ b/Documentation/networking/devlink/nfp.rst
@@ -18,3 +18,48 @@ Parameters
- permanent
* - ``reset_dev_on_drv_probe``
- permanent
+
+Info versions
+=============
+
+The ``nfp`` driver reports the following versions
+
+.. list-table:: devlink info versions implemented
+ :widths: 5 5 90
+
+ * - Name
+ - Type
+ - Description
+ * - ``board.id``
+ - fixed
+ - Part number identifying the board design
+ * - ``board.rev``
+ - fixed
+ - Revision of the board design
+ * - ``board.manufacture``
+ - fixed
+ - Vendor of the board design
+ * - ``board.model``
+ - fixed
+ - Model name of the board design
+ * - ``fw.bundle_id``
+ - stored, running
+ - Firmware bundle id
+ * - ``fw.mgmt``
+ - stored, running
+ - Version of the management firmware
+ * - ``fw.cpld``
+ - stored, running
+ - The CPLD firmware component version
+ * - ``fw.app``
+ - stored, running
+ - The APP firmware component version
+ * - ``fw.undi``
+ - stored, running
+ - The UNDI firmware component version
+ * - ``fw.ncsi``
+ - stored, running
+ - The NSCI firmware component version
+ * - ``chip.init``
+ - stored, running
+ - The CFGR firmware component version
--
2.25.0.rc1
^ permalink raw reply related [flat|nested] 22+ messages in thread* [PATCH 10/17] devlink: add parameter documentation for the mlx4 driver
2020-01-09 22:46 [PATCH 00/17] devlink documentation refactor Jacob Keller
` (8 preceding siblings ...)
2020-01-09 22:46 ` [PATCH 09/17] devlink: document info versions for each driver Jacob Keller
@ 2020-01-09 22:46 ` Jacob Keller
2020-01-09 22:46 ` [PATCH 11/17] devlink: add a driver-specific file for the qed driver Jacob Keller
` (7 subsequent siblings)
17 siblings, 0 replies; 22+ messages in thread
From: Jacob Keller @ 2020-01-09 22:46 UTC (permalink / raw)
To: netdev; +Cc: Jiri Pirko, Jacob Keller, Tariq Toukan
The mlx5 and mlxsw drivers have driver-specific documentation for the
devlink features they support. No such file was added for mlx4.
Add a file to document the mlx4 devlink support. Initially it contains
only the devlink parameters.
Signed-off-by: Jacob Keller <jacob.e.keller@intel.com>
Cc: Tariq Toukan <tariqt@mellanox.com>
---
Documentation/networking/devlink/index.rst | 1 +
Documentation/networking/devlink/mlx4.rst | 43 ++++++++++++++++++++++
2 files changed, 44 insertions(+)
create mode 100644 Documentation/networking/devlink/mlx4.rst
diff --git a/Documentation/networking/devlink/index.rst b/Documentation/networking/devlink/index.rst
index 4035cbefda7c..0cbafef607d8 100644
--- a/Documentation/networking/devlink/index.rst
+++ b/Documentation/networking/devlink/index.rst
@@ -29,6 +29,7 @@ parameters, info versions, and other features it supports.
:maxdepth: 1
bnxt
+ mlx4
mlx5
mlxsw
mv88e6xxx
diff --git a/Documentation/networking/devlink/mlx4.rst b/Documentation/networking/devlink/mlx4.rst
new file mode 100644
index 000000000000..4fa5c2b51c52
--- /dev/null
+++ b/Documentation/networking/devlink/mlx4.rst
@@ -0,0 +1,43 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====================
+mlx4 devlink support
+====================
+
+This document describes the devlink features implemented by the ``mlx4``
+device driver.
+
+Parameters
+==========
+
+.. list-table:: Generic parameters implemented
+
+ * - Name
+ - Mode
+ * - ``internal_err_reset``
+ - driverinit, runtime
+ * - ``max_macs``
+ - driverinit
+ * - ``region_snapshot_enable``
+ - driverinit, runtime
+
+The ``mlx4`` driver also implements the following driver-specific
+parameters.
+
+.. list-table:: Driver-specific parameters implemented
+ :widths: 5 5 5 85
+
+ * - Name
+ - Type
+ - Mode
+ - Description
+ * - ``enable_64b_cqe_eqe``
+ - Boolean
+ - driverinit
+ - Enable 64 byte CQEs/EQEs, if the FW supports it.
+ * - ``enable_4k_uar``
+ - Boolean
+ - driverinit
+ - Enable using the 4k UAR.
+
+The ``mlx4`` driver supports reloading via ``DEVLINK_CMD_RELOAD``
--
2.25.0.rc1
^ permalink raw reply related [flat|nested] 22+ messages in thread* [PATCH 11/17] devlink: add a driver-specific file for the qed driver
2020-01-09 22:46 [PATCH 00/17] devlink documentation refactor Jacob Keller
` (9 preceding siblings ...)
2020-01-09 22:46 ` [PATCH 10/17] devlink: add parameter documentation for the mlx4 driver Jacob Keller
@ 2020-01-09 22:46 ` Jacob Keller
2020-01-14 8:41 ` [EXT] " Michal Kalderon
2020-01-09 22:46 ` [PATCH 12/17] devlink: add a file documenting devlink regions Jacob Keller
` (6 subsequent siblings)
17 siblings, 1 reply; 22+ messages in thread
From: Jacob Keller @ 2020-01-09 22:46 UTC (permalink / raw)
To: netdev; +Cc: Jiri Pirko, Jacob Keller, Ariel Elior, GR-everest-linux-l2
The qed driver recently added devlink support with a single devlink
parameter. Add a driver-specific file to document the devlink features
that the qed driver supports.
Signed-off-by: Jacob Keller <jacob.e.keller@intel.com>
Cc: Ariel Elior <aelior@marvell.com>
Cc: GR-everest-linux-l2@marvell.com
---
Documentation/networking/devlink/index.rst | 1 +
Documentation/networking/devlink/qed.rst | 26 ++++++++++++++++++++++
2 files changed, 27 insertions(+)
create mode 100644 Documentation/networking/devlink/qed.rst
diff --git a/Documentation/networking/devlink/index.rst b/Documentation/networking/devlink/index.rst
index 0cbafef607d8..2007e257fd8a 100644
--- a/Documentation/networking/devlink/index.rst
+++ b/Documentation/networking/devlink/index.rst
@@ -34,4 +34,5 @@ parameters, info versions, and other features it supports.
mlxsw
mv88e6xxx
nfp
+ qed
ti-cpsw-switch
diff --git a/Documentation/networking/devlink/qed.rst b/Documentation/networking/devlink/qed.rst
new file mode 100644
index 000000000000..e7e17acf1eca
--- /dev/null
+++ b/Documentation/networking/devlink/qed.rst
@@ -0,0 +1,26 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===================
+qed devlink support
+===================
+
+This document describes the devlink features implemented by the ``qed`` core
+device driver.
+
+Parameters
+==========
+
+The ``qed`` driver implements the following driver-specific parameters.
+
+.. list-table:: Driver-specific parameters implemented
+ :widths: 5 5 5 85
+
+ * - Name
+ - Type
+ - Mode
+ - Description
+ * - ``iwarp_cmt``
+ - Boolean
+ - runtime
+ - Enable iWARP functionality for 100g devices. Notee that this impacts
+ L2 performance, and is therefor not enabled by default.
--
2.25.0.rc1
^ permalink raw reply related [flat|nested] 22+ messages in thread* RE: [EXT] [PATCH 11/17] devlink: add a driver-specific file for the qed driver
2020-01-09 22:46 ` [PATCH 11/17] devlink: add a driver-specific file for the qed driver Jacob Keller
@ 2020-01-14 8:41 ` Michal Kalderon
2020-01-14 20:07 ` Jacob Keller
0 siblings, 1 reply; 22+ messages in thread
From: Michal Kalderon @ 2020-01-14 8:41 UTC (permalink / raw)
To: Jacob Keller, netdev; +Cc: Jiri Pirko, Ariel Elior, GR-everest-linux-l2
> From: Jacob Keller <jacob.e.keller@intel.com>
> Sent: Friday, January 10, 2020 12:46 AM
>
> External Email
>
> ----------------------------------------------------------------------
> The qed driver recently added devlink support with a single devlink
> parameter. Add a driver-specific file to document the devlink features that
> the qed driver supports.
>
> Signed-off-by: Jacob Keller <jacob.e.keller@intel.com>
> Cc: Ariel Elior <aelior@marvell.com>
> Cc: GR-everest-linux-l2@marvell.com
> ---
> Documentation/networking/devlink/index.rst | 1 +
> Documentation/networking/devlink/qed.rst | 26
> ++++++++++++++++++++++
> 2 files changed, 27 insertions(+)
> create mode 100644 Documentation/networking/devlink/qed.rst
>
> diff --git a/Documentation/networking/devlink/index.rst
> b/Documentation/networking/devlink/index.rst
> index 0cbafef607d8..2007e257fd8a 100644
> --- a/Documentation/networking/devlink/index.rst
> +++ b/Documentation/networking/devlink/index.rst
> @@ -34,4 +34,5 @@ parameters, info versions, and other features it
> supports.
> mlxsw
> mv88e6xxx
> nfp
> + qed
> ti-cpsw-switch
> diff --git a/Documentation/networking/devlink/qed.rst
> b/Documentation/networking/devlink/qed.rst
> new file mode 100644
> index 000000000000..e7e17acf1eca
> --- /dev/null
> +++ b/Documentation/networking/devlink/qed.rst
> @@ -0,0 +1,26 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +===================
> +qed devlink support
> +===================
> +
> +This document describes the devlink features implemented by the ``qed``
> +core device driver.
> +
> +Parameters
> +==========
> +
> +The ``qed`` driver implements the following driver-specific parameters.
> +
> +.. list-table:: Driver-specific parameters implemented
> + :widths: 5 5 5 85
> +
> + * - Name
> + - Type
> + - Mode
> + - Description
> + * - ``iwarp_cmt``
> + - Boolean
> + - runtime
> + - Enable iWARP functionality for 100g devices. Notee that this impacts
> + L2 performance, and is therefor not enabled by default.
Small typos: Note instead of Notee and therefore instead of therefor
Other than that looks great, thanks a lot for adding this.
Michal
> --
> 2.25.0.rc1
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [EXT] [PATCH 11/17] devlink: add a driver-specific file for the qed driver
2020-01-14 8:41 ` [EXT] " Michal Kalderon
@ 2020-01-14 20:07 ` Jacob Keller
0 siblings, 0 replies; 22+ messages in thread
From: Jacob Keller @ 2020-01-14 20:07 UTC (permalink / raw)
To: Michal Kalderon, netdev; +Cc: Jiri Pirko, Ariel Elior, GR-everest-linux-l2
On 1/14/2020 12:41 AM, Michal Kalderon wrote:
>> From: Jacob Keller <jacob.e.keller@intel.com>
>> Sent: Friday, January 10, 2020 12:46 AM
>> +
>> +Parameters
>> +==========
>> +
>> +The ``qed`` driver implements the following driver-specific parameters.
>> +
>> +.. list-table:: Driver-specific parameters implemented
>> + :widths: 5 5 5 85
>> +
>> + * - Name
>> + - Type
>> + - Mode
>> + - Description
>> + * - ``iwarp_cmt``
>> + - Boolean
>> + - runtime
>> + - Enable iWARP functionality for 100g devices. Notee that this impacts
>> + L2 performance, and is therefor not enabled by default.
> Small typos: Note instead of Notee and therefore instead of therefor
> Other than that looks great, thanks a lot for adding this.
>
> Michal
I think this got merged. I'll go ahead and send a follow-up patch to
clean those up. Nice catch!
Regards,
Jake
^ permalink raw reply [flat|nested] 22+ messages in thread
* [PATCH 12/17] devlink: add a file documenting devlink regions
2020-01-09 22:46 [PATCH 00/17] devlink documentation refactor Jacob Keller
` (10 preceding siblings ...)
2020-01-09 22:46 ` [PATCH 11/17] devlink: add a driver-specific file for the qed driver Jacob Keller
@ 2020-01-09 22:46 ` Jacob Keller
2020-01-09 22:46 ` [PATCH 13/17] devlink: add documentation for ionic device driver Jacob Keller
` (5 subsequent siblings)
17 siblings, 0 replies; 22+ messages in thread
From: Jacob Keller @ 2020-01-09 22:46 UTC (permalink / raw)
To: netdev; +Cc: Jiri Pirko, Jacob Keller, Tariq Toukan
Also document the regions created by the mlx4 driver. This is currently
the only in-tree driver that creates devlink region snapshots.
Signed-off-by: Jacob Keller <jacob.e.keller@intel.com>
Cc: Tariq Toukan <tariqt@mellanox.com>
---
.../networking/devlink/devlink-region.rst | 54 +++++++++++++++++++
Documentation/networking/devlink/index.rst | 1 +
Documentation/networking/devlink/mlx4.rst | 13 +++++
3 files changed, 68 insertions(+)
create mode 100644 Documentation/networking/devlink/devlink-region.rst
diff --git a/Documentation/networking/devlink/devlink-region.rst b/Documentation/networking/devlink/devlink-region.rst
new file mode 100644
index 000000000000..efa11b9a20da
--- /dev/null
+++ b/Documentation/networking/devlink/devlink-region.rst
@@ -0,0 +1,54 @@
+.. 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.
+
+The major benefit to creating a region is to provide access to internal
+address regions that are otherwise inaccessible to the user. They can be
+used to provide an additional way to debug complex error states.
+
+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]
+ pci/0000:00:05.0/fw-health: size 64 snapshot [1 2]
+
+ # Delete a snapshot using:
+ $ devlink region del pci/0000:00:05.0/cr-space snapshot 1
+
+ # 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
+
+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.
diff --git a/Documentation/networking/devlink/index.rst b/Documentation/networking/devlink/index.rst
index 2007e257fd8a..3d351beedb0a 100644
--- a/Documentation/networking/devlink/index.rst
+++ b/Documentation/networking/devlink/index.rst
@@ -16,6 +16,7 @@ general.
devlink-health
devlink-info
devlink-params
+ devlink-region
devlink-trap
devlink-trap-netdevsim
diff --git a/Documentation/networking/devlink/mlx4.rst b/Documentation/networking/devlink/mlx4.rst
index 4fa5c2b51c52..7b2d17ea5471 100644
--- a/Documentation/networking/devlink/mlx4.rst
+++ b/Documentation/networking/devlink/mlx4.rst
@@ -41,3 +41,16 @@ parameters.
- Enable using the 4k UAR.
The ``mlx4`` driver supports reloading via ``DEVLINK_CMD_RELOAD``
+
+Regions
+=======
+
+The ``mlx4`` driver supports dumping the firmware PCI crspace and health
+buffer during a critical firmware issue.
+
+In case a firmware command times out, firmware getting stuck, or a non zero
+value on the catastrophic buffer, a snapshot will be taken by the driver.
+
+The ``cr-space`` region will contain the firmware PCI crspace contents. The
+``fw-health`` region will contain the device firmware's health buffer.
+Snapshots for both of these regions are taken on the same event triggers.
--
2.25.0.rc1
^ permalink raw reply related [flat|nested] 22+ messages in thread* [PATCH 13/17] devlink: add documentation for ionic device driver
2020-01-09 22:46 [PATCH 00/17] devlink documentation refactor Jacob Keller
` (11 preceding siblings ...)
2020-01-09 22:46 ` [PATCH 12/17] devlink: add a file documenting devlink regions Jacob Keller
@ 2020-01-09 22:46 ` Jacob Keller
2020-01-09 22:57 ` Shannon Nelson
2020-01-09 22:46 ` [PATCH 14/17] devlink: rename and expand devlink-trap-netdevsim.rst Jacob Keller
` (4 subsequent siblings)
17 siblings, 1 reply; 22+ messages in thread
From: Jacob Keller @ 2020-01-09 22:46 UTC (permalink / raw)
To: netdev; +Cc: Jiri Pirko, Jacob Keller, Shannon Nelson
The IONIC device driver allocates a devlink and reports versions. Add
documentation for this driver.
Signed-off-by: Jacob Keller <jacob.e.keller@intel.com>
Cc: Shannon Nelson <snelson@pensando.io>
---
Documentation/networking/devlink/index.rst | 1 +
Documentation/networking/devlink/ionic.rst | 29 ++++++++++++++++++++++
2 files changed, 30 insertions(+)
create mode 100644 Documentation/networking/devlink/ionic.rst
diff --git a/Documentation/networking/devlink/index.rst b/Documentation/networking/devlink/index.rst
index 3d351beedb0a..ce0ee563d83a 100644
--- a/Documentation/networking/devlink/index.rst
+++ b/Documentation/networking/devlink/index.rst
@@ -30,6 +30,7 @@ parameters, info versions, and other features it supports.
:maxdepth: 1
bnxt
+ ionic
mlx4
mlx5
mlxsw
diff --git a/Documentation/networking/devlink/ionic.rst b/Documentation/networking/devlink/ionic.rst
new file mode 100644
index 000000000000..48da9c92d584
--- /dev/null
+++ b/Documentation/networking/devlink/ionic.rst
@@ -0,0 +1,29 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=====================
+ionic devlink support
+=====================
+
+This document describes the devlink features implemented by the ``ionic``
+device driver.
+
+Info versions
+=============
+
+The ``ionic`` driver reports the following versions
+
+.. list-table:: devlink info versions implemented
+ :widths: 5 5 90
+
+ * - Name
+ - Type
+ - Description
+ * - ``fw``
+ - running
+ - Version of firmware running on the device
+ * - ``asic.id``
+ - fixed
+ - The ASIC type for this device
+ * - ``asic.rev``
+ - fixed
+ - The revision of the ASIC for this device
--
2.25.0.rc1
^ permalink raw reply related [flat|nested] 22+ messages in thread* Re: [PATCH 13/17] devlink: add documentation for ionic device driver
2020-01-09 22:46 ` [PATCH 13/17] devlink: add documentation for ionic device driver Jacob Keller
@ 2020-01-09 22:57 ` Shannon Nelson
0 siblings, 0 replies; 22+ messages in thread
From: Shannon Nelson @ 2020-01-09 22:57 UTC (permalink / raw)
To: Jacob Keller, netdev
On 1/9/20 2:46 PM, Jacob Keller wrote:
> The IONIC device driver allocates a devlink and reports versions. Add
> documentation for this driver.
>
> Signed-off-by: Jacob Keller <jacob.e.keller@intel.com>
> Cc: Shannon Nelson <snelson@pensando.io>
> ---
> Documentation/networking/devlink/index.rst | 1 +
> Documentation/networking/devlink/ionic.rst | 29 ++++++++++++++++++++++
Seems like a reasonable start - thanks!
Acked-by: Shannon Nelson <snelson@pensandi.io>
> 2 files changed, 30 insertions(+)
> create mode 100644 Documentation/networking/devlink/ionic.rst
>
> diff --git a/Documentation/networking/devlink/index.rst b/Documentation/networking/devlink/index.rst
> index 3d351beedb0a..ce0ee563d83a 100644
> --- a/Documentation/networking/devlink/index.rst
> +++ b/Documentation/networking/devlink/index.rst
> @@ -30,6 +30,7 @@ parameters, info versions, and other features it supports.
> :maxdepth: 1
>
> bnxt
> + ionic
> mlx4
> mlx5
> mlxsw
> diff --git a/Documentation/networking/devlink/ionic.rst b/Documentation/networking/devlink/ionic.rst
> new file mode 100644
> index 000000000000..48da9c92d584
> --- /dev/null
> +++ b/Documentation/networking/devlink/ionic.rst
> @@ -0,0 +1,29 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +=====================
> +ionic devlink support
> +=====================
> +
> +This document describes the devlink features implemented by the ``ionic``
> +device driver.
> +
> +Info versions
> +=============
> +
> +The ``ionic`` driver reports the following versions
> +
> +.. list-table:: devlink info versions implemented
> + :widths: 5 5 90
> +
> + * - Name
> + - Type
> + - Description
> + * - ``fw``
> + - running
> + - Version of firmware running on the device
> + * - ``asic.id``
> + - fixed
> + - The ASIC type for this device
> + * - ``asic.rev``
> + - fixed
> + - The revision of the ASIC for this device
^ permalink raw reply [flat|nested] 22+ messages in thread
* [PATCH 14/17] devlink: rename and expand devlink-trap-netdevsim.rst
2020-01-09 22:46 [PATCH 00/17] devlink documentation refactor Jacob Keller
` (12 preceding siblings ...)
2020-01-09 22:46 ` [PATCH 13/17] devlink: add documentation for ionic device driver Jacob Keller
@ 2020-01-09 22:46 ` Jacob Keller
2020-01-09 22:46 ` [PATCH 15/17] devlink: add a devlink-resource.rst documentation file Jacob Keller
` (3 subsequent siblings)
17 siblings, 0 replies; 22+ messages in thread
From: Jacob Keller @ 2020-01-09 22:46 UTC (permalink / raw)
To: netdev; +Cc: Jiri Pirko, Jacob Keller, Jakub Kicinski
Rename the trap-specific netdevimsim.rst file, and expand it to include
documentation of all the devlink features currently implemented by the
netdevsim driver code.
Signed-off-by: Jacob Keller <jacob.e.keller@intel.com>
Cc: Jakub Kicinski <jakub.kicinski@netronome.com>
---
.../devlink/devlink-trap-netdevsim.rst | 20 ------
.../networking/devlink/devlink-trap.rst | 2 +-
Documentation/networking/devlink/index.rst | 2 +-
.../networking/devlink/netdevsim.rst | 72 +++++++++++++++++++
drivers/net/netdevsim/dev.c | 2 +-
5 files changed, 75 insertions(+), 23 deletions(-)
delete mode 100644 Documentation/networking/devlink/devlink-trap-netdevsim.rst
create mode 100644 Documentation/networking/devlink/netdevsim.rst
diff --git a/Documentation/networking/devlink/devlink-trap-netdevsim.rst b/Documentation/networking/devlink/devlink-trap-netdevsim.rst
deleted file mode 100644
index b721c9415473..000000000000
--- a/Documentation/networking/devlink/devlink-trap-netdevsim.rst
+++ /dev/null
@@ -1,20 +0,0 @@
-.. SPDX-License-Identifier: GPL-2.0
-
-======================
-Devlink Trap netdevsim
-======================
-
-Driver-specific Traps
-=====================
-
-.. list-table:: List of Driver-specific Traps Registered by ``netdevsim``
- :widths: 5 5 90
-
- * - Name
- - Type
- - Description
- * - ``fid_miss``
- - ``exception``
- - When a packet enters the device it is classified to a filtering
- indentifier (FID) based on the ingress port and VLAN. This trap is used
- to trap packets for which a FID could not be found
diff --git a/Documentation/networking/devlink/devlink-trap.rst b/Documentation/networking/devlink/devlink-trap.rst
index 03311849bfb1..cbaa750de37d 100644
--- a/Documentation/networking/devlink/devlink-trap.rst
+++ b/Documentation/networking/devlink/devlink-trap.rst
@@ -233,7 +233,7 @@ help debug packet drops caused by these exceptions. The following list includes
links to the description of driver-specific traps registered by various device
drivers:
- * :doc:`devlink-trap-netdevsim`
+ * :doc:`netdevsim`
Generic Packet Trap Groups
==========================
diff --git a/Documentation/networking/devlink/index.rst b/Documentation/networking/devlink/index.rst
index ce0ee563d83a..2417d56e27cc 100644
--- a/Documentation/networking/devlink/index.rst
+++ b/Documentation/networking/devlink/index.rst
@@ -18,7 +18,6 @@ general.
devlink-params
devlink-region
devlink-trap
- devlink-trap-netdevsim
Driver-specific documentation
-----------------------------
@@ -35,6 +34,7 @@ parameters, info versions, and other features it supports.
mlx5
mlxsw
mv88e6xxx
+ netdevsim
nfp
qed
ti-cpsw-switch
diff --git a/Documentation/networking/devlink/netdevsim.rst b/Documentation/networking/devlink/netdevsim.rst
new file mode 100644
index 000000000000..2a266b7e7b38
--- /dev/null
+++ b/Documentation/networking/devlink/netdevsim.rst
@@ -0,0 +1,72 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=========================
+netdevsim devlink support
+=========================
+
+This document describes the ``devlink`` features supported by the
+``netdevsim`` device driver.
+
+Parameters
+==========
+
+.. list-table:: Generic parameters implemented
+
+ * - Name
+ - Mode
+ * - ``max_macs``
+ - driverinit
+
+The ``netdevsim`` driver also implements the following driver-specific
+parameters.
+
+.. list-table:: Driver-specific parameters implemented
+ :widths: 5 5 5 85
+
+ * - Name
+ - Type
+ - Mode
+ - Description
+ * - ``test1``
+ - Boolean
+ - driverinit
+ - Test parameter used to show how a driver-specific devlink parameter
+ can be implemented.
+
+The ``netdevsim`` driver supports reloading via ``DEVLINK_CMD_RELOAD``
+
+Regions
+=======
+
+The ``netdevsim`` driver exposes a ``dummy`` region as an example of how the
+devlink-region interfaces work. A snapshot is taken whenever the
+``take_snapshot`` debugfs file is written to.
+
+Resources
+=========
+
+The ``netdevsim`` driver exposes resources to control the number of FIB
+entries and FIB rule entries that the driver will allow.
+
+.. code:: shell
+
+ $ devlink resource set netdevsim/netdevsim0 path /IPv4/fib size 96
+ $ devlink resource set netdevsim/netdevsim0 path /IPv4/fib-rules size 16
+ $ devlink resource set netdevsim/netdevsim0 path /IPv6/fib size 64
+ $ devlink resource set netdevsim/netdevsim0 path /IPv6/fib-rules size 16
+ $ devlink dev reload netdevsim/netdevsim0
+
+Driver-specific Traps
+=====================
+
+.. list-table:: List of Driver-specific Traps Registered by ``netdevsim``
+ :widths: 5 5 90
+
+ * - Name
+ - Type
+ - Description
+ * - ``fid_miss``
+ - ``exception``
+ - When a packet enters the device it is classified to a filtering
+ indentifier (FID) based on the ingress port and VLAN. This trap is used
+ to trap packets for which a FID could not be found
diff --git a/drivers/net/netdevsim/dev.c b/drivers/net/netdevsim/dev.c
index 2eb4ca564745..97922f9834a7 100644
--- a/drivers/net/netdevsim/dev.c
+++ b/drivers/net/netdevsim/dev.c
@@ -287,7 +287,7 @@ struct nsim_trap_data {
};
/* All driver-specific traps must be documented in
- * Documentation/networking/devlink/devlink-trap-netdevsim.rst
+ * Documentation/networking/devlink/netdevsim.rst
*/
enum {
NSIM_TRAP_ID_BASE = DEVLINK_TRAP_GENERIC_ID_MAX,
--
2.25.0.rc1
^ permalink raw reply related [flat|nested] 22+ messages in thread* [PATCH 15/17] devlink: add a devlink-resource.rst documentation file
2020-01-09 22:46 [PATCH 00/17] devlink documentation refactor Jacob Keller
` (13 preceding siblings ...)
2020-01-09 22:46 ` [PATCH 14/17] devlink: rename and expand devlink-trap-netdevsim.rst Jacob Keller
@ 2020-01-09 22:46 ` Jacob Keller
2020-01-09 22:46 ` [PATCH 16/17] devlink: introduce devlink-dpipe.rst " Jacob Keller
` (2 subsequent siblings)
17 siblings, 0 replies; 22+ messages in thread
From: Jacob Keller @ 2020-01-09 22:46 UTC (permalink / raw)
To: netdev; +Cc: Jiri Pirko, Jacob Keller
Take the little bit of documentation for resources from various commit
messages and combine it into a new devlink-resource.rst file.
This could probably be expanded on even further by someone with more
knowledge of how the devlink resources work.
Signed-off-by: Jacob Keller <jacob.e.keller@intel.com>
---
.../networking/devlink/devlink-resource.rst | 62 +++++++++++++++++++
Documentation/networking/devlink/index.rst | 1 +
2 files changed, 63 insertions(+)
create mode 100644 Documentation/networking/devlink/devlink-resource.rst
diff --git a/Documentation/networking/devlink/devlink-resource.rst b/Documentation/networking/devlink/devlink-resource.rst
new file mode 100644
index 000000000000..93e92d2f0752
--- /dev/null
+++ b/Documentation/networking/devlink/devlink-resource.rst
@@ -0,0 +1,62 @@
+.. 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.
+
+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.
diff --git a/Documentation/networking/devlink/index.rst b/Documentation/networking/devlink/index.rst
index 2417d56e27cc..10b51d863a5c 100644
--- a/Documentation/networking/devlink/index.rst
+++ b/Documentation/networking/devlink/index.rst
@@ -17,6 +17,7 @@ general.
devlink-info
devlink-params
devlink-region
+ devlink-resource
devlink-trap
Driver-specific documentation
--
2.25.0.rc1
^ permalink raw reply related [flat|nested] 22+ messages in thread* [PATCH 16/17] devlink: introduce devlink-dpipe.rst documentation file
2020-01-09 22:46 [PATCH 00/17] devlink documentation refactor Jacob Keller
` (14 preceding siblings ...)
2020-01-09 22:46 ` [PATCH 15/17] devlink: add a devlink-resource.rst documentation file Jacob Keller
@ 2020-01-09 22:46 ` Jacob Keller
2020-01-09 22:46 ` [PATCH 17/17] devlink: document region snapshot triggering from userspace Jacob Keller
2020-01-11 1:07 ` [PATCH 00/17] devlink documentation refactor David Miller
17 siblings, 0 replies; 22+ messages in thread
From: Jacob Keller @ 2020-01-09 22:46 UTC (permalink / raw)
To: netdev; +Cc: Jiri Pirko, Jacob Keller
Primarily based on the DPIPE netdev conference paper, introduce a new
file to document the dpipe interface.
This likely needs further improvement, but is at least a good overall
start.
Signed-off-by: Jacob Keller <jacob.e.keller@intel.com>
---
.../networking/devlink/devlink-dpipe.rst | 252 ++++++++++++++++++
Documentation/networking/devlink/index.rst | 1 +
2 files changed, 253 insertions(+)
create mode 100644 Documentation/networking/devlink/devlink-dpipe.rst
diff --git a/Documentation/networking/devlink/devlink-dpipe.rst b/Documentation/networking/devlink/devlink-dpipe.rst
new file mode 100644
index 000000000000..468fe1001b74
--- /dev/null
+++ b/Documentation/networking/devlink/devlink-dpipe.rst
@@ -0,0 +1,252 @@
+.. 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 quiet 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 }
+ }
diff --git a/Documentation/networking/devlink/index.rst b/Documentation/networking/devlink/index.rst
index 10b51d863a5c..087ff54d53fc 100644
--- a/Documentation/networking/devlink/index.rst
+++ b/Documentation/networking/devlink/index.rst
@@ -13,6 +13,7 @@ general.
.. toctree::
:maxdepth: 1
+ devlink-dpipe
devlink-health
devlink-info
devlink-params
--
2.25.0.rc1
^ permalink raw reply related [flat|nested] 22+ messages in thread* [PATCH 17/17] devlink: document region snapshot triggering from userspace
2020-01-09 22:46 [PATCH 00/17] devlink documentation refactor Jacob Keller
` (15 preceding siblings ...)
2020-01-09 22:46 ` [PATCH 16/17] devlink: introduce devlink-dpipe.rst " Jacob Keller
@ 2020-01-09 22:46 ` Jacob Keller
2020-01-11 1:07 ` [PATCH 00/17] devlink documentation refactor David Miller
17 siblings, 0 replies; 22+ messages in thread
From: Jacob Keller @ 2020-01-09 22:46 UTC (permalink / raw)
To: netdev; +Cc: Jiri Pirko, Jacob Keller
Now that devlink regions can be triggered via
DEVLINK_CMD_REGION_TRIGGER, document this in the devlink-region.rst
file.
Signed-off-by: Jacob Keller <jacob.e.keller@intel.com>
---
Documentation/networking/devlink/devlink-region.rst | 10 ++++++++--
1 file changed, 8 insertions(+), 2 deletions(-)
diff --git a/Documentation/networking/devlink/devlink-region.rst b/Documentation/networking/devlink/devlink-region.rst
index efa11b9a20da..1a7683e7acb2 100644
--- a/Documentation/networking/devlink/devlink-region.rst
+++ b/Documentation/networking/devlink/devlink-region.rst
@@ -12,10 +12,13 @@ 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.
The major benefit to creating a region is to provide access to internal
-address regions that are otherwise inaccessible to the user. They can be
-used to provide an additional way to debug complex error states.
+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 :doc:`devlink-health`
example usage
-------------
@@ -37,6 +40,9 @@ example usage
# Delete a snapshot using:
$ devlink region del pci/0000:00:05.0/cr-space snapshot 1
+ # Trigger (request) a snapshot be taken:
+ $ devlink region trigger pci/0000:00:05.0/cr-space
+
# Dump a snapshot:
$ devlink region dump pci/0000:00:05.0/fw-health snapshot 1
0000000000000000 0014 95dc 0014 9514 0035 1670 0034 db30
--
2.25.0.rc1
^ permalink raw reply related [flat|nested] 22+ messages in thread* Re: [PATCH 00/17] devlink documentation refactor
2020-01-09 22:46 [PATCH 00/17] devlink documentation refactor Jacob Keller
` (16 preceding siblings ...)
2020-01-09 22:46 ` [PATCH 17/17] devlink: document region snapshot triggering from userspace Jacob Keller
@ 2020-01-11 1:07 ` David Miller
17 siblings, 0 replies; 22+ messages in thread
From: David Miller @ 2020-01-11 1:07 UTC (permalink / raw)
To: jacob.e.keller; +Cc: netdev, jiri
From: Jacob Keller <jacob.e.keller@intel.com>
Date: Thu, 9 Jan 2020 14:46:08 -0800
> This series updates the devlink documentation, with a few primary goals
>
> * move all of the devlink documentation into a dedicated subfolder
> * convert that documentation to the reStructuredText format
> * merge driver-specific documentations into a single file per driver
> * add missing documentation, including per-driver and devlink generally
>
> For each driver, I took the time to review the code and add further
> documentation on the various features it currently supports. Additionally, I
> added new documentation files for some of the features such as
> devlink-dpipe, devlink-resource, and devlink-regions.
>
> Note for the region snapshot triggering, I kept that as a separate patch as
> that is based on work that has not yet been merged to net-next, and may
> change.
>
> I also improved the existing documentation for devlink-info and
> devlink-param by adding a bit more of an introduction when converting it to
> the rst format.
Series applied, thanks Jacob.
^ permalink raw reply [flat|nested] 22+ messages in thread