From 0b0f945f54584621f4f91da701909f8e78c9eb69 Mon Sep 17 00:00:00 2001 From: Jacob Keller Date: Thu, 9 Jan 2020 14:46:20 -0800 Subject: devlink: add a file documenting devlink regions 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 Cc: Tariq Toukan Signed-off-by: David S. Miller --- .../networking/devlink/devlink-region.rst | 54 ++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 Documentation/networking/devlink/devlink-region.rst (limited to '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. -- cgit v1.2.3-59-g8ed1b From 9cd3e2c64f889a48b0d14bda22e867722b55497e Mon Sep 17 00:00:00 2001 From: Jacob Keller Date: Thu, 9 Jan 2020 14:46:25 -0800 Subject: devlink: document region snapshot triggering from userspace 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 Signed-off-by: David S. Miller --- Documentation/networking/devlink/devlink-region.rst | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) (limited to 'Documentation/networking/devlink/devlink-region.rst') 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 -- cgit v1.2.3-59-g8ed1b